A brain and a file
Both are just text
an agent reads.
The difference is not format. It is what happens to them over the next three months, while you are busy.
Five questions, answered twice
Where does it live?
A file in your repository, on your disk.
On the server, read over MCP as the agent works.
What happens when the source changes?
Nothing. Someone has to notice and rewrite it.
The pages behind it are re-read every six hours by content hash. What changed is replaced; what did not costs one request.
How big can it get?
As big as the context you are willing to spend on it, every call.
Our largest brain holds nearly seven hundred notes. The agent searches and takes the five it needs.
Do you know what it does not know?
No. It answers with whatever it happens to contain.
Its goal becomes an exam. The score names the categories it cannot answer, and the agent is told the gaps before it searches.
What happens when someone learns something new?
They edit their copy. Yours stays as it was.
An agent writes it back, the owner approves it, and every agent has it.
When a file is the right answer
Often. A brain is a service, and a service is a dependency.
It never changes
Your commit conventions, your directory layout, the three rules everyone breaks. Written once, true for years. Re-reading a source that has no source is machinery for nothing.
You work offline
A brain needs the network and an account. A file needs neither, and on a plane that is the whole argument.
It is three paragraphs
Search earns its keep somewhere past a hundred notes. Below that, putting the whole thing in context is simpler and cheaper.
Any brain exports to CLAUDE.md, a Skill or AGENTS.md — take the snapshot and go.
Use both.
A file for what you decided and will not revisit. A brain for anything with a source that keeps moving — an SDK, an API, a design system, a platform someone else maintains.