世界记忆
多 agent 共用
同一主人名下的 agent 把会话都交进这份库，抽取统一在中心跑；大家都能查、都能接着用，换设备也接得上。
01 / architecture
三栏，
一份权威
中心自己不需要有 agent；每台设备上跑一个本地节点。 备份按复制序号一条条追平，核对无误才允许接班；接班时换一代凭证， 旧中心再送东西过来会被直接拒绝。点下面的方块，看每一格实际落了什么。
01
拓扑：点开每一格
细线是数据流；线上跑的小亮点，代表正在路上的一份数据。选中后，检视卡会列出它在磁盘上的实际结构。
edge · 边缘设备
hub · 中心
transcript.db
memory.db
core.db
ledger.db
keys/
backups/
secrets.enc
standby · 备份
追平
校验
缺条目 ⇒ 不接班
配对 / 入库
行 / 快照
复制序号
正在路上的一份数据
02
数据落在哪里
中心与节点各自是一个目录。账本不出中心，密钥不进模型，备份不藏私钥明文—— 这三条决定了整个运维的样子。
hub · --data-dir
中心
| ├transcript.db | 原始对话，只增不改；每轮一行，永远不覆盖 |
| ├memory.db | 记忆本体，25 张正式核心表 + 7 张侧表（第 6 版）：结论行、实体行、来源与审计 |
| ├core.db | agent 自己的加密小本：每 agent 一份，正文 / 修订 / 随手记三张加密表 |
| ├keys/ | core 每份小本的独立钥匙（32 字节），不通过 agent 工具暴露 |
| ├ledger.db | 账本、配额、进度书签——不出中心 |
| ├backups/ | 原始对话、记忆与清单三件，保留最近 7 组 |
| ├hub.key | 中心私钥，可用 hub key export 加密归档 |
| └secrets.enc | 密钥箱；开它的口令另存，不跟着备份走 |
node · data_dir
边缘
| ├device.key | 节点私钥：配对和签名的根 |
| ├replica/ | 整份下载下来的只读副本和检索索引；这一半只读，不会被改写 |
| ├pending.db | 断线后本地攒下的东西；断满一天之后的本地整理批次写这里 |
| ├dr/ | 脱离中心（断满五天）之后每小时自备份；没确认的永远不删 |
| └node-state.json | 同步、离线、自己当中心——三种状态记在这里 |
sync_state connected
self_distill false
offline_elapsed_ms 0
pending_turns 0
staging_rows 0
dr_backup_count 0
读数没有正文、没有路径——运维面只回答「有没有卡住」，不搬运内容。
导入为什么不由核心代劳
契约 > 插件
- 每家都在变各家 agent 的会话格式、字段和版本都在动；核心写死任何一家，改一次就要动核心。
- agent 自带转换器按契约把会话写成事件；入库验收不过就改转换器，核心不解析任何私有格式。
- 新增源要试跑四种来源已经过验收；新来源附一份试跑说明，照同一把尺子验。
03
身份是哈希，位置只是步号
模型眼里只有 [e12] 这样的短句柄——句柄就是召回结果前面的编号，拿着它能换回那条记忆； 完整定位符留给程序。七个编号各管一件事：哪个是真身份，哪个只是给人看的序号，哪个只管机器之间怎么同步。
读法：sha256(a | b) 里的竖线是「拼起来再算哈希」；末尾带 ? 的字段可以没有。
session_uid
sha256(source_agent | device_id | session_key | agent_instance_id?)
一个会话的身份；同一会话在另一台机器上导入仍是它
thread_uid
sha256(session_uid | thread_key)
会话里的对话线，子 agent 与主线程分开
turn_uid
源 turn id，或本轮第一条 user 消息的 event_uid
一轮的身份；源头没有原生轮号时，用推导出来的形式
event_uid
sha256(thread_uid | native_key | content_hash | occurrence)
事件的真实身份；把记忆指回原文，靠的就是它
revision_id
sha256(source_sha256 | adapter_version | ingest_version)
同一来源内容的一次解释版本
seq
首次入库分配的稳定步号（追加式）
只用于展示与引用，不是身份
commit_seq
(epoch, commit_seq) 中心复制顺序
只活在复制层，永远不会进到记忆的编号里
一句话：模型只看得到句柄，真正认身份的是哈希；序号给人看，复制序号给机器同步用。
实时合成器 · 选中字段即参与哈希
session_uid = sha256( … )
—
等待输入
04
五个常驻端点，四个转录读
五个写与配对常驻；四个转录读只给已配对设备；下行快照在发布时出现。对外的东西越少，越能说清它答应了什么。
hub serve · v1HTTP
| 端点 | 动作 | 说明 |
|---|---|---|
| /v1/pair | post | 用一次性码完成设备配对 |
| /v1/challenge | post | 让设备签个名，证明它是它 |
| /v1/ingest | post | 带签名写入一批事件，并防重复提交 |
| /v1/rows | post | 把离线攒下的行送回来；中心答 200 才允许继续拉快照 |
| /v1/state | get | 同步进度和中心状态 |
| /v1/snapshot/memory | get | 整份下载记忆快照（发布时） |
| 转录读取 · 只给已配对设备 | ||
| /v1/transcript/sessions | get | 中心全部可见会话的清单 |
| /v1/transcript/session | get | 按会话回放轮正文，支持分页 |
| /v1/transcript/search | get | 在中心全文索引上按词查原话 |
| /v1/transcript/turn | get | 按 turn_uid 取目标轮与前后各 ≤10 轮 |
另外还有备份复制面 /v1/replicate* 和配对时读取的 /v1/identity；它们只在接班或配对时用，不在日常设备路径上。
# 座位来自 --llm-config 或可重复的 --replies
# 两者都不给 → 退出 3，错误面点名这两个旗标
$ recollect-hub import --data-dir ./data \
fixtures/exchange/synthetic_basic.json
imported 1 session · 1 revision
$ recollect-hub cycle once --data-dir ./data --llm-config ./llm.toml
cycle seats=1 batches=1 committed=1
$ recollect-hub index status --data-dir ./data
memory_version 6
rows ·
watermark advanced
上面是一段示意调用序列；真实读数以本机 --help 与 index status 为准。
05
局域网里，或者隔着半个国家
同一台设备、同一个局域网、异地——三种连法用同一套东西，不需要为「远程」再部署一套服务。 默认跑在可信的私有网络里：异地把两台机器用隧道或组网拉进同一个私网，不把端口直接开到公网。
01 / 本机
一台机器就是中心
没有远端也能跑：导入、抽取、召回都在本机完成。
02 / 局域网
直连一个地址
设备地址簿里记一条 LAN 地址，节点按顺序试，连上就走。
03 / 异地
经隧道或组网
地址簿里再加一条；上次成功的排最前面，换网不用先等一条死路超时。
- 认机器，不认地址每台设备用自己的私钥签名，中心提前钉好公钥。签名不绑 IP，换网络不用重新配对；但没有那把私钥，占住同一个 IP 也签不过。
- 只开一个口所有对外通信走同一个加密端口，设备和中心互相验身份；不另开管理口、调试口。
- 配对只用一次一次性配对码换设备身份；之后靠签名，不靠密码。
- 转录读也认设备四条转录读路由只对已配对设备开放；读一次落一行审计，只记谁读了哪个会话，不记正文。
- 密钥不进模型密钥只从管道进，不进模型、不进参数表；每个 agent 的小本各用一把独立钥匙。
- 账本不出中心配额和进度只留在中心，备份里也没有；私钥从不以明文进备份。
06
多台设备、多个 agent，谁看得到谁
默认按「可信 agent 环境」设计：同一局域网里的已配对设备都算自己人。世界记忆共用，core 各归各的。
core
只认一把钥匙
每个 agent 的加密小本各用一把独立钥匙；core_* 只对这一个 agent 身份开放，别的 agent 调不到。
会话原文
记忆里只有指针
原文只留在 agent 侧和中心；共享记忆里存的是 turn_uid 指针，不是原文。recollect_turn 凭指针取回那一轮（前后各 ≤10 轮），recollect_session 按会话回放；两者走同一把可见性闸。
跨机读取
中心优先，断线回落 可信局域网
边缘先向中心的四条转录路由要数据；中心不可达才读本机，并在回执里标 source=local + degraded，不会假装中心零命中。
默认前提：同一局域网里的已配对设备视为可信——能配对进来，就能读中心会话，不再按主人切分。 这条局域网信任只作用于转录读；世界记忆和 core 仍按原来的闸。不要把未受信任的设备配进来，也不要把中心暴露到公网； 异地就用隧道或组网，把机器拉进同一个私网。
术语小词典十一个词，读别的页卡住时回来查
- 句柄
- 召回结果前面的 [1]。拿着它能换回那条记忆。
- 指针
- 一条记忆指向原始对话里某一轮、某一段的编号。原文不动，指针就不失效。
- 进度书签
- 处理到第几行的记号。成功了才前移，失败就停在那，下次接着来。
- 闸
- 一道自动检查。过不了就不往下走，并写清原因；不是靠人盯着。
- 本地整理
- 连不上中心时，节点在本地暂存的数据上继续做抽取，不等网。
- 回并
- 网络恢复后，把本地攒下的东西按固定顺序送回中心，一步不能跳。
- 锚
- 一个人、一个项目、一台机器在库里的固定身份；关于它的记忆都挂在上面。
- 幂等
- 同一份东西送两次，只算一次，不会写重。
- 接班
- 备份追平并核对通过后转正；旧中心随即被挡住，不能再写。
- 快照
- 某一刻整份记忆的拷贝；发布时下发给节点，平时按增量同步。
- 转录读
- 按会话或 turn_uid 从中心取原话；四条只读路由只对已配对设备开放。