A thesis, not a product
Project memory is not another database for your coding agent. Your repository already is the project memory. AI just exposed the one thing it was systematically missing: why.
Read the argument One practice for the why layer: Keep the Why ↗
README, docs, tests, build scripts, changelog, license: one clone carries the repository-native knowledge of the project. Whoever has the clone has that knowledge — not every artifact a project ever produced, but the part that has to outlive any platform.
Plain text, an open version control system, no vendor between you and your files. That is why a repository from 2006 still opens today, and why one from today will open in 2046.
That used to mean people. Now it means the coding agents too, and the classic layout already covers most of what they need.
A repository is the one place a software project keeps the durable knowledge about itself, and it becomes memory to the degree its layout makes that knowledge findable — an entry point, a place for each kind, an index to load from. That layout has worked for decades, for people, without a platform. It works for coding agents for the same reason: plain files, next to the code, versioned by Git, readable by anything that can read a directory.
| Element | The question it answers | Who reads it | Who maintains it today |
|---|---|---|---|
README.md | What is this, should I care, how do I start | evaluators, new developers, agents on first contact | humans and agents |
docs/ | How do I configure, operate, troubleshoot | users, agents doing the work | humans and agents |
CHANGELOG.md | What changed, in which version | upgraders, reviewers, agents reconstructing the past | humans and agents |
CONTRIBUTING.md | How does a change get in, which conventions apply | contributors, agents about to change code | humans |
LICENSE, SECURITY.md, CODE_OF_CONDUCT.md | Under which terms, how to report, how to behave | everyone | humans |
tests/ | What the code is supposed to do, executably | developers, CI, agents checking their own work | humans and agents |
pyproject.toml, package.json, Cargo.toml, … | What this depends on, how it is built and published | build tools, agents setting up | humans and agents |
AGENTS.md, CLAUDE.md | Where an agent should look first, which conventions to follow | agents | humans, since 2025 |
| Git history | Who changed what, when, in which commit | everyone, if they dig | everyone, as a byproduct |
context/ | Why is it built this way, what was tried and rejected | anyone about to change something, human or agent | agents in the session where the reason surfaces, confirmed by people |
That is project memory, and it has been for a long time. Each row is a plain file or a Git object; each comes with the clone; each but the last answers what and how. Issues and pull request discussions sit next to it as hosted collaboration memory — valuable, searchable, platform-bound, and not in the clone. Knowledge that matters for understanding or changing the project in the long run has to find its way back from those discussions into the repository, into one of the rows above.
Because coding agents have a memory problem, and it is not the one people usually name. An agent remembers what is in its context window. A new session starts from nothing: the explanation you gave yesterday is gone, the question you settled gets asked again, the turn you ruled out gets proposed again. That is session memory, and many of the products now sold as "project memory" are a response to it. Take the memory an agent needs apart and it falls into three zones:
lives with you
Who you are, how you like to work, what you never want to see again. A global note, an Obsidian vault, a Markdown file the agents on your machine can read. Not a project's business.
lives in the world
What the world knows. An agent does not have to hold it; like you, it can look it up.
lives in the repository
What this project is, how it works, what changed — and why it is the way it is. The table above, nearly complete. Agents already maintain the README, the docs and the changelog, and use them without being told to. What they cannot find anywhere is the why.
Session memory remembers what happened. Project state remembers where the project is. The why layer preserves why it became what it is.
People had a mechanism for the why, for the few large decisions a year: Architecture Decision Records, written by hand, and most projects still have none. What was missing was an affordable mechanism for the hundred small reasons that actually make a codebase what it is — the retry loop that looks over-engineered, the flag a customer's proxy made necessary, the ordering constraint that looks safe to parallelize. Those lived in one person's head and left with that person, because writing each one down cost more than it seemed worth.
Agents change that cost. The reasoning is spoken out loud anyway, and an agent that is in the conversation can write it down as a byproduct: synthesized, short, in a fixed form, committed together with the code it explains. Sometimes there is only a reason and no code — a change started and abandoned once the reason not to became clear. That is the case that matters most, because nothing else, no diff, no commit, no PR, would ever record it. It is also the case that has been measured: twenty fresh agent sessions on the same codebase, asked to simplify the same retry wrapper — without a recorded reason, seven of ten offered the already-rejected simplification again; with one context/ entry, all ten found it and none did (the experiment, transcripts and grades).
So the missing layer is one more directory. It closes a natural gap instead of opening a new system: it lives where the rest already lives, is versioned by the same Git, travels with every clone and fork, shows up in the pull request beside the code diff where the reviewer needs it, and merges under the same review as the code. No extra layer to buy, no service to keep running, no account whose expiry takes the memory with it.
Repo-native project memory is not one tool. It is a model for how durable project knowledge is organized: the README, docs, tests, configuration and history hold the what and how; context/ holds the why; Git stores, versions, distributes and reviews all of it; the agent is the interface that captures and retrieves; Keep the Why is one convention and implementation for the why layer. Your repository already is your project memory — Keep the Why fills the layer it was missing.
stores · versions · distributes · reviews
Git, and the layout above. You already have it.
the interface: captures, retrieves, asks
Whichever coding agent you work with — any that reads a SKILL.md or an AGENTS.md.
integrates into the working session
Synthesizes what is worth keeping into context/ under clear rules, and asks before it writes when unsure. Instructions, in the open cross-agent skill format. Without it, or something like it, the layer stays empty.
checks and verifies the structure
Fields, values, index, nothing hidden. A small Python package, in CI or run by the agent after it writes. Nice to have the moment more than one person or agent writes.
shows it
The graph, an entry with its Git history, what still needs a person. A read-only page over the files and Git, local or exported. The day-to-day work runs through the agent.
That is it. Task fulfilled, no further complexity. Anything beyond it — project management, dashboards for teams, workflows — can be built on top, and for a company that may be the right call. Open source should not have to depend on it. A project that drops every part except the repository loses nothing: the directory is still Markdown, still in Git, still readable.
This page and Keep the Why are by the same person, and the tool came first: it started as decision records for agents, and the broader view here is what building it taught. Read the thesis as the claim and the tool as one way to act on it — the claim holds with or without that implementation, and it would hold for another one.
Those manage work. This remembers why the code is what it is.
They lower the cost of writing things down; people still decide what is true.
The thesis is a diagnosis and a convention. It is not the whole solution, and four things are weaker than the headline sounds.
A repository holds knowledge; it is memory only to the degree the layout makes it findable. For people the layout does that. For agents it does too, at the scale of a lean index and a few dozen topic files. At hundreds of entries, "what do I need to know about this subsystem right now" is a retrieval problem, and search over the files — full-text, an index, embeddings — becomes worth having. Repo-native and good search do not exclude each other; "no database" is a claim about where the knowledge lives, not a search strategy.
The layer stays empty without an agent that fills it, and activation is not guaranteed. context/ is not an established convention yet, so an agent has to be told about it; whether it then loads the instruction depends on the platform. Where that fails, the result is the old ADR failure: a good schema and an empty directory. That is exactly what the skill is for, and with it the layer does fill: the one implementation linked here measures its activation per release and per agent and publishes the misses — in the last measured series every session on a project that had opted in loaded it. Anyone adopting the layer with another tool should measure the same thing.
Structure can be checked; truth cannot. A linter verifies fields, values and the index. It cannot tell a right reason from a confidently wrong one, and a wrong why that the next agent treats as fact is worse than none. That is why an entry carries how well its origin is known (confirmed, inferred, unknown), why writes can require a person's yes, and why "unknown" is a legal answer — the convention takes what can honestly be done with today's means and does not pretend to more. It still only helps if someone reads. Who confirms, who marks an entry superseded, who resolves a contradiction is work the convention names and does not remove. Extra Markdown in a pull request can be skimmed exactly like an ADR.
Much of the why never reaches the repository. In real teams it lives in chat, tickets, wikis and heads. "Write it back" is the right rule and a process problem, not a file-format one; the convention makes the destination cheap to reach and gives an agent that is in the conversation a place to put what it heard. It does not reach the conversations the agent was not part of.
This is a documentation discipline with an agent as the writing hand, not a memory subsystem. It wins on ownership, review and longevity. It loses where activation fails, where nobody reads, where the repository is large, and for the knowledge that never gets written down. Read it as a thesis plus a convention, not as "the memory problem is solved."
None of this is a discovery. That the reasoning behind design decisions gets lost, and that writing it down costs more at the time than it visibly returns, has been studied in software engineering for decades — the design-rationale literature, and the architecture community's name for the loss, knowledge vaporization (Jansen and Bosch, 2005). Architecture Decision Records (Nygard, 2011; adr.github.io) are the practical answer for the few large decisions, and research keeps finding the same gap below them: rationale that is obsolete or missing because of the imbalance between the cost of documenting it and its value to the person writing it (arXiv:2405.19623). Recent work on AI-assisted engineering adds the other half of the problem: decisions are now produced faster than teams can validate them, and something has to distinguish conjecture from verified knowledge (arXiv:2601.21116).
What this page adds is small and specific. AI did not create the need for the why; it changed the economics of capturing it, because the reasoning is now spoken in the working session anyway — and the result has a natural home, a row in the repository next to the others.
Disagree, or see a layer this page misses? The place for that is the repository's Discussions — arguments about the thesis, experiences from your own repositories, other conventions for the why layer. Corrections to the text are pull requests.