brain — the recorder

brain-mcp — AI 对话记录器

你的 AI 历史记录正在被删除。 Claude Code 会在启动时删除超过 cleanupPeriodDays（默认 30）天的会话文件。运行以下命令，看看你的历史记录会从哪里开始消失：

# macOS
find ~/.claude/projects -name '*.jsonl' -exec stat -f '%Sm  %N' -t '%Y-%m-%d' {} + | sort | head -3
# Linux
find ~/.claude/projects -name '*.jsonl' -printf '%TY-%Tm-%Td %p\n' | sort | head -3

你看到的最早日期，就是历史记录的终点。brain-mcp 会在记录消失前将其保存下来——包括整个会话、子 Agent 记录和已保存的工具输出，逐字节精确保留、经过内容哈希校验并存储在本地；你可以通过引用查询，并使用 sed 和 shasum 验证；它还会告诉你哪些内容已被删除，并将其恢复。

如果 Claude Code 删除了记录

brain-mcp health          # the receipt: "3 session(s) and 41 file(s) are gone from where the
                          #   agent kept them; the floor holds every one" — each re-hashed
                          #   against the manifest when the recorder first noticed it
brain-mcp restore --list  # what can be put back
brain-mcp restore <id>    # writes the session (and its folder) back, byte-exact, then:
                          #   cd <its working directory> && claude --resume <id>

restore 绝不会覆盖不同的字节（字节相同则不做任何操作），操作要么全部完成，要么全部不做，并支持 --dry-run 和 --to <dir>。它仅是一个 CLI 子命令——没有 MCP 工具会在数据底座之外写入内容。

安装

pipx install brain-mcp           # or: uvx brain-mcp
brain-mcp install cc             # CC hooks + 60-second scheduler
brain-mcp serve                  # the MCP server (stdio) — add to your client config

也可以作为 Claude Code 插件安装（通过一个步骤同时安装 hooks 和服务）：

/plugin marketplace add mordechaipotash/brain-marketplace
/plugin install brain

功能

• 在源头捕获。 通过 Stop/SessionEnd hooks 捕获 Claude Code 会话（增量行 + 最终快照）；通过每 60 秒一次的轮询扫描捕获 Codex、Pi，以及 Claude Code 会话自身文件夹中的所有内容（子 Agent 和工作流记录、.meta.json、tool-results/）。共用一个暂存区和一个数据底座。
• 保留字节。 数据底座位于 ~/.brain/lake/<lane>/<session>.jsonl——只追加，与原文件逐字节相同，并附有只追加的 sha256 清单。不会解析后丢弃任何内容；DuckDB 索引是缓存，可完全从数据底座重新生成。
• 提供引用，或明确弃答。 每条搜索结果都附带 {file, line span, sha256}，任何人都可以用 sed -n 'A,Bp' file | shasum -a 256 验证，无需数据库。无结果时，会明确弃答，并列出实际搜索过的通道和日期。
• 如实报告健康状态。 fresh 表示数据底座包含 Agent 文件中显示的全部内容；stale 表示 Agent 文件中有记录器未捕获的内容；unknown 表示尚未测量，而非健康——绝不会将其归为“看起来没问题”。
• 提供可验证的备份。 brain-mcp backup <dest> 会同步数据底座和清单，并在目标位置重新计算抽样文件的哈希。验证可能失败；这正是这样设计的原因。
• 永远只进行一次网络获取，而且与用户无关。 没有遥测、云服务、账户，也没有 HTTP 客户端。例外是：首次构建索引时，DuckDB 会从 DuckDB 自有的扩展仓库下载其全文搜索扩展（fts），并将其缓存在 ~/.duckdb 下。brain-mcp install 会提前进行此下载并说明这一点；brain-mcp doctor 会报告该扩展是否已缓存。

7 个 MCP 工具

工具	说明
brain_search	对所有记录进行 BM25 搜索；返回带引用的结果，或明确弃答
brain_get	获取引用对应的原始行，并验证 sha
brain_recent	按时间顺序显示近期活动，每行均带引用
brain_sessions	按日期/Agent 显示会话卡片
brain_health	按通道报告来源与数据底座的新鲜度（unknown ≠ healthy），并提供 Agent 删除内容的记录凭据
brain_capture_status	检查记录机制本身是否正常运行（暂存区、心跳、数据底座）
brain_backup	创建经过验证的备份；只在数据底座之外写入

