agentsync MCP server

agentsync

把同一台电脑上多个 AI 智能体的会话记录，按项目目录归到一起，让它们互相能看见彼此做过什么。

English · 部署说明 · 接进智能体的提示词 · 存储格式逆向笔记

---

问题

你在同一个项目 E:\smart_rescue 里：

• 昨天用 Codex 改固件
• 前天用 WorkBuddy 调 Keil 工程
• 上周用 Antigravity 分析架构

它们各自把历史锁在自己的目录里 —— ~/.codex/sessions/、~/.workbuddy/projects/、~/.gemini/antigravity/ —— 互不知情。

于是每次新开一个会话，第一件事都是人肉复述背景："上次那个 BOM 的问题修好了，现在…"

agentsync 解决这件事。三件事：

1. 收集 —— 读各客户端原生存储（JSONL / SQLite / protobuf），归一化成统一的会话模型
2. 归类 —— 用会话里记录的 cwd / workspace_uris，把它挂到具体项目目录上
3. 分发 —— 生成跨智能体交接摘要给任何智能体读；需要主动查询时再显式开 MCP

    ┌─────────────┐  ┌─────────────┐  ┌──────────────┐  ┌────────────┐
    │ Codex       │  │ WorkBuddy   │  │ Antigravity  │  │ CodeBuddy  │
    │ rollout.jsonl│  │ *.jsonl     │  │ *.db+protobuf│  │ *.jsonl    │
    └──────┬──────┘  └──────┬──────┘  └──────┬───────┘  └─────┬──────┘
           │                │                │                │
           └────────────────┴────────────────┴────────────────┘
                                    │  adapters（只读，零副作用）
                          ┌─────────▼──────────┐
                          │  ~/.agentsync/     │
                          │  index.db (FTS5)   │
                          └─────────┬──────────┘
                    ┌───────────────┼────────────────┐
                    │               │                │
         ┌──────────▼────────┐ ┌────▼──────────┐ ┌───▼──────────────┐
         │ 索引库内快照       │ │ CLI 搜索/查看 │ │ MCP server       │
         │ CONTEXT.md + md   │ │ agentsync ... │ │ 需显式注册才生效  │
         └───────────────────┘ └───────────────┘ └──────────────────┘

零第三方依赖，只用 Python 3.9+ 标准库（SQLite + FTS5）。

---

不干扰别的智能体（设计约束）

这是首要约束，不是事后补的优化。四条硬规则，都有测试守：

规则	做法	为什么
不碰别人的数据库	有 -wal 时把 db+wal 拷到自家 tmp 再读；无 -wal 时用 immutable=1 直读	用 mode=ro 打开 WAL 库会在原目录建 -shm，且读事务会让对方无法 checkpoint，WAL 越涨越慢
不往项目里塞文件	快照默认落在 ~/.agentsync/projects/<slug>-<hash>/，要写进项目必须显式 --in-project	项目里多出几十个 md，会被各客户端的 grep / 文件树 / 上下文打包一起读进去
不白占上下文	MCP 默认不注册；要注册执行 mcp --register，5 个工具约 290 tokens	注册后这份 schema 每次请求都要带上，属于每轮都付的固定成本
不做后台常驻	没有守护进程、没有文件监听，只有你敲命令时才跑	不抢 CPU、不抢 IO、不改变任何客户端的启动路径

自检命令（数字都是当场算的，不是写死的）：

agentsync cost      # 上下文占用 / 注册状态 / 冷启动 / 读路径副作用
agentsync mcp --unregister    # 反悔：一键恢复到零开销

回归测试 tests/test_isolation.py 会断言：读 WAL 库不新增文件、能读到未 checkpoint 的数据、临时副本清理干净、导出默认不写项目目录。

---

快速开始

三种装法，任选：

# ① 单文件版，下载即用，不用装（需 Python 3.9+）
#    https://github.com/landerli107/agentsync/releases/latest
python agentsync-0.5.0.pyz scan

# ② 源码
git clone https://github.com/landerli107/agentsync.git
cd agentsync

# ③ 装成命令
pip install -e .

跑起来：

agentsync doctor                       # 体检：哪些客户端能读到
agentsync scan                         # 建索引（首次几秒，之后增量 ~1.6s）
agentsync projects                     # 看哪些项目被智能体碰过
agentsync sync --project E:/myproject  # 生成跨智能体交接摘要
agentsync path --project E:/myproject  # 摘要文件在哪（给智能体提示词用）
agentsync search "BOM"                 # 中文全文搜索
agentsync show codex:01a17d4a          # 看某个会话全文
agentsync cost                         # 对客户端/模型的实际影响面

上面的 agentsync 换成 python agentsync.py 或 python agentsync-0.5.0.pyz 同样有效。

装完之后还要让智能体知道怎么用：见 把 agentsync 接进智能体 —— 含可直接复制的提示词，以及为什么默认用「项目指令文件」而不是 MCP。

产出的目录长什么样

~/.agentsync/projects/e-your-project-1a2b3c4d/    ← 默认落点，不写进你的项目
├── CONTEXT.md          ← 跨智能体交接摘要（新会话先读这个）
├── index.json          ← 机器可读清单
└── sessions/
    ├── codex/2026-10-28_整理一下项目结构_3013ca63ba3f.md
    ├── workbuddy/2026-11-02_打开Keil和VSCode工程_262687f55c.md
    └── antigravity/2026-11-04_Embedded-Firmware-Code-Explanation_e50716c6a441.md

想让它在项目目录里出现（方便智能体在文件树里看到），加 --in-project：

