Memory

Memory 保存以后还会用的结论，不是完整聊天。

以后还会影响判断的内容，才值得写成 Memory。已经做出的决策、必须遵守的约束、当前项目状态，或者明确的下一步，都适合留下。

完整聊天不要整段塞进来。聊天可以先成为 Source。只有值得跨任务复用的部分，才进入 Memory。

留什么才是关键。一条范围清楚、结论明确的短条目，通常比对话式摘要更好找。项目变了，它也更好修订或停用。

​

什么应该进入 Memory

下面几类内容通常值得保存。

• “公开 HTTP 契约变化后，先重新生成签入仓库的客户端。”
• “这个项目要求 Python 3.11 及以上。”
• “OpenClaw 项目模式当前仍按 agent 隔离。”
• “下一步运行契约测试，并检查生成代码没有漂移。”

这些内容换一个会话，或者过几天再看，仍然有用。

临时调试输出、礼貌寒暄、一次性的工具进度，通常不该直接写成 Memory。先保留 Source，需要时再提炼。

​

Memory 不是一行可覆盖文本

Memory 看起来像一条结论，实际上有三层身份。

Memory Artifact Revision
└── logical entry_id
    └── immutable entry_version_id

​

Artifact Revision

每次 Memory 生命周期发生有效变化，会形成新的不可变 Artifact Revision。Revision 保存当时的清单和 change set。

​

逻辑条目

entry_id 表示同一条长期知识。修订后仍是这个逻辑条目。

​

条目版本

entry_version_id 指向某次具体内容。修订会创建新条目版本，并保留 previous_version_id、来源和创建它的 Memory Revision。

维护一条 Memory 时，只保存 entry_id 不够。精确 Citation 还需要对应的 Memory Revision 和条目版本 ID。

​

清单决定当前状态

某个 Memory Revision 的清单，是当时的权威目录。每个条目都会记下稳定的 entry_id、精确的 entry_version_id、内容哈希，以及 active 或 inactive。

retire 把条目变成停用状态，使它退出默认召回。内容和旧 Revision 仍然保留。

修订也不是原地覆盖。它创建下一条目版本，再让新 Memory Revision 的清单指向它。

​

两条写入路径

身份和清单清楚以后，再看内容是怎么写进去的。

​

显式写入

你已经确认要保存的内容时，直接调用 remember_memory。

{
  "scope_id": "project:powercontext-101",
  "kind": "decision",
  "text": "Regenerate and inspect the checked-in client before running contract tests."
}

这条路径不需要模型，也不需要先创建 Source。它可以带 expected_revision 保护并发更新。内容真的变了，就返回 Memory 版本引用和精确条目 Citation。内容规范化后和现有条目一样，就是无变更，这时只返回当前 Memory 版本引用，entry 可以是 null。

​

从 Source 抽取

自动路径先采集 Source，再由调度器或 flush_memory 处理 Source 窗口。

Source window
→ bounded evidence
→ model candidate
→ domain validation
→ canonicalization and deduplication
→ atomic Memory commit
→ cursor update

模型输出只是不可信 Candidate。它只能引用当前操作提供的证据 ID，不能凭空引用其他 Source 或 Artifact。

PowerContext 在同一事务中提交 Memory Revision、条目版本和启用状态搜索投影。任何一步失败，都不能留下“Revision 已提交但索引没更新”的半成品。

重复的规范形式内容可以变成无变更，不必制造一个没有语义变化的新 Revision。

显式写入和 Source 抽取都能产生 Memory，但证据链不同。要证明某条 Memory 来自刚才的 Source，检查条目的精确 source_refs，不要只看搜索文本相似。

​

修订和停用

已经留下的条目还可以改，也可以先停用。修订应针对当前精确 Citation。新内容创建下一条目版本，旧版本仍可读取。

停用同样需要精确目标。

Memory Revision + entry_id + entry_version_id

停用后，默认启用状态列出和召回不再返回它。include_inactive 可用于审计。旧 Artifact Revision 和条目版本仍存在。

如果其他工作进程已经更新了 Memory 头版本，你手里的旧 Citation 会产生冲突。重新读取当前状态，检查差异后再决定，不要机械猜下一个 Revision。

​

搜索怎么工作

