brain.md — AI Coding Agent 的持久化记忆层

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

核心设计与定位

1. 解决的核心问题

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

2. 本地优先与 Git 原生

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

---

运作机制与技能 (Skills)

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

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

---

命令行工具（CLI）命令参考

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，并报告指向不存在页面的空链接。

---

如何开始

1. 全局安装/配置：在全局或本地方便的地方拉取该仓库并执行一次 ./setup 脚本进行全局初始化。
2. 项目初始化：在需要记忆的项目根目录下，执行 brain-setup 初始化脑图骨架。
3. 接入智能体：执行 brain wire 为 Claude Code 或 Codex 生成引导配置文件。