BRAIN.md

BRAIN.md — 为你的项目提供持久记忆层

AI 会忘掉一切——除非你给它一个大脑。

没有 BRAIN.md
❯ 继续搞认证流程吧
✦ 没问题！能先给我一些背景吗：
  · 这是什么类型的应用？
  · 技术栈是什么？
  · 遇到了什么问题？
  · 有什么需要注意的约束吗？
❯ 好吧……我在做一个本地优先的笔记应用，Electron + SQLite，单用户，没有后端。上周我们聊过为什么 JWT 不适合这里……两周前我们排除了 Redis……你还帮我分析过各种方案的权衡……总之，我想继续讨论持久化策略……
你刚打了 318 个字。这个月第四次了。
有了 BRAIN.md
❯ 继续搞认证流程吧
✦ 已读取 brain/pages/auth.md — 继续上次进度：
  · Electron + SQLite，本地优先，单用户
  · JWT 已排除——没有服务端，开销不值得
  · 待定：会话持久化方案

从哪里开始？
刚一句话。AI 已经知道你上次停在哪了。

BRAIN.md 就是本地的一个 Markdown 文件夹，完全属于你。可以 Git 管理、随处迁移、用任何工具直接阅读。

立即上手 GitHub

工作原理

1. 对话
你和 agent 一起理清一个问题——权衡、约束、下一步怎么做。
2. 大脑
brain update-truth 原子性地重写 compiled_truth，并追加一条 timeline 记录。
3. 任务
下一个任务——任意 agent、新对话、甚至新机器——先读取 brain/，一上来就已经掌握全部背景。

↺ 下一个任务本身就是一次新对话——它会先读大脑，让循环重新开始。

为什么是 BRAIN.md

README.md 面向人类。 AGENTS.md 告诉 AI 如何在仓库里干活。 但两者都不记录你 为什么 这样决策—— 那正是项目大脑的职责：把那些你每次开新对话都要重新解释一遍的决策，一次性存下来。

项目大脑存储的是决策级知识—— 经过审查、结构化，权威到足以指导后续推理和代码生成的结论。 它住在 brain/ 文件夹里，随仓库一起交付。

项目根目录的 BRAIN.md 是协议入口： 任何读到它的编码代理都知道怎么使用这个项目大脑。 不需要运行时服务，也不需要 MCP 服务器——只有普通文件约定加一个零依赖 CLI。

文件 读者 用途
README.md 人类 快速开始、贡献指南
AGENTS.md AI 编码代理 如何在这个代码库中工作
BRAIN.md 任何编码代理 协议入口：如何读写项目大脑
brain/ AI 推理代理 + 人类 决策、权衡和理由，可直接服务后续代理

结构

六个固定根页面覆盖项目级视角：背景、架构、 流程、思维导图、技术栈和路线图。它们只会被更新，不会被重复创建， 也不携带 timeline——历史由 git 负责。可以用 mermaid 图让内容更直观。

