详细设计说明

让模型带着"正确上下文"执行，而不是带着"所有历史"执行

这份文档把 Memory / Context 从"上下文装配的一个步骤"提升为独立子系统。重点回答五个动作（预检 / 召回 / 压缩 / 写回 / 隔离）如何在 token 预算、隐私边界、长期经验三个约束下协同工作，避免超长上下文、跨租户串数据、危险经验沉淀这三类典型故障。

1. 定位与概念

1.1 总体架构图

Memory 跨三层存在：T1 配置（保留时长 / 写回开关 / scope 策略），T2 长期 + 团队共享（跨 Run 召回），T3 短期 + 装配（Run 内）。五个动作按 token 预算调度，外层受 scope 隔离硬约束。点色块跳章节。

1.2 上下文装配时序图

五动作有序触发：Precheck（估 token）→ Retrieval（按 scope 召回）→（超预算才走）Compression → ctx 就绪 → LLM Call → 终态后 Writeback。左侧是 Harness s2_context_assemble，右侧是 Memory Store。点 lifeline 跳章节。

1.3 为什么要做：缺口与解决的问题

6 类已在生产发生过的真实故障 → 对应 D1–D5 五条强约束。

1.4 三层职责分工

Memory store 横跨三层、每层策略不同——T1 只读底座、T3 用完即弃、T2 是所有写回与召回的唯一持久层。

"是否写长期"的决策只在 T2 发生——配合终态门禁（仅 SUCCEEDED 写）+ PII 过滤（写前剔 token / cookie / 临时密钥）形成闭环。

2. 预检 Precheck

2.1 职责与触发时机

预检是 Memory 子系统的入口：每次 Harness 进入 s2_context_assemble 阶段，就会先做一次预检估算，再决定召回、压缩、装配的具体策略。它的核心输出是"当前估算 token / 目标预算 / 是否需要压缩"三个标量，下游所有动作都基于这个输出做决策。

2.2 token 预算估算口径

估算的是"如果按当前候选条目全量装配，会用掉多少 token"。组成包括 system prompt、history（按 session 配置的最近 N 轮）、工具 schema 描述、候选记忆条目（来自召回前的初步候选集）四部分。估算精度不要求字面级精确——能在 5% 误差内即可，足够支撑触发决策。

2.3 触发压缩的判定规则

把估算结果与目标预算比较，目标预算定为 model_context_window × 0.8，留 20% 给响应输出。判定规则按优先级如下。

2.4 输出 Trace

预检每次产出一条 StepTrace，作为 s2 的子步骤记录，包含current_tokens、target_budget、decision（pass / trim / compress / reject）、candidate_count 四个关键字段。这条 trace 是后续调试"为什么 prompt 这么长"的第一手数据。

3. 召回 Retrieval

召回是 Memory 子系统里最复杂的一个动作——它涉及向量检索、关键词检索、多维打分、阈值截断、降级路径多个环节，单独成篇详细描述。本节只给总览，所有实现细节请直接看专篇文档。

3.1 五阶段管道

3.2 与本子系统的边界

Retrieval 的输入：当前 query、CallerIdentity（来自 RunContext）、token 预算余量（来自 §2 Precheck）。输出：一组 MemoryItem，由 §4 Compression 决定是否要进一步压缩、由 ctx 装配最终拼成 system message 段。所有写入 store 的元数据（来源 / 写入时间 / 频次）由 §5 Writeback 维护，召回时只读不写。

详细设计：Memory Retrieval 召回算法设计 →（scope 过滤的 DAO 注入细节、Hybrid 融合公式、四维打分的归一与权重区间、截断三闸优先级、六类故障降级动作、ToolTrace 字段集、Provider 选型边界）

4. 压缩 Compression

4.1 压缩策略链

压缩是分级递进的，先做轻量动作再做重量动作；每一级压缩后都做一次预检，能进入预算就停止。

1. 裁剪冗余历史 · 去重相同事实、合并相近操作（无信息损失）
2. 摘要工具结果 · 超长 tool_result 只保留摘要 + 引用 ID，原始结果留在 trace
3. LLM 压缩历史对话 · 用专用压缩 LLM 把若干轮对话合并成一段摘要
4. 二次预检 · 仍超预算 → 拒绝执行（绝不允许超长 prompt 进 LLM）

4.2 关键约束（一票否决清单）

压缩本质是"丢信息以换 token"，但有些信息丢了之后整个 Run 就失去意义。这份清单是压缩链路的硬约束：压缩前后必须存在；丢失任意一项，本次压缩失败，回退到上一级压缩或拒绝执行。

4.3 降级链

压缩本身可能失败（专用 LLM 不可用、超时、输出格式错误等），需要明确的降级路径。

压缩动作每次写一条 StepTrace + summary_id，记录原始 token / 压缩后 token / 压缩模型 / 关键约束校验结果，便于事后追溯"这条 prompt 为什么变短了"。

5. 写回 Writeback

5.1 按终态决定写回

写回是 Run 收口阶段（Harness s8_trace 之后、Run finalize）的最后一个动作。是否写长期记忆完全由 RunState 终态决定，不允许业务层覆盖。

5.2 写前安全过滤

即便终态是 SUCCEEDED，写入长期 store 之前还要过一道安全过滤——这一层是 Memory 子系统对外的最后一道隐私边界。

5.3 写回元数据

每条写入的长期 memory 都要带溯源信息：source_run_id（来自哪次 Run）、confidence（0-1 置信度，未来支持基于多次确认升权）、expires_at（可选过期时间）。这些字段是后续做"记忆版本化、过期淘汰、置信度更新"的基础。

写回动作每次写一条 StepTrace + AuditLog 关键事件 memory_written，记录条目种类、大小、source_run_id，便于审计"这条记忆是怎么进来的"。

6. 隔离 + 安全过滤

6.1 三层 scope 强制隔离

scope 是 Memory 子系统最底层的安全约束，任何召回 / 写回路径都必须先过 scope。三层从强到弱依次为 tenant、user、session。

6.2 隔离不变式（必测）

这三条不变式是上线前必须通过的验收测试，缺一项不允许放行。

1. 用户隔离：用户 A 的 user_memory 在任何召回 / 检索 / 列表接口下，都不得被用户 B 的 Run 看到
2. session 隔离：不同 session 的 session 私有摘要不得跨串（团队共享 memory 不在此约束内，那走 team scope）
3. tenant 隔离：不同租户的任何 memory 在任何路径下都不得跨可见，包括误用 SQL、误用缓存键、误用向量索引

6.3 安全过滤与 scope 的协同

scope 隔离管"读路径不串"，安全过滤管"写路径不漏"。两者协同覆盖三类典型故障：

6.4 PII 处理策略

PII 不是简单的"全部脱敏"——不同类型 PII 的处理策略不同。设计原则是：能 mask 就 mask，必须保留原文的字段（如长期联系邮箱）打 PII tag 便于后续 GDPR 删除。

所有打了 PII tag 的字段在 store 层支持按 user_id 一键删除，配合公司 GDPR 流程使用。