What is a brain repo?
One business role kept as a folder that an AI agent can open and act from.
Definition
brain repo (n.) – a single business role kept as a folder containing the craft it needs, the memory of what it has already learned, the playbooks it executes, and the log of why it works the way it does.
A brain repo is a role written down as files instead of held in a person: repo is short for repository, the versioned folder the role lives in. A role is normally stored in a person. Ask what the marketing role knows and the answer is whatever the person doing it can recall that afternoon. A brain repo moves that store into files. The craft documents hold the standing knowledge, the playbooks hold the repeatable procedures, the memory holds what has been learned since, and the log holds the reasoning behind the calls that were made.
The test of a brain repo is not how much is in it. It is whether an agent with no prior context can open the folder and act correctly from what it finds. A folder that only makes sense to the person who wrote it has failed, and the failure belongs to the folder rather than to the reader.
Brain repos are built one at a time. A second role is not started until the first is reliable, because correctness gates are what scale, and copying a role that is only sometimes right multiplies the wrong thing.
The word brain is doing narrow work here. It does not mean the folder thinks. It means the folder holds what the role knows, which is the part that used to leave when a person did.
Brain repo meaning, with an example
The name is two plain words. Brain is what the role knows. Repo is where that knowledge is kept: a folder under version control, so every change to it has a date and a reason. Together they name the unit that company as code is built from: one role, one folder.
A hypothetical: say the bookkeeping role lives in one person who closes the books each month from memory. As a brain repo, it becomes a folder. The craft document states the standards the books are held to. A playbook holds the month-end close, written during a real close rather than afterward, with a verify step after each action. The memory file records what has been learned since, such as an account that posts late. The why-log records why the close runs in the order it does.
The check is the same as for any brain repo: an agent with no prior context opens the folder and runs the close. Every point where it stops or guesses is a gap in the folder, fixed in the folder. The failure mode carries over too: a folder that passes this check once and is never amended drifts from the work it describes.
“You're like, 'Do you have an army of people behind you somewhere?' And he's like, 'Nope.'”
What goes in one
Four things, and the split matters more than the naming. Craft documents: how this role does its work well, written as standards rather than as instructions for a single task. Playbooks: the procedures the role runs, each one written so a stranger could execute it. Memory: what has been learned since the folder was created, appended rather than rewritten. A why-log: the decisions and the reasoning behind them.
What does not go in one is credentials. A brain repo references the accounts it needs and never contains the keys to them.
The failure it prevents
Knowledge held in a person has a half-life measured in employment. Every departure resets some part of the company to zero, and the reset is invisible until somebody needs the thing that left. Teams respond by hiring for continuity, which is expensive, or by writing documentation nobody maintains, which decays quietly.
A brain repo is not a better wiki. A wiki is read by people who already know most of it. A brain repo is executed by something with no memory of yesterday, which means the gaps get found immediately rather than at the worst moment.
Where it goes wrong
The common failure is a folder that documents the happy path only. A procedure written from memory after a good day omits the parts where the author hesitated, and those are exactly the parts an agent will get wrong. The fix is to write the document during a real run rather than afterward.
The second failure is a folder that grows without being read. If nothing has been deleted from a brain repo in months, it is probably accumulating rather than improving.