Skip to content

长期记忆同步 schema 3:各端要遵守的规则 ​

本文写给实现同步客户端的人。线上格式和服务端行为见同步服务仓库的 docs/long-term-memory-v3.md;这里写客户端一侧:怎么保存基线、怎么合并、提取进度和整理权怎么用。

电脑端的实现在 memory/long_term_merge.py(合并,纯函数)、memory/long_term_sync.py(导出、导入、本机状态)、app/memory_server/long_term_sync.py(发布、应用、整理权)、services/chat_sync/long_term.py(上传和拉取)。冷存在 memory/cold_store.py,见第 10 节。

合并规则有一份各端共用的样例:tests/fixtures/long_term_merge_cases.json。每条样例给出基线、本机、远端三份文档和期望的合并结果,期望结果是手写的。另一端的实现跑同一份样例,结果必须逐字段相同。样例由 scripts/make_long_term_merge_cases.py 生成,改规则时先改这个脚本里的期望值。

1. 基线和待上传 ​

每个角色在本机存两样东西:

名称内容什么时候更新
基线服务器确认过的版本号、那一版的文档原样、以及「把那份文档导入本机再导出」得到的条目自己的上传被接受;完整应用了一个远端版本
待上传一个操作号、它基于的版本号、要上传的文档本机内容和基线不一样时生成;被接受后清掉;应用远端版本时清掉

没被服务器接受的上传不能当基线。它只说明本机有什么,不说明别的设备有什么。

基线要存两种形式,是因为导入再导出不是原样往返:默认值、本机不认识的字段、来源 ID 的写法都会变。判断「本机改没改」拿本机导出和基线的本机形式比;判断「远端改没改」拿远端文档和基线的文档原样比。只存一种,没改过的条目会被当成改过。

2. 上传和拉取 ​

上传:
  有待上传 → PUT {operationId, baseRevision, document}
    accepted           → 待上传变成基线
    conflict           → 什么都不记,接着拉取
    两者都不是         → 换新的操作号和完成时间,退避后重试
    服务器返回 400     → 服务器还不认识这种写法;照常拉取,然后退避重试
拉取:
  远端已过期             → 基线版本号跟到远端的版本号,内容不动;
                           之前没读到过那一版的话,下次上传把 lineage 加 1
  远端版本号 < 基线版本号 → 服务器丢了历史,丢掉基线
  远端版本号 = 基线版本号 → 不动,记下「此刻手里是最新的」
  否则取回整份,交给合并
合并(在本机记忆锁里):
  local  = 导出本机现状
  merged = merge(基线, local, remote)
  把 merged 写进本机
  基线 = (remote 的版本号, remote 文档原样, remote 单独导入再导出的条目)
  merged 和 remote 内容不同 → 排一次发布

连续 5 次冲突后退避,不无限重试。

「合并后还欠一次发布」要和新基线一起落盘,不能只记在内存里:进程在保存合并结果之后、排上发布之前退出时,重启后靠这个标记补发。跟随一个过期或倒退的版本号之后同样要补发。

上传还在路上时,本机可能又生成了一份新的待上传快照。被换下来的那份要留着(电脑端留最近 3 份):

  • 服务器接受的是被换下来的那份:它成为基线,新的待上传改为基于这个新版本号。
  • 回执丢了、之后拉到的远端版本内容和自己发过的某一份相同:直接把它记为基线,不做合并。它本来就在本机里,再合并一次会把它的增量算两遍。

写入本机时,merged 里和本机当前导出完全相同的条目,本机那一行不动。整行重建会丢掉协议里没有的本机字段。

3. 合并规则 ​

条目的键是 (kind, subject, id)。下面「本机改了」指本机导出和基线的本机形式不同,「远端改了」指远端文档和基线的文档原样不同。

