How it Works
brain update-truth atomically rewrites compiled_truth and appends a timeline entry.brain/ first and starts already caught up.↺ That next task is itself a new chat — which reads the brain and starts the loop again.
Why BRAIN.md
README.md is for humans.
AGENTS.md tells AI how to work in your repo.
Neither remembers why you decided things — that's what the brain holds:
the decisions you'd otherwise re-explain in every new chat.
A project brain stores decision-grade knowledge —
conclusions that have been reviewed, structured, and are authoritative enough
to guide downstream reasoning and code generation.
It lives in a brain/ folder and ships with your repo.
A single BRAIN.md at the project root is the
protocol entry point: any coding agent that reads it knows how to work with
the brain. No runtime service, no MCP server — just plain-file conventions
plus one zero-dependency CLI.
| File | Audience | Purpose |
|---|---|---|
| README.md | Humans | Quick start, contribution guide |
| AGENTS.md | AI coding agents | How to work on this codebase |
| BRAIN.md | Any coding agent | Protocol entry point — how to read & write the brain |
| brain/ | AI reasoning agents + humans | Decisions, tradeoffs, rationale — ready for downstream agents |
Structure
Six fixed root pages cover the project-wide views — background, architecture,
flow, mindmap, stack, and roadmap. They are only ever updated, never created,
and carry no timeline: their history lives in git. Lean on
mermaid diagrams to make them visual.
pages/*.md are granular, append-safe knowledge units
in one of five categories — decision,
concept, project,
person, reference.
Each tracks the current best understanding (compiled_truth)
and the full evidence chain (timeline).
Page Format
Every page in pages/ has two sections.
compiled_truth is
the current authoritative answer — rewrite it freely as understanding evolves.
The timeline is
append-only evidence. When a conclusion changes, update-truth
atomically rewrites compiled_truth and appends a
decision entry. The old truth stays in the record.
Timeline entry kinds: decision,
evidence,
reversal,
note. Rewriting a compiled_truth
and appending its decision entry happen in one
atomic write — you cannot do one without the other.
Cross-references use wiki-link syntax
[[page-id]]
where page-id matches the frontmatter id field exactly.
Run brain lint-links to confirm every link resolves.
Features
# zero runtime deps
$ npm i -g @mindmux/brain-md
lean CLI — plain Node, no deps
brain CLI has zero runtime dependencies — no service, no MCP server, no daemon. The brain itself is plain Markdown in your repo.↳ rewrites compiled_truth
↳ appends timeline entry
…in one atomic write
brain CLI. Mis-shaped frontmatter and trace-less truth rewrites are structurally impossible — so there is no validator to run.a3f1c4b decision: chose postgres
8d22e01 reversal: dropped redis
f90b3aa evidence: p99 spike
…
[[db-choice]]
[[auth-strategy]]
$ brain lint-links ✓
[[page-id]] syntax. IDs match frontmatter exactly, and lint-links confirms every reference resolves.Use PostgreSQL. ✓ reviewed
NOT a raw note dump
NOT a vector index
Authoritative decisions only
Pi · OpenCode
4 installable skills,
shared across agents
BRAIN.md. No vendor lock-in.Get Started
Install once, init a project — then keep coding. Your agent reads BRAIN.md, and every brain write goes through the brain CLI. You don't maintain the files by hand.
brain-bootstrap skill — not a shell command.Existing repo → drafts from code / docs /
git logEmpty project → interviews you
$ brain update-root architecture
$ brain create-page --id config-as-markdown --category decision …
✓ root pages + key decisions seeded
We chose Markdown for diff-ability and zero migrations. Here's the original call and the trade-offs we weighed…
FAQ
What is BRAIN.md?
BRAIN.md is a plain-file convention for storing project knowledge in a repository. It gives agents and humans a predictable place to find decisions, rationale, constraints, and current project context.
How is BRAIN.md different from README.md or AGENTS.md?
README.md usually explains how to understand or use a project. AGENTS.md usually tells coding agents how to work in the repository. BRAIN.md points to the project brain: structured knowledge about why decisions were made, what is currently true, and what context should guide future work.
How is BRAIN.md different from MCP?
MCP is a protocol integration layer for connecting tools and context providers to AI applications. BRAIN.md is not a runtime protocol. It is a repository-local Markdown convention plus a small CLI, so the project knowledge remains readable, reviewable, and versioned in git.
Why does it separate compiled_truth and timeline?
compiled_truth records the current best understanding of a topic. timeline records the evidence, decisions, reversals, and notes that led there. The split lets agents read the current answer quickly while preserving the reasoning history when they need to audit it.
Which agent platforms are supported?
Skills install into Claude Code, Codex, Cursor, Pi, and OpenCode. Any agent that can read files can use the brain via BRAIN.md.
Does setup or init install the Claude Code SessionStart hook?
No. brain setup and brain init do not write .claude/settings.json. After init, optionally run brain install-hooks in the project root. That is project-local only: a SessionStart hook injects a compact brain list-pages snapshot. Reverse with brain uninstall-hooks.