知识与记忆同步协议 v1（概述）

这一页给人看，讲协议是做什么的、怎么用。规范以英文版 knowledge-sync-v1.md 为准，两边有出入时按英文版。

它做什么

同步协议让一个人的多个客户端（桌面、终端或脚本）和服务器之间双向同步本人的私人知识、原文、文件夹、记忆和包清单，并保留每一次修改的版本记录。协议是中立的：任何客户端、任何服务器照规范都能实现，circle-hub 只是其中一个服务器实现，地址在 /api/sync/v1。

它不做的事：不把内容发布到团队，不授权，不安装或运行包，不读业务系统，也不导出团队内容或别人分享给你的内容。它是普通的 HTTP 接口，不是 MCP 工具，模型看不到它。

一次同步怎么走

  1. 读取同步状态（GET /state）：同步方式、当前版本标识、容量和服务器实际的批量限制。
  2. 登记本机客户端（POST /clients），再开一个可续传的同步会话（POST /sessions）。
  3. 分页读取服务器上的清单，比较两边，问服务器缺哪些对象（missing）。
  4. 分批上传服务器缺的（upload），下载本机缺的（download）。上传的内容在提交前谁都读不到。
  5. 提交（commit）：服务器在同一个事务里比较版本、重新核验引文和来源，然后一次性生效。

每个对象按规范形式（RFC 8785 的 JSON 规范化，加上可编辑文本统一换行为 LF、去掉开头的 BOM、NFC）计算 SHA-256 作为它的身份。原文和逐字引文按原样字节保存，不做任何改写。

冲突和重试

  • 提交时带上次看到的版本标识。期间内容变了（包括在控制台或经 MCP 的修改），服务器拒收并返回最新状态，客户端合并后再提交，不会被静默覆盖。
  • 同一条内容两边都改了，两个版本都保留，标为“有冲突”，不按时间挑一个。有冲突的记忆不会自动加载。客户端提交一个同时接续两边的新版本就解决了冲突。
  • 每次写操作带一个操作编号。网络断了就原样重发，或按编号取回回执，不会重复写入。

同步方式与清除

默认“同步到 Hub”。本人可以改成“仅保存在本机”：先预检影响，再确认清除，服务器上的私人副本被清除，文件夹分享随之失效；分享到团队的副本和本机副本保留，清除之前的服务器备份仍含旧内容。重新选择“同步到 Hub”会从一个空的新代次开始，由本机副本重新上传。

清除时，服务器为运行单独保存的、这一代次私人原文的副本也一并清除；引用过它们的运行，根据标为“不可用”，原因是已登记的 GROUNDS_PURGED。运行记录和摘要不改写，清除记录只追加。预检会报告将清掉的副本数（run_held_originals）和受影响的运行数（affected_runs）。

发现文档与二次确认

服务器在 /.well-known/knowledge-sync 公布发现文档（不需要令牌）：同步地址、支持的版本与能力名、申请令牌时的访问范围、本地工具地址，以及读取团队记忆、分享到团队分别用哪个 MCP 工具和参数。客户端照文档取地址，不必写死。

公布了 first-sync-notice 的服务器在同步状态里报告 never_synced：这个账号的客户端从没在这台服务器上传、提交、中止过会话或改过同步方式时为 true。默认仍是同步到服务器；客户端第一次连上时据此明确告诉用户个人内容会同步上去、随时可以改成仅本机。提示由客户端显示。

公布了 share-single-item 的服务器接受单条分享（POST /share）：仅保存在本机时，条目带团队标记、又连着服务器的，只上传这一条和它自己的来源。团队标记是客户端本机条目上由本人设定的标记，不进同步对象，也不改对象标识。服务器按普通分享同样的顺序重新核对依据、引文、来源能否分享、团队里是否重复和凭据扫描；通过就追加团队条目和团队持有的来源副本，不在服务器留个人副本；不通过时答复登记的拒收码。两种结果都记共享回执。

公布了 purge-confirmation 的服务器不会只凭令牌清除：客户端请求清除时，服务器记下这次请求并答复需要确认，给出确认入口；本人在 Hub 控制台的同步方式里确认后才执行，客户端用同一请求重试即可拿到结果。确认请求 10 分钟内有效。公布了 error-detail 的服务器在错误里附 detail，是这个错误码登记的说明和下一步。

身份

用本人的访问令牌（Authorization: Bearer …）。令牌经 MCP 标准授权取得（OAuth 2.1，访问范围是本 Hub 的 <issuer>/mcp），或由管理员签发。同步只针对令牌所属的账号，管理员也不能同步别人的内容；别人的会话、对象和不存在的一样答复。

兼容

v1 以后只做加法：已有的路由、字段、取值（包括同步方式的线上取值 hub）和冻结样例都不变。客户端遇到不认识的答复字段要忽略，遇到不认识的错误码按一般失败处理并显示错误里的说明；服务器继续拒收不认识的请求字段。新功能只以服务器公布的能力名提供。错误码表见英文版第 12 节，由 node tools/gen-sync-error-table.ts 从已登记的协议码生成。