You spend an afternoon with a coding agent settling something real. Why Markdown over SQLite. Why option B is out. What "done" means for this version. The reasoning is good, the trade-offs are weighed, the call is made.
Then the session ends.
Open a fresh one tomorrow — or switch machines, or move from Claude Code to Codex — and the agent asks the same questions again. What does this project do? Why not B? Didn't we already decide this? The model isn't weak. It just never had anywhere durable to put the conclusion. The work survives as code; the why behind it evaporates into a chat log nobody reopens.
So we built a small standard for the missing piece, and we're open-sourcing it: brain.md.
What it is
brain.md gives a project a brain — its durable decisions, requirements, and constraints, written down as plain Markdown that lives in the repo and outlives every session.
Two things ship in the box:
-
A contract — a single
BRAIN.mdfile at the project root that tells any coding agent how the brain works. An agent learns to use it just by reading that file. -
A toolkit — a small
brainCLI plus a few install-once skills that scaffold and maintain the brain.
The brain itself is just Markdown files in your repo — nothing to stand up before you start. It grew out of MindMux, our project-brain workbench, which drives a brain through MCP and a lot more. brain.md is the open layer underneath: the format and the contract, so any agent that can read a file can use one — with MindMux, or with nothing but your editor and a terminal.
What a brain actually looks like
It's a brain/ directory of Markdown, and it has two kinds of file.
Root pages — a fixed set of six, the project at a glance: background, architecture, flow, mindmap, stack, roadmap. These you only ever update.
Pages — one durable unit of knowledge each: a decision, a concept, a person, a reference. You create them as you go. There's no limit and no ceremony.
The part that makes a page more than a note is its shape. Every page carries two layers:
-
compiled_truth— the current best understanding, rewritable as a whole. -
timeline— an append-only trail of how that understanding got there.
One layer keeps you moving. The other lets you trace your way back. When you overturn a past call, you don't quietly edit history — you append a reversal to the timeline, and the change of mind stays on the record.
The design bet: files plus a CLI
None of this is a new idea on its own. AGENTS.md and CLAUDE.md already let you hand an agent standing instructions. brain.md's bet is narrower and, I think, more useful: make the memory structured, and make it correct by construction.
Here's the mechanism. Reads and writes both go through the brain CLI — you never hand-edit a brain file. That sounds like a limitation; it's the whole point. Because the CLI is the only writer:
- Frontmatter is always generated, so it can't drift into an invalid shape.
- Rewriting
compiled_truthand appending itstimelineentry happen in one atomic write — so the understanding can never change without leaving a trace.
That second property is the one that matters. The most common way a knowledge base rots is a silent edit: someone changes the conclusion and the reasoning behind it is lost. Route every write through one command and that failure mode is structurally impossible. There's no validator in brain.md because there's nothing left for a validator to catch.
What's actually different
If you've reached for adjacent tools, here's the honest contrast.
-
vs. a flat
CLAUDE.md/ rules file — those are great for instructions, but they're one growing blob you maintain by hand. A brain is structured, addressable knowledge with a built-in audit trail. Different job. -
vs. memory that lives inside a tool — a vector store, a model's own memory, a hosted service: those are runtimes over your knowledge. A brain is the substrate itself — plain files in git, diffable in a PR, readable by a human, an agent, or
grep. Put a runtime on top of it (MindMux does, over MCP; more can) and the knowledge still belongs to the repo, not the tool. - vs. saving chat history — chat history is the process. A brain is the conclusion. You don't want every raw sentence back; you want the handful of judgments you'll need again.
It's also not locked to one model or one tool. The contract is a file, so the same brain works across Claude Code, Codex, and whatever you use next.
See it work
Install the tools once:
./setup # links the skills into every agent you choose (~/.claude, ~/.codex, …)
Then, in any project, the agent scaffolds and seeds a brain (brain-setup, then brain-bootstrap), and from there it just works. The payoff shows up across sessions:
You Let's store config as Markdown, not SQLite — easier to diff and migrate.
Agent Capturing that as a decision so it outlives this session.
$ brain create-page --id config-as-markdown --category decision \
--title "Store config as Markdown, not SQLite"
✓ page created · indexed
— three weeks and a fresh session later —
You Why aren't we using a database for config?
Agent $ brain read-page config-as-markdown
We chose Markdown for diff-ability and zero migrations. Here's the original
call and the trade-offs we weighed …
No re-explaining. The next conversation starts from what you already settled.
Try it
A brain is memory for the project, not for the model. Plug in a different agent next month and the thing that stays is the brain.
If that's a problem you have, it takes about five minutes to feel:
- Repo: github.com/mindmuxai/brain.md
- Standard: projectbrain.md
- Works with Claude Code and Codex today. Apache-2.0. Issues and PRs welcome.
If the first thing you notice is "I didn't have to explain all of this again," it's working. That's why we built it.
Originally published on MindMux Blog.
Top comments (1)
The single-writer CLI is the move most people will underrate. compiled_truth plus an append-only timeline, written atomically through one command, is the cleanest answer I have seen to the silent-edit failure: the conclusion cannot change without leaving the reason it changed, and that beats a validator every time.
Where I would push: a session leaves behind two things with opposite lifecycles, not one. There is the settled conclusion, which is your sweet spot and which the CLI guards well, and there is the open loop, what is still undecided, what changed since last session, what the next step is. The open loop has no compiled_truth to rewrite because it is the unfinished part, and it is the thing I watch rot first, since it goes stale the moment you stop updating it. A guarded single write fits the decided half; the volatile half wants to be cheap to rewrite every time you close a task, which is more a write-back habit than a protected write.
That second layer is what I build for Claude Cowork as cowork-os: same plain-Markdown-in-the-repo DNA, but focused on operating state, open questions, diff-since-last-session, next step, plus a Memory Update step at the end of each task, sitting alongside a decision substrate like yours rather than replacing it. MIT, and a star helps if it is useful.
Does a brain have a place for the not-yet-settled, an open-question or current-status page, or is it only for knowledge that has already reached a compiled_truth?