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:

TypeUsed for
Person, Organization, Place, Object, EventNamed things worth referring to again: people, teams, components, services, meetings.
FactA subject-predicate-object statement. The least structured write: reach for it when the subject or object isn't a thing you'd otherwise track.
PreferenceA stated like, want or opinion, as its own node. Prioritised in recall over a generic fact saying the same thing.
Session, MessageShort-term memory: the raw conversation, kept verbatim and in order.
ReasoningTraceA 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.