Memory Bank: Persistent Memory of an AI Agent for a Project
An AI agent has no memory between sessions. Every new chat starts from a blank page: it knows the language, knows the framework, knows "best practices in general" — but it doesn't know your project. Why you chose PostgreSQL and not Kafka for that queue. How you name your endpoints. That an order can't be paid twice. The agent learned all of this in the previous session — and forgot it the moment you closed the chat.
It's like bringing a new developer into the team every morning. Technically strong, but with zero context about what's already been decided here. On day one they won't do anything wrong — they simply don't know "how it's done here," so they'll do it "the industry average way." A month of such days and your code drifts apart in style.
What a Memory Bank Is
A Memory Bank is persistent project context that lives right in the repository as markdown files, and that the agent reads first thing in every new session. Usually it's a CLAUDE.md at the root plus a few referenced files next to the code.
The memory lives in git alongside the code. Code changes — memory updates, and both ride in one commit. The agent doesn't "recall" a past conversation — it re-reads the current state from the files. That's why the memory survives closing a chat, switching the model, and a new person joining the team: it's in the repository, not in someone's head or in the history of a single dialog.
What to Put In It
A Memory Bank is not a retelling of the code (the agent will read the code anyway). It's what isn't visible from the code:
- Decisions and their reasons. What was decided once and why: "idempotency is stored in Redis with a 24-hour TTL," "we avoid distributed transactions and use Saga + Outbox." Without this the agent re-invents the choice every time — and differently each time.
- Project structure and stack. Which services exist, what each is responsible for, who the neighbors are, the maturity level, which libraries are "ours" in this project.
- Agreements. Conventions that aren't enforced automatically anywhere: naming, layer boundaries, what's allowed and what isn't.
- Links to the spec. A pointer to the source of truth about the domain — so the agent goes and reads the contract instead of guessing.
The key difference from ordinary documentation: documentation is written for people and explains the system "in general." A Memory Bank is written for the AI — it's working context the agent loads to make decisions in your style, not the average one. People can read it too, but the target reader is the agent.
Where It Sits in the Methodology
A Memory Bank on its own is only one layer. It gives the agent a history of decisions, but it doesn't give the structure by which those decisions can be checked. Without a machine-checkable spec the memory stays a set of notes from which a linter — AI or otherwise — can extract nothing.
For the deep dive — how the Memory Bank is built into the methodology (Layer 2), why it's useless without the structure of a spec, and how it works together with an executable standard (rules the agent applies on every PR) and the structure of a task spec — see AI writes the code. So why bother with a methodology?. I don't retell that logic here — I point to it.
Two more things sit alongside it. MCP gives the agent "hands" — access to files, databases, and APIs; the Memory Bank gives it the "memory" of how to use those hands in your particular project. And the source of truth about the domain that the memory links to is a task spec: the structure by which the agent checks instead of guessing.
In Short
A Memory Bank turns the agent from a perpetual newcomer into an old-timer familiar with the project's history. It lives in the repository, updates together with the code, and is read at the start of every session. But it only works on top of structure: memory answers "what we decided," the spec answers "against what to check it." One without the other is half the job.