agent-milestone

MCP server 项目（MCP-native）：给 Agent 的对话/任务轨迹做 git 式版本控制——让每次和 Agent 的协作都能「记住、回看、分支、对比、重放、留档」。

项目介绍

agent-milestone 是一个 MCP-native 的 Agent 轨迹版本控制系统。

它把 Agent 的对话、工具调用和任务过程抽象成 Git 的同一套模型：

step         = 不可变对象（user / assistant / tool call / tool result）
step hash    = SHA-256 内容寻址
parent_hash  = 把 step 连成一条任务轨迹
milestone    = 命名 ref，指向某个 step
branch       = 另一个 ref，从某个 milestone 分叉

在这个模型上提供：

• 版本控制：checkpoint / checkout / branch / diff / rollback / undo

• 轨迹重放：replay dry-run，只输出工具调用计划，不执行工具

• 历史管理：reflog / rename / delete / gc / prune

• 自动记录：Claude Code SessionEnd hook 自动解析 transcript

• Agent 接入：MCP server，让 Agent 主动调版本控制工具

• 本地控制台：GitHub 风格分支树、folder/branch/tag 图标、Diff 标签页

• 隐私优先：本地 SQLite + 写入前密钥脱敏

可以这样理解：

Git 管代码；agent-milestone 管 Agent 的对话、工具调用和决策轨迹。两者可以配合使用：Git 记录代码状态，agent-milestone 记录当时 Agent 做了什么、为什么这么做。

它适合：

• Claude Code / Codex / MCP Agent 的长期任务

• 多方案排查：同一问题分叉成不同 branch

• 复盘和审计：回到某个 milestone，看当时完整工具调用

• 安全回滚：移动 ref 指针，不删除历史 step

• 导出留档：把轨迹渲染成 Markdown 提交到 GitHub

Related MCP server: palinode

为什么做

每次和 agent 对话、跑任务之后，都会忘记「当时到底在做什么」。想要一个长期的里程碑：能记住、能回看、能撤回、能导出留档。

定位

• 做什么：MCP server，给 Agent 的任务轨迹做 git 式版本控制。

  • 核心：checkpoint 存里程碑 / checkout 回看 / export 导出 markdown

  • 版本控制：branch 分叉 / diff 轨迹对比 / replay 安全重放计划

  • 管理：list_milestones / rename / delete / gc / prune / reflog

• 差异化：Atlas 管代码（ACP-first），本服务管对话轨迹（MCP-native）。

• 不做什么：多租户、云端同步——刻意不做，本地优先 = 隐私 + 工程判断。

核心模型（git 的同一套技巧）

不可变对象 + 指针：

• step：轨迹的最小单元——一条 user/assistant 消息、一次 tool 调用或 tool 结果。内容寻址（SHA-256）。

• 每个 step 通过 parent_hash 链接成一条链，链就是一次任务的轨迹。

• milestone（checkpoint）：一个命名指针，指向某个 step 的 hash。

• 分叉天然免费（branch 只是另一个指针）；diff 便宜（走两条链回到分叉点）。

组件

安装

cd agent-milestone
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"   # 运行 + pytest/ruff 开发依赖
# 或最小安装：pip install -e .

使用

路径 0：本地 Web 控制台（人用）

python ui.py
# 或安装后：
agent-milestone-ui

打开 http://127.0.0.1:8765，可以在浏览器里完成：

• 浏览所有 milestone / branch

• 查看完整轨迹

• 新建 checkpoint

• 从任意 ref 新建 branch

• 把 milestone 移动到某个 branch 文件夹

• 选择两个 ref 做 diff

• replay dry-run

• 回滚到指定 ref / 撤回上一个操作

• rename / delete

• 查看 reflog

• 导出 Markdown

• GC dry-run

路径一：自动记录（SessionEnd hook）

在 Claude Code 的 settings.json 配 SessionEnd hook 指向 record.py，每次会话结束自动把整段对话轨迹解析成 step 存库，无需手动操作：

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          { "type": "command", "command": "python3 /path/to/agent-milestone/record.py" }
        ]
      }
    ]
  }
}

