agent-context-substrate

The substrate is the asset; the model is an interchangeable client.

git clone https://github.com/thomaskawas/agent-context-substrate.git
cd agent-context-substrate
make setup && make demo

Requirements: Python 3.12+, Docker, make. make setup creates a venv and installs the dependencies, about 1.4 GB since the demo runs on CPU and skips the CUDA wheels; allow a few minutes on a slow connection. The database binds 127.0.0.1:5432, so stop anything already holding that port.

Why this exists

I build long-running projects with AI agents, and re-establishing context at the start of every session was the tax I paid most often. Uploading the same files, re-explaining the same decisions, watching the useful part of the window fill with material the model had already seen twice. A better model would ship and none of it moved across. The problem was never that the context was missing. It was that the context was not addressable: no way to ask a question and get back only what answers it, so you send everything and hope. The fix was to stop treating context as something you carry into a session and start treating it as something you query.

A reference implementation of a model-independent memory substrate for AI agents: project memory lives outside the model in a queryable, versioned store, exposed through one MCP gateway. Swap the model; keep everything. Claude today, Gemini or GPT tomorrow, same project memory underneath. Instead of pasting history back into every session, retrieval selects the small set of records the current task actually needs.

This repository is a clean-room reference implementation of that pattern, written from scratch against a synthetic corpus so every number on this page reproduces from a clean clone with the pinned dependencies. It is the pattern, not the system I run on my own work.

No API keys required: make demo runs entirely on local components. The pinned local models (name and revision) are the default adapter profile, local (make warmup, run automatically by make demo, pre-downloads ~180 MB once); the hermetic zero-download deterministic profile backs the tests and the always-on CI gate.

Related MCP server: AI Memory MCP Server

Layout

src/acs/adapters/base.py is the thesis in code: four small interfaces every external capability sits behind. src/acs/store/ treats memory as a system of record (versioned, auditable, genuinely deletable). src/acs/retrieval/ is the pipeline as small, separately testable stages. eval/ is the gate: changes ship by matching or beating baseline.lock.json, or they don't ship.

Design rationale lives in docs/adr/: nine decision records. Most are half a page; three run longer, where the argument needed the room.

Also in docs/: architecture.md for why each layer exists, threat-model.md for the adversarial boundaries and where each defence lives, principles.md for the rules the rest follows from, and build-your-own.md for the build sequence this repo followed.

What it demonstrates

• Ingest writes both representations in one pass: embeddings for similarity, an entity/relation graph for structure. Every document is embedded; a document that states no relation contributes no edges.

• Retrieval is a four-stage pipeline: hybrid vector + full-text search with a tunable blend, multi-query fusion (RRF), cross-encoder rerank, and an entity-anchored partition where the graph reorders the reranked list so a topical reranker stops confusing one component with its similarly-named sibling. Per-consumer retrieval profiles are data, not code.

• Governance: retrieval changes ship by matching or beating a locked eval baseline. Memory is SCD2-versioned with time-travel reads, purge genuinely deletes (vectors included), and the audit log refuses mutation at the database level.

• Access: one MCP gateway serves the substrate to any MCP client, scoped per caller. A quarantined research loop fills gaps with citation-mandatory write-back.

• Portability: every provider sits behind an adapter; the embedder is pinned on purpose.

The lineage id and the timestamps both come from make history: bare, it lists current memories with their ids; with LINEAGE=<id> it walks one memory's version chain and prints each version's validity window. Those windows are ISO timestamps so that a TS= you paste back resolves to the version you actually read, rather than one a second either side of it. Ids are generated per clone, so yours will not match any shown here.

make purge genuinely deletes (golden-set targets included, when they belong to the purged subject), so a benchmark against a purged corpus refuses to run as incomplete rather than quietly reporting lower recall. make demo resets to a clean corpus.

Every benchmark number on this page comes from an ablation over a seeded synthetic corpus (corpus/generate.py), reproducible from a clean clone and gated in CI (the deterministic profile on every push, the local profile on the bench-local label) against a locked baseline that also locks the corpus digest. Read the deltas, not the absolutes: recall@5 / mrr@5 on a synthetic corpus demonstrate what each stage contributes, never real-world quality. To see where a stage earns its delta, run .venv/bin/python eval/run_benchmark.py --by-family.

The ablation, local profile

Each stage earns a different thing, which is the argument for a pipeline rather than for one better retriever. tests/test_readme_table.py fails if this table and eval/baseline.lock.json ever disagree, so the table cannot drift from the numbers the gate enforces. The gate is a floor, so a change that improves a metric passes it and the numbers here stand until the baseline is re-locked on purpose with make lock-baseline, which then fails this table until it is brought up to match. Local profile, 120 golden queries, k=5, stage-1 merge rank, corpus digest ad7bf7ca. Reproduce with make demo.

What these numbers do and do not support, including why the model-lane comparison is a bound rather than a curve, is set out in docs/limitations.md.