BRAIN.md

BRAIN.md — A persistent memory layer for your projects

Your AI forgets everything — unless you give it a brain.

Without BRAIN.md
❯ Let's keep working on the auth flow
✦ Happy to help! Could you first share some context:
  · What kind of app is this?
  · What's your tech stack?
  · What problem are you running into?
  · Any constraints I should know about?
❯ Okay so... I'm building a local-first note-taking app, Electron + SQLite, single user, no backend. Last week we talked about why JWT doesn't fit here... Two weeks ago we ruled out Redis... You also helped me think through the trade-offs on... Anyway, I want to pick up on the persistence strategy...
You just typed 318 words. Fourth time this month.
With BRAIN.md
❯ Let's keep working on the auth flow
✦ From brain/pages/auth.md — Picking up from last time:
  · Electron + SQLite, local-first, single user
  · JWT ruled out — no server, not worth the overhead
  · Still open: session persistence strategy

Where do you want to start?
One prompt in. AI already knows where you left off.

BRAIN.md is a local Markdown folder. It's yours. Git it, move it, read it with any tool.

Get started GitHub

How it Works

1. Chat
You work through a problem with an agent — trade-offs, constraints, what to do next.
2. Brain
brain update-truth atomically rewrites compiled_truth and appends a timeline entry.
3. Task
The next task — any agent, new chat, new machine — reads 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).

my-project/
my-project/ ├── BRAIN.md ← protocol entry point └── brain/     ├── index.md ← generated by reindex     ├── background.md ← why this project exists     ├── architecture.md ← system shape & modules     ├── flow.md ← key end-to-end flows     ├── mindmap.md ← feature mindmap     ├── stack.md ← technology choices     ├── roadmap.md ← milestones & sequencing     └── pages/         ├── db-choice.md         └── auth-strategy.md

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.

pages/auth-strategy.md
--- id: auth-strategy title: Authentication Strategy category: decision status: active created: "2026-06-10T11:20" updated: "2026-06-20T09:15" ---   ## compiled_truth Use JWT with short-lived access tokens. Session cookies ruled out for API-first clients. See [[api-versioning]].   ## timeline - time: 2026-06-20T09:15 kind: reversal summary: Dropped OAuth — scope creep source: internal-review-2026-06 affects: [auth-strategy, stack]

Features

# no service, no MCP server
# no npm install

$ node brain.mjs ls
runs on plain Node — zero deps
Zero Dependencies
No npm install, no runtime service, no background daemon. One zero-dependency reference CLI, run with node. The brain ships in your repo.
$ brain update-truth --id db-choice
↳ rewrites compiled_truth
↳ appends timeline entry
…in one atomic write
Correct by Construction
Every read and write goes through the brain CLI. Mis-shaped frontmatter and trace-less truth rewrites are structurally impossible — so there is no validator to run.
$ git log --oneline brain/
a3f1c4b decision: chose postgres
8d22e01 reversal: dropped redis
f90b3aa evidence: p99 spike
…
Git-Native
Brain files track in git. The timeline gives human-readable provenance; git diff gives the full record.
# architecture.md references:
[[db-choice]]
[[auth-strategy]]

$ brain lint-links ✓
Wiki-Link Cross-Refs
Pages link with [[page-id]] syntax. IDs match frontmatter exactly, and lint-links confirms every reference resolves.
## compiled_truth
Use PostgreSQL. ✓ reviewed
NOT a raw note dump
NOT a vector index
Authoritative decisions only
Decision-Grade
Holds the reviewed decisions you'd otherwise repeat to your AI every time — not a memory dump or a log of every observation.
Claude Code · Codex
any agent that reads files

4 installable skills,
shared across agents
Agent-Agnostic
An open standard with neutral naming. Four skills install once and work with Claude Code, Codex, and any file-reading agent. No vendor lock-in.

Get Started

Quick start
# 1. clone & install once (global) git clone https://github.com/mindmuxai/brain.md cd brain.md && ./setup → installed 4 skills into ~/.claude/skills # 2. scaffold + seed in any project /brain-setup # creates BRAIN.md + brain/, wires agent configs /brain-bootstrap # seeds from code + git log # 3. wire the brain CLI brain() { node skills/brain-page/bin/brain.mjs "$@"; } # 4. read & write through the CLI brain list-pages brain read-page db-choice brain update-truth --id db-choice --summary "why it changed" brain reindex && brain lint-links

View full documentation →

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?

Claude Code and Codex are supported today. More platforms are on the way.