Everything goes in the repo. This is true for engineers, and it is doubly true for coding agents.
Personally, I learned that by working with a team of engineers. Instead of pawing through various shared drives and websites to find a critical piece of information, you just paw through the repo. Whatever isn't in there is hard to find, and over time it stops getting used.
The same is true for agents, only more so. An agent starts every run from nothing. It doesn't remember the last session, it rebuilds what it knows from whatever it can read, and what it can read is the repo. You can give it MCPs to search everywhere else, but it really just relies on the repo. They're kind of lazy that way. If it is in a shared folder, it is effectively invisible to the AI.
But we don't keep our tickets in the repo, do we?
This is because there are really two classes of memory: the assets that form the living context, and the items that reflect the workflow state. They serve different purposes.
The living context is the docs, specs, decisions, and even the code itself. This is soft and mutable, because we (and the agents) learn as we build and as requirements evolve. It reflects our ambiguous work reality, messy as that often is. So I let it move. After a release I'll have the agent reread the docs, compare them to what we know now, and fix what's stale. An agent keeping its own notes current is a feature to embrace, not a bug to block.
The trick with the soft side is what the agent reads, not how much. I don't hand it the whole repo. I keep short CLAUDE.md files in the right places, and they point to the fuller docs it can open when it needs them. It pulls what the task in front of it actually requires and leaves the rest. Most of the work is deciding what gets into the window.
But the workflow state is hard: it shows what's done, what's blocked, and what's next. I learned the hard way that this does not belong in Markdown files in the repo, where the agents can quietly change things. An agent will tidy a list, mark something done that isn't, move a dependency around, and mean well doing it. Your plan drifts because the edits are lost in a sea of changes, and you don't catch it until nothing lines up.
So I moved this out-of-band, into a small store with a defined schema, accessed through agent tools that provide and enforce an interface. The agent can still change the state, but only through that interface, and the interface holds the shape. In the repo's code, the agents are unconstrained. In the workflow state, they obey the rules.
Most of what I see goes all the way one way or the other. Either nothing is held down and the state rots, or everything is held down and the agent fights the format while you reformat all day. The two kinds of memory aren't the same thing, so one rule for both was never going to work.
Let the agent loose where the assets need to drift to match a soft reality driven by externalities. Lock it down where we impose order because reality is ours to define.
The repo is the memory. Decide, on purpose, which half the agent is allowed to rewrite.
The framework behind this: Trust Topology →