How it works
A memory graph is a folder. Files are nodes, links between them are edges, and a small schema says which types exist.
The folder
memory/graph/ _schema.kgl node and relationship types README.md orientation for anyone opening the folder sessions/ one file per session: its messages, in order entities/ people/ places/ objects/ organizations/ events/ facts/ subject-predicate-object statements, by month preferences/ things a user likes, wants or prefers reasoning/ why decisions were made reflections/ higher-level syntheses (see Maintenance) .index/ search and alias indexes (derived, rebuildable)
.index/ is derived data: it can always be rebuilt from the .kgl files, so you can leave it out of git.
Node types
Memory uses the POLE+O entity types plus memory-specific ones:
| Type | Used for |
|---|---|
Person, Organization, Place, Object, Event | Named things worth referring to again: people, teams, components, services, meetings. |
Fact | A subject-predicate-object statement. The least structured write: reach for it when the subject or object isn't a thing you'd otherwise track. |
Preference | A stated like, want or opinion, as its own node. Prioritised in recall over a generic fact saying the same thing. |
Session, Message | Short-term memory: the raw conversation, kept verbatim and in order. |
ReasoningTrace | A goal, its outcome, and which memories informed it. |
Typed links
Edges are first-class and live inside the node that points. The relationship types are mentions, about, belongs_to, relates_to, follows, supersedes and informed_by. They are what make this a graph instead of a pile of notes.
@Fact billing-service uses_database postgres subject: "billing-service" predicate: uses_database object: "PostgreSQL 16" updated: 2026-11-16T09:42:10 [about] → entities/objects/billing-service.kgl#billing-service
Corrections don't erase history
When a fact or preference changes, the old node isn't overwritten. It is closed out with valid_to, and a new node holding the current value links back to it with supersedes. Hard deletion exists (delete_memory) for genuine mistakes; git history still has the audit trail.
Writing
The agent writes through MCP tools. Every write is a precise edit to a .kgl file, serialised with a file lock, and updates the search and alias indexes. A memory library that created git commits on its own would be presumptuous, so it never does: you decide when to commit. (An opt-in batching helper exists for people who want it.)
The recommended pattern is that the agent calls the write tools directly, from its own understanding of the conversation. There is also a small, deliberately unambitious regex extractor that runs on add_message for callers that only log raw messages. Turn it off with --no-auto-extract when the agent is writing its own memories.
Entity resolution
Mentions are normalised (lower-cased, punctuation stripped, whitespace collapsed) and looked up in an alias index, so "John", "john" and " John. " resolve to one entity instead of minting duplicates. The matching is deliberately simple; fuzzier identity such as nicknames or initials comes from registering aliases. The index is derived and rebuildable. To rename or merge entities, edit the files and reindex; see Maintenance.
Recall
get_context is the main read call. In three tiers, within a token budget, it returns recent messages from the session, hybrid search hits over long-term memory (facts and preferences first), and one hop of graph expansion from each hit. Details in Search & recall.