Knowledge Graph

Memories as Nodes

Every memory is a node in the knowledge graph:

Field	Description
id	Unique identifier for this memory version
entity_id	Groups all versions of the same entity
content	The knowledge, as natural language text
layer	Semantic layer (0=Domain, 1=Concept, 2=Fact, 3=Episode)
parent_id	Link to the parent memory in the hierarchy
valid_from / valid_to	When this information was true

Entity Identity

The entity_id groups memory versions. When retain decides that new content updates an existing memory, the new version gets the same entity_id. The old version gets a valid_to timestamp; the new one becomes current.

Query all versions of an entity:

GET /api/v1/entities/alice-location/history

Relationships

Memories are connected by typed, weighted edges:

Field	Description
source_id	Origin memory
target_id	Target memory
type	Relationship kind (e.g., “is_about”, “related_to”, “part_of”)
strength	Connection strength, 0.0 to 1.0

Relationship types are not prescribed — the LLM infers appropriate types during retain. Common types include related_to, is_about, part_of, contradicts, and supports.

Graph Hierarchy

The parent_id field creates a tree mirroring the semantic layers:

Domain (layer 0)
  └── Concept (layer 1)
        └── Fact (layer 2)
              └── Episode (layer 3)

Orphaned memories (no parent_id) are candidates for organization by reflect.

Graph Closure

MemLayer maintains a pre-computed transitive closure of the parent-child hierarchy. This makes hierarchical queries like “find all memories under the Programming domain” a single lookup instead of recursive traversal.

How the Graph Improves Recall

Semantic search finds entry points. Graph traversal discovers related memories that wouldn’t match the query directly:

• Parent: A broader concept providing context
• Siblings: Related facts under the same parent
• Relationships: Explicitly linked memories
• Children: More specific details

A query for “technical skills” might match “experienced with Haskell”. Graph traversal then discovers the parent concept “Functional Programming”, siblings like “has used Erlang”, and children like “gave a talk on monads”.

Memory Namespaces

Each agent has a completely isolated namespace — its own knowledge graph, relationships, and hierarchy. One agent’s operations have no effect on another’s data.