2026.10.20
brain.md: Keeping Project Decisions for the Next Coding Agent
brain.md stores durable project knowledge in repository Markdown and exposes it through a small CLI, helping coding agents carry context across sessions.
What it is for
brain.md is a persistent memory layer for coding agents. Instead of leaving decisions, requirements, constraints, and rejected alternatives in a chat session, it records durable project knowledge as Markdown in or alongside the repository. Its protocol is the BRAIN.md file, so an agent that can read files can use the project brain without requiring a specific model runtime.
That makes it a plausible fit for developers who switch between Claude Code, Codex, and other file-oriented coding agents, as well as teams that want new sessions to recover important context. The project is not intended to duplicate implementation details that are already obvious from source code or Git history. Its focus is the harder-to-reconstruct reasoning behind a project.
Known capabilities
After installation, brain init creates BRAIN.md, initializes brain data, and wires guidance into CLAUDE.md and AGENTS.md. Existing files are not overwritten wholesale; the marked brain block is updated instead. The repository also describes workflows for bootstrapping existing projects, reading and writing pages, rebuilding indexes, and checking links.
The CLI is the sole writer. A page contains rewritable compiled_truth and an append-only timeline. Updating the current understanding records the associated timeline entry in one atomic write, keeping the present conclusion tied to its history. The brain location can also be redirected through brainRoot, allowing an external sidecar instead of the default project directory.
Release v0.4.0 changed root pages to an on-demand model. A new brain no longer receives six empty templates during initialization. A root page is created only when authored content exists for one of the supported slots: background, architecture, flow, mindmap, stack, or roadmap. This keeps initialization lean, but it also means that useful project knowledge still has to be deliberately created.
Limits and deployment considerations
brain.md is a toolkit, not a ready-made knowledge base. Initialization establishes the protocol and structure; an existing project still needs bootstrap work or manual curation. Markdown keeps the data portable and reviewable, but the quality of the brain depends on whether people maintain it. The CLI can enforce its write model, not decide which organizational knowledge is accurate or worth preserving.
Codex integration has explicit environment constraints. The README lists Codex CLI 0.153.4 or newer as the supported baseline and requires Node 18+, a POSIX shell, and awk; native Windows shells are not supported. Generated hook commands contain an absolute project path, so moving a project or using another clone/worktree requires uninstalling and reinstalling the hook. The hook emits page metadata rather than full page bodies, and Codex limits execution to five seconds.
Teams should also decide where brain data belongs, whether it is committed with the repository, and how sensitive information is excluded. The supplied sources do not establish performance figures, minimum hardware, or security guarantees. brain.md should therefore not be treated as an automatic solution for context quality, secret management, or agent correctness.
Bottom line
For teams frustrated by coding agents forgetting project decisions between sessions, brain.md offers a straightforward model: keep durable facts in Markdown, record changes through a CLI, and expose one protocol to multiple agents. It is better understood as a project-knowledge maintenance tool than as an automatic memory service. Its value will depend on whether maintaining the brain becomes part of normal development. The repository metadata identifies Apache License 2.0; adopters should still review the specific version and their own deployment requirements.
Sources
Sources checked: 2026-10-20