Skip to content
ReviewRamble

The weekly brief

AI, reviewed, in your inbox.

  • New reviews of tools, models, MCP servers and repos, with the verdict up front
  • Re-checked prices and ratings when something changes
  • New analysis pieces as they are published

Models, agents, MCP servers and the tools actually worth your time.

One email a week. Unsubscribe with the link in any brief. How we use your email

brain.md

MindMux's small CLI and four agent skills that keep a project's decisions and constraints as Markdown pages in the repo.

Reviewed by ReviewRamble editors · Updated

View on GitHub Open source

Share this page:XLinkedInFacebookRedditWhatsAppEmail

Our rating

3.4/5

brain.md is a tidy way to make an agent write down why a decision was made, and it does little more than a well-kept docs folder with stricter rules.

What is brain.md?

brain.md is a convention plus a tool for writing down what a coding agent should not forget about a project. brain init adds a BRAIN.md protocol file, a brain/ folder and a marked block in CLAUDE.md and AGENTS.md that tells any agent how to use it. Each page has one of six categories, such as decision, concept or reference, a rewritable current summary and an append-only timeline of evidence, and every write goes through the brain CLI so the format stays valid.

Four skills drive it: brain-setup scaffolds and wires a project, brain-bootstrap drafts the first pages from the code, docs and git log or by interviewing you, brain-page is the manual for reading and writing, and brain-ingest folds a conversation or document into the brain. Optional SessionStart hooks for Claude Code and Codex hand the agent the page index at the start of each session.

The CLI is a zero-dependency Node.js script, published on npm as @mindmux/brain-md under the Apache 2.0 licence by MindMux. The repository was created in June 2026; v0.4.2 shipped on 13 November 2026.

Is brain.md worth it?

The idea is sound and the scope is honest. brain.md does not try to record everything an agent does; it asks the agent to capture only what will still matter in six months and cannot be read back from the code, and to keep a trail when that understanding changes. update-truth rewrites a page's summary and appends a timeline entry in one write, so a reversed decision leaves a record rather than vanishing.

There is not much code behind it, which is both the appeal and the limit. The CLI and installer come to roughly 1,750 lines of JavaScript with no dependencies, plus four skill files and tests. There is no search command: the agent lists pages by id, title and category and reads the ones that look relevant, which works for dozens of pages and gets harder with hundreds. Capture depends on the agent following BRAIN.md; nothing records a session automatically, unlike claude-mem or ai-memory, so a busy agent can simply forget.

The hooks are restrained. The Codex SessionStart hook sends only the page index, capped at 8 KiB, has five seconds to run, and exits quietly if the CLI fails; it needs Node 18 and a POSIX shell, so native Windows is out. Hooks contain an absolute path and must be reinstalled when a project moves. Because the brain lives in the repository, anyone with access to the repo can read it, which is the point, and also a reason to keep secrets out.

Adoption is modest: 722 stars, nine contributors and 814 npm downloads in the 30 days to 19 November. For a team that already keeps architecture decision records, brain.md adds a format agents are told to maintain; for one that keeps nothing, it is a cheap first step.

Where it earns its place

  • A three-person team whose agents keep reopening settled design choices

    Make the agent read past decisions before proposing a new approach

    Run brain init, then the brain-bootstrap skill to draft decision pages from the git log; the CLAUDE.md block tells the agent to load relevant pages at task start. Free, and the pages show up in code review.

  • A developer who switches between Claude Code and Codex on one repository

    Give both agents the same project knowledge at session start

    Install the SessionStart hooks for both with brain install-hooks and brain install-hooks --agent codex; each session gets the page index, up to 8 KiB, and reads full pages on demand.

Before you commit

Setup
npm install -g @mindmux/brain-md, then brain setup -y to copy the skills into each detected agent, then brain init in the project. Needs Node 18 or newer.
Integrations
Agent skills for Claude Code, Codex, Cursor and Pi; SessionStart hooks for Claude Code and Codex; any agent that reads AGENTS.md or CLAUDE.md can follow the protocol. No MCP server.
Data and privacy
Pages are Markdown in the repository's brain/ folder, or a path set by brainRoot; nothing is sent anywhere by the CLI. Whatever the agent writes is visible to anyone with repository access.
Limits
No search or embeddings; the Codex hook snapshot is capped at 8 KiB and five seconds; hooks hold an absolute path and must be reinstalled after a move; native Windows shells are not supported.

What’s good

  • Plain Markdown in the repo, versioned with the code
  • Append-only timeline keeps the reason a decision changed
  • Zero-dependency CLI; nothing to host
  • Bootstrap skill drafts first pages from code and git log

What’s not

  • No search; agents browse a page list
  • Capture relies on the agent remembering to write
  • Hooks need a POSIX shell; native Windows unsupported
  • Small project: 9 contributors, 814 npm downloads a month

Best for

Small teams who want Claude Code or Codex to keep architecture decisions and constraints in the repository, in a format a person can review in a pull request.

brain.md alternatives

brain.md: common questions

Is brain.md worth it?
brain.md is a tidy way to make an agent write down why a decision was made, and it does little more than a well-kept docs folder with stricter rules. We rate it 3.4 out of 5.
How much does brain.md cost?
Free under the Apache 2.0 licence; no service or account.
What are the downsides of brain.md?
No search; agents browse a page list; capture relies on the agent remembering to write; hooks need a POSIX shell; native Windows unsupported; small project: 9 contributors, 814 npm downloads a month.
Who is brain.md best for?
Small teams who want Claude Code or Codex to keep architecture decisions and constraints in the repository, in a format a person can review in a pull request.
Is brain.md safe for company data?
Pages are Markdown in the repository's brain/ folder, or a path set by brainRoot; nothing is sent anywhere by the CLI. Whatever the agent writes is visible to anyone with repository access.
What are the best brain.md alternatives?
The closest alternatives we have reviewed are ai-memory, claude-obsidian and OpenWiki.

Answers checked Nov 20, 2026.