记忆存储服务最佳实践：Scope 设计、检索范围、写入与审计 - 表格存储

多轮对话、跨会话和多 Agent 场景下设计稳定 Scope、合理使用同步异步写入、控制检索范围与 TopK 的实践建议。

设计稳定的 Scope

Scope 是记忆隔离和检索范围控制的基础。接入前先确定四级字段在业务中的含义，避免后续写入和检索口径不一致。

四级字段的推荐映射：

字段	推荐映射
`appId`	应用、产品或业务线，例如 `customer_service`
`tenantId`	终端用户、租户或企业 ID，例如 SaaS 多租户应用的租户 ID
`agentId`	Agent 角色或机器人实例，例如 `sales_assistant`
`runId`	会话 ID、任务 ID 或运行 ID，例如 `session_20260513`

写入时使用完整 Scope：

{
  "appId": "customer_service",
  "tenantId": "user_001",
  "agentId": "assistant",
  "runId": "session_20260513"
}

完整 Scope 写入有两点收益：数据归属清晰，后续可按会话粒度查询短期记忆。

检索时按业务目标选择范围

SearchMemories 检索长期记忆时，appId 和 tenantId 必填，agentId 和 runId 可使用通配符 *。根据业务目标选择不同的 Scope 组合。

当前会话内检索

四级 Scope 全部填写，仅检索当前会话产生的长期记忆。

{
  "appId": "customer_service",
  "tenantId": "user_001",
  "agentId": "assistant",
  "runId": "session_20260513"
}

适用于只希望使用当前会话历史的场景，例如客服会话内的多轮跟进。

跨会话检索

runId 通配，其他字段精确，检索同一 Agent 在该用户下所有会话的长期记忆。

{
  "appId": "customer_service",
  "tenantId": "user_001",
  "agentId": "assistant",
  "runId": "*"
}

适用于同一个 Agent 跨会话复用用户偏好的场景，例如出行助手在多次行程中沿用座位偏好。

跨 Agent、跨会话检索

agentId 和 runId 都通配，仅锁定 appId 和 tenantId，检索同一用户在该应用下的所有长期记忆。

{
  "appId": "customer_service",
  "tenantId": "user_001",
  "agentId": "*",
  "runId": "*"
}

适用于同一用户下多个 Agent 共享长期记忆的场景。Hermes 和 OpenClaw 插件默认采用此策略。

优先写入对话消息

AddMemories 支持 messages 和 text 两种输入。对话型 Agent 优先使用 messages，并保留 role、timestamp 以及消息级 metadata。

{
  "messages": [
    {
      "role": "user",
      "content": "我以后出差都优先订靠窗座位",
      "timestamp": "2026-05-13T10:00:00Z",
      "metadata": {
        "channel": "chat"
      }
    },
    {
      "role": "assistant",
      "content": "好的，我会记住这个偏好。"
    }
  ]
}

写入对话消息有两点收益：

原始消息可作为短期记忆查询，便于回放和排查。
服务端结合对话上下文抽取长期记忆，更容易识别 atomic_fact、temporal_anchor、preference 等 unit_type。

合理使用同步写入

AddMemories.sync 默认值为 false，即异步写入。异步写入先保存原始消息，再由后台任务抽取长期记忆，写入完成后约 15 秒内可被 SearchMemories 召回。

不同链路的推荐取值：

场景	`sync` 取值	原因
在线对话链路	`false`（默认）	避免阻塞用户请求
调试、测试、数据导入校验	`true`	写入完成后立即检索可观察抽取结果
写入后立即检索的业务流程	`false`，业务侧加 15 秒等待	同步写入完成后仍存在短暂索引刷新延迟

控制检索 TopK

SearchMemories.topK 默认值为 10，取值范围 1~50。多数 Agent 场景设置为 5~10 即可。

调整原则：

TopK 调大可以提高召回，但下游上下文长度和处理成本同步增加。
仅注入 Agent 真正需要的记忆，避免无关记忆稀释提示词权重。

对于效果优先场景，保持 Rerank 开启

SearchMemories.enableRerank 默认值为 true。对相关性要求较高的对话场景保持默认值即可。

仅在以下场景关闭 Rerank：

明确需要降低单次检索延迟。
做检索效果对比测试，需要关闭重排作为基线。

说明

关闭Rerank后，预估检索准确率下降约10%。

使用 Metadata 标记数据来源

metadata 适合存储轻量标签，例如：

{
  "source": "chat",
  "channel": "web",
  "topic": "preference"
}

使用建议：

键名保持稳定。同一含义只用一个字段，避免 src、source、from 混用。
值使用字符串，不嵌套对象。
不存放大段文本，长正文写入 text 或 messages.content。
检索时需要按维度过滤的字段，全部写入 metadata，便于审计和过滤。

查询短期记忆用于回放和排查

短期记忆是原始会话消息。回放某个会话、核对用户原话或排查长期记忆抽取结果时，调用 ListMemoryStoreMessages。

该接口要求 appId、tenantId、agentId、runId 四级 Scope 全部填写，不支持通配符。

{
  "appId": "customer_service",
  "tenantId": "user_001",
  "agentId": "assistant",
  "runId": "session_20260513"
}

使用请求审计定位问题

写入或检索结果不符合预期时，先通过 ListMemoryStoreRequests 拉取请求审计：

查看 AddMemories 请求是否成功。
查看异步写入对应的抽取任务是否失败。
查看 SearchMemories 请求使用的 Scope 和返回状态。
按 requestId 关联应用侧日志，定位问题发生的具体调用。

请求审计返回字段语义参见 API 接口介绍。

Agent 插件接入建议

使用 Hermes 或 OpenClaw 插件时，保留插件默认策略：

写入时使用精确 Scope。
检索时使用同一租户下跨 Agent、跨会话的 Scope。
记忆库不存在时由插件自动创建。

业务对隔离要求更严格时（例如不同 Agent 之间不能共享记忆），改用 SDK 直接调用，并在检索时指定完整 Scope。插件接入步骤和参数详见 Agent 生态集成。