基线本机远端结果
有没改改了或删了取远端
有改了没改取本机
有删了没改删
有删了改了取远端
有改了删了删;本机的修改是用户确认(userConfirmCount 增加)或纠正(versionHistory 里出现了基线没有的 correction,按 text 和 replacedAt 比,不按条数比,因为历史只留最后几条)时保留本机
有改了改了按字段合并
无有无取本机,不产生退役记录;但事实的 ID 在远端的退役记录里时丢弃
无无有取远端
无有有按字段合并

没有基线(第一次同步、升级后分不清上次上传有没有被接受、基线和远端的 lineage 不同)时,整份按「无」的三行处理。

按字段合并时,每个字段先看哪一边相对基线变了:只有一边变就取那一边;两边都变才用下表。

字段两边都变时
absorbed、archived、signalJudged任一为真则为真
status取更靠后的:pending < active < confirmed < promote_blocked < promoted < archived < denied/merged/superseded/retracted
reinforcement、disputation、userConfirmCount、userFactReinforceCount、importance远端的值 + (本机的值 − 基线里本机形式的值);两边值相同也照此相加,因为是两次独立的增加。importance 截到 1–10。没有基线时取较大值
subZeroDays、subZeroLastIncrementDate 和各个「最近一次」时间(updatedAt、reinLastSignalAt、dispLastSignalAt、promotedAt、confirmedAt、archivedAt、voidedAt、suppressedAt、evidenceReviewedAt、evidenceReviewAttemptAt、sourceUpgradedAt)取较大值。两台设备在同一天各记一次负分天数,是同一天,不能相加
sourceMessageIds、sourceFactIds、sourceReflectionIds、mergedFromIds、countedFactIds、signalFactIds远端的顺序在前,接上本机多出来的,去掉任何一边相对基线删掉的,超出上限保留靠后的
正文和其余字段先定出合并后的 status 和 archived;本机达到了这个状态而远端没有时取本机,否则取远端
一边有、另一边没有的字段没有的那一边基线里也没有:取有的一边。基线里有(是删掉的):按上一行处理

文档顶层:

  • evidence.retirements 按 id 三方合并,保持远端的顺序,本机新增的接在后面。同一条两边都改时合并来源;合并后如果有纠正消息的时间还没解析出来,就去掉截止时间,等下次解析。
  • evidence.confirmations 按 fingerprint 三方合并。
  • 两个列表合并后各自最多留 20000 条,超出时从最前面丢。两份各自合法的列表合起来可能超限,不截断的话合并结果既写不进本机也传不上去。
  • progress 见第 4 节,organizer 见第 5 节。
  • maintenance 每个键取较大值;lineage 取较大值。
  • cold 见第 10 节。合并后名单里的条目一律不在 entries 里。

远端是 schema 1 或 2 时先当成 schema 3 读:事实一律算已判分,evidence、progress 按空处理。schema 1 文档里缺少的未确认反思不算删除(schema 1 从不带它们)。

4. 提取进度 ​

progress.a 和 progress.b 记「哪些消息已经送去提取过事实」,内容是消息的 32 位 ID。a 是只看用户发言的那一遍,b 是看双方发言的那一遍。有没有提取出事实都要记。

  • 记进度和保存事实在同一把锁里做,先存事实再存进度。导出快照也在这把锁里读,所以快照里出现某条进度时,它对应的事实一定也在。
  • 合并:远端的列表在前,接上本机相对基线新增的,超过 2000 条从最前面丢。服务器的版本是一条线,所以丢哪些各端一致,不需要看时间。
  • 组提取窗口时去掉 ID 已在对应进度里的消息;窗口空了就不调模型。没有共用 ID 的消息总是照常提取。
  • 别的设备说的话,收到后至少等 15 分钟,并且在等待结束之后确认过一次自己手里是最新的快照(远端版本号等于基线、没有待应用的远端版本),才由本机提取。等待期间做过的检查不算:对方可能在那之后才发布进度。等待用本机时钟计。
  • 积压的消息分轮提取,每轮有条数上限,只删掉这一轮处理完的;某一轮反复失败只放弃那一轮。
  • 收到的消息要在写进近期记忆之前另存。写进去之后它们看起来和本机一直就有的消息一样,这时再崩溃就找不回「哪些是新收到的」了。另存时跳过已经在等待的 ID。
  • 提取落盘后如果不是立刻发布(电脑端延后 60 秒),要留一个落盘的记号,进程重启后据此补发,否则别的设备会因为没看到进度而重复提取。
  • 被丢出进度的旧消息可能被再提取一次。新事实和更早提取出的事实引用了同一条消息时,把这一对送去现有的去重仲裁,由模型判断是不是同一件事。不能只因为来源相同就合并。

