Architecture: an append-only agent memory reference

This page maps the actual modules and data flow of the reference implementation. It is a local, in-memory teaching/demo system — not a remote database or cloud service. No durability or privacy guarantee is implied or implemented.

Module map

agentmemory/mem.py — Append-only Entry dataclass and MemoryStore.
agentmemory/retrieval.py — Pluggable scorers: BM25Scorer and TagScorer.
agentmemory/ledger.py — Provenance ledger linking each entry to its source.
agentmemory/consolidate.py — Consolidation logic for merging or summarizing entries.
agentmemory/eval.py — Evaluation harness for retrieval quality.

All code is MIT licensed — see /code/LICENSE. Browse the source at /code/agentmemory/.

Data flow

Write — an agent observation becomes an immutable Entry (id, text, source, tags, metadata, timestamp).
Append — MemoryStore.add() stores it in order; entries cannot be mutated.
Query — Retrieval.search() tokenizes the query and scores entries via the selected scorer.
Provenance — ledger.py records the source reference for every entry, so retrieval can always point back.
Consolidation — consolidate.py optionally merges or summarizes older entries (boundary kept separate).
Evaluation — eval.py runs synthetic queries and reports metrics.

Boundaries and developer responsibilities

This reference intentionally separates concerns:

Append-only store — entries are immutable; no in-place updates.
Retrieval — scoring is pluggable; swap in an embedding model via the same interface.
Provenance — every entry carries a source reference; the ledger tracks it.
Consolidation — merging/summarization is a separate step, not part of the core store.

As a developer, you are responsible for memory scope, retention policy, redaction of sensitive data, and trust boundaries. This code does not implement durability, encryption, or access control — treat it as a reference for semantics, not a production service.

Try the quickstart See evaluation results