{"id":51727970,"url":"https://github.com/mindmuxai/brain.md","last_synced_at":"2026-07-17T22:17:12.787Z","repository":{"id":367018834,"uuid":"1273038999","full_name":"mindmuxai/brain.md","owner":"mindmuxai","description":"A persistent, file-based memory layer for coding agents — give Claude Code, Codex \u0026 others a project brain (durable decisions, requirements, constraints) via a zero-dependency CLI.","archived":false,"fork":false,"pushed_at":"2026-06-24T07:20:38.000Z","size":102,"stargazers_count":55,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-24T10:12:38.055Z","etag":null,"topics":["agent-memory","ai-agents","claude-code","cli","codex","coding-agents","context-engineering","developer-tools","knowledge-management","llm","markdown","project-brain","project-memory"],"latest_commit_sha":null,"homepage":"https://projectbrain.md","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mindmuxai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-18T06:45:01.000Z","updated_at":"2026-06-24T08:58:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mindmuxai/brain.md","commit_stats":null,"previous_names":["mindmuxai/brain.md"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mindmuxai/brain.md","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindmuxai%2Fbrain.md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindmuxai%2Fbrain.md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindmuxai%2Fbrain.md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindmuxai%2Fbrain.md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mindmuxai","download_url":"https://codeload.github.com/mindmuxai/brain.md/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindmuxai%2Fbrain.md/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35597336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-17T02:00:06.162Z","response_time":116,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-agents","claude-code","cli","codex","coding-agents","context-engineering","developer-tools","knowledge-management","llm","markdown","project-brain","project-memory"],"created_at":"2026-07-17T22:17:12.172Z","updated_at":"2026-07-17T22:17:12.777Z","avatar_url":"https://github.com/mindmuxai.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://projectbrain.md/icon.svg\" width=\"84\" height=\"84\" alt=\"brain.md\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ebrain.md\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eA persistent memory layer for your coding agents.\u003c/b\u003e\u003cbr\u003e\n  An open, agent-agnostic standard for capturing a project's durable knowledge as plain\n  Markdown — read and written through one small CLI. It lives in your repo and travels across agents, machines, and models.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-Apache--2.0-171717?style=flat-square\" alt=\"License: Apache-2.0\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/CLI-zero%20dependencies-171717?style=flat-square\" alt=\"Zero-dependency CLI\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/agents-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Cursor%20%C2%B7%20Pi-171717?style=flat-square\" alt=\"Agents: Claude Code, Codex, Cursor, Pi\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/version-0.1.0-171717?style=flat-square\" alt=\"Version 0.1.0\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#why-a-brain\"\u003eWhy\u003c/a\u003e ·\n  \u003ca href=\"#quick-start\"\u003eQuick start\u003c/a\u003e ·\n  \u003ca href=\"#see-it-work\"\u003eSee it work\u003c/a\u003e ·\n  \u003ca href=\"#the-brain-cli\"\u003eCLI\u003c/a\u003e ·\n  \u003ca href=\"#how-it-works\"\u003eHow it works\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nThis repository is the **toolkit**, not a brain itself. Install it once, then run `brain-setup`\ninside any project: it scaffolds a [`BRAIN.md`](./skills/brain-setup/assets/BRAIN.md) protocol\nfile and a `brain/` directory into **your** repo. From then on, any coding agent — Claude Code,\nCodex, anything that reads files — learns to use that brain just by reading the project's\n`BRAIN.md`. The brain is plain Markdown, lives in the repo, and outlives every session.\n\n## Why a brain\n\nA coding agent's knowledge lives nowhere durable. The reasons behind a decision, the\nconstraints you agreed on, the path *not* taken — they sit in chat logs and in your head,\nand they vanish the moment the session ends. The next agent starts from zero.\n\nA brain fixes that. It is the project's **persistent memory**: the durable decisions,\nrequirements, and constraints, written down as plain Markdown next to the code.\n\n- **Repo-native** — Markdown that lives in your project and travels in git, with or without a runtime on top.\n- **Agent-agnostic** — the contract is a file (`BRAIN.md`). Any agent that can read it can use the brain.\n- **Correct by construction** — every write goes through the `brain` CLI, so the brain's\n  invariants can't be broken by a malformed edit. There is no validator because none is needed.\n\nThe test for what belongs in it: **will this still matter in six months, and is it hard to\nreconstruct from the code itself?** If yes, it goes in the brain. Pure implementation details\nand anything readable straight from the code and git history stay where they are.\n\n## Quick start\n\n**1. Install the tools once (global):**\n\n```bash\n./setup        # symlinks skills/ into every detected agent (~/.claude/skills, ~/.codex/skills, …)\n./uninstall    # reverses it cleanly; never touches any project's brain data\n```\n\n**2. Initialize a project** — run the **brain-setup** skill in it. It scaffolds `BRAIN.md` +\nthe brain skeleton, wires the chosen agents' config files, and can install a pre-commit hook.\n\n**3. Seed real knowledge** — run the **brain-bootstrap** skill. On an existing project it reads\nthe code, docs, and `git log` to draft the root pages and capture key decisions; on a near-empty\none it interviews you. (Setup leaves the brain empty on purpose — seeding is a separate, deliberate step.)\n\n**4. Work as usual.** The agent reads and writes the brain only through the `brain` CLI,\nfollowing `BRAIN.md` — brain files are never hand-edited.\n\n## See it work\n\nThe point of a brain is what happens *across* sessions — a decision made today is still\nthere, with its rationale, weeks later:\n\n```text\nYou    Let's store config as Markdown, not SQLite — easier to diff and migrate.\n\nAgent  Capturing that as a decision so it outlives this session.\n       $ brain create-page --id config-as-markdown --category decision \\\n             --title \"Store config as Markdown, not SQLite\"\n       ✓ page created · indexed\n\n— three weeks and a fresh session later —\n\nYou    Why aren't we using a database for config?\n\nAgent  $ brain read-page config-as-markdown\n       We chose Markdown for diff-ability and zero migrations. Here's the original call\n       and the trade-offs we weighed …\n```\n\n## The `brain` CLI\n\nReading and writing the brain both go through one zero-dependency Node CLI (run with `node`):\n\n```bash\nbrain() { node skills/brain-page/bin/brain.mjs \"$@\"; }\n\nbrain brain-dir                              # where is the brain?\nbrain list-pages                             # list pages\nbrain read-page my-decision                  # read a page\nbrain create-page --id my-decision --category decision --title \"Use X over Y\"\necho \"the new understanding\" | brain update-truth --id my-decision --summary \"why it changed\"\nbrain append-timeline --id my-decision --kind evidence --summary \"benchmark confirmed it\"\necho \"## Overview …\" | brain update-root architecture\nbrain wire --agent claude-code,codex,opencode,cursor,pi   # wire CLAUDE.md / AGENTS.md to BRAIN.md\nbrain reindex \u0026\u0026 brain lint-links\n```\n\nA page carries a rewritable **compiled_truth** (the current best understanding) plus an\nappend-only **timeline** (the chain of evidence). `update-truth` rewrites the truth and appends\nits timeline entry in one atomic write — so the understanding can never change without a trace.\n\n## How it works\n\nThree design choices keep the brain durable and tamper-evident:\n\n- **Correct by construction, no validator.** The CLI is the only writer. Frontmatter is always\n  generated, and `update-truth` rewrites understanding + records why in a single atomic write.\n  The two things a validator used to guard are now structurally impossible.\n- **Exactly one brain, location-independent.** It defaults to `./brain`, but a project can\n  redirect it via `brainRoot` in `.mindmux/preferences.json` (e.g. an external sidecar). Every\n  command resolves the location itself — tools never create a second, shadow brain.\n- **Pure files, portable.** The brain is Markdown plus one Node script — it lives in your repo\n  and travels in git, and runtimes (MindMux over MCP, more to come) layer on top of the same files.\n\nThe skills that drive it all:\n\n| skill | what it does |\n|---|---|\n| **brain-setup** | scaffold `BRAIN.md` + the brain skeleton, wire agent configs, optional pre-commit hook |\n| **brain-bootstrap** | seed the brain from code / docs / `git log` — or interview you on a greenfield project |\n| **brain-page** | the operating manual for reading and writing pages + root pages (carries the `brain` CLI) |\n| **brain-ingest** | digest a conversation, document, or research result into the brain |\n\n---\n\n\u003csub\u003ebrain.md is led and incubated by **MindMux** — the standalone open-source landing of\nMindMux's Brain Spec + coding-agent adapter. The specification layer uses neutral naming so it\ncan be adopted widely; stewardship and maintenance belong to MindMux. Licensed under Apache-2.0.\u003c/sub\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmindmuxai%2Fbrain.md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmindmuxai%2Fbrain.md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmindmuxai%2Fbrain.md/lists"}