{"slug": "show-hn-brain-md-a-persistent-memory-layer-for-your-coding-agents", "title": "Show HN: Brain.md – A persistent memory layer for your coding agents", "summary": "Brain.md, an open standard for persistent project memory, allows coding agents to store and retrieve durable knowledge as plain Markdown files in a repository, ensuring decisions and constraints outlive individual sessions. The tool, installed via a CLI, scaffolds a BRAIN.md protocol file and brain directory, enabling any agent that reads files to use the brain across sessions and machines.", "body_md": "**A persistent memory layer for your coding agents.**\n\nAn open, agent-agnostic standard for capturing a project's durable knowledge as plain\nMarkdown — read and written through one small CLI. It lives in your repo and travels across agents, machines, and models.\n\n[Why](#why-a-brain) ·\n[Quick start](#quick-start) ·\n[See it work](#see-it-work) ·\n[CLI](#the-brain-cli) ·\n[How it works](#how-it-works)\n\nThis repository is the **toolkit**, not a brain itself. Install it once, then run `brain-setup`\n\ninside any project: it scaffolds a [ BRAIN.md](/mindmuxai/brain.md/blob/main/skills/brain-setup/assets/BRAIN.md) protocol\nfile and a\n\n`brain/`\n\ndirectory 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\n\n`BRAIN.md`\n\n. 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\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.** Agent-agnostic**— the contract is a file (`BRAIN.md`\n\n). Any agent that can read it can use the brain.**Correct by construction**— every write goes through the`brain`\n\nCLI, so the brain's 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**1. Install the tools once (global):**\n\n```\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`\n\n+\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`\n\nto 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`\n\nCLI,\nfollowing `BRAIN.md`\n\n— brain files are never hand-edited.\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```\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\nReading and writing the brain both go through one zero-dependency Node CLI (run with `node`\n\n):\n\n```\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         # wire CLAUDE.md / AGENTS.md to BRAIN.md\nbrain reindex && 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`\n\nrewrites the truth and appends\nits timeline entry in one atomic write — so the understanding can never change without a trace.\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 generated, and`update-truth`\n\nrewrites understanding + records why in a single atomic write. The two things a validator used to guard are now structurally impossible.**Exactly one brain, location-independent.** It defaults to`./brain`\n\n, but a project can redirect it via`brainRoot`\n\nin`.mindmux/preferences.json`\n\n(e.g. an external sidecar). Every command resolves the location itself — tools never create a second, shadow brain.**Pure files, portable.** The brain is Markdown plus one Node script — it lives in your repo 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|---|---|\nbrain-setup |\nscaffold `BRAIN.md` + the brain skeleton, wire agent configs, optional pre-commit hook |\nbrain-bootstrap |\nseed the brain from code / docs / `git log` — or interview you on a greenfield project |\nbrain-page |\nthe operating manual for reading and writing pages + root pages (carries the `brain` CLI) |\nbrain-ingest |\ndigest a conversation, document, or research result into the brain |\n\nbrain.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.", "url": "https://wpnews.pro/news/show-hn-brain-md-a-persistent-memory-layer-for-your-coding-agents", "canonical_source": "https://github.com/mindmuxai/brain.md", "published_at": "2026-06-29 10:14:36+00:00", "updated_at": "2026-06-29 10:29:41.085062+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools", "large-language-models"], "entities": ["Brain.md", "Claude Code", "Codex", "BRAIN.md", "brain CLI"], "alternates": {"html": "https://wpnews.pro/news/show-hn-brain-md-a-persistent-memory-layer-for-your-coding-agents", "markdown": "https://wpnews.pro/news/show-hn-brain-md-a-persistent-memory-layer-for-your-coding-agents.md", "text": "https://wpnews.pro/news/show-hn-brain-md-a-persistent-memory-layer-for-your-coding-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-brain-md-a-persistent-memory-layer-for-your-coding-agents.jsonld"}}