Storing the decisions you make — and the reasoning behind each one — somewhere that still exists tomorrow and that any AI tool can read.
The idea that outlives the tools
What does not persist does not exist. And if it persists only inside one tool, it still does not.
The model provides no durable project memory. Your harness may well keep session history — transcripts to resume, branch, summarise — but a transcript is a record of one conversation, not a record of what the project decided, and it belongs to that product. What has to survive sessions, tools and people needs a persistence layer you chose. Without one, none of what you worked out becomes something the next session can act on: it did not forget, it never had it. All that remains is the code, and code tells you what you did, not why you chose it over the alternative.
That why is the expensive part. It is the two hours of argument, the approach you tried that failed, the client constraint written down nowhere. Reconstructing it costs more than rewriting the code.
And there is a second half almost nobody looks at: the memory has to be yours, not the tool's. If your decisions live inside a product that only speaks to one agent, the day you switch agents you start from zero. And you will switch — you switched at least once in the last year. A memory layer exposed over an open protocol can be read by any agent, this one and the next one.
The rule for what to store is simple: store what cannot be deduced by reading the repository. That you use pnpm is deducible. That you rejected a library because the infra team will not approve it is not.
How it works, stage by stage
That was the why. This is the machine: what happens at each stage and, above all, which decision is yours at each one. If there is a stage where you decide nothing, that stage is being decided for you by the tool.
01
Capture
What happens
Something triggers a save: an argument closed, a bug fixed, a convention agreed. The trigger can be you writing it down, or the agent noticing that a decision was made.
What you decide
What counts as a trigger. Save on every message and memory turns into noise; save only when you remember to, and nothing ever gets saved.
02
Shape
What happens
Every memory is written to the same structure: what was done, why, which files it touches, and what surprised you. With no structure there is nothing to filter on later.
What you decide
The test for what goes in: whatever cannot be deduced by reading the repository. That they use pnpm can be deduced. That they rejected a library because infrastructure will not approve it, cannot.
03
Index
What happens
What is stored gets indexed by project, by date and by topic — and almost always by meaning too, as a vector, so it can be searched by what you meant rather than the exact words you used.
What you decide
The topics. A stable topic like `architecture/auth` makes today's decision update March's instead of sitting beside it and quietly contradicting it.
04
Retrieval
What happens
A query mixes three signals: semantic similarity, recency, and topic match. A handful comes back, not everything. Fifty retrieved memories are as useless as none.
What you decide
How many, and how far back. This is the dial that decides whether memory helps or buries the request you just typed.
05
Injection
What happens
The chosen memories enter the window as plain text, ahead of your message, and take up room like anything else. This is the part almost nobody looks at: memory is not free, it is paid for in context.
What you decide
The budget. If memory eats a third of the window, the agent starts every task with less room for the actual problem.
06
Review
What happens
A memory can quietly become false. Serious systems give it a state — current, needs review — and that state travels with the memory every time it is retrieved.
What you decide
Confirming or discarding. Nobody else can: the agent has no way of knowing whether that client constraint still holds.
Signs you are missing it
You open a session by pasting a summary of what you were doing.
The agent proposes something you already tried and abandoned.
Someone asks “why is this built this way?” and nobody knows.
You switched AI tools and it felt like starting over.
Common mistakes covering it
Storing the what without the why. A decision without its reasoning reverses itself within three weeks.
Storing everything. A memory full of noise is a memory nobody consults.
Letting memory age without review. A stale memory that is now false is worse than none.
Confusing it with the instructions file. Instructions are standing rules; memory is history.
None of them is mandatory. Covering the discipline is mandatory; these are known ways of doing it.
Engram
Gentleman ProgrammingService
Persistent memory for coding agents, with search, typed observations, and conflict detection between memories.
Problem, mechanism & fit
The actual pain
Yesterday's architecture decision evaporated when you closed the terminal, and tomorrow the agent will propose the option you already rejected.
How it works
Stores typed observations — decisions, fixed bugs, conventions, discoveries — scoped to a project, and exposes them over an open protocol so any agent can search them. When a new memory contradicts an old one it flags it instead of silently overwriting.
When it fits
When a project runs for months and decisions matter more than code. Conflict detection is what separates it from a notes file: a stale memory that is now false does more damage than none at all.
gbrain
Garry TanService
A Markdown knowledge base with hybrid search, an entity graph, and synthesised answers with citations.
Problem, mechanism & fit
The actual pain
Most note systems hand back a list of pages. You do not want pages: you want the answer, and you want to know what is missing.
How it works
Syncs Markdown repositories into a database with vector search. It combines semantic and keyword search with reranking, builds an entity graph with typed relations, and synthesises answers that cite their sources — including what it could not find.
When it fits
When the knowledge you need is not in the code: business context, people, decisions, research. To know what exists in the repository, a code index is the right tool.
claude-mem
Alex NewmanService
Memory that captures observations by itself, unprompted, and re-injects them at session start.
Problem, mechanism & fit
The actual pain
A memory that depends on the agent remembering to save is a memory that will forget to save.
How it works
A trigger records compressed observations after every action — bugs, decisions, discoveries — into a local database with semantic search. At session start, another trigger injects a project summary without the model having to ask.
When it fits
When you want passive capture and zero friction. The price is control: you capture everything, noise included. Explicit capture costs discipline but yields cleaner memories.
Also helps with
MCP
Anthropic, open standardProtocol
Capability
An open protocol connecting any agent to external tools, data and services.