brain.md: a Markdown brain where update-truth rewrites the truth and keeps the trace

brain init deliberately hands you an empty brain

Initializing a project is a scaffolding step and nothing more. `brain init` ensures `BRAIN.md` exists, scaffolds empty brain data in a brainRoot-aware way, and default-wires `CLAUDE.md` and `AGENTS.md`. The wiring rule is the careful part: if those two files already exist, only the marked brain block inside them is updated, never the whole file. Seeding is left as a deliberate next step, and it is done by the brain-bootstrap skill, which on an existing project reads the code, the docs and `git log` to draft the root pages and capture key decisions, and on a near-empty project interviews you instead. So the first run of this tool produces structure and wiring, and a second pass through a skill produces content. Anyone expecting `brain init` to arrive with a populated brain has misread the step order.

The npx route cannot use bare brain init, and the README says so

The global install is two commands:

npm install -g @mindmux/brain-md
brain setup -y
# reverse: brain uninstall   # never touches any project's brain data

`brain setup -y` puts `brain` on the PATH and copies skills into every detected agent directory, `~/.claude/skills` and the rest. The npx alternative has a trap the documentation calls out in the command itself: npx does not leave `brain` on your PATH, so both steps have to go through the package name, which is why the second command is `npx @mindmux/brain-md init` rather than bare `brain init`. A third route exists for working from a checkout, where `./setup` runs the same installer and accepts `--symlink` while developing the toolkit. There is also a direct path into the script for setups without a global binary, `node ~/.claude/skills/brain-page/bin/brain.mjs init`, which is the shape the shell function in the CLI section wraps.

compiled_truth is rewritable, the timeline is not

The page model is two fields and the asymmetry between them is the design. A page carries a `compiled_truth`, the current best understanding, which gets rewritten, and a `timeline`, an append-only chain of evidence, which does not. `update-truth` rewrites the truth and appends its timeline entry in one atomic write, so the understanding can never change without leaving a trace. That is what makes the later question, why are we not using a database for config, answerable weeks later with the original call and the trade-offs that were weighed. The documented commands show the shape of a write:

brain create-page --id config-as-markdown --category decision \
      --title "Store config as Markdown, not SQLite"

and the matching read is `brain read-page config-as-markdown`. The six-month claim in the walkthrough is a narrative device rather than a measurement, but the underlying promise, that a reversed decision is still legible, is a property of the data structure.

Correct by construction, with no validator because none is needed

One of the three claims in favour of the design is that every write goes through the `brain` CLI, so the brain's invariants cannot be broken by a malformed edit, and the stated conclusion is that there is no validator because none is needed. The guarantee is real but narrower than it reads, and the documentation itself shows where the boundary is. The working instructions say all reads and writes go through the CLI following `BRAIN.md`, never hand-edit brain files. That last clause is a policy, not a mechanism: nothing stops an editor from writing the file, and the append-only timeline is only append-only for writes that take the documented path. What the CLI guarantee buys is that a well-formed command cannot produce a half-written page, since truth and timeline move together.

The admission test is six months and hard to reconstruct

The rule for what belongs in the brain is stated as a two-part test: will this still matter in six months, and is it hard to reconstruct from the code itself? If both answers are yes, it goes in. Pure implementation details, and anything readable straight from the code and git history, stay where they are. That test is doing the work that a curation policy normally does, and it is stricter than a general notes file because the second clause excludes anything the repository already records. The maintenance loop around it has four moves: load the relevant pages at the start of a task, capture decisions and constraints when they settle rather than when they are proposed, skip implementation noise, and reverse a page when you overturn it. Reversal is a first-class operation here, which is a different default from appending a correction and leaving the wrong claim standing.

The Codex hook needs CLI 0.153.4, Node 18, awk and a POSIX shell

Hook installation is opt-in and takes an agent flag. `brain install-hooks --agent codex`, run from the project root, installs `.codex/hooks/brain-session-start` and merges one `SessionStart` command into `.codex/hooks.json`; `brain uninstall-hooks --agent codex` removes it. With no flag the target is Claude Code, and `--agent claude-code` is also accepted. The requirements are stated tightly: Codex CLI 0.153.4 or newer is the supported baseline and older releases have not been validated, Node 18 plus a POSIX shell with `awk` must be available, and native Windows shells are not supported, so the integration is macOS and Linux only. The hook finds the CLI in installed skill directories or on the PATH, with `BRAIN_CLI` able to point at an absolute `.mjs` path. Hooks must be enabled through `features.hooks`, which this release turns on by default, and the installer deliberately leaves global configuration, `config.toml` and trust settings alone. Malformed settings or a foreign script already at the destination produce a failure the visible text does not finish describing.

Four skills ship in the package, one is never named

The npm manifest publishes four skills: `skills/brain-page/` with its SKILL.md, bin and lib directories, plus `skills/brain-setup/`, `skills/brain-bootstrap/` and `skills/brain-ingest/`. The visible README names the first three. It describes brain-setup for the same flow plus a pre-commit hook, and brain-bootstrap for seeding content, and brain-page is implied everywhere as the CLI layer, since every command is `node skills/brain-page/bin/brain.mjs`. `skills/brain-ingest/` appears only in the published file list. So a user who installs the package gets a fourth skill on disk that the documentation they were given never explains, which is worth resolving before you rely on the toolkit being fully described. Two other details from the same file: there is no dependencies key at all, which is the mechanical form of the zero-dependency claim, and the test script is `node --test` with no test framework.

This repository is the toolkit, and uninstall leaves the brains alone

The distinction the project leads with is between the repository and the thing it produces. This is the toolkit, not a brain; the brain is the `BRAIN.md` file and `brain/` directory that a project gets from `brain init`. That split is why the reverse command carries an explicit reassurance, that `brain uninstall` never touches any project's brain data, and why the argument for the format rests on being plain Markdown in git rather than on a database: with or without a runtime on top, the file travels. The tree reflects the split as well, with `bin/`, `setup`, `uninstall`, `package.json` and `skills/` at the top level, where `setup` and `uninstall` are extensionless files. One loose end in the documentation is worth knowing about: the CLI listing ends mid-command at `brain uninstall-`, having already listed `brain uninstall-hooks` a few lines earlier.

Editorial conclusion

Use brain.md when the reasons behind your decisions are being rediscovered by every new agent session, because the admission test it states, will this still matter in six months and is it hard to reconstruct from the code, is sharper than most memory conventions and the timeline makes an overturned decision legible. Do not adopt it expecting the initialization to fill the brain, since `brain init` deliberately ships an empty one and seeding is a separate skill. Verify three things before you wire it into a team: that `skills/brain-ingest/` is documented somewhere you can read, because it ships in the npm package and is absent from the visible README, that Codex agents are on CLI 0.153.4 or newer with a POSIX shell and awk, and that everyone agrees never to hand-edit the files, since that guarantee exists only on writes that go through the CLI.

Frequently asked questions

Official sources

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