Practical Agent Memory Reference
A runnable, MIT‑licensed implementation of store, retrieve, provenance, and consolidate operations for AI agents — grounded in a small, reproducible test fixture.
Hero image: Nikon D4 HTTP Server Working… by Takashi Hososhima, CC BY‑SA 2.0. Cropped and re‑encoded for this site; derivative remains CC BY‑SA 2.0.
Store
Add entries with explicit event IDs and timestamps. The ledger keeps an append‑only record of every mutation, so you can trace exactly what changed and when.
Retrieve
Query with BM25 or a tag‑based scorer. Both return ranked results with scores, and the retrieval layer is designed to be swapped or extended without touching the core store.
Provenance
Every stored item carries its source, event ID, and insertion time. The provenance module answers “where did this come from?” and supports audit‑style checks.
Consolidate
Merge or summarise older entries to keep memory bounded. The consolidation pass is deterministic for a given input, so its behavior can be inspected and tested before adaptation.
Observed fixture metrics
Synthetic corpus: 16 entries, 5 queries, seed 7, k=5. Two independent runs produced identical aggregate rows.
BM25
- mean_recall@k: 0.90
- mean_precision@k: 0.28
- MRR: 1.00
Tag scorer
- mean_recall@k: 1.00
- mean_precision@k: 0.32
- MRR: 1.00
These are observed numbers on a tiny fixture, not a benchmark. Full JSON output differs between runs; the cause is not yet diagnosed. No bit‑reproducibility, Python 3.9 compatibility, or external performance guarantee is claimed.
Scope and limitations
This reference is intentionally small. It is not a production‑grade memory system, nor a claim of proprietary benchmark results. It exists to give you a clear, runnable starting point for agent memory design. The code is MIT licensed and you are free to adapt it.
The download includes the reference package, runnable examples, MIT license and evaluation artifact.
.jpg){kind=link}