大家好，我们是 agentctxsync（Agent Context Sync）的作者，道荣和露。这个项目最近开源了，写篇文章介绍一下，顺便记录一下做这个东西的过程。

• 起因很简单，我们俩都是 AI 工具的重度用户，Hermes、Codex、opencode 换着用。用得越多，越被一个问题困扰：AI 的记忆是"绑设备"的。

白天在公司电脑上跟 AI 聊了一下午，上下文很完整，AI 对我们的项目背景门儿清。晚上回家打开笔记本，同一个工具，它完全不记得我们是谁。喂过的上下文、聊过的方案，一夜归零。换一个 Agent 更甚，Hermes 里聊的活儿，Codex 一点都不知道。

搜了一圈，没有现成好用的方案，索性自己写了一个。就是 agentctxsync。

它是什么

• 一句话：把 AI 会话跨设备、跨 Agent 同步起来。在公司电脑上跟 Hermes 聊的会话，回家可以在另一台电脑的 Codex 里接着聊。

• 架构不复杂，两头：

• 本地：每个 Agent 挂一个 MCP 客户端，负责读写这个 Agent 自己的存储格式，SQLite、JSONL、JSON 文件都行；

• 服务端：自己部署，FastAPI 加 PostgreSQL，管所有同步，带一个中英双语的 Web 管理界面。

• 目前支持 6 种 Agent：Hermes、OpenAI Codex、opencode、Reasonix、OpenClaw、WorkBuddy。每种对应一个适配器，新增 Agent 只需要写一个新的适配器，服务端和同步引擎不用动。

设计取舍，说几个我们花了心思的地方

同步要稳。这是核心，我们最怕数据同步出幺蛾子。启动自动增量拉取，首次配对自动引导推送，之后每 5 分钟双向同步一次。跨设备续写只推新增消息，消息按会话、角色、时间戳三元组去重，幂等。大批量同步自动分批，拉取每批 15 个会话，推送按会话数和消息数双上限切分，不会把请求撑到超时。

多租户要隔离得干净。多用户、多 Workspace，每个空间独立 API Key。管理员能管用户、管邀请码，但看不到任何用户空间里的会话和消息。这个边界是原则问题，个人数据托管在别人服务器上的时候，这条不能含糊。

Web 界面也做了。中英双语，有信息概览、跨工作空间的全部会话列表、Markdown 会话查看器、回收站、导出导入。删错能捞回来，数据能导出成 Markdown 或 JSON.gz，用户想换地方，数据随时带得走。

客户端自动更新。从服务器拉新版，逐文件 SHA256 校验，通过后原子替换，留一份旧版备份，升级失败可回滚。自己搭过类似系统的人都知道，这块最容易翻车。

• 📷 此处插入截图：信息概览 — 工作空间、同步状态、配额与最近会话（docs/screenshots/02-dashboard.png）复制后请在知乎编辑器里重新上传此图

开发中踩过的坑，说三个典型的

第一个是 Windows 的坑。早期会话 id 带冒号前缀，在 Windows 上写入文件名时会静默变成 NTFS 备用数据流，文件看着在，内容全藏在隐藏流里，适配器永远读不到，排查了很久才发现。后来把 canonical id 全部改成裸 id，归属记在独立字段里，从根上绕开。

第二个是 SQLite 锁竞争。Hermes 内置的 SQLite 有个 WAL-reset 的 bug，被迫回退到 journal_mode=DELETE，这种模式下任何写事务都会阻塞并发读者。我们的后台同步直接写 state.db，一写就把 Hermes 自己的读取堵住，桌面端 30 秒超时直接报错。现在的处理是写连接 busy_timeout 压到 5 秒，启动拉取延迟 8 秒避开读取高峰，后台拉取改成增量。实在不行还能关掉自动同步。治本的办法是升级 Hermes 自带的 SQLite 版本。

第三个是去重失效。Reasonix 桌面端会规范化重写本地转录，把时间戳剥掉、前置系统提示词，我们按会话、角色、时间戳三元组去重就失效了，每轮同步把相同内容反复入库。最后加了内容级兜底去重才解决。Codex 也有个类似的怪癖，同一毫秒内多条消息共享一个时间戳，去重会把不同内容误判成重复，我们做了确定性微调，每条消息错开 1 毫秒。

一次意外救场

说个发生在我们自己身上的真事。初版做出来没多久，道荣家里那台电脑的 Hermes 整个崩了，本地的会话数据完全没法用。当时心里一凉，聊过的那些会话，说没就没了吗？

然后想起来，会话都已经同步到服务器上了。把环境重新弄好，agentctxsync 重新接上，之前的所有会话一条条全拉了回来，一条没丢。

平时它就在后台每 5 分钟静悄悄同步一次，几乎感觉不到它的存在。真出事那天才发现，它一直在兜底。

上手三步

1. 服务器上跑一下部署脚本，自动建好管理员和默认工作区；

2. Web 界面注册，建 Workspace，拿 API Key（格式 ws_xxx）；

3. 在接入帮助页按你的 Agent 下载客户端包，解压、注册、填 Key，重启 Agent。

不用改一行代码。每个 Agent 独立挂一个实例，指向同一个 Workspace 就自动互相同步。

现状

项目 MIT 协议开源，代码在 github.com/westsource/agentctxsync，官网 agentctxsync.com，备案已经完成。技术栈 FastAPI、PostgreSQL、MCP Server，Python 3.11 到 3.13。

如果你也在被 AI 的跨设备失忆折腾，欢迎来试试。有想法、有意见，GitHub 上直接提 issue，我们都在。