Quickstart — Run the Agent Memory Reference
Two commands get you from a fresh archive to a working memory store and a reproducible evaluation. Tested on Python 3.14 only.
Get the code
Download the reference archive from /downloads/agentmemory-reference.zip, then unpack and enter the folder:
unzip agentmemory-reference.zip
cd agentmemory-referenceThe archive contains the agentmemory package at the root, plus examples/ and evaluation/.
Run the quickstart example
This script writes a few entries, queries them, and prints the top results. It exercises the append-only store and the BM25 retrieval path.
PYTHONPATH=. python3 examples/quickstart.pyExpect exit code 0 and a short list of scored memories. The exact IDs are generated at runtime, so don’t rely on them.
Run the evaluation harness
The eval uses a synthetic corpus of 16 entries and 5 queries. It writes a JSON artifact to eval-results.json.
PYTHONPATH=. python3 -m agentmemory.eval --seed 7 --k 5 --out eval-results.jsonIn the reference run, BM25 aggregate metrics were mean_recall@k 0.9, mean_precision@k 0.28, MRR 1.0; the tag scorer gave 1.0, 0.32, 1.0. These are observations, not guarantees — the full JSON output is not bit-reproducible across runs.
Minimal API example
The core interface is intentionally small. Here’s the whole flow from mem.py and retrieval.py:
from agentmemory.mem import Entry, MemoryStore
from agentmemory.retrieval import Retrieval, BM25Scorer
store = MemoryStore()
store.add(Entry(text="agent observed a failed login", tags=["auth", "error"]))
store.add(Entry(text="user reset password successfully", tags=["auth"]))
retrieval = Retrieval(scorer=BM25Scorer())
results = retrieval.search(store, "login failure", k=2)
for r in results:
print(r.entry.id, r.score)No external dependencies, no model downloads. The Retrieval class accepts any scorer with a score_all method, so you can plug in an embedding-based encoder later without changing the harness.
Source and examples — Browse the package at /code/agentmemory/mem.py, /code/agentmemory/retrieval.py, and the full module list. Example scripts: quickstart.py and provenance.py. Evaluation output: eval-results.json. Code is MIT licensed — see /code/LICENSE.