收到的消息只补 a 这一遍。b 这一遍只由说出这些话的设备自己跑:它在那台设备上本来就排得晚(每跑三次 a 才跑一次),接收方等 15 分钟后几乎总会抢在前面,等于把这一遍系统性地多跑一份。代价是说话的设备聊完后一直没跑 b 时,那段对话里角色自述的内容不会成为事实。

5. 整理权 ​

organizer: {deviceId, renewedAt, rank} 记哪台设备在整理这个角色。只有持有者做反思合成、晋升并合入画像、反思和画像精炼、每周自省、判分、旧条目复查。提取事实、用户的确认/否认/删除/纠正、展示后的反馈、群组分区,各端照常做。

rank:电脑且开了证据链(强力记忆)4,手机且开了 3,电脑 2,手机 1。模型配置不全的设备记 0:不认领,正持有就放弃。

「持有」的判断只看基线:基线文档里的 organizer.deviceId 等于本机设备 ID。本机改了待上传文档里的 organizer 不算,要等服务器接受。没开同步的角色不受这套规则限制。

本机另存一条不上传的记录:最近一次看到 organizer 的 (deviceId, renewedAt) 发生变化的本机时间。本机时钟被往回调就把它重置为现在。

h = 基线里的 organizer,r = 本机的 rank
r == 0            → h 是自己就放弃,否则不动
h 不存在          → 认领
h 是自己          → rank 变了,或距上次看到变化满 1 小时 → 续期(写新的 renewedAt)
                    另外:有别的内容要发布时,顺带把 renewedAt 更新进这次快照
r > h.rank        → 认领
距上次看到变化满 2 小时 → 认领
其余              → 不动

renewedAt 取自持有者自己的时钟,任何设备都只拿它判断「变没变」,不拿它和自己的时钟比大小。

顺带续期只在「本来就要发布」时做:没有别的内容要发布时不会为了续期单独生成快照,那是每小时一次的续期负责的。认领、改 rank、放弃正在等待发布时也不顺带改。

合并 organizer:本机没改取远端;远端没改取本机;两边都改时,本机的 rank 严格更高才保留本机,否则取远端。所以两台设备同时认领只有一台成功。

服务端只接受声明里写的那台设备发布、更新或撤掉这份声明;其他设备上传时要把已发布的 organizer 原样带上。

6. 已判分 ​

事实的 signalJudged 表示它已经判过分。不是持有者的设备提取出的事实带着 signalJudged: false 发布;持有者拉到后补判,判完置真,分数和标记在同一份快照里发出。合并时任一边为真即为真。

持有者没开证据链时不判分,这些事实保持未判,等开了的设备成为持有者后补判。

