Brain MD

brain.md

  A persistent, file-based memory layer for your coding agents.
  An open, agent-agnostic standard for capturing a project's durable knowledge as plain
  Markdown — read and written through one small CLI. It lives in your repo and travels across agents, machines, and models.

  Why ·
  Quick start ·
  See it work ·
  CLI ·
  How it works

This repository is the toolkit, not a brain itself. Install it once, then in any project run
brain init: it scaffolds a BRAIN.md protocol file, a
brain/ directory, and default-wires agent config files into your repo. From then on, any
coding agent — Claude Code, Codex, anything that reads files — learns to use that brain just by
reading the project's BRAIN.md. The brain is plain Markdown, lives in the repo, and outlives
every session.

Why a brain

A coding agent's knowledge lives nowhere durable. The reasons behind a decision, the
constraints you agreed on, the path *not* taken — they sit in chat logs and in your head,
and they vanish the moment the session ends. The next agent starts from zero.

A brain fixes that. It is the project's persistent memory: the durable decisions,
requirements, and constraints, written down as plain Markdown next to the code.

- Repo-native — Markdown that lives in your 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 can't be broken by a malformed edit. There is no validator because none is needed.

The test for what belongs in it: will this still matter in six months, and is it hard to
reconstruct from the code itself? If yes, it goes in the brain. Pure implementation details
and…