Memory Storage Service のベストプラクティス：スコープの設計、取得範囲、書き込み、監査 - Tablestore

このドキュメントでは、安定したスコープの設計、同期書き込みと非同期書き込みの使用、マルチターン、クロスセッション、マルチエージェントのシナリオにおける取得範囲と topK の制御方法について説明します。

安定したスコープの設計

スコープはメモリを分離し、取得範囲を制御します。統合の前に、書き込み基準と取得基準の間の不整合を防ぐために、4 レベルのフィールドのビジネス上の意味を定義してください。

4 レベルのフィールドの推奨マッピングは次のとおりです。

フィールド	推奨マッピング
`appId`	アプリケーション、製品、または事業部門。例：`customer_service`
`tenantId`	エンドユーザー、テナント、またはエンタープライズ ID。たとえば、SaaS マルチテナントアプリケーションのテナント ID です。
`agentId`	エージェントのロールまたはボットインスタンス。例：`sales_assistant`
`runId`	セッション ID、タスク ID、または実行 ID。例：`session_20260513`

データを書き込む際は、完全なスコープを使用します。

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

完全なスコープでデータを書き込むことで、データの帰属が明確になり、セッションレベルで短期記憶をクエリできます。

ビジネス目標に応じた取得範囲の選択

SearchMemories で長期記憶を取得する場合、appId と tenantId パラメーターは必須です。agentId と runId パラメーターには、ワイルドカード文字 (*) を使用できます。ビジネス目標に合ったスコープの組み合わせを選択してください。

現在のセッション内での取得

現在のセッション内で生成された長期記憶のみを取得するには、4 つのスコープフィールドすべてに値を指定します。

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

このアプローチは、マルチターンのカスタマーサービス会話でのフォローアップの質問など、現在のセッションの履歴にのみアクセスする場合に最適です。

セッションをまたいだ取得

runId にワイルドカード文字を使用し、他のフィールドに正確な値を指定することで、特定のエージェントとユーザーに関連付けられたすべてのセッションから長期記憶を取得します。

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

このスコープは、旅行アシスタントが将来の旅行のために座席の好みを記憶するなど、単一のエージェントが複数のセッションにわたってユーザーの好みを再利用する必要がある場合に最適です。

エージェントとセッションをまたいだ取得

agentId と runId の両方にワイルドカード文字を使用し、appId と tenantId のみを指定して、特定のアプリケーション内のユーザーのすべての長期記憶を取得します。

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

このスコープは、複数のエージェントがユーザーの長期記憶を共有する必要がある場合に役立ちます。Hermes および OpenClaw プラグインは、デフォルトでこの戦略を使用します。

会話メッセージの優先

AddMemories は、messages と text の 2 つの入力タイプをサポートしています。対話型エージェントは messages を優先し、role、timestamp、およびメッセージレベルの metadata を保持します。

{
  "messages": [
    {
      "role": "user",
      "content": "今後の出張では、窓側の席を優先的に予約してください。",
      "timestamp": "2026-05-13T10:00:00Z",
      "metadata": {
        "channel": "chat"
      }
    },
    {
      "role": "assistant",
      "content": "承知いたしました。このご希望を記憶しておきます。"
    }
  ]
}

会話メッセージを書き込むことには、2 つのメリットがあります。

短期記憶として元のメッセージをクエリできるため、会話の再生やトラブルシューティングが可能になります。
サーバー側で会話のコンテキストから長期記憶を抽出できるため、atomic_fact、temporal_anchor、preference などのユニットタイプの識別が簡素化されます。

同期書き込みの適切な使用

AddMemories.sync パラメーターのデフォルト値は false (非同期書き込み) です。このモードでは、サービスはまず元のメッセージを保存し、次にバックグラウンドタスクとして長期記憶を抽出します。通常、メモリは書き込み操作の完了後 15 秒以内に SearchMemories で取得可能になります。

