Highlights
- ActiveGraph keeps two distinct storage layers, an event store that is the durable source of truth, and a graph store that is a live projection of current state. FalkorDBGraphStore replaces the default in-memory projection with a real FalkorDB graph, letting you query it with Cypher, share it across processes, and keep large graphs off the heap.
-
The graph store is a projection, not a persistence layer. Durability comes from the event store. If the FalkorDB graph is wiped, replaying the event log rebuilds it instantly. FalkorDB's value is in where the current-state view lives and how you query it.
-
Three reasons to reach for it: you want to query live agent state with Cypher, you want to share the projection across processes, or your graph is large enough that you want to offload it to a remote server like FalkorDB Cloud rather than keeping it in process memory.
Building agents is easy. Building agents that hold up in production is a different problem entirely. The moment you move beyond a single-session demo, questions pile up fast: where does state live, how do you inspect what your agents are actually doing, and how do you share context across processes without rebuilding everything from scratch. ActiveGraph was designed with those questions in mind. It draws a clear line between two distinct storage layers, each with a specific job, and FalkorDBGraphStore is how FalkorDB plugs into that architecture to give your agent graph something the default in-memory store never could: a live, queryable, shareable view of current state backed by a real graph database.
What is ActiveGraph?
ActiveGraph is an open source framework for building multi-agent systems with built-in visibility into what your agents are doing. As agents work through tasks, ActiveGraph builds a graph of the interactions, objects, and relationships involved in the run. That graph is the operational backbone of the system, and it is what agents query as they make decisions.
It was built by Yohei Nakajima, and if you have not come across it yet, the repo is worth a look: https://github.com/yoheinakajima/activegraph
Two Stores, two jobs
ActiveGraph has two storage layers, each with a distinct role.
The event store records everything that happens. The graph store is where your agent graph lives right now, queryable, traversable, and ready to use.
FalkorDBGraphStore is a graph store backend. It takes the current-state projection that would otherwise sit in process memory and moves it into FalkorDB, where you can query it with Cypher, share it across processes, and keep even large graphs running smoothly. The event store handles durability. FalkorDB handles the live view, and it handles it fast.
Behaviors -> emit events -> EventStore (the log, source of truth)
|
apply_event projects
|
GraphStore (current state)
|
InMemoryGraphStore -> process memory (default)
FalkorDBGraphStore -> FalkorDB
What we contributed
1. Query current state with Cypher. Once the projection lives in FalkorDB, you can run Cypher queries directly against the live agent graph. Build dashboards, run ad-hoc inspections, or query across runs from outside the process.
-- All objects of a given type
MATCH (o:AGObject {type: 'person'}) RETURN o.id, o.data
-- A node and what it points at
MATCH (r:AGRelation {source: $id}) RETURN r.target, r.type
2. Share the projection across processes. One writer and multiple read-only inspectors can all point at the same FalkorDB graph. The default in-memory store is invisible to anything outside the process it lives in.
Setup
Install
# Server mode, recommended for anything beyond a quick local experiment
pip install 'activegraph[falkordb]'
# Embedded mode, zero infrastructure, good for demos
pip install 'activegraph[falkordb-embedded]'
Run a FalkorDB Server
docker run -d --rm -p 6379:6379 falkordb/falkordb:latest
Wire it in
from activegraph import Graph, FalkorDBGraphStore
store = FalkorDBGraphStore(host="localhost", port=6379)
graph = Graph(graph_store=store)
# Use the graph exactly as you would with the in-memory store
alice = graph.add_object("person", {"name": "Alice"})
bob = graph.add_object("person", {"name": "Bob"})
graph.add_relation(alice.id, bob.id, "knows")
Graph is the only place the seam is exposed. Everything else, behaviors, the runtime, the event log, is unchanged.
With environment variables
The deployment-friendly path. Leave connection details out of your code and supply them from the environment.
export FALKORDB_HOST=localhost
export FALKORDB_PORT=6379
from activegraph import FalkorDBGraphStore
# No connection args, picks up FALKORDB_* from the environment
store = FalkorDBGraphStore()
Connect to FalkorDB
Point FalkorDBGraphStore at FalkorDB Cloud and your agent graph projection has managed infrastructure behind it without running your own server.
Naming Graphs Across Runs
Multiple runs can share one FalkorDB server by giving each its own named graph:
store = FalkorDBGraphStore(host="localhost", graph_name=f"run-{run_id}")
Replaying an existing run into FalkorDB
You can take a run that was recorded with the default in-memory store and rebuild its current-state projection in FalkorDB by replaying the event log:
from activegraph import Runtime, FalkorDBGraphStore
store = FalkorDBGraphStore(host="localhost", graph_name="run-42")
rt = Runtime.load("runs.db", run_id="run-42", graph_store=store)
# The log has been replayed into FalkorDB, query it with Cypher
Best Use Cases for ActiveGraph + FalkorDB
FAQ
FalkorDBGraphStore is the right choice when you want to:
- Query current state with Cypher. Build dashboards, run ad-hoc inspections, or explore the live agent graph from outside the process.
- Share the projection across processes. One writer and multiple read-only inspectors all pointing at the same FalkorDB graph.
- Keep a large graph running lean. Move a growing projection out of process memory and into a database built to handle it.
The bigger your agent graph gets, the more this matters. A live, queryable, shareable view of current state is a different capability than anything sitting in process memory.
Give it a spin, star the repo, and let us know what you build.
How does FalkorDBGraphStore differ from the default in-memory store?
The default store keeps the agent graph as a variable in process memory. FalkorDB moves that projection into a real graph database, so you can query it with Cypher, share it across processes, and keep large graphs off the heap.
Can I use FalkorDB Cloud instead of running my own server?
Yes. Point FalkorDBGraphStore at FalkorDB Cloud and your agent graph projection has managed, remote infrastructure behind it with no self-hosting required.
Do I need to modify my agent code to use FalkorDBGraphStore?
No. You inject it at Graph construction with Graph(graph_store=store) and everything else stays the same. Behaviors, runtime, and event log are all unchanged.
