你的 coding agent 会忘事,给它一个不会忘的大脑

一个开放的项目记忆标准——把项目的持久知识写成纯 Markdown,任何 coding agent 都能通过一个小巧的 CLI 读写,并随你跨 agent、跨机器、跨模型一路带着走。

·Joyqi·1 分钟阅读

你花了一下午,和一个 coding agent 把一件真正要紧的事敲定:为什么选 Markdown 而不是 SQLite、为什么砍掉方案 B、这一版的「做完」到底指什么。推理很扎实,取舍权衡过了,结论也拍了。

然后,会话结束。

第二天开个新会话——或者换台机器、从 Claude Code 切到 Codex——agent 又把同样的问题问了一遍:这个项目是干嘛的?为什么不用 B?这个我们不是早就定了吗?不是模型不行。只是它从来没有一个能持久存放结论的地方。代码留下了,背后的「为什么」却蒸发进了一段再没人打开的聊天记录。

所以我们针对这块缺失做了一个小标准,并开源了它:brain.md。

它是什么

brain.md 给项目一个大脑——它的持久决策、需求和约束,写成纯 Markdown,留在仓库里,熬过每一次会话。

开箱即得两样东西:

  • 一份契约 —— 项目根目录下一个 BRAIN.md 文件,告诉任何 coding agent 这个大脑该怎么用。agent 只要读这个文件,就知道该怎么用它。
  • 一套工具 —— 一个小巧的 brain CLI,外加几个装一次就好的 skill,负责搭建和维护这个大脑。

大脑本身只是仓库里的一堆 Markdown 文件——动手前不需要先启动任何服务。它脱胎于 MindMux——我们的项目大脑工作台,MindMux 通过 MCP 等一整套能力来驱动大脑。而 brain.md 是其中开放的那一层:格式与契约,让任何能读文件的 agent 都能拥有一个大脑——配合 MindMux,或者只用你的编辑器和一个终端,都行。

一个大脑长什么样

它是一个装着 Markdown 的 brain/ 目录,里面有两种文件。

Root pages(根页面) —— 固定六个,一眼看清整个项目:background、architecture、flow、mindmap、stack、roadmap。这些只更新,不新建。

Pages(页面) —— 每个承载一个持久的知识单元:一个决策、一个概念、一个人、一份参考。边走边建,数量不限,没有繁文缛节。

一个页面之所以不只是「便签」,靠的是它的结构。每个页面有两层:

  • compiled_truth —— 当前最佳理解,可以整体重写。
  • timeline —— 只增不改的轨迹,记录这个理解是怎么形成的。

一层让你往前走,一层让你能回溯。当你推翻过去的判断时,你不会偷偷改掉历史——而是往 timeline 追加一条 reversal,让这次「改主意」留在记录里。

设计赌注:文件 + 一个 CLI

这些单拎出来都不是新点子。AGENTS.md 和 CLAUDE.md 早就能给 agent 下常驻指令。brain.md 的赌注更窄,但我觉得更有用:让记忆有结构,并且 correct by construction(从构造上就保证正确)。

机制是这样的:读和写都走 brain CLI——你永远不手动编辑大脑文件。听起来像个限制,其实这正是关键。因为 CLI 是唯一的写入者:

  • frontmatter 永远由程序生成,不会变形为无效格式。
  • 重写 compiled_truth 和往 timeline 追加那一条,发生在同一次原子写入里——所以理解绝不可能在不留痕迹的情况下被改动。

第二条才是要害。一个知识库最常见的腐烂方式,是一次悄无声息的编辑:有人改了结论,背后的理由却丢了。把每次写入都收敛到一条命令上,这种失败模式就在结构上不可能发生。brain.md 里没有 validator,因为已经没什么需要 validator 去兜底的了。

到底有什么不同

如果你用过相近的工具,这里是诚实的对比。

  • 对比扁平的 CLAUDE.md / rules 文件 —— 它们很适合放指令,但那是一大团你手工维护、不断膨胀的文本。大脑是有结构、可寻址的知识,自带审计轨迹。是不同的活儿。
  • 对比活在某个工具里的记忆 —— 向量库、模型自带的记忆、托管服务:它们是构建在你知识之上的运行时。而大脑是知识本身那一层——git 里的纯文件,能在 PR 里 diff,人、agent 或 grep 都能读。在它上面加一层运行时(MindMux 就这么干,走 MCP;更多工具也可以),知识依然属于仓库,而不是工具。
  • 对比存聊天记录 —— 聊天记录是过程,大脑是结论。你要的不是把每句原话找回来,而是那少数几条你以后还用得上的判断。

也不绑死在某个模型或工具上。契约是一个文件,所以同一个大脑在 Claude Code、Codex,以及你下一个要用的东西之间通用。

看它跑起来

工具装一次:

./setup        # 把 skills 接到你选中的每个 agent(~/.claude、~/.codex、…)

然后在任何项目里,agent 会搭好并播种一个大脑(brain-setup,再 brain-bootstrap),接下来就自然而然了。真正的回报体现在跨会话的时候:

你     配置就用 Markdown 存,别用 SQLite —— 更好 diff,迁移也省事。

Agent  这就把它记成一条 decision,让它熬过这次会话。
       $ brain create-page --id config-as-markdown --category decision \
             --title "Store config as Markdown, not SQLite"
       ✓ page created · indexed

—— 三周后,一个全新的会话 ——

你     配置为什么不用数据库?

Agent  $ brain read-page config-as-markdown
       我们当初选 Markdown 是为了好 diff、零迁移。这是最初的决定,
       以及我们权衡过的取舍……

不用再解释一遍。下一段对话直接从你已经敲定的地方接着走。

试试看

大脑是项目的记忆,不是某个模型的记忆。下个月换一个 agent,留下来的还是这个大脑。

如果这正是你遇到的问题,大概五分钟就能体会到:

如果你注意到的第一件事是「这些我居然不用再解释一遍了」,那它就生效了。这就是我们做它的原因。

Share to