brain.md: a Markdown memory layer your coding agents read through one CLI

The problem brain.md addresses: decisions that die with the session

A coding agent's reasoning does not survive the context window. The README states the case plainly: the reasons behind a decision, the constraints agreed on, the path not taken, sit in chat logs and in your head and vanish when the session ends, so the next agent starts from zero. brain.md is aimed at that gap rather than at code generation. It is for teams and individuals who run Claude Code, Codex, Cursor or Pi against the same repository over weeks and keep re-explaining the same architectural choices to a fresh context. The repository is explicit that it is the toolkit, not a brain itself: you install it once, then run brain init per project. The inclusion test the README gives is narrow on purpose. Will this still matter in six months, and is it hard to reconstruct from the code itself? Implementation details and anything readable from code and git history are supposed to stay out. That filter is what separates this from dumping session transcripts into a folder.

BRAIN.md as the contract, and the brain directory as the payload

The mechanism is deliberately unexotic. brain init scaffolds a BRAIN.md protocol file, creates a brain/ directory, and wires agent config files into your repository. BRAIN.md is the contract: the README says any agent that can read it can use the brain, which is why the project calls itself agent-agnostic. The brain itself is plain Markdown that travels in git. Pages carry two distinct structures. A compiled_truth field holds the current best understanding and is rewritable. A timeline is append-only and records the chain of evidence. That split is the most interesting design decision in the repository, because it lets a page change its mind without erasing the record of why. The CLI exposes it directly: brain update-truth --id my-decision --summary "why it changed" rewrites the compiled truth, while brain append-timeline --id my-decision --kind evidence --summary "benchmark confirmed it" adds to the record. The README claims writes are correct by construction because they all pass through the CLI, and states there is no validator because none is needed. Treat that as a claim about the write path, not about content quality. A malformed argument can still be rejected; a well-formed but wrong decision cannot.

Installing the CLI and initializing a project

The README gives two installation routes. The global one puts brain on your PATH and copies skills into detected agent directories such as ~/.claude/skills. npm install -g @mindmux/brain-md followed by brain setup -y. Reversal is brain uninstall, which the README says never touches any project's brain data. If you would rather not install globally, both steps run through npx, with the caveat that npx does not leave brain on your PATH, so the second command must be the full package invocation rather than bare brain init: npx @mindmux/brain-md setup -y then npx @mindmux/brain-md init. From a git checkout of the repository, ./setup runs the same installer and accepts --symlink while developing the toolkit. Per-project initialization is brain init from the project root. It ensures BRAIN.md exists, scaffolds empty brain data, and default-wires CLAUDE.md and AGENTS.md. The wiring behavior is worth noting: the files are created if missing, and if they already exist only the marked brain block is updated, never the whole file. Optional additions are the brain-setup skill for the same flow plus a pre-commit hook, brain install-hooks for a project-local Claude Code SessionStart snapshot, and brain install-hooks --agent codex for a Codex startup, resume and compaction snapshot. The README also shows a shell function for running the CLI straight from the checkout: brain() { node skills/brain-page/bin/brain.mjs "$@"; }.

What daily use actually looks like, and where it breaks down

The README's own walkthrough is the honest picture. An agent decides to store config as Markdown rather than SQLite, and captures it with brain create-page --id config-as-markdown --category decision --title "Store config as Markdown, not SQLite". Three weeks and a fresh session later, a question about the database is answered by brain read-page config-as-markdown, which returns the original call and the trade-offs weighed. Nothing in that flow is automatic. The agent has to choose to write, and the README instructs agents to load relevant pages at task start, capture decisions when they settle, skip implementation noise, and reverse when overturning, all through the CLI rather than hand-editing. That is the failure mode to plan for: a brain is only as good as its write discipline, and a project where nobody runs create-page accumulates an empty directory. The README does not describe a mechanism that detects a missing or stale page, and it does not publish accuracy or retrieval benchmarks, so there is no evidence here about how reliably an agent finds the right page at the right time. The seeding step is also manual by design. brain init leaves content seeding as a deliberate next step, handled by the brain-bootstrap skill, which reads code, docs and git log to draft root pages on an existing project, or interviews you on a near-empty one. Until that runs, the brain is scaffolding.

