We have officially OPEN-SOURCED projectbrain.md - A persistent memory layer for your projects.

You spend an afternoon with a coding agent settling something real. Why Markdown over SQLite. Why option B is out. What "done" means for this version. The reasoning is good, the trade-offs are weighed, the call is made.

Then the session ends.

Open a fresh one tomorrow — or switch machines, or move from Claude Code to Codex — and the agent asks the same questions again. What does this project do? Why not B? Didn't we already decide this? The model isn't weak. It just never had anywhere durable to put the conclusion. The work survives as code; the why behind it evaporates into a chat log nobody reopens.

So we built a small standard for the missing piece, and we're open-sourcing it: brain.md.

What it is

brain.md gives a project a brain — its durable decisions, requirements, and constraints, written down as plain Markdown that lives in the repo and outlives every session.

Two things ship in the box:

A contract — a single BRAIN.md file at the project root that tells any coding agent how the brain works. An agent learns to use it just by reading that file.
A toolkit — a small brain CLI plus a few install-once skills that scaffold and maintain the brain.

The brain itself is just Markdown files in your repo — nothing to stand up before you start. It grew out of MindMux, our project-brain workbench, which drives a brain through MCP and a lot more. brain.md is the open layer underneath: the format and the contract, so any agent that can read a file can use one — with MindMux, or with nothing but your editor and a terminal.

What a brain actually looks like

It's a brain/ directory of Markdown, and it has two kinds of file.

Root pages — a fixed set of six, the project at a glance: background, architecture, flow, mindmap, stack, roadmap. These you only ever update.

Pages — one durable unit of knowledge each: a decision, a concept, a person, a reference. You create them as you go. There's no limit and no ceremony.

The part that makes a page more than a note is its shape. Every page carries two layers:

compiled_truth — the current best understanding, rewritable as a whole.
timeline — an append-only trail of how that understanding got there.

One layer keeps you moving. The other lets you trace your way back. When you overturn a past call, you don't quietly edit history — you append a reversal to the timeline, and the change of mind stays on the record.

The design bet: files plus a CLI

None of this is a new idea on its own. AGENTS.md and CLAUDE.md already let you hand an agent standing instructions. brain.md's bet is narrower and, I think, more useful: make the memory structured, and make it correct by construction.

Here's the mechanism. Reads and writes both go through the brain CLI — you never hand-edit a brain file. That sounds like a limitation; it's the whole point. Because the CLI is the only writer:

Frontmatter is always generated, so it can't drift into an invalid shape.
Rewriting compiled_truth and appending its timeline entry happen in one atomic write — so the understanding can never change without leaving a trace.

That second property is the one that matters. The most common way a knowledge base rots is a silent edit: someone changes the conclusion and the reasoning behind it is lost. Route every write through one command and that failure mode is structurally impossible. There's no validator in brain.md because there's nothing left for a validator to catch.

What's actually different

If you've reached for adjacent tools, here's the honest contrast.

vs. a flat CLAUDE.md / rules file — those are great for instructions, but they're one growing blob you maintain by hand. A brain is structured, addressable knowledge with a built-in audit trail. Different job.
vs. memory that lives inside a tool — a vector store, a model's own memory, a hosted service: those are runtimes over your knowledge. A brain is the substrate itself — plain files in git, diffable in a PR, readable by a human, an agent, or grep. Put a runtime on top of it (MindMux does, over MCP; more can) and the knowledge still belongs to the repo, not the tool.
vs. saving chat history — chat history is the process. A brain is the conclusion. You don't want every raw sentence back; you want the handful of judgments you'll need again.

It's also not locked to one model or one tool. The contract is a file, so the same brain works across Claude Code, Codex, and whatever you use next.

See it work

Install the tools once:

./setup        # links the skills into every agent you choose (~/.claude, ~/.codex, …)

Then, in any project, the agent scaffolds and seeds a brain (brain-setup, then brain-bootstrap), and from there it just works. The payoff shows up across sessions:

You    Let's store config as Markdown, not SQLite — easier to diff and migrate.

Agent  Capturing that as a decision so it outlives this session.
       $ brain create-page --id config-as-markdown --category decision \
             --title "Store config as Markdown, not SQLite"
       ✓ page created · indexed

— three weeks and a fresh session later —

You    Why aren't we using a database for config?

Agent  $ brain read-page config-as-markdown
       We chose Markdown for diff-ability and zero migrations. Here's the original
       call and the trade-offs we weighed …

No re-explaining. The next conversation starts from what you already settled.