7. 其他约定 ​

  • 事实的 eventWhen、反思的 temporalScope 允许显式写 null,表示这条已经检查过事件时间、没有可填的。接收方见到这个键就不再让模型检查一遍。
  • 反思和画像带 userConfirmCount、countedFactIds、factSourceCounts。接收方手里有全部 countedFactIds 对应的事实时自己按事实当前状态算来源计数(已撤回的不算),缺了就用带来的 factSourceCounts。条目本身没变、只有它依据的事实变了的时候也要重算。
  • 本机判断「这条反思是不是只有角色自述、还没有用户信号」时(确认、晋升、按时间推进这三处),同样按 countedFactIds 对应事实的当前状态现算:被撤回的不算,后来认定为用户原话的算用户。存下来的 factSourceCounts 只在有依据事实不在本机时兜底,不因为现算而改写。电脑端渲染提示词时仍用存下来的数(那条路径不能去读归档文件)。
  • 退役和确认记录超过 16000 条时,由持有者从最早的开始清到 12000 条;单条退役记录的来源只留最新 2000 个。只清服务器已经有的内容:本机的证据和基线完全一致时才清,有还没发布的记录时先等它发布。清理过的设备在同步面板提示 7 天(long_term_memory_evidence_trimmed);合并前因为超长而只取了最新 20000 条的设备同样提示。
  • 任一列表超过 20000 条时快照发不出去。持有者这时连未发布的最早记录一起清;没有任何设备持有时本机也清(否则连认领都发不出去)。别的设备持有时本机不清、不生成上传,只报告原因(long_term_memory_evidence_capacity_exceeded),等持有者的下一份快照合并进来。合并前本机只取最新的 20000 条,所以合并总能做。持有者一直不出现时,本机按整理权规则认领;认领已经写好待发布时,清理就归本机做(否则认领也发不出去)。

8. 旧重复事实的一次性清理 ​

旧版本留下两类重复:同一句话被两台设备(或一台设备两次)各提取一份;意思相同、说法不同的事实,其中很多已经被反思吸收(平时的去重会跳过已吸收的事实)。清理每个角色只做一次,由整理权持有者做。

  • 记号:maintenance.legacyDedup(协议里已有的 maintenance 表,取值 1–1000 的整数,合并时两边取较大值)。值 ≥ 1 表示这个角色已经清理过,任何设备都不再清。各端必须原样保存和合并这张表,不认识的键也一样,不能丢。清理规则以后有改动时把值加 1,各端就会再清一次。
  • 提名:同一角色、同一主体,满足任一条就成对:来源消息 id 有交集;去掉空白和标点后文字相同;向量相似度 ≥ 0.80(平时去重是 0.85)。已被反思吸收的事实也参与,包括因为吸收满 7 天已经挪进归档的那些;已经被仲裁归档过的不参与。
  • 判断:每对都交给模型,用平时去重的同一份提示词,较新的一条作为 candidate,每次最多 20 对。只有判成 merge(留旧的)或 replace(留新的)才动;判成两件事、或模型多次答不出来的,都不动。不能只因为来源相同就合并。 同一条事实在本轮已经被并掉时,后面涉及它的判断不再生效。
  • 降级:被并掉的事实进冷存(第 10 节),带上 arbitration_archived_at 和 superseded_by(指向留下的那条),不删除。已经因为年龄在归档里的,补上这两个字段后同样挪进冷存。快照里只发它的冷存名单项:status: superseded,带 archivedAt 和 supersededById,没有正文;接收方手里有这一行就挪进自己的冷存,没有就只记名单,不会复活,也不算退役记录。只挪走、不写 arbitration_archived_at 是错的:它就不再是冷存行,名单里也不会有它。
  • 改指:反思的 source_fact_ids、counted_fact_ids,以及画像条目的 counted_fact_ids,都改指到最后留下的那条(被并掉的又被并进别的,就一路跟到底),同时去重。covered_fact_ids 只是记录,不改。来源计数按 §7 现算。被并掉的那条已被吸收、留下的那条还没有时,把留下的那条标成已吸收。
  • 备份和恢复:动手前把整个角色目录复制一份(电脑端在 memory/<角色>/backups/legacy-dedup-<时间>/)。恢复走冷存的恢复入口,把被并掉的事实用新 id 加回来,冷存里那条和名单都保持不动;如果沿用旧 id,名单里还有它,下次合并时就会被重新挪回冷存。
  • 中断:每批判断的结果都要落盘,中断后接着判,已经判过的不再问。

9. 退役断言审查的上限(各端本地规则,不进协议) ​

