功能说明

一次会话的完整节奏

理解功能最快的方式是看 AI 在一场对话里到底调了什么：

1. 开场：recall_directives —— 取回你定过的习惯、叮嘱、约束，本次会话全程遵守。它同时返回一个权威的 now（AI 没有可靠的内部时钟，所有时间判断以它为准）。
2. 每一轮开口前：search_memory —— 传 query（你这句原话 + 上一轮回复要点）和 terms（扩展词群）。这一步是”想一下”，不是等你点名才查。
3. 话题收束时：write_memory —— 把决策、承诺、偏好、事实批量写进去。
4. 你追问过去：命中不了就换入口 —— recall_timeline（按时间）、recall_topic（按实体）、recall_episodes（翻原话）、get_related（顺着关联走）。

22 个工具

写入与演进

工具	做什么
write_memory	批量写入记忆。支持类型、词群、实体、标签、附件、supersedeIds（取代旧条目）、notify（通知同事）、audience（放宽可见范围）
supersede	给已存在的两条记忆补”取代”关系：headId 是新的，supersededIds 是旧的
forget	标记一条记忆为已遗忘。不物理删除，库里仍留痕
set_memory_audience	事后调整某条记忆的可见范围（只有归属人能做）

检索

工具	做什么
search_memory	主力检索：原句走向量通道，扩展词群走词法三路，结果融合排秩
recall_topic	按实体/名词精确取，比全库检索快，适合”上次说的那个 xxx”
recall_timeline	按时间区间取，适合”上周""九月那阵子”
recall_session	按会话号取：把某一场对话里记下的内容一起拉出来
get_memory	按 id 取单条完整内容
get_related	顺着关联关系扩展（共现、引用、取代）
recall_directives	取回习惯 / 叮嘱 / 指令
recall_constraints	取回带领域标记的硬约束（写代码、做设计前必查）

情景层（原话）

工具	做什么
log_episodes	把对话原话逐字冷存档
recall_episodes	回跳原话：蒸馏后的记忆丢了细节时用

推送与签收

工具	做什么
inbox	我这边待确认的事项（包括 AI 建议、同事指派）
ack	签收一条待确认事项
outbox	我发出去的事项，以及对方的到达/签收状态

其他

工具	做什么
get_asset	取附件本体（图片、文件）。检索只给提货单，不给字节
reveal_secret	取出被抹成占位符的凭据明文（仅本地模式）
stats	库的规模与检索统计
list_spaces	列出空间树（云端组织模式）
list_members	列出组织成员（云端组织模式）

本地版的边界：list_spaces、list_members 在本地模式下返回空并附说明，notify、audience 类入参会被明确拒绝（不是静默忽略）——一台机器只有一个个人空间，没有第二个成员可通知。

检索是怎么走的

一次 search_memory 实际上并发走了四条路，再融合排秩：

• 词法三路：扩展词群命中、词项命中、中文 bigram 字面命中。这一路负责”精确”。
• 向量一路：把原句编码成向量做近邻。这一路负责”换了说法也能找到”——但需要装向量增强包，没装就自动跳过（不是报错）。

融合用 RRF（倒数排名融合），不比较两边的原始分数——词法分和余弦相似度不是同一个量纲，直接加权相加是错的。

词群和原句不能互换：原句塞进 terms 会让词法路被噪声淹没，词群塞进 query 会让语义路读到一个没有主语的短语。这条在实现里是硬分工的。

记忆怎么演进

小本本没有 UPDATE。改一条记忆的正确姿势是”写新的、把旧的挂上去”：

旧：客户 A 的报价用 ¥ 报价            ← 仍在库里，带 superseded 标记
新：客户 A 的报价改用 $ 报价（2026-10）  ← 链头，回答现状一律以它为准

这么设计的原因是：如果记忆能被静默改写，你就永远无法判断 AI 此刻说的话是从哪来的。保留被取代的那条，才能回答”当初为什么那么定、什么时候改的、谁改的”。

写新条目时如果忘了带 supersedeIds，写入响应里的 supersedeCandidates 会列出词群高度重叠的旧条目——补链可以，用”再写一条”来覆盖不行。

事件链与自检

每一次写入都会在库里追加一条事件，事件带前一条的哈希。xbb verify 重算整条链：

xbb verify
# chain OK

它的能力边界要说清楚：能证明文件没被截断、某一行没被单独改过；不能证明整条链没被重算——因为链的起点没有外部锚定。所以它的定位是”损坏检测”，不是”对外举证”。

附件（文件记忆）

让 AI 记住一张图或一个文件，走的是 write_memory 的 attachments：只登记引用（本机绝对路径 + 描述 + 标签），不搬字节。

一个容易被忽略的要点：附件的 description 是它唯一的检索入口。附件不进全文索引，所以描述必须写开——“这张图是 10 月 20 日评审用的流程图，含三级审批节点”能搜到，“上面那张图”搜不到。

检索命中时返回的是提货单（id / mime / 字节数 / 描述 / 路径 / 状态），不含字节本身。真要取时调 get_asset，可以要路径也可以要内联内容。状态有四种：ok 没变、changed 盘上文件已变、missing 文件没了、evicted 云端欠费被回收（记忆还在）。

托盘与管理窗口

装好之后后台常驻一个本地服务，监听 127.0.0.1:17630：

• /ui —— 管理窗口（库规模、检索统计、检查更新、模式切换）
• /healthz —— 存活探针
• /stats —— 统计
• /hooks/turn —— 供宿主主动推送”这一轮结束了”

托盘菜单可以：启动/退出、本地 ⇄ 云端切换、检查更新、开机自启。

xbb serve            # 前台启动（带托盘与管理窗口）
xbb serve --detach   # 后台常驻，无控制台窗口
xbb serve --headless # 无托盘无窗口（CI / 无显示环境）
xbb autostart on     # 开机自启

可见范围与归属

每条记忆默认只有你自己可见。放宽范围是显式动作：{org:true} 表示全组织，{spaces:[...]} 表示某个部门（且只能授权到你自己子树内的空间，越界整笔被拒）。

检索结果里带 owner 与 mine：mine:false 表示这是别人的记忆，AI 转述时必须说清是谁记的，不能当成你的经历复述。