🤖 致 AI 助手

你正在阅读此内容，是因为你的用户在运行 THE RECORDER，并让你访问他们的 AI 历史记录。这是诚信约定。

唯一规则：你从这些工具中陈述的所有内容，都必须附带引用或明确弃答——没有第三种情况。 附带引用的说法必须包含可核查的指针（文件 + 行范围 + sha256）；在据此推理前，先用 brain_get(expect_sha256=...) 验证。明确弃答表示“在工具测量的范围和日期内，未找到达到阈值的内容”——并不表示“这件事从未发生”。绝不要用自己的猜测填补弃答。

• 将回忆作为他们的话呈现，并注明日期：“你在 2026-08-19 写道：‘…’（sess-7f2a.jsonl:412）”——绝不要说成是你自己的知识。一条说法配一条引用。
• brain_get 返回 verified: false，意味着索引后底层记录发生了变化。请直截了当地说明这一点。
• 健康状态响应中只要有任何 unknown 通道，就绝不能说“看起来一切正常”。诚实的说法是：“2 个通道数据新鲜，1 个过期，1 个未测量。”
• “我对 X 是怎么想的” → brain_search(query, role="user")。这会返回此人写下的内容：在 harness 以 user 角色注入的文本（已测量，其中四分之一到三分之二的“user”行属于此类，包括技能正文、提醒、斜杠命令包装文本、压缩摘要、Codex 上下文块）默认会被排除，除非传入 include_machine=True；子 Agent 记录也会被排除，除非传入 include_subagents=True。“我的想法是如何演变的” → 添加 order="time_asc"；使用 since / until 限定范围。服务端不会对你的用户的想法发表意见；它保存的是他们的话，并附有凭据。

底层记录格式

~/.brain/
  spool/<lane>/                 hooks + scanner write here (atomic, dot-tmp invisible)
  lake/<lane>/<session>.jsonl   THE FLOOR: append-only, byte-identical to the origin;
                                a rewrite opens <session>.g2.jsonl — old kept, never deleted
  lake/cc_sessiondir/<project>/<session>/...   a CC session's folder, mirrored at the
                                same relative paths (subagents/, tool-results/, *.meta.json)
  manifest/manifest.jsonl       one versioned line per chunk: byte range, line range, sha256
  offsets/<lane>/<session>      hook fast-path line counters
  health/*.last_run             side-effect heartbeats (mtimes are the proof, never a report)
  brain.duckdb                  the index — a cache, re-derivable from lake/ + manifest/

Agent 保存对话记录的位置：Claude Code ~/.claude/projects/**/*.jsonl（滚动窗口！）、Codex ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl、Pi ~/.pi/agent/sessions/**/*.jsonl。

其他动词

brain-mcp record                  # one capture tick (the scheduler runs this every 60s)
brain-mcp health [--exit-nonzero-on-stale]   # cron-able
brain-mcp doctor                  # capture status, health, fts cache, the receipt, runaway generations
brain-mcp restore [<id>] [--list] [--to DIR] [--dry-run]   # put a deleted session back
brain-mcp redact <file> --lines A B --reason "..."   # tombstone a secret; audited in manifest
brain-mcp migrate-v1 <all_conversations.parquet>     # import v1 data (marked v1_derived)
brain-mcp uninstall               # removes hooks + scheduler; your floor is KEPT

v1 → v2

v2 围绕一个原则重新构建：先捕获字节，再推导其他一切。 v1 将对话解析为 parquet 并丢弃原始内容——v2 的底层记录格式从结构上杜绝了这种情况。v1 的 25 个工具缩减为 7 个：合成类工具（“认知模式”“切换成本”）已移除，因为无法附带行范围引用的说法，不是本服务会作出的说法。迁移：brain-mcp migrate-v1——v1 的记录会保留并标记为派生数据；只要源数据仍存在，就优先采用有底层记录支持的内容。

Windows：不在 v2.0 的支持范围内。定时任务使用 LaunchAgent（macOS）/ systemd 用户定时器（Linux）。

MIT。