brain.md — AI 编码智能体持久化记忆层

brain.md 是一个开源工具包，旨在为 AI 编码智能体（如 Claude Code、Codex 等）提供持久且规范的文件级记忆层。它通过在项目代码库中维护一组纯 Markdown 文件，帮助智能体记住项目的关键决策、需求和开发约束，从而避免在会话结束时丢失宝贵的设计上下文。

核心设计与定位

在传统的 AI 辅助开发中，智能体在每次启动新会话、更换模型或切换工具时都会面临「失忆」问题。所有的历史决策、架构选型、踩坑记录等，如果只存在于之前的聊天上下文中，就会在新会话中荡然无存。brain.md 允许将这些经过「深思熟虑」的结果直接持久化在项目本身中。

Git 协同： 记忆数据以纯 Markdown 格式直接保存在项目的 /brain（或 /brain.md）文件夹中，随 Git 一起提交和同步。任何能够读取文件的 AI 智能体都能在新会话中立刻恢复项目上下文，完全无平台绑定，无锁定数据库，无迁移成本。
极简 CLI： 提供零依赖的 Node.js 命令行工具（CLI），确保所有的写入操作都符合既定的 Schema，做到「构造即正确（correct-by-construction）」，无需复杂的校验逻辑。
编译态事实 + 时间线链条： 每个 Page 文档都包含两部分：
1. compiled_truth（编译态事实）： 代表对当前项目这一主题的最新、最全的理解。
2. timeline（时间线）： 记录这一理解是如何一步步演进的，包括所有重大的决策、事实观测和逆转（reversal）记录。

brain.md 核心由三个核心技能驱动：

brain-setup：初始化项目的记忆层，脚手架生成初始的目录结构和根页面（Root Pages，如 background.md, architecture.md 等）。
brain-bootstrap：从现有的项目代码、文档或仓库中自动提取、推理并初始化最基础的项目背景知识。
brain-page：通过 CLI 命令行工具进行 Page 的读取、创建、更新编译态事实和追加时间线记录等日常操作。

brain.md 提供了一个零依赖的 Node 命令行工具，开发者或智能体可以直接在项目根目录运行（通常通过 node skills/brain-page/bin/brain.mjs 或映射的别名 brain 执行）：

命令	描述
`brain brain-dir`	解析并输出当前项目的 brain 文件存放目录（默认为 `./brain`，可在 `.mindmux/preferences.json` 中自定义）。
`brain list-pages`	列出当前 brain 中所有已启用的 Page 页面列表。
`brain read-page <id>`	读取并显示指定 ID 页面（不含扩展名）的完整内容（含 frontmatter, compiled_truth, timeline）。
`brain create-page --id <id> --category <category> --title "<title>"`	创建并生成标准结构的全新 Page。类别可选：`project`, `concept`, `decision`, `person`, `reference`。
`echo "new truth" \	brain update-truth --id <id> --summary "<why>"`	原子性地重写某个 Page 的 `compiled_truth` 事实部分，并自动在时间线中追加一条更新缘由（summary）。
`brain wire --agent claude-code,codex`	将特定 AI 智能体的控制入口（如 `CLAUDE.md` 或 `AGENTS.md`）与 `BRAIN.md` 关联起来，使智能体启动时自动获知如何阅读与维护项目的脑图。
`brain reindex`	重新扫描并重建 `brain/index.md` 索引文件。
`brain lint-links`	检查并扫描脑图页面中所有以双括号 `[[page-id]]` 形式定义的 Wiki-link，并报告指向不存在页面的空链接。