写入之后，下一次请求要靠搜索把它找回来。Memory 搜索不是把所有文本按一个相似度分数排序。它先确定当前 Memory 头版本，再根据能力和请求选择模式。

模式	前提	行为
fts	FTS 投影可用	使用关键词证据召回
vector	嵌入模型、配置档、维度和 backend 向量能力完整	只走向量检索
hybrid	FTS 与向量都可用	合并两路结果
auto	运行时判断	优先混合，不可用时选择 FTS

如果查询嵌入暂时不可用或超时，auto 在 FTS 可用时可以退回 FTS。显式请求 vector 或 hybrid 时不能静默改模式，调用者应看到能力错误。

​

Fusion 与重排序

混合搜索使用 reciprocal rank fusion 合并 FTS 和向量排名。当前实现的 RRF 常数是 60。

向量 admission 会把 unit-normalized L2 distance 换算为 cosine similarity，并应用最低相似度门槛。命中结果会保留 matched_by，说明来自 FTS、向量或两者。

可选重排序在检索之后运行。它可以改变最终顺序，但不会改写 Memory 或搜索索引。Rerank 开始后使用已选定的 Revision 快照，不应因为另一个写入推进头版本就悄悄换数据。

​

PreparedContext 不是搜索响应的复制

搜到了，还不等于这一次请求就会把整段内容塞进模型。prepare_context 会先粗召回候选，再由构建器在共享 UTF-8 字节预算中选最终内容。

当前构建器有几个明确上限。最多 16 个 Memory 粗候选。最多 8 个 Experience 候选。最终合计最多 8 项，其中 Experience 最多 2 项。单项内容最多 2000 字节。

这些是当前实现细节，可能随版本调整。稳定契约是最终内容受 max_bytes 限制、带精确 Citation，并标记为 untrusted_history。

结果只有两种正常状态。

empty → content is null, content_bytes is 0
ready → content is nonblank, content_bytes matches UTF-8 bytes

PreparedContext 是本轮输入，不会自动变成新的 Memory。

​

用 OpenAPI 案例推演

先显式写入。

{
  "scope_id": "project:powercontext-101",
  "kind": "decision",
  "text": "Regenerate and inspect the checked-in client before running contract tests."
}

再搜索它。

{
  "scope_id": "project:powercontext-101",
  "query": "What should happen before contract tests?",
  "mode": "fts",
  "limit": 5
}

检查响应时看这四件事。命中的 memory_ref 应是当前精确 Revision。结果里应包含 entry_id 和 entry_version_id。matched_by 应符合请求模式。prepare_context 的 Citation 应指回同一个条目版本。

然后把内容修订成下面这样。

Regenerate the checked-in client, inspect the diff, and then run contract tests.

旧 Citation 此后仍能用于历史读取，但不能当作当前条目去修订或停用。

​

容易误判的情况

​

auto 返回 FTS，不是混合

检查嵌入模型、配置档 ID、维度、backend 向量能力，以及当前 Memory 头版本的向量投影是否完整。

​

刷新处理了 Source，但没有新 Revision

模型可能返回无变更，或者 Candidate 经过规范化后与现有内容重复。先检查 Source 证据链和 change set。

​

搜索有命中，PreparedContext 却是空结果

PreparedContext 还有相关性、去重和字节预算约束。搜索命中不保证最终一定入选。

​

Rerank 时 Memory 头版本已更新

当前搜索保持开始时选择的 Revision 快照。下一次搜索才会读取新头版本。

​

怎么知道分清了

1. Artifact Revision、条目 ID、条目版本 ID 是三层身份。
2. 停用是停用，不是删除。
3. 显式写入不需要模型，也不需要先有 Source。
4. 抽取 Candidate 要经过证据和领域校验。
5. auto 可以降级，显式向量或混合请求失败时不能静默改模式。
6. PreparedContext 仍是临时、不可信、有预算的视图。

对象已经清楚时，去安装并运行 Server 写出第一条 Memory。要看采集路径，走 Source 与 Memory。

​

下一步

再看谁来接着做

Memory 回答以后还要知道什么。Handoff 回答谁来接着做，以及从哪里开始。

阅读 Handoff

写出第一条 Memory

先启动本地 Server，写出一条 Memory，搜到它，再拿到带 Citation 的 PreparedContext。

开始第一条闭环