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" updated: "2026-06-20T09:15" ---   ## compiled_truth Use JWT with short-lived access tokens. Session cookies ruled out for API-first clients. See [[api-versioning]].   ## timeline - time: 2026-06-20T09:15 kind: reversal summary: Dropped OAuth — scope creep source: internal-review-2026-06 affects: [auth-strategy, stack]

特性

# 无服务，无 MCP 服务器
# 无需 npm install

$ node brain.mjs ls
运行在普通 Node 上，零依赖
零依赖
不需要 npm install，不需要运行时服务，也没有后台守护进程。一个用 node 运行的零依赖参考 CLI。项目大脑随仓库一起交付。
$ 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
任何能读取文件的代理

4 个可安装技能，
跨代理共享
代理无关
中立命名的开放标准。四个技能安装一次，即可服务 Claude Code、Codex 和任何能读文件的代理。没有厂商锁定。

开始使用

快速开始
# 1. 克隆并全局安装一次 git clone https://github.com/mindmuxai/brain.md cd brain.md && ./setup → 已安装 4 个技能到 ~/.claude/skills # 2. 在任意项目中搭建并播种 /brain-setup # 创建 BRAIN.md + brain/，接入 agent 配置 /brain-bootstrap # 从代码和 git log 播种知识 # 3. 接入 brain CLI brain() { node skills/brain-page/bin/brain.mjs "$@"; } # 4. 只通过 CLI 读写 brain list-pages brain read-page db-choice brain update-truth --id db-choice --summary "为什么改变了" brain reindex && brain lint-links

查看完整文档 →

常见问题

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，更多平台正在陆续开发中。