Learn how production agents remember.
Production agent memory is not a vector database. It is a system that keeps raw evidence and derives queryable memory views from it.
Most agents ship the same minimum memory loop: a file store, an index, recall at turn start, extraction at run end, and a raw session log. That loop serves one user and one agent. Production memory serves many tenants, many agents, and years of history. At that scale, memory is a subsystem of its own, with its own lifecycle, its own clocks, and its own failure modes. This repo scales that loop into a full memory subsystem, one section per design decision.
Contents: Pipeline · Method · Systems · Sections · Structure · Running
One rule carries the whole design:
Raw events are never dropped. Derived memories can always be rebuilt.
Everything after capture is a view: a queryable copy computed from the events, never the only copy. If extraction, consolidation, or an index goes wrong, the system rebuilds it from the event log. MemMachine takes the same position: keep full episodes as ground truth, then layer profiles, indexes, and contextual retrieval on top.
The same system runs on three schedules:
| Hot path | Warm path | Cold path | |
|---|---|---|---|
| When | every query | run end | background or scheduled |
| Work | plan, retrieve, rerank, assemble, inject | append raw event, write gate, extract candidates | consolidate, dedupe, supersede, build profile, reindex, evaluate |
| Constraint | low latency, strict token budget | one extra model call, no long block | can be slow, must be safe |
The minimum loop already has this shape: recall before the turn, extraction at run end, consolidation in the background. This track keeps the same three clocks and scales each one.
Every section is self-contained and uses the same four-part lens:
- Opening. What problem this stage solves.
- Mechanism. The moving parts and how data moves.
- Per system. How real systems implement it, in one table.
- Failure modes. What breaks and how to mitigate it.
To learn from this repo:
- Read the sections in order. Each builds on the stage before it.
- Run a section's offline checks:
python sections/NN-name/src/test.py. No key needed. - Diff a section's
src/against the section before it. The diff is the one mechanism that section adds.
Each system is a worked example in the per-system table of the sections listed.
| System | Why people use it | Read it for | Sections |
|---|---|---|---|
| Claude Code | Frontier coding agent. Its auto memory keeps markdown files per project directory. | Scoped stores, background consolidation | 1, 5 |
| Hermes Agent | Long-term assistant: remembers you, learns workflows, runs anywhere. | Raw session log, approval-gated writes | 1, 2, 3 |
| MemMachine | Open memory layer that keeps full conversation episodes as ground truth. | Episode ledger, contextual retrieval | 2, 8 |
| Mem0 | Widely used memory layer with a curated store: new facts merge in, not pile on. | The LLM write gate | 3 |
| LangMem | LangChain's memory SDK: records validate against app schemas at write time. | Typed records and profiles | 4 |
| Hindsight | Memory engine that keeps facts, observations, and opinions apart. | Epistemic types, reflection | 4 |
| Graphiti / Zep | Temporal knowledge graph memory: old facts get closed, not overwritten. | Bitemporal fields, SUPERSEDE |
5 |
| A-Mem | Agentic memory: new notes link to and evolve existing ones. | Dynamic linking, agentic consolidation | 6 |
| Sleep-time Compute | Moves consolidation off the query hot path into background time. | Cold-path consolidation | 6 |
| AgentRunbook-C | Stores trajectories as files and lets a coding agent search them in a sandbox. | Agentic file retrieval | 8 |
Sections 7 to 10 compare design patterns (wiki vs graph views, retrieval strategies, assembly policies, metrics) rather than single systems.
Ten sections, one design decision each. Each row links to one self-contained writeup with runnable code.
| # | Section | Question | Key mechanisms |
|---|---|---|---|
| Extraction | |||
| 1 | Memory contract | Whose memory is this? | Scope, tenant and user isolation, retention, sensitivity |
| 2 | Event ledger | What counts as evidence? | Append-only log, occurred_at vs recorded_at |
| 3 | Write policy | Is this worth remembering? | Novelty, durability, explicit write decisions |
| 4 | Typed memory | What kind of memory is it? | Episodic, semantic, procedural, epistemic types |
| Consolidation | |||
| 5 | Temporal resolution | Conflict, or an update? | Bitemporal fields, SUPERSEDE, non-destructive operations |
| 6 | Consolidation | How do events become knowledge? | Compression, abstraction, propose-validate-commit |
| 7 | Index views | How is one ledger queried many ways? | Sparse, dense, temporal, graph, wiki, profile views |
| Recall | |||
| 8 | Hybrid retrieval | How is the right memory found? | BM25 plus vector plus graph, source expansion, routing |
| 9 | Context assembly | How is memory injected safely? | Evidence bundles, token budget, untrusted-data framing |
| 10 | Evaluation and governance | Did memory actually help? | Write, retrieval, context, and end-to-end metrics |
learn-agent-memory/
├── README.md # track map
├── sections/ # one folder per section
│ ├── 01-memory-contract/ # README.md per section, runnable chain starts here
│ ├── ...
│ └── 10-evaluation-governance/ # holds the whole engine
└── assets/ # shared images
Each section folder is NN-name/ and contains README.md, README.zh-TW.md, and README.zh-CN.md, plus a runnable src/.
Each section carries the prior section's src/ forward and adds one mechanism,
so the diff between two adjacent sections is that section's mechanism, and section 10 holds the whole engine.
Everything is stdlib Python (dataclasses, sqlite3). No third-party dependencies, no API key, no setup.
Each section has test.py with offline checks. Run from the repo root:
python sections/01-memory-contract/src/test.py- Add a system. Slot a new memory system into a section's per-system table.
- Deepen a section. Add a mechanism, clearer diagram, or sharper failure mode.
- Correct the record. These pages are educational reconstructions from papers and docs. Sourced corrections are welcome.
Favor named, verifiable mechanisms over speculation. Cite sources.
- MemMachine: ground-truth-preserving memory, contextual retrieval over full episodes.
- Zep / Graphiti: temporal knowledge graph for agent memory, bitemporal facts.
- Hindsight: retain, recall, reflect. Epistemic split between facts, observations, and opinions.
- A-Mem: agentic memory, new notes link to and evolve existing ones.
- Memory-R1: RL-trained memory manager over
ADD / UPDATE / DELETE / NOOP. - Sleep-time Compute: background consolidation off the query hot path.
- Karpathy's LLM Wiki: idea file. An LLM-maintained markdown wiki compiled over immutable sources.
- HippoRAG: knowledge graph plus Personalized PageRank, multi-hop evidence in one retrieval step.
- LongMemEval: long-term interactive memory benchmark, five task families.
- LongMemEval-V2: agent-experience benchmark, AgentRunbook-C agentic file retrieval.