How this differs from CLAUDE.md, AGENTS.md or a docs folder

The obvious alternative is the file you already have: a CLAUDE.md or AGENTS.md that agents read at startup. brain.md does not replace those. brain init wires them, which tells you the intended relationship. Those files are the entry point; the brain is the store behind it. A second alternative is a conventional docs/ directory or an ADR folder. The difference is in the write path and the page shape. An ADR is a document a human writes and edits, and revising one usually means rewriting history or adding a superseding file. A brain page instead separates a rewritable compiled_truth from an append-only timeline, and the CLI enforces that separation. The cost is a layer of tooling between you and your Markdown: the README says never hand-edit brain files. If your team's instinct is to open the file and fix a typo, that instinct now conflicts with the project's model. The other structural difference is portability. Because the contract is a file and the payload is Markdown in the repository, the same brain is readable by Claude Code, Codex, Cursor or Pi without a per-vendor integration. A hosted memory service would give you retrieval you did not have to maintain, and it would also put your project's decisions behind an account and a network call. brain.md chooses the opposite trade.

Licence, maintenance and the cost of keeping a brain alive

The repository is Apache-2.0. That permits commercial and private use and includes an explicit patent grant, with the usual obligations around preserving notices and stating changes. This is a description of the licence text, not legal advice; if you redistribute the CLI or embed it, read the licence yourself. On maintenance, the material shows a short and recent history: v0.1.0 on 2026-08-11, v0.2.0 on 2026-08-13, and a last push on 2026-09-09. Two releases and a single month of activity is not a track record, and nothing here establishes a support commitment or a deprecation policy. The technical surface is small, which works in your favor: the CLI is zero-dependency Node run with node, and the stored artifact is Markdown in your own git repository. If the project stalls, you keep the data in a readable form. The recurring cost is not the install, it is the upkeep. Every durable decision needs a create-page call, every overturned decision needs update-truth, and the README's own instruction to maintain the brain while coding means this is a habit, not a one-time setup. Plan for someone owning that habit, and expect to run brain list-pages and brain lint-links periodically to catch pages that drifted or links that broke.

Who should adopt brain.md, and what to check first

Adopt it if you run multiple coding agents against one repository and the same questions keep coming back, and if you accept that the brain is maintained by hand through a CLI. The zero-dependency install and the plain-Markdown payload make the downside small: worst case you have a directory of Markdown in git. Do not adopt it if you expect memory to be captured without agent cooperation, or if you want retrieval that works over a large corpus without someone curating pages. The README gives no retrieval benchmarks and no accuracy claims, so an uncurated brain is just an unread folder. Two things are worth verifying on a scratch branch before you commit. First, run brain init on a project that already has CLAUDE.md and AGENTS.md and inspect the diff, to confirm for yourself that only the marked brain block changes. Second, confirm the CLI resolves in your environment, either as the global brain bin after npm install -g @mindmux/brain-md or via node ~/.claude/skills/brain-page/bin/brain.mjs, since the README notes that npx leaves nothing on your PATH. If both hold, the remaining question is not technical. It is whether you will run brain create-page the next time a decision settles.

Editorial conclusion

Adopt brain.md if your agents lose decisions between sessions and you are willing to run brain create-page and brain update-truth as part of normal work; skip it if you want memory captured automatically with no agent cooperation, since nothing in the README claims writes happen without the CLI. Before committing, run brain init on a scratch branch and confirm the CLAUDE.md and AGENTS.md wiring only touches the marked brain block, then check that node ~/.claude/skills/brain-page/bin/brain.mjs resolves under your Node version.

Official sources

1. License: Apache-2.0
2. mindmuxai/brain.md on GitHub
3. Project website
4. README
5. Releases