A coding agent needs more than a vector index of old files. It needs to know where a symbol sits in the current repository, which boundaries it crosses, why an architectural choice was made, and whether earlier changes succeeded. “Spatial” is useful here as repository topology over time—not as a claim about human-like memory.
The memory must be revision-aware. Git identifies content and history through objects and commits; paths, line numbers, and symbols can move. A fact that was correct at one commit should not be silently presented as current at another.
Four memory planes
A practical design separates four kinds of evidence:
- Topology memory: packages, files, symbols, imports, references, build units, tests, ownership, schemas, services, and their typed edges.
- Decision memory: architectural decisions, rejected alternatives, constraints, owners, review dates, and superseding decisions.
- Episode memory: task requests, approved plans, patches, tool results, test evidence, incidents, rollbacks, and reviewer outcomes.
- Retrieval memory: lexical and semantic indexes used to find relevant items, with pointers back to the authoritative source.
Do not merge these into one untyped embedding store. A semantic neighbor is not a dependency, a prior patch is not a policy, and a comment is not necessarily an architectural decision.
Identity must include time
A useful symbol key can include:
repository + commit + path + language + symbol kind + qualified name + signatureThis identity is deliberately commit-scoped. To follow a symbol across changes, maintain inferred alias edges based on rename detection, syntax, references, and reviewable heuristics. Record confidence and allow an alias to be rejected. There is no universally stable symbol identity across arbitrary refactors.
Git blame can help attribute lines to commits, and rename/copy analysis can improve history inspection. It still does not explain design intent. Git notes can attach metadata to objects without changing those objects, but notes are stored separately and must be explicitly shared and managed. Neither feature replaces a maintained decision record.
Store claims with provenance
Every memory item should answer:
- What is the claim or artifact?
- Which repository revision and environment does it describe?
- Where did it come from?
- Was it observed, parsed, inferred, or written by a person?
- How confident is it?
- Who can read it?
- When should it be revalidated or deleted?
- What supersedes it?
Content hashes make parsed artifacts and tool results reusable. They do not make conclusions eternal: a test result also depends on its command, dependencies, environment, and configuration.
Retrieve by topology first
For a new task, retrieval can follow a bounded sequence:
- Resolve the target repository and commit.
- Find exact lexical matches for named paths, symbols, errors, or configuration keys.
- Expand through typed graph edges to nearby definitions, consumers, tests, owners, and boundaries.
- Retrieve active decisions that govern those nodes.
- Retrieve recent, relevant episodes and their outcomes.
- Use semantic search to fill gaps, keeping matches labeled as retrieval hints.
- Fit the result to a context budget using evidence type, recency, confidence, and task relevance.
This produces a compact context bundle with citations back to files, commits, decisions, and test runs. The agent can reread authoritative sources when a cached summary is stale or disputed.
GitHub code navigation demonstrates the value of exact definitions and references; TypeScript project references and the Rust compiler query graph demonstrate explicit topology used for build and incremental work. A long-term memory system can preserve these facts by revision and combine them with decisions and outcomes.
Preserve intent as maintained records
Architectural rationale should live in a small, reviewable record with:
- decision and status;
- context and constraints;
- alternatives considered;
- consequences and enforced invariants;
- owners and review date;
- affected components;
- supersedes and superseded-by links.
The enforceable part belongs in code, tests, schemas, lint rules, or policy. Memory helps an agent find the invariant; executable checks prevent regression. If a decision conflicts with the current repository or a later record, surface the conflict rather than selecting whichever text ranks highest.
Forgetting is required
Long-term memory without deletion becomes a liability. Define retention and invalidation rules for:
- secrets and personal data;
- source deleted for legal or contractual reasons;
- stale summaries after the underlying content changes;
- failed hypotheses and rejected patches;
- old incident data;
- model-generated inferences that were never confirmed.
Access control should be evaluated at retrieval time. An embedding or summary derived from restricted code remains restricted. Deleting the source while retaining derived vectors or summaries is not complete deletion.
Evaluate memory by prevented mistakes
Useful metrics include:
- relevant dependency, owner, or decision retrieved;
- stale claim rate;
- unsupported-memory citation rate;
- architectural regressions caught by existing invariants;
- irrelevant context tokens;
- successful symbol continuity across refactors;
- secrets or unauthorized artifacts retrieved;
- reviewer corrections to inferred links.
Compare against simple lexical search and current-tree navigation. If the memory adds tokens without improving decisions or verification, it is not helping.
A practical first version
Begin with one repository. Index the current commit's packages, files, symbols, references, tests, and owners. Add concise decision records and store completed-task evidence with exact commit and command metadata. Use lexical retrieval plus bounded graph expansion; add semantic search only where it measurably improves recall. Reindex changed content by hash, invalidate stale summaries, and require every returned memory item to cite its source.
The aim is not an agent that remembers everything. It is an agent that can locate the current structure, recover the reasons that still apply, distinguish evidence from inference, and forget what should no longer be used.