跳转至

记忆记录与检索契约 Schema

这一页把智能体系统里记忆与检索所需的最小契约层放在一起：记忆记录长什么样、检索请求应该带哪些字段，以及记忆层至少要满足哪些约束，才能避免它变成泄漏、噪声和错误自信的来源。

如果 追踪模式与事件目录 回答的是“这些东西如何出现在遥测里”，而 生命周期工件模式 回答的是“哪些东西算受治理的运行工件”，那么记忆与检索模式回答的就是“记忆层里到底允许存在什么样的记录和过滤规则”。

规范记忆案例（Canonical memory cases）

记忆与检索契约（memory and retrieval contract）应该为三个规范案例（canonical cases）区分不同的记忆边界（memory boundaries）。支持分流（Support triage） 保存请求者上下文（requester context）、工单状态（ticket state）、idempotency_key 证据（idempotency_key evidence）和短期工作笔记（short-lived working notes）。内部知识助手（Internal knowledge assistant） 需要检索新鲜度（retrieval freshness）、来源归因（source attribution）、租户过滤器（tenant filters）、记忆来源（memory provenance）和访问控制（access control）。事件协调（Incident coordination） 保存事件时间线（incident timeline）、响应归属（response ownership）、交接摘要（handoff summaries）、升级状态（escalation status）和事件后经验（post-incident lessons），但不能把临时事件噪声（transient incident noise）变成持久真相（durable truth）。

1. 为什么需要单独的模式层

记忆里最常见的失败路径通常是这样的：

  • 智能体记住了某些东西；
  • 检索返回了某些东西；
  • 但团队已经无法有把握地回答：
  • 这到底是什么类型的记录；
  • 它从哪里来；
  • 谁本来有权读取它；
  • 它为什么会进入提示。

所以，把记忆层描述成“我们有个向量存储”远远不够。更稳妥的做法是把它描述成类型化记录和类型化检索规则。

2. 核心实体

一个最小可用的层，通常围绕三个实体就够了：

  • memory_record
  • retrieval_query
  • retrieval_result

这已经足够把第 5-7 章、策略层、追踪模式和参考运行时串起来。

3. 记忆记录

memory_record 描述记忆层里的单条具体记录。

kind: memory_record
record_id: mem-tenant-acme-001
tenant_id: tenant-acme
memory_class: profile
key: preferred_language
value: English
source: user_confirmed_preference
provenance: user_confirmed_preference
revision: 1
trust_level: high
created_at: 2026-04-07T12:00:00Z
retention: long_term

这里最关键的是：

  • tenant_id 防止检索跨越租户边界；
  • memory_class 区分 short_term、long_term 和 profile；
  • source 与 provenance 能帮助区分观察结果和已验证事实；
  • revision 让历史不会被静默覆盖；
  • trust_level 防止所有记录被一视同仁。

对于记忆投毒复核（memory poisoning review），应该通过记忆投毒复核字段（memory poisoning review fields）把记录或候选写入（candidate write）描述成可审查的安全对象（security object），而不只是检索载荷（retrieval payload）：

write_trust_boundary: untrusted_write
activation_policy: delayed_activation_review
contamination_scope: tenant_local
policy_influence: false
provenance_check: required
quarantine_state: quarantined
rollback_ref: mem-rollback-2026-05-001

这些字段把 untrusted write、delayed activation、cross-tenant contamination、policy influence、provenance check 和 quarantine and rollback 连接到机器可检查的记忆模式（machine-checkable memory schema）。

4. 检索查询

retrieval_query 描述的不是一个简单文本搜索，而是完整的记忆读取上下文。

kind: retrieval_query
trace_id: trace-001
session_id: session-001
tenant_id: tenant-acme
principal_id: user-42
purpose: answer_generation
allowed_classes:
  - profile
  - long_term
filters:
  trust_min: medium
  max_age_days: 90
  require_provenance: true
limit: 5

这很重要，因为检索不应该是“神秘搜索”，而应该是正常的受控读取路径。

5. 检索结果

retrieval_result 记录运行时最终决定放回上下文里的内容。

kind: retrieval_result
trace_id: trace-001
session_id: session-001
selected_records:
  - record_id: mem-tenant-acme-001
    memory_class: profile
    trust_level: high
    provenance: user_confirmed_preference
  - record_id: mem-tenant-acme-177
    memory_class: long_term
    trust_level: medium
    provenance: validated_service_rule
selection_reason:
  - profile_match
  - tenant_match
  - trust_filter_passed
excluded_records: 12

这样团队后面就能解释：

  • 为什么偏偏是这些记录进了提示；
  • 到底哪些限制起了作用；
  • 有多少记录被过滤掉了。

6. 它和策略层的关系

记忆读取路径和记忆写入路径几乎不应该共用同一套规则：

  • 写入路径更关注校验、来源证明和保留规则；
  • 读取路径更关注租户边界、信任过滤器和类别限制。

所以，一个好的记忆模式几乎总是和策略即代码并排存在。

7. 它和追踪模式的关系

追踪模式 里已经有一些字段和事件直接支撑记忆纪律：

  • context_layers_built
  • memory_persisted
  • memory_class
  • provenance
  • revision

这说明记忆与检索契约不只是一个独立文档，它还是清晰遥测的基础。

8. 它和参考包的关系

agent_runtime_ref 已经有支撑这套模型的运行原语：

内置的 memory.yaml 通过 seed_records 把这件事具体化：每条种子记录（seed record）都带有稳定的 memory_id，以及 tenant_id、memory_class、kind、content、source、confidence、provenance 和 revision；打包类别（bundled kinds）是 language_preference、validated_fact 和 working_note，因此演示（demo）可以同时展示检索过滤（retrieval filtering）与记录脉络（lineage）。参考种子记录（mem-001、mem-002 和 mem-003）有意覆盖 trusted_profile、trusted_service 与 session_state 来源（sources），并包含 ephemeral_session_note 这样的来源信息（provenance），让检索示例（retrieval examples）能呈现不同的信任与持久化级别（trust and persistence levels）。非资料种子内容（Non-profile seed content）还包括策略式事实（policy-like fact）Support tickets must use the support queue and include requester_id. 以及工作笔记（working note）Recent runtime demo used create_ticket as the main write capability. 加载器（Loader）也会校验这个形状（shape）：Memory store config must be a mapping、'memory' must be a mapping、'seed_records' must be a list、Memory record #{idx} must be a mapping、Memory record #{idx} field must be a string: {key}、Memory record #{idx} field must be a string: {field}、Memory record #{idx} field must be a string: memory_id、Memory record #{idx} field must be a string: provenance、Memory record #{idx} field is required: {key}、Memory record #{idx} field is required: memory_id、Memory record #{idx} confidence must be a number、Memory record #{idx} confidence must be between 0 and 1 和 Memory record #{idx} revision must be an integer 和 Memory record #{idx} revision must be positive，直接记忆存储构造（direct memory store construction）会用 Memory store records must be MemoryRecord 拒绝畸形注入记录（malformed injected records），并用 Memory store candidate must be MemoryCandidate 拒绝畸形直接候选（malformed direct candidates），直接构造记录（direct construction records）使用稳定错误（stable errors）Memory record field must be a string: {field}、Memory record field is required: {field}、Memory record confidence must be a number、Memory record confidence must be between 0 and 1、Memory record revision must be an integer 和 Memory record revision must be positive，候选修订模式（Memory candidate revision mode）会用 Memory candidate revision mode must be a string 和 Memory candidate revision mode is not supported: {revision_mode} 校验，候选置信度（Memory candidate confidence）会用 Memory candidate confidence must be a number 和 Memory candidate confidence must be between 0 and 1 校验，候选字段（Memory candidate field）会用 Memory candidate field must be a string: {field} 和 Memory candidate field is required: {field} 校验，记忆查询字段（Memory lookup field）会用 Memory lookup field must be a string: {field} 和 Memory lookup field is required: {field} 校验，记忆查询限制（Memory lookup limit）会用 Memory lookup limit must be an integer 和 Memory lookup limit must be non-negative 校验。

这很有价值，因为书里不只是解释记忆契约，也给出了可运行的骨架。

9. 最小不变量

一个健康的记忆与检索层，至少应该保证：

  • 每条记录都有 tenant_id 和 memory_class；
  • 持久记录带有 provenance 和 revision；
  • 检索总是受类别和数量限制；
  • 检索请求明确知道“谁在读、为什么读”；
  • 检索结果能从追踪里还原；
  • 摘要不是默认真相。

10. 最常见的断裂点

这里的典型问题通常很容易识别：

  • 检索返回的是“相似”，却不是“有用”；
  • 记忆记录没有按信任等级区分；
  • 摘要静默覆盖了更可靠的事实；
  • 检索忽略租户边界；
  • 提示吞进了太多未经筛选的上下文；
  • 来源证明只存在于文档里，不存在于运行时里。

11. 现在就该做什么

先过一遍这份短清单，把所有回答为“否”的地方单独记下来：

  • 每条记录是否都有 tenant_id、memory_class、provenance 和 revision？
  • 记忆读取策略和记忆写入策略是否真的不同？
  • 检索是否受信任等级、类别和数量限制？
  • 你能解释某条记录为什么进入了提示吗？
  • 是否有防止跨租户检索的保护？
  • 记忆决策是否能在追踪和会话导出里看到？

如果连续几个答案都是“否”，那说明你已经有了记忆，但还没有真正的记忆纪律。

下一步做什么