さまざまなシナリオでの推奨事項は、次の表のとおりです。

シナリオ	`sync` の値	理由
オンライン会話パス	`false` (デフォルト)	ユーザーリクエストのブロッキングを回避するため。
デバッグ、テスト、およびデータインポートの検証	`true`	即時取得を有効にして、抽出結果を検証するため。
書き込み後の即時取得が必要なビジネスフロー	`false`、クライアント側で 15 秒の待機を実装	同期書き込みが完了した後でも、短いインデックス更新のレイテンシーが発生する可能性があります。

取得 topK の制御

SearchMemories.topK パラメーターのデフォルト値は 10 で、範囲は 1 から 50 です。ほとんどのエージェントシナリオでは、5 から 10 の間の値で十分です。

値を調整する際は、次の原則に従ってください。

topK 値を大きくすると再現率は向上しますが、下流タスクのコンテキスト長と処理コストも増加します。
エージェントが本当に必要とするメモリのみを注入してください。これにより、無関係なメモリによってプロンプトが希釈されるのを防ぎます。

Rerank の有効化の維持

SearchMemories.enableRerank パラメーターは、デフォルトで true に設定されています。高い関連性が要求される会話シナリオでは、このデフォルト設定を維持することを推奨します。

Rerank は、次のシナリオでのみ無効にしてください。

単一リクエストの取得レイテンシーを明示的に短縮する必要がある場合。
取得パフォーマンスのテストを実施しており、ベースラインを確立するために Rerank を無効にする必要がある場合。

説明

Rerank を無効にすると、取得精度が約 10% 低下すると推定されます。

メタデータを使用したデータソースのタグ付け

metadata フィールドを使用して、軽量のタグを保存できます。例：

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

次の推奨事項に従ってください。

キー名は一貫させてください。同じ意味には、src、source、from のようなキーを混在させず、単一のキーを使用してください。
ネストされたオブジェクトではなく、文字列値を使用してください。
大きなテキストブロックを保存しないでください。代わりに、長い形式のコンテンツは text または messages.content フィールドに書き込んでください。
監査とフィルタリングを簡素化するために、取得フィルタリングに必要なフィールドはすべて metadata に保存してください。

再生とトラブルシューティングのための短期記憶のクエリ

短期記憶は、元の会話メッセージで構成されています。ListMemoryStoreMessages API を呼び出すと、会話の再生、ユーザーの元の発言の検証、長期記憶の抽出結果のトラブルシューティングができます。

この API では、appId、tenantId、agentId、runId の 4 つのスコープフィールドすべてに値を指定する必要があります。ワイルドカード文字はサポートされていません。

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

トラブルシューティングのためのリクエスト監査の使用

書き込みまたは取得の結果が期待どおりでない場合は、まず ListMemoryStoreRequests API を使用してリクエスト監査を取得してください。

AddMemories リクエストが成功したかどうかを確認してください。
非同期書き込みの抽出タスクが失敗したかどうかを確認してください。
SearchMemories リクエストのスコープとそのリターンステータスを確認してください。
requestId を使用してアプリケーション側のログを関連付け、問題を引き起こした特定の呼び出しを特定してください。

リクエスト監査によって返されるフィールドの説明については、「API リファレンス」をご参照ください。

エージェントプラグインの統合

Hermes または OpenClaw プラグインを使用する場合は、デフォルトのプラグイン戦略を維持することを推奨します。

書き込み操作には正確なスコープを使用します。
取得操作には、同じテナント内でエージェントとセッションをまたぐスコープを使用します。
メモリストアが存在しない場合、プラグインが自動的に作成できるようにします。

ビジネスでより厳密な分離が必要な場合 (たとえば、異なるエージェントがメモリを共有してはならない場合)、SDK を使用して直接呼び出しを行い、取得時に完全なスコープを指定してください。プラグインの統合手順とパラメーターについては、「エージェントエコシステム統合」をご参照ください。