pages/*.md 是细粒度、可安全追加的知识单元， 归属于五类之一：decision、 concept、project、 person、reference。 每个页面同时记录当前最佳理解（compiled_truth） 和完整证据链（timeline）。

my-project/
my-project/ ├── BRAIN.md ← 协议入口 └── brain/     ├── index.md ← reindex 生成     ├── background.md ← 项目为何存在     ├── architecture.md ← 系统形态与模块     ├── flow.md ← 关键端到端流程     ├── mindmap.md ← 功能思维导图     ├── stack.md ← 技术选择     ├── roadmap.md ← 里程碑与顺序     └── pages/         ├── db-choice.md         └── auth-strategy.md

页面格式

pages/ 中的每个页面都有两个部分。 compiled_truth 是当前的权威答案—— 随着认知演进，可以自由重写。

timeline 是只追加的证据记录。 当结论改变时，update-truth 会原子地重写 compiled_truth，并追加一条 decision 记录。旧结论仍保留在历史中。

Timeline 条目类型包括：decision、 evidence、 reversal、 note。重写 compiled_truth 和追加对应的 decision 条目在一次原子写入中完成； 两件事不能只做其中一件。

交叉引用使用 wiki-link 语法 [[page-id]]， 其中 page-id 必须与 frontmatter 的 id 字段完全匹配。 运行 brain lint-links 可验证每个链接都能解析。

pages/auth-strategy.md
--- id: auth-strategy title: Authentication Strategy category: decision status: active created: "2026-06-10T11:20:00" updated: "2026-06-20T09:15:00" ---   <!-- compiled_truth -->   # Authentication Strategy Use JWT with short-lived access tokens. Session cookies ruled out for API-first clients. See [[api-versioning]].   ## Timeline - time: 2026-06-20T09:15:00 kind: reversal summary: Dropped OAuth — scope creep source: internal-review-2026-06 affects: [auth-strategy, stack]

特性

# 无服务，无 MCP 服务器
# 零运行时依赖

$ npm i -g @mindmux/brain-md
精简 CLI — 纯 Node，无依赖
零依赖
通过 npm 安装一次。brain CLI 零运行时依赖——无需服务、无需 MCP 服务器、无需守护进程。项目大脑本身就是仓库里的普通 Markdown。
$ brain update-truth --id db-choice
↳ 重写 compiled_truth
↳ 追加 timeline 条目
在一次原子写入中完成
结构保证正确
每次读写都通过 brain CLI。格式错误的 frontmatter 和无追踪记录的 truth 重写在结构上不可发生——根本不需要跑验证器。
$ git log --oneline brain/
a3f1c4b decision: chose postgres
8d22e01 reversal: dropped redis
f90b3aa evidence: p99 spike
…
Git 原生
Brain 文件由 git 跟踪。timeline 提供人类可读的来源记录，git diff 提供完整变更历史。
# architecture.md 引用：
[[db-choice]]
[[auth-strategy]]

$ brain lint-links ✓
Wiki 链接交叉引用
页面使用 [[page-id]] 语法互相链接。ID 与 frontmatter 完全匹配，lint-links 会确认每个引用都能解析。
<!-- compiled_truth -->
Use PostgreSQL. ✓ reviewed
不是原始笔记堆砌
不是向量索引
只存权威决策
决策级知识
存储经过审查、足够权威、可以指导代码生成的结论；不是记忆倾倒，也不是观察日志。
Claude Code · Codex · Cursor
Pi · OpenCode

4 个可安装技能，
跨代理共享
代理无关
中立命名的开放标准。四个技能安装一次，即可接入 Claude Code、Codex、Cursor、Pi、OpenCode——任何能读文件的代理都可通过 BRAIN.md 使用项目大脑。没有厂商锁定。

开始使用

安装一次、初始化项目，然后继续写代码。Agent 会读 BRAIN.md，并通过 brain CLI 读写项目大脑——你不需要手改这些文件。

1 · 安装并初始化
# 每台机器装一次 — 无需克隆仓库 npm install -g @mindmux/brain-md brain setup -y → 技能装入 Claude Code、Codex、Cursor、Pi、OpenCode # 每个项目做一次（在项目根目录） brain init → BRAIN.md + 空 brain/ + 接入 CLAUDE.md / AGENTS.md brain install-hooks → 可选：Claude Code SessionStart 注入 brain list-pages（仅项目内） # 不想全局安装？每一步都用 npx（PATH 上没有裸 brain）： # npx @mindmux/brain-md setup -y # npx @mindmux/brain-md init # npx @mindmux/brain-md install-hooks
2 · 和 agent 一起工作
❯ 给这个项目播种 brain
✦ 运行 brain-bootstrap 技能 — 不是 shell 命令。
  已有仓库 → 从代码 / 文档 / git log 起草
  空项目 → 通过访谈收集

$ brain update-root architecture
$ brain create-page --id config-as-markdown --category decision …
✓ 根页面与关键决策已写入
— 几周后，全新会话 —
❯ 配置为什么不用数据库？
✦ $ brain read-page config-as-markdown
我们选了 Markdown，方便 diff、零迁移。这是当初的决定和权衡…
写代码时 agent 会在任务开始时加载 brain，决策落地后立刻写入 — 全程走 CLI。

查看完整文档 →

常见问题

BRAIN.md 是什么？

BRAIN.md 是一种在仓库中存储项目知识的普通文件约定。它为代理和人类提供一个可预测的位置，用来查找决策、理由、约束和当前项目上下文。

BRAIN.md 与 README.md 或 AGENTS.md 有什么不同？

README.md 通常说明如何理解或使用一个项目。AGENTS.md 通常告诉编码代理如何在仓库中工作。BRAIN.md 指向项目大脑：关于决策原因、当前事实和未来工作上下文的结构化知识。

BRAIN.md 与 MCP 有什么不同？

MCP 是把工具和上下文提供方连接到 AI 应用的协议集成层。BRAIN.md 不是运行时协议，而是仓库本地的 Markdown 约定加一个小型 CLI，让项目知识保持可读、可审查，并由 git 版本化。

为什么要分离 compiled_truth 和 timeline？

compiled_truth 记录某个主题当前最可靠的理解。timeline 记录形成该理解的证据、决策、反转和备注。二者分离后，代理可以快速读取当前答案，同时在需要审计时保留推理历史。

目前支持哪些 Agent 平台？

技能可安装到 Claude Code、Codex、Cursor、Pi 和 OpenCode。任何能读取文件的代理都可以通过 BRAIN.md 使用项目大脑。

setup 或 init 会装上 Claude Code 的 SessionStart hook 吗？

不会。brain setup 和 brain init 都不会写入 .claude/settings.json。init 之后可在项目根目录可选执行 brain install-hooks，仅作用于当前项目：SessionStart 时注入一份精简的 brain list-pages。撤销用 brain uninstall-hooks。