Brain.Md
A persistent, file-based memory layer for coding agents that lives as a brain/ Markdown folder in your repo.
BRAIN.md picks one problem and solves it structurally: your agent forgets why you ruled out Redis two weeks ago. The mechanism is the selling point — atomic update-truth writes that make a truth rewrite without a timeline entry impossible, wiki-link cross-references that brain lint-links actually validates, and a brain/ folder you commit so git diff is the full provenance record. There is no runtime and no MCP server to keep alive, which is precisely why it survives on a laptop or in CI. The honest tradeoff is discipline: memory is only captured when someone runs a brain CLI command, so teams that want automatic capture will find Mem0 or an editor's built-in memory heavier but less
Verified 1d ago · liveness 45/100 · cite: rightaichoice.com/tools/brain-md
- Developers running Claude Code or Codex on long-lived projects
- Teams that want AI context preserved without a hosted service
- Solo developers tired of re-explaining context in every new chat
- Open-source maintainers documenting decisions for AI contributors
- People who want a GUI knowledge-management tool
- Teams needing cloud-hosted memory with semantic search
- Projects where the coding agent cannot read local Markdown files
We scan live Reddit threads, YouTube comments, X posts, G2 reviews and other communities — and hand you an honest verdict in under a minute.
- Honest verdict, not marketing
- Real pros & cons from real users
- Attributed quotes with receipts
3 free scans · no card needed
Skip BRAIN.md if nobody on the team will consistently run brain update-truth, because a memory layer nobody writes to gives your agent a stale brain instead of a useful one.
Capture discipline is the real cost: every conclusion you want remembered has to be written through a brain CLI command by a human, and that time is not billed anywhere but it adds up.
BRAIN.md is free and open source, with the CLI installed from npm as @mindmux/brain-md, so the cost comparison is your team's time rather than a subscription. Against hosted memory services, the trade is money and vendor lock-in for the discipline of running brain update-truth. Against doing nothing, the trade is a few minutes of writing per decision for agents that start each session already caught up.
In short
Brain.Md — A persistent, file-based memory layer for coding agents that lives as a brain/ Markdown folder in your repo. Best for Developers running Claude Code or Codex on long-lived projects, Teams that want AI context preserved without a hosted service, Solo developers tired of re-explaining context in every new chat. Free to use.
What people actually say about Brain.Md — is it worth it?
We ran a structured research pass across product reviews, community discussions, and post-purchase forum threads to surface the patterns vendors won't publish themselves. Below: the recurring strengths, the hidden costs people mention most, and the cohort that consistently regrets adopting this tool.
2 mentions across 1 source (Hacker News) · researched Jul 3, 2026.
Average across the 1 source that answered — each source counts once, not each post.
- +Zero-dependency CLI works offline, no servers required.
- +File-based Markdown memory is Git-versionable and portable.
- +Free and open source—no subscription or API keys needed.
- +Structured six-page root gives agents a consistent project overview.
- +Granular pages with compiled_truth and timeline capture decision history.
- −Very slim community feedback—only 2 Hacker News posts available.
- −No integrations with common tools like Slack or Zapier.
- −Agent compliance is not guaranteed; agents may ignore the brain.
- −Manual process could become neglected in fast-paced projects.
- −Success depends on team discipline to keep brain updated.
- • No hidden costs—fully free and open source.
Viability Score
How well maintained and how widely used is Brain.Md? Built from what the vendor actually publishes (docs, changelog, tutorials, integrations, pricing), whether the site is live, and how much real users discuss it. How we calculate this
Last calculated: October 2026
How we score →Key Features
- Local brain/ Markdown folder committed alongside your repo
- Zero-dependency CLI in plain Node.js, installed via npm i -g @mindmux/brain-md
- No runtime daemon, no MCP server, no network dependency
- BRAIN.md at the project root as the protocol entry point any Markdown-reading agent can follow
- Six fixed root pages: background, architecture, flow, mindmap, stack, roadmap
- Six root pages are update-only, never created, with history kept in git
- Five granular page categories under pages/: decision, concept, project, person, reference
- compiled_truth section holding the current authoritative answer for a page
- Append-only timeline with entry kinds: decision, evidence, reversal, note
- brain update-truth atomically rewrites compiled_truth and appends the timeline entry in one write
- Wiki-link cross-references in [[page-id]] syntax matched against the frontmatter id field
- brain lint-links validates that every cross-reference resolves
- brain reindex regenerates brain/index.md
- brain-setup and brain-bootstrap scaffolding commands
- Frontmatter fields: id, title, category, status, created, updated
About Brain.Md
BRAIN.md gives your coding agent a memory that survives between chats without adding a service, a daemon, or a cloud dependency. You keep working with an agent the way you already do — trade-offs, constraints, decisions — and then compile what you settled into a brain/ Markdown folder that ships inside your repository. A single BRAIN.md at the project root is the protocol entry point: any agent that reads Markdown knows how to read and write the brain. Six fixed root pages hold the project-wide views — background, architecture, flow, mindmap, stack, and roadmap — and they are only ever updated, never created, so their history lives in git rather than in a timeline. Granular pages under pages/ are append-safe knowledge units in one of five categories: decision, concept, project, person, and reference. Each page carries compiled_truth (the current authoritative answer) plus an append-only timeline of decision, evidence, reversal, and note entries. Correctness is enforced structurally: brain update-truth rewrites compiled_truth and appends the matching timeline entry in one atomic write, so you cannot produce a trace-less rewrite. Cross-references use [[page-id]] wiki-link syntax validated by brain lint-links, and brain reindex regenerates brain/index.md. The CLI is plain Node.js with zero runtime dependencies, installed with npm i -g @mindmux/brain-md. It is aimed at developers running Claude Code or Codex on long-lived projects, and at teams who want shared AI context without handing their project memory to a hosted service.
Behind the Verdict
BRAIN.md is best understood as a convention plus a guardrail, not a platform. The convention is the file layout: BRAIN.md as the protocol entry point at the repo root, six fixed root pages for project-wide views, and pages/*.md for granular knowledge in five categories. Any agent that can read local Markdown can participate, which is the whole point — no SDK, no server handshake, no per-vendor connector. The guardrail is the CLI. brain update-truth exists so that changing a conclusion and recording that you changed it are the same operation: compiled_truth is rewritten and a decision entry is appended in one atomic write. That single design choice is what separates this from a folder of notes an agent might quietly contradict. brain lint-links gives cross-references the same treatment, turning a malformed [[page-id]] into a visible failure rather than a dead link. brain reindex keeps brain/index.md regenerated from what is actually on disk. Strengths: the brain travels with the code — clone the repo, get the memory; the timeline keeps old truths and reversals readable next to the current answer, and git history sits underneath as the raw record. The six root pages being update-only is a sensible constraint, since their evolution is already captured by commits. Weaknesses are the mirror image of the design. Capture is deliberate, so an undisciplined team ends up with a brain that is accurate but thin. There is no semantic retrieval layer — agents read the Markdown files directly, so the brain rewards a tidy page set and punishes sprawl. Collaboration is git collaboration: branches, merges, and review are the sync mechanism, and merge conflicts on a hot page are a real thing teams will hit. The fixed shape of the root pages means you adapt to the structure rather than shaping it. Where it fits: long-lived repositories with real architectural decisions, teams standardising on Claude Code or Codex, and open-source maintainers who want AI contributors to inherit the reasoning behind the code. Where it does not: throwaway prototypes, teams that need a GUI to browse their knowledge, and anyone whose agent cannot read local files.
Researching Brain.Md? Get your full AI stack in 60 seconds.
Free, no signup — tell us your goal and get tools matched to your budget & existing stack.
Real-world workflow fit
Concrete scenarios for the personas Brain.Md actually fits — and what changes day-one when you adopt it.
You rule out a session-store approach with the agent, then run brain update-truth on the auth-strategy page so compiled_truth changes and a decision entry lands in the timeline in one write.
Outcome: The next chat opens by reading brain/pages/auth-strategy.md from your repo, so the agent picks up the Electron and SQLite constraints without you retyping them.
Each project gets a BRAIN.md entry point and a brain/ folder; root pages such as stack.md and architecture.md carry mermaid diagrams that are updated as the system changes.
Outcome: Because the brain versions with git, a new engineer clones the repo and their agent inherits the same decisions and constraints as everyone else's.
Every architectural decision is captured as a page with a compiled_truth answer and an append-only timeline, then cross-linked with [[page-id]] references that brain lint-links checks.
Outcome: Contributors' agents can read why the project is shaped the way it is, and reversals stay visible in the timeline instead of being overwritten.
Use Cases
- Record an architectural decision and its rationale so the next agent session starts already informed
- Keep agents current as constraints, stack choices, and trade-offs change
- Onboard a fresh agent to an existing project by pointing it at brain/
- Audit past decisions by reading the timeline on each knowledge page
- Share one project brain across a team through Git so every agent behaves consistently
- Reverse a decision while preserving the previous truth and the evidence that changed your mind
- Give human contributors the same decision-grade context your agents read
Limitations
- This is a file-based memory layer: no runtime service and no MCP server.
- Writing happens only when you run a CLI command such as brain update-truth, so memory is captured deliberately rather than automatically.
- There is no semantic search or automated retrieval — agents read the Markdown files directly.
- Collaboration and any sync depend on Git, and cross-page history outside git lives in each page's append-only timeline.
- Pages link with [[page-id]] syntax and must resolve via brain lint-links, so malformed links surface as failures instead of being silently ignored.
- The protocol entry point is a single BRAIN.md at the project root, and the six root pages are updated rather than created, so the structural shape is fixed.
as of 2026-10-10
Verification history
We have re-verified Brain.Md 9 times since . Each pass re-reads the vendor's own pages and re-checks every listed field against that evidence; passes where nothing had changed are marked as such.
- — re-checked, vendor evidence unchanged
- — re-checked, vendor evidence unchanged
- — re-checked, vendor evidence unchanged
- — re-checked, vendor evidence unchanged
- — re-checked, vendor evidence unchanged
- — re-checked, vendor evidence unchanged
Showing the 6 most recent of 9 verification passes.
Free to cite with attribution — this page re-verifies continuously.
Where the pricing makes sense
The company stage and team size where Brain.Md's pricing actually pencils out — and where peers do it cheaper.
BRAIN.md is free and open source, with the CLI installed from npm as @mindmux/brain-md, so the cost comparison is your team's time rather than a subscription. Against hosted memory services, the trade is money and vendor lock-in for the discipline of running brain update-truth. Against doing nothing, the trade is a few minutes of writing per decision for agents that start each session already caught up.
Setup time & first value
How long it actually takes to get something useful out of Brain.Md — broken out by persona, not the marketing-page minute.
Solo developer: one npm i -g @mindmux/brain-md install plus brain-setup and brain-bootstrap to scaffold BRAIN.md and the six root pages, then your first brain update-truth — an afternoon to a working brain. Small team: add the same in a couple of repos and agree who writes decisions, so a day or two. The real ramp is habit, not installation; the CLI has zero runtime dependencies and needs no
Switching to or from Brain.Md
How to bring data in from common predecessors and how to get it back out — written for the switcher, not the buyer.
- →From a hand-maintained AGENTS.md or README notes: move the decision-grade content into pages/*.md under the right category and leave BRAIN.md as the protocol entry point.
- ↗To a hosted memory service: export each page's compiled_truth and timeline into the service's ingestion path, though the git diff provenance does not travel with it.
Resources & Guides
Tutorials & Learning
YouTube returned 6 videos for “Brain.Md”, and we withheld 6: 6 could not be judged, because “Brain.Md” is a single word that other videos use for other things. We are showing none, because we could not prove any of them are about Brain.Md.
Official links
Tools that pair well with Brain.Md
Common stack mates teams adopt alongside Brain.Md, with the specific reason each pairing earns its keep.
Pieces for Developers
Pieces for Developers is an on-device AI memory layer that captures your work every 2 seconds for instant recall and MCP piping.
Continue
Open-source AI coding agent for VS Code and JetBrains — free to fork since Cursor acquired Continue in January 2026.
Kiro
Kiro turns prompts into specs, validates them, then ships with parallel AI coding agents
Featured Head-to-Head Comparisons
Brain Md vs Spider Cloud
If you need real-time web data for AI agents or RAG pipelines, Spider Cloud is the obvious choice with its Rust engine, 99.9% uptime, and sub-cent cost per 1k pages. If you're building software with LLM coding assistants and frustration at lost context across sessions, Brain.Md is a free, elegant, file-based memory layer that persists decisions alongside your code. The two tools solve different problems—one feeds data into AI, the other preserves AI's understanding of your project.
Brain Md vs Temporal Ai
For teams building reliable, long-running AI agents or microservices that must survive failures, Temporal AI is the clear choice with its durable execution and extensive SDK support. For solo developers using Claude Code or Codex who want to avoid re-explaining context between sessions, BRAIN.md is a simpler, free, and lightweight solution. Choose based on whether you need fault-tolerant orchestration or persistent memory for coding agents.
Brain Md vs Voyage Ai
Voyage AI wins for enterprise RAG with domain-optimized embeddings and low-dimensional vectors; Brain.Md wins for AI-assisted coding with persistent, versionable memory. If you need accurate retrieval on finance/legal documents, choose Voyage. If you're a developer wanting AI agents to remember project context, choose Brain.Md.
Alternatives to Brain.Md
View allPieces for Developers
Pieces for Developers is an on-device AI memory layer that captures your work every 2 seconds for instant recall and MCP piping.
Frequently Asked Questions
Best-of guides
Used Brain.Md? Help shape our editorial sentiment research.