agentsync sync --project E:/myproject --in-project   # → E:/myproject/.agentsync/
agentsync path --project E:/myproject                # 随时查它到底在哪

CONTEXT.md 里放的是能直接读的摘要，不是原始日志堆砌：

## 各智能体最新状态

### codex · 2026-11-04 01:14 · 6 个会话
- 最近会话：**你现在是否还保存了原厂的全套搜索程序和流程？**（145 条消息）
- 用户最后提出的问题：请你把原厂的程序修复实现闭环，自己测好…
- 该会话最后回复要点：22 个场景通过，包括红蓝正常取放、空抓、掉球…

### workbuddy · 2026-11-02 00:06 · 17 个会话
- 最近会话：**打开Keil和VSCode工程**（73 条消息）
- 该会话最后回复要点：**根因是 project.uvprojx 带了 UTF-8 BOM**，
  Keil 的老解析器直接拒绝读取…

## 最近活动时间线
| 时间 | 智能体 | 会话 | 消息 |
|---|---|---|---|
| 2026-11-04 01:14 | codex | 原厂搜索程序闭环 | 145 |
| 2026-11-02 00:06 | workbuddy | 打开Keil和VSCode工程 | 73 |

## 可能未收尾的线索
- [codex] 毕设任务分解 → 夹取机构尚未完成装车验证，整机只能验收到"到达待夹取位置"

支持的客户端

客户端	数据来源	可读内容
WorkBuddy	~/.workbuddy/projects/<slug>/*.jsonl	完整对话 + 工具调用 + AI 标题
WorkBuddy AI	~/.workbuddy-ai/projects/...	同上
CodeBuddy	~/.codebuddy/projects/...	同上
Codex	~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl	完整对话 + 工具调用
Antigravity	~/.gemini/antigravity/conversation_summaries.db + conversations/*.db	标题、项目、时间、用户提问
Claude Code	~/.claude/projects/...	完整对话
Gemini CLI	~/.gemini/tmp/*/chats/*.json	完整对话
Trae / Trae CN	%APPDATA%/Trae*/User/**/state.vscdb	尽力解析
任意客户端	~/.agentsync/inbox/*.md	手动/脚本投递通道

MCP：让智能体自己去查

python agentsync.py mcp     # stdio，newline-delimited JSON-RPC

工具	作用
search_sessions	跨客户端全文搜索，可限定项目
get_session	按 sid / 标题取完整对话
project_history	取某项目的跨智能体摘要
recent_activity	最近 N 小时各智能体动了哪些项目
list_projects	列出所有被访问过的项目

MCP 是可选的显式动作，默认不注册：

agentsync mcp --register                 # 写入 ~/.workbuddy/mcp.json（自动备份原文件）
agentsync mcp --register --config <路径> # 其他客户端（Claude Desktop / Cursor / CodeBuddy）
agentsync mcp --unregister               # 一键撤回，上下文占用回到 0

注册后由命令行自己起服务，等价于手写：

{
  "mcpServers": {
    "agentsync": {
      "command": "python",
      "args": ["/绝对路径/agentsync/agentsync.py", "mcp"]
    }
  }
}

代价：5 个工具约 290 tokens 进每次请求，进程冷启动约 200ms。改完要在客户端的连接器管理页对新 MCP 点「信任」才生效。

不想付这份开销也有替代方案：直接让智能体读摘要文件，或者让它自己敲 agentsync search "关键词" —— CLI 的输出只在真正调用时才进上下文。

为什么不用现成的

项目	覆盖	为什么不够用
SpecStory	Cursor、Claude Code、Gemini CLI、Copilot	不认识 Codex / Antigravity / WorkBuddy / CodeBuddy；桌面端已转商业化
claude-code-log	仅 Claude Code	单客户端，无跨客户端归一化
ccusage	仅 Claude Code	统计 token 用量，不是会话同步
ChatLog	微信	场景不同

现实是：每个智能体客户端的存储格式都不一样，没有通用项目能覆盖全家桶。agentsync 的做法是给每家写一个薄适配器，归一化成同一个模型 —— 加新客户端只需要加一个类。

实测数据

在一台长期使用的开发机上（Windows 11，Python 3.13）：

• 全量索引 232 个会话 / 11,124 条消息，5.8 秒
• 增量扫描（无变化）1.3 秒
• 单项目跨 3 个客户端 25 个会话，CONTEXT.md 生成 0.2 秒

已知限制

• Antigravity 的模型回复在磁盘上是加密/压缩的，只能稳定拿到用户提问、标题、项目、时间。要全量回复请走 inbox 通道或在客户端里接 MCP。
• Trae 尚未打通：state.vscdb 里只有配置键，聊天正文位置没定位到，适配器已留占位。
• Codex 续聊会为同一 session_id 写新的 rollout 文件，agentsync 按文件名时间序合并并做「后缀-前缀重叠」去重，不会丢历史。
• 只做读取，不修改任何客户端的数据。

开发

python -m unittest discover -s tests -v   # 26 个测试

agentsync/
├── agentsync.py      CLI 入口
└── asx/
    ├── adapters.py   各客户端存储适配器（加新客户端改这里）
    ├── store.py      SQLite 索引 + FTS5 trigram
    ├── export.py     Markdown 镜像 + CONTEXT.md
    ├── scan.py       增量扫描编排
    ├── mcp.py        MCP stdio server
    ├── pb.py         无 schema protobuf 文本抽取
    ├── model.py      Session / Msg 归一化模型
    └── util.py       路径/时间/文件名工具

License

MIT