路径二：主动版本控制（MCP 工具）

把 server.py 注册成 MCP server 后，agent 在对话里像开发者用 git 一样主动调。

checkpoint(name, steps) -> str —— 存档

• 输入：一个名字 + 一段轨迹（step 列表）

• 做什么：把轨迹存进 SQLite，给最后一步打上这个名字

• 返回：tip hash（前 12 位）

• 类比：git commit -m "对账排查"

checkout(name) -> list[dict] —— 回看 / 撤回

• 输入：里程碑名字

• 做什么：按名字找到指针，沿 parent_hash 往回走，还原整条轨迹

• 返回：轨迹（第一步 → 最后一步）

• 类比：git checkout 对账排查

export(name) -> str —— 导出留档

• 输入：里程碑名字

• 做什么：把轨迹渲染成 markdown

• 返回：markdown 文本，可直接 commit 到 GitHub

• 类比：git log 排版成文档

branch(name, from_ref) -> dict —— 分叉

• 类比：git branch feature main

• 分支只是另一个 ref，不会复制 step。

diff(left, right) -> dict —— 轨迹对比

• 沿两条链回溯到共同前缀，返回 fork hash、左独有、右独有 step 摘要。

replay(name) -> dict —— 安全重放

• 默认 dry-run，只返回工具调用计划，不执行任何工具。

• 需要真实执行时由调用方自己接 executor。

reflog(name?) -> list[dict] —— ref 历史

• checkpoint / branch / rename / delete / prune 全记录。

gc(dry_run=True) / prune(...) —— 存储回收

• gc 删除没有任何 ref 可达的 step。

• prune 按时间或保留数量清理旧 ref，再触发 gc。

rollback(name, to_ref) / undo_last(name) —— 回滚

• rollback 把 ref 指针移回指定 milestone/branch，不删除历史 step。

• undo_last 沿 reflog 撤回最近一次 checkpoint/rollback。

set_parent(name, parent_ref) —— 分支文件夹

• 把已有 milestone/branch 移动到某个 branch 文件夹下，控制台会按树形展示。

隐私与存储

• 默认写入前脱敏 API key、Bearer token、password、Redis/Postgres 连接串。

• DB 路径可通过 AGENT_MILESTONE_DB 覆盖。

• 不想同步 iCloud 查看页时设置 AGENT_MILESTONE_AUTO_ICLOUD=0。

存储

统一存到 ~/.claude/agent-milestone/milestones.db（store.py 里的 DEFAULT_DB_PATH），record.py 和 server.py 都引用它。

验证

python store.py      # 自检，应打印 self-check ok
python test_e2e.py   # 端到端：checkpoint → checkout → export
python view.py       # 生成 trails.html 轨迹查看页（浏览器直开，看所有里程碑+step）

操作手册

出问题先查 RUNBOOK.md，每条 = 症状 → 原因 → 处理。

状态（2026-10-08 阶段 2 + 本地控制台已跑通）

阶段 1 + 阶段 2 + 本地控制台已完整验证：store 自检、pytest、工具级端到端、以及新会话里 Agent 通过 MCP 实际调用核心工具。

已完成并验证 ✅

断点（阶段 1 收尾必做，全部关闭）

1. DB 路径不合一 ✅ 统一到 store.py 的 DEFAULT_DB_PATH。

2. record.py 真实 .jsonl 解析 ✅ 真实 transcript 解析 413 步、tool 关联 100%。

3. server.py 注册后 agent 实际调用 ✅ 2026-09-08 新会话实际调用验证通过。

下一步（roadmap）

• 阶段 2：branch / diff / replay / reflog / gc / prune

• 本地 Web 控制台：分支树 / folder 图标 / Diff tab / 回滚 / 导出

• 阶段 3：真实 demo 视频、pipx/uvx 安装体验、发布到 PyPI

• 数据库加密 / retention 策略

铁律

阶段 1 没跑通之前，任何新功能都不许加。