新提取的事实要和退役记录逐对比较,判断是不是在重复一条已经退役的说法。一次提取最多送审 60 对(三批):先审上一轮留下的,再审截止时间都已知的。第一条候选不管有多少对都整条送审,避免卡住。超出上限的候选连同当时证明出来的来源编号存到本机的待审队列,下一次同类提取时先审;它落盘之前,它引用的那几条消息不计入提取进度,这样任何设备都不会把这些消息当成已经读过。队列里的候选落盘时如果碰到纠正时间还不知道,就退回队列等下一轮,不让它所在的新窗口失败。配对数超过上限时,先尽量把所有退役记录的纠正时间解析出来再配对,查不到也不影响后面原有的检查。

10. 冷存 ​

冷存放的是只留在本机硬盘上、以备不时之需的记忆:召回、检索、合成、判分、精炼都读不到它,只有恢复、导出成文件、隐私删除能读。

  • 哪些条目进冷存:去重仲裁输掉的事实(带 superseded_by)、被撤回的事实、群组主体按时间归档的事实,以及归档的反思和画像条目。被反思吸收、因为满 7 天挪进归档的事实不进冷存,它们照旧给召回用。
  • 正文不进快照,也不进任何云备份。 快照的可选顶层字段 cold 是一张名单,每项恰好是 {kind, subject, id, status, archivedAt},事实被取代时另带 supersededById:
    • status:事实为 superseded 或 retracted,反思和画像为 archived;
    • supersededById 只在事实且 superseded 时出现;
    • 不重复,不能和 entries 里的条目同键,最多 20000 项。服务端按这几条校验。
  • 合并 cold:
    • 按 (kind, subject, id) 合并,远端的顺序在前,接上本机新增的;
    • 同一项两边都改时,status 取更靠后的(同级取远端),archivedAt 取较大值,supersededById 跟着取中的 status 走;
    • 基线里有、远端没有的项,是整理权持有者清掉的,保持清掉,不管本机手里有什么;本机清掉、远端没改的同样保持清掉;
    • 合并后名单里的键一律从 entries 移除,名单优先于任何一边对这一行的修改。没有基线的设备拿本机条目合并时,名单里的键也不能作为新条目传回;
    • 合并后超过 20000 项时从最前面丢。
  • 导入:名单里的键,本机手里有活跃(或可检索归档里)的副本,就挪进本机冷存,状态取名单里的;本机已经在冷存的不动;没有的只记名单。被撤回的事实仍按名单里的状态参与来源计数(第 7 节「已撤回的不算」),本机手里没有这行时用带来的计数兜底。
  • 导出:本机冷存的私聊条目只进 cold,不进 entries。名单记在本机状态文件 long_term_portable.json 里,和证据记录放在一起;导出时先列上次合并后的名单,再接上本机此后新进冷存的条目。
  • 旧快照:名单出现之前写的快照会整行带着降级条目(事实是 archived + archivedAt + superseded/retracted,反思和画像是带 archived 或 archivedAt 的)。读到时一律当成名单项处理:本机有这行就挪进冷存,没有就只记名单;下次发布时改成名单形式。
  • 清理:名单超过 16000 项时,由整理权持有者从最前面清到 12000 项,和第 7 节证据记录的做法一样,只清服务器已经有的内容。被清掉、本机冷存里还有的键要记下来(电脑端在 coldPruned),否则下次导出又会把它列回去。被清掉的键防复活只能靠基线:没有基线、又一直留着这行活跃副本的设备会把它传回来,这是已知限制。
  • 同一个键在冷存和活跃区都有时,冷存优先。 典型来源是从云存档恢复了旧版文件。读取时一律按冷存处理,活跃区那份在下一次写入时移走。
  • 恢复:从冷存拿回来一律用新 id,冷存那行和名单都不动。群组主体的事实不同步,恢复时沿用原 id、离开冷存。
  • 隐私删除同时删冷存,删不干净就整体失败。

电脑端的冷存事实分片放在 memory/<角色>/fact_cold/,反思和画像仍在原来的 reflection_archive/、persona_archive/,三者共用 memory/archive_shards.py 的分片写法。冷存不进 Steam 云存档。