Graph-based memory is a memory layer where the agent's persistent state is stored as a graph of nodes and edges.
The graph is the memory; the retrieval is graph traversal. The graph-based memory pattern is the right pattern when the agent's state is naturally relational — the agent's knowledge has references, the agent's history has connections, and the agent's reasoning is about relationships between concepts.
When graph-based memory is the right pattern
Graph-based memory is the right pattern when the agent's retrieval needs to be relational. The agent is asking "what is related to this?" rather than "what is similar to this?" The graph-based memory pattern is also the right pattern when the agent's knowledge has a natural structure: the agent has users, the users have projects, the projects have tasks, the tasks have decisions, and the decisions have outcomes. The graph captures the structure and the retrieval respects it.
Graph-based memory is also the right pattern when the agent's memory needs to be explainable. The graph's edges are explicit connections, and the agent's reasoning can be traced back through the edges to the source. The graph-based memory pattern is the right pattern for auditable systems.
The graph's structure
The graph typically has:
- Entity nodes. The things the agent knows about. The entities can be objects (people, places, things), concepts (ideas, categories), or events (decisions, actions, observations).
- Relationship edges. The connections between the entities. The edges are typed (the connection is a specific relationship: works_on, owns, related_to, caused_by).
- Attribute nodes. The properties of the entities. The attributes are tied to the entity nodes through "has_attribute" edges.
- Source nodes. The provenance of the data. The source nodes are tied to the entities and edges through "sourced_from" edges, and the source nodes are what the agent's reasoning can be traced back to.
The retrieval is graph traversal
The graph-based memory's retrieval is not a similarity search; the retrieval is a graph traversal. The agent starts at a node (the query's anchor), and the agent traverses the edges to find the related nodes. The traversal is bounded by depth (the agent traverses up to N edges away) and by type (the agent traverses only specific types of edges).
The graph traversal is the right pattern when the agent's queries are about relationships. The traversal is also the right pattern when the agent's reasoning needs to be explainable: the agent can show the path through the graph that produced the answer.
Operator implications
The graph-based memory pattern is the right place to start when an operator is adding a memory layer to an agent that needs to reason about relationships. The most common operator issues with graph-based memory are: the graph is too sparse (the agent is not writing the right edges), the graph is too noisy (the agent is writing too many edges), the graph is too slow (the agent is traversing too many nodes), and the graph is too rigid (the agent cannot add new edge types at runtime).
The graph-based memory pattern is also the right place to start when an operator is debugging an agent that is making the wrong relationships. The graph's edges are the source of the agent's reasoning, and the graph's edges are the place to investigate.
Related terms
Graph-based memory is one of the implementations of the memory layer. The graph-based memory is complementary to embedding search: the embedding search is the right pattern for similarity, the graph traversal is the right pattern for relationships. The graph-based memory is often implemented as a session's persistent state. The graph-based memory's traversal is one of the inputs to the observability layer.
For the full primer, see Memory & State.