brain.md

Overview of brain.md

What it is

brain.md is a persistent, file-based memory layer for coding agents. It provides an open, agent-agnostic standard for capturing a project's durable knowledge as plain Markdown, read and written through a zero-dependency CLI. The brain lives in the repository and travels across agents, machines, and models. The toolkit scaffolds a BRAIN.md protocol file and a brain/ directory, and default-wires agent config files into the repo. Any coding agent that can read files can use the brain by reading the project's BRAIN.md (plain Markdown).

Key features

• Repo-native — Markdown that lives in the project and travels in git, with or without a runtime on top.
• Agent-agnostic — the contract is a file (BRAIN.md). Any agent that can read it can use the brain.
• Correct by construction — every write goes through the brain CLI, so the brain's invariants cannot be broken by a malformed edit. No validator is needed.
• Compiled truth and append-only timeline — each page carries a rewritable compiled_truth (current best understanding) plus an append-only timeline (chain of evidence). update-truth rewrites the truth and appends its timeline entry in one atomic write.
• Lifecycle hooks for Claude Code and Codex — brain install-hooks installs session-start hooks that load brain context automatically.
• Zero-dependency Node CLI — the brain command runs with node and has no external dependencies.

Use cases

• Persisting durable decisions, requirements, and constraints across coding sessions so they survive when a session ends.
• Giving a new coding agent access to the project's history and rationale without starting from zero.
• Recording knowledge that is hard to reconstruct from code alone (e.g., why a path was not taken, trade-offs weighed).

Getting started

Install the tools globally (no clone required): bash npm install -g @mindmux/brain-md brain setup -y Or use npx (does not leave brain on PATH): bash npx @mindmux/brain-md setup -y Initialize a project (from the project root): bash brain init After initialization, BRAIN.md and a brain/ directory are created, and agent config files (CLAUDE.md, AGENTS.md) are default-wired.

License and pricing

Licensed under Apache-2.0. Open source.

Based on the project's public README and repository metadata.