brain.md：把项目决策留给下一次编码代理

它解决什么问题

brain.md 是一个面向编码代理的持久化记忆层。它不把项目知识放在某次聊天或某个模型会话里，而是把值得长期保留的决策、需求、约束和取舍写成仓库中的 Markdown。项目 README 将它描述为一个开放、代理无关的标准：只要代理能够读取文件，就可以按 BRAIN.md 中的约定使用这份项目记忆。

它适合经常切换 Claude Code、Codex 或其他文件型编码代理的个人开发者，也适合多人维护、需要让新会话快速理解背景的团队。它尤其关注“为什么这样做”和“哪些路已经被否定”，而不是把代码中已经能直接读出的实现细节再抄一遍。

已知功能

安装工具后，项目可以通过 brain init 创建 BRAIN.md、初始化 brain/ 数据，并接入 CLAUDE.md 与 AGENTS.md。已有配置文件不会被整文件覆盖，而是更新标记的 brain 区块。仓库说明还提供了 bootstrap、页面读写、索引和链接检查等工作流，用于在开发过程中加载相关页面、记录新决策，并在决策被推翻时留下反向记录。

brain CLI 是唯一写入入口。页面包含可重写的 compiled_truth，以及追加式 timeline；更新当前理解时，同时记录形成该理解的证据。这样的结构让“当前结论”和“结论如何形成”分开保存。项目也支持通过 brainRoot 将记忆目录重定向到外部 sidecar，而不是固定在默认的 ./brain。

v0.4.0 的一个明确变化是根页面按需创建。新项目初始化后不再自动铺设六个空模板；只有在确实有内容时，update-root 才创建 background、architecture、flow、mindmap、stack 或 roadmap 页面。这能减少空文件，但也意味着初始化并不等于完成知识整理，使用者仍需主动播种真实内容。

采用前的限制

它是 toolkit，不是预填充好的项目知识库。brain init 只搭建协议和骨架，现有项目还需要通过 bootstrap 或人工整理，才能形成有价值的页面。Markdown 也意味着内容质量依赖团队是否持续维护；CLI 能约束写入结构，却不能替团队判断哪些信息值得长期保留。

Codex 钩子存在明确环境边界：README 将 Codex CLI 0.153.4 或更高版本列为支持基线，并要求 Node 18+、POSIX shell 与 awk；原生 Windows shell 不受支持。生成的命令包含绝对项目路径，移动项目或切换到独立 clone/worktree 前需要卸载并重新安装钩子。钩子只输出页面元数据，正文仍需按需读取；Codex 执行时间还有五秒限制。

另一个部署考虑是版本与配置治理。brain 数据会进入仓库或外部 sidecar，团队应先决定其存放位置、提交策略和敏感信息边界。来源没有提供性能、最低硬件要求或安全保证，因此不能把它视为自动解决上下文质量、机密管理或代理正确性的系统。

结论

如果你的痛点是编码代理每次会话都忘记项目决策，brain.md 提供了一条朴素路径：用 Markdown 保存长期事实，用 CLI 记录变化，再让不同代理读取同一份协议。它更像项目知识维护工具，而不是自动记忆服务；是否值得采用，取决于团队能否把维护 brain 纳入日常开发。仓库标注为 Apache License 2.0，具体版本采用前仍应按自身流程审阅。

资料来源

• GitHub repository metadata
• Project README
• Official release
• Official project page

资料核对日期：2026-10-20