記憶儲存服務最佳實務：Scope 設計、檢索範圍、寫入與審計 - Tablestore

多輪對話、跨會話和多 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 生態整合。