brain.md skill
Persistent project memory in Markdown: decisions, requirements and constraints stay in the repo for each new session.
- 593 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- `brain init` and `brain install-hooks` change `CLAUDE.md`, `AGENTS.md` and the project's hook configuration.
- The memory is committed to git with the code, so secrets must stay out of its pages.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/brain-mdDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- `brain init` and `brain install-hooks` change `CLAUDE.md`, `AGENTS.md` and the project's hook configuration.
- The memory is committed to git with the code, so secrets must stay out of its pages.
This is third-party code. Review the repository files before installing.
What it does
brain.md keeps a project's durable knowledge in plain Markdown pages next to the code. `brain init` creates the `BRAIN.md` protocol file and a `brain/` directory, then writes a block into `CLAUDE.md` and `AGENTS.md`, so Claude Code, Codex and other agents begin by reading this memory. Every change goes through a small dependency-free `brain` CLI. `create-page` starts a page, `update-truth` rewrites the current understanding and appends a timeline entry at once, `read-page` returns a page, `reindex` refreshes the index. The `brain-bootstrap` skill fills the memory from the code, docs and `git log` of an existing project.
Who it is for. Developers whose agent forgets agreed decisions in every new session while the reasons stay in a chat.
Good fit when
- In a new session the agent suggests an option the team has already rejected.
- Claude Code and Codex both work on the project and share one memory.
- The reason for choosing Markdown over SQLite should survive past this week.
- Decisions of a long-lived project are collected from code and git history.
Not a fit when
- You need search over past chats, not decision pages.
- Memory must stay outside the repository and out of git.
- A one-evening project with no decisions that last half a year.
Example request
Capture in the project memory the decision to store config as Markdown instead of SQLite, with the reason.Limitations
The README lists version 0.4.1. The CLI is written for Node, so without a global install `brain` runs only through `npx`. An agent or a person decides what enters the memory by asking whether it will matter in six months, so pages gather clutter without review. Memory files are edited only with `brain` commands; hand edits are not intended. `brain init` changes `CLAUDE.md` and `AGENTS.md` (the marked block only), and the optional pre-commit hook runs on every commit.
How to disable. Run `brain uninstall`: it removes globally installed skills and never touches project data. `brain uninstall-hooks` removes the hooks. Delete the block in `CLAUDE.md` and `AGENTS.md`, the `brain/` directory and `BRAIN.md` yourself.
FAQ
How do I get started?
Install `npm install -g @mindmux/brain-md`, run `brain setup -y`, then `brain init` in the project root. Next run the `brain-bootstrap` skill to fill the memory from code and `git log`.
What does a memory page hold?
A rewritable `compiled_truth` with the current understanding and an append-only `timeline`. `update-truth` changes the first and adds a line to the second in one atomic write.
Can I skip the global install?
Yes: `npx @mindmux/brain-md setup -y`, then `npx @mindmux/brain-md init`. `npx` does not put `brain` on the PATH, so both commands go through it.
What belongs in the memory?
What will still matter in six months and is hard to rebuild from code. Implementation details and anything visible in code and git history stay there.
How do I connect Codex?
Run `brain install-hooks --agent codex` in the project root. It creates `.codex/hooks/brain-session-start` and adds a `SessionStart` entry to `.codex/hooks.json`.
Discussion
No questions or reviews yet.
Related
SkillsLong-term agent memory in local Markdown files with a link graph, semantic search and MCP access
Skills keep project memory in a docs/ai folder: short size-capped files, a one-page handoff and a verifier for the install
hipocampus gives an agent file-based memory: a 3,000-token topic index loads each session and shows what came up before
One local binary that gives Claude Code, Codex and Cursor shared memory across sessions, with a knowledge graph on disk and no API keys
A local workbench for Claude Code, Codex, Pi and OpenCode: memory changes wait for your review, then an audit follows each turn
Agent memory in one Go binary: facts outlive sessions, are found by meaning and by keyword, and unused ones fade over time
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| brain.md (this card) | no | 593 | |
| Episodic Memory | no | 499 | searches past conversations with agents; brain.md keeps decision pages with a timeline in the repository |
| Claude-Mem | no | 113,534 | stores observations from sessions and injects them into new ones; brain.md keeps written-up decisions as project files |
README in short
The repository is the toolkit, not a ready memory. Setup copies skills into the directories of detected agents, and `brain init` creates the memory inside your project.