by mindmuxai
A persistent, file-based memory layer for coding agents — give Claude Code, Codex & others a project brain (durable decisions, requirements, constraints) via a zero-dependency CLI.
# Add to your Claude Code skills
git clone https://github.com/mindmuxai/brain.mdbrain.md is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by mindmuxai. A persistent, file-based memory layer for coding agents — give Claude Code, Codex & others a project brain (durable decisions, requirements, constraints) via a zero-dependency CLI. It has 55 GitHub stars.
brain.md's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.
Clone the repository with "git clone https://github.com/mindmuxai/brain.md" and add it to your Claude Code skills directory (see the Installation section above).
brain.md is primarily written in JavaScript. It is open-source under mindmuxai on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh brain.md against similar tools.
No comments yet. Be the first to share your thoughts!
Unlocks once the catalog security scan passes (runs nightly).
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
This repository is the toolkit, not a brain itself. Install it once, then run brain-setup
inside any project: it scaffolds a BRAIN.md protocol
file and a brain/ directory 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.
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.
BRAIN.md). Any agent that can read it can use the brain.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 anything readable straight from the code and git history stay where they are.
1. Install the tools once (global):
./setup # symlinks skills/ into every detected agent (~/.claude/skills, ~/.codex/skills, …)
./uninstall # reverses it cleanly; never touches any project's brain data
2. Initialize a project — run the brain-setup skill in it. It scaffolds BRAIN.md +
the brain skeleton, wires the chosen agents' config files, and can install a pre-commit hook.
3. Seed real knowledge — run the brain-bootstrap skill. On an existing project it reads
the code, docs, and git log to draft the root pages and capture key decisions; on a near-empty
one it interviews you. (Setup leaves the brain empty on purpose — seeding is a separate, deliberate step.)
4. Work as usual. The agent reads and writes the brain only through the brain CLI,
following BRAIN.md — brain files are never hand-edited.
The point of a brain is what happens across sessions — a decision made today is still there, with its rationale, weeks later:
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 …
brain CLIReading and writing the brain both go through one zero-dependency Node CLI (run with node):
brain() { node skills/brain-page/bin/brain.mjs "$@"; }
brain brain-dir # where is the brain?
brain list-pages # list pages
brain read-page my-decision # read a page
brain create-page --id my-decision --category decision --title "Use X over Y"
echo "the new understanding" | brain update-truth --id my-decision --summary "why it changed"
brain append-timeline --id my-decision --kind evidence --summary "benchmark confirmed it"
echo "## Overview …" | brain update-root architecture
brain wire --agent claude-code,codex # wire CLAUDE.md / AGENTS.md to BRAIN.md
brain reindex && brain lint-links
A page carries a rewritable compiled_truth (the current best understanding) plus an
append-only timeline (the chain of evidence). update-truth rewrites the truth and appends
its timeline entry in one atomic write — so the understanding can never change without a trace.
Three design choices keep the brain durable and tamper-evident:
update-truth rewrites understanding + records why in a single atomic write.
The two things a validator used to guard are now structurally impossible../brain, but a project can
redirect it via brainRoot in .mindmux/preferences.json (e.g. an external sidecar). Every
command resolves the location itself — tools never create a second, shadow brain.The skills that drive it all:
| skill | what it does |
|---|---|
| brain-setup | scaffold BRAIN.md + the brain skeleton, wire agent configs, optional pre-commit hook |
| brain-bootstrap | seed the brain from code / docs / git log — or interview you on a greenfield project |
| brain-page | the operating manual for reading and writing pages + root pages (carries the brain CLI) |
| brain-ingest | digest a conversation, document, or research result into the brain |
brain.md is led and incubated by MindMux — the standalone open-source landing of MindMux's Brain Spec + coding-agent adapter. The specification layer uses neutral naming so it can be adopted widely; stewardship and maintenance belong to MindMux. Licensed under Apache-2.0.