Persistent Memory for AI Coding Agents: Governance

Persistent memory for AI coding agents should be treated as platform infrastructure, not as a bigger prompt. The useful design is layered: small repo instructions for stable norms, auditable issue and PR history for team decisions, structured storage for observations and preferences, retrieval for large knowledge, and strict write controls so stale, poisoned, or secret-bearing context does not become durable.

The operational problem is simple. Real engineering work spans days, branches, review threads, failed builds, local setup quirks, architecture decisions, and team preferences. A coding agent that starts each session cold will repeat discovery work. An agent that remembers everything will eventually carry bad context into every task. The platform job is to decide what gets remembered, where it lives, who can trust it, and when it expires.

Memory is more than context

Active context is what the model sees right now. Persistent memory is the system that decides what can be written, retrieved, summarized, injected, deleted, and audited across sessions. Mixing those two concepts creates brittle systems.

Always-loaded files such as AGENTS.md or CLAUDE.md are useful because they are deterministic and reviewable. They work well for stable instructions: test commands, repo layout, coding conventions, dependency rules, and review expectations. They are poor places for long task logs, speculative agent summaries, or branch-specific assumptions. They consume tokens on every run, and one bad instruction can affect unrelated work.

On-demand memory has the opposite trade-off. It keeps active context smaller, but retrieval quality now matters. The agent has to ask the right question, find the right memory, and rank it against source-of-truth material. For platform teams, the answer is not one memory store. It is a controlled read and write path across several stores.

Use memory layers with clear jobs

A durable coding-agent setup should separate memory by authority and lifespan.

• Repo instruction files: stable team guidance, kept short, reviewed in git, loaded predictably.
• ADRs, specs, issues, and PRs: authoritative decision history tied to code review and delivery.
• Structured local or managed storage: per-repo observations, user preferences, task state, command outcomes, and known constraints.
• Vector or RAG indexes: semantic recall over docs, ownership notes, ADRs, and PR discussion when exact lookup is not enough.
• Session-end snapshots: handoff summaries for unfinished work, current branch assumptions, open questions, and next commands.
• Workspace snapshots: file diffs and execution state, useful for resumption but not a substitute for validated knowledge.

This structure keeps durable team policy away from temporary task state. It also prevents personal preferences from leaking into shared repo rules. A user preference such as "answer concisely" should not live beside a team rule such as "security review is required for auth changes."

Design the write path first

The most important memory decision is not retrieval. It is writing. Memory poisoning happens when untrusted input becomes trusted future context. For coding agents, untrusted input can arrive through README snippets, issue comments, PR feedback, generated logs, dependency docs, web pages, copied stack traces, or even code comments.

Concretely, every memory write should carry a schema:

• Type: observation, preference, decision, task state, policy, command result, or risk.
• Scope: user, repo, team, branch, worktree, service, or time-boxed task.
• Source: file path, commit, issue, PR, transcript, command, or human approval.
• Authority: code and CI outrank ADRs, ADRs outrank PR comments, PR comments outrank agent summaries.
• Freshness: timestamp, expiry, revalidation rule, and owner where needed.
• Security status: scanned, redacted, blocked, approved, or needs review.

Do not let agents freely save imperative instructions from untrusted sources. Store facts as facts. "The payment service test command failed on commit X with error Y" is safer than "Always skip payment tests." The first can be verified. The second can silently change future behavior.

Human approval should be required for any memory derived from untrusted files, web pages, issue comments, customer data, credential-adjacent logs, or anything that looks like policy. Agents can propose memory diffs, but durable instructions should go through review, especially when they affect shared repo rules or team policy.

Make retrieval boring and ranked

The read path should be predictable enough that engineers can debug it. Rank authoritative sources first: code, tests, and CI; then ADRs and specs; then issues and PR decisions; then repo instruction files; then agent summaries; then user chat; then external material.

When the agent injects retrieved memory into context, keep the format explicit. Include source, age, scope, and confidence. If two memories conflict, show the conflict instead of merging them into a convenient summary. A stale branch note should not override a current failing test. A three-month-old "known flaky" note should trigger revalidation, not automatic dismissal of a failure.

For deterministic facts such as commands, owners, service names, and dependency policy, use structured lookup before semantic search. Vector retrieval is useful for broad recall, but it can make a near match look authoritative. Platform teams need both precision and provenance.

Controls for stale, poisoned, and secret-bearing memory

Security controls belong in the memory layer, not only in the prompt. A practical baseline includes secret scanning before write, path restrictions for memory tools, allow-lists for writable memory locations, audit logs for create, update, and delete actions, and retention rules by memory type.

MCP memory servers and similar tools can provide a useful standard interface, but the interface is not governance. Reference implementations need production hardening, storage controls, access policy, backup behavior, and threat modeling before team use. A generic memory tool that can write arbitrary observations is a privileged state mutation surface.

Deletion also needs design. Removing a memory from one table is not enough if it still exists in summaries, vector indexes, logs, backups, or downstream generated notes. The platform should track where memory records have been copied or indexed, then test deletion as a product behavior.

Persistent memory for AI coding agents checklist

• Keep repo instruction files short, reviewed, and limited to stable team guidance.
• Use issues, PRs, ADRs, and specs as the authoritative memory plane for decisions.
• Store agent-authored memory in typed records with source, scope, authority, and expiry.
• Require approval for instruction-like memories and anything from untrusted sources.
• Run secret detection and redaction before every durable write.
• Separate user preferences, team norms, branch state, and repo facts.
• Prefer deterministic lookup for exact operational facts, then semantic retrieval for broad recall.
• Inject retrieved memory with provenance, age, scope, and conflict warnings.
• Measure stale-memory rate, poisoning resistance, deletion correctness, latency, cost, and developer trust.

A practical reference architecture

Start with git-reviewed AGENTS.md or CLAUDE.md files for stable repo guidance. Treat them as operating notes, not enforcement. Keep policy enforcement in CI, tests, permissions, scanners, and review gates.

Add structured storage, often SQLite or a managed database, for task state, validated observations, user preferences, command outcomes, and correction history. Index ADRs, specs, code ownership, and PR discussions for retrieval, but preserve source links and timestamps. At session end, write a compact task snapshot that states what changed, what failed, what remains open, and what should be checked next.

The durable memory system should help the agent resume work without giving it unchecked authority. That is the core design principle: remember enough to avoid waste, but never so much that old, untrusted, or secret-bearing context becomes invisible infrastructure.