View a markdown version of this page

長期記憶のための構造化メタデータ - Amazon Bedrock AgentCore

長期記憶のための構造化メタデータ

Amazon Bedrock AgentCore Memory のメタデータフィルタリングを使用すると、構造化属性を長期メモリレコードに追加できます。これらの属性を使用して、取得時に返されるレコードを絞り込むことができます。名前空間は、プライマリエンティティ (ユーザー、テナント、患者、クライアント) によって既にメモリを分離しています。ただし、単一の名前空間内では、広範なセマンティック検索は意味が近いものをすべて返します。メタデータフィルタリングを使用すると、特定の属性値に一致する結果のみを取得できます。たとえば、優先度の高いレコードのみ、特定の部門からのレコードのみ、または特定の時間範囲内に作成されたレコードのみを取得できます。

メタデータフィルタリングを使用すると、次のことができます。

  • 名前空間内のビジネスディメンション (優先度、部門、チャネル、時間範囲) によるスコープの取得

  • 作成時に構造化メタデータをイベントとメモリレコードにアタッチする

  • メモリ取り込み中に会話コンテンツからメタデータを自動的に抽出する大規模言語モデル (LLM) を使用する

  • 一貫したフィルタリングのために LLM 抽出値を特定の値に制限する

  • ロジックで適用されるListMemoryRecordsRetrieveMemoryRecordsまたは のクエリごとに最大 5 AND つのフィルターを組み合わせる

  • 追加のインデックス付きキーを宣言せずに、システムによって生成されたタイムスタンプ (x-amz-agentcore-memory-createdAtx-amz-agentcore-memory-updatedAt) をフィルタリングする

開始方法

メタデータフィルタリングの設定には、次の 5 つのステップが含まれます。

  1. インデックス付きキーとメタデータスキーマを使用してメモリを作成する

    • インデックス付きキーCreateMemory (または UpdateMemory) を使用して、フィルタリングするメタデータキー (、、 など) priority channelを宣言しますtags。メモリあたり最大 10 個のインデックス付きキーを宣言できます。インデックス付きキーは、フィルター式でクエリ可能な属性を定義します。インデックス付きキーを追加すると、削除することはできません。

    • メタデータスキーマ — LLM が会話から値を抽出する方法を制御する戦略metadataSchemaで を定義します。スキーマは、抽出するキー、イベント間の競合を解決する方法、適用する検証制約を指定します。メタデータスキーマはオプションです。メタデータスキーマを使用しない戦略はメタデータ抽出を実行しません。

  2. 設定の検証 — を使用してGetMemory、インデックス化されたキーと戦略メタデータスキーマが正しく設定されていることを確認します。

  3. メタデータを使用してデータを取り込む — オプションメタデータCreateEventを使用して イベントを送信するか、 を使用してレコードに直接メタデータを指定しますBatchCreateMemoryRecords。イベント駆動型の取り込みの場合、LLM は結果のメモリレコードのメタデータを自動的に抽出して入力します。この抽出は、メタデータがイベントにアタッチされていない場合でも、戦略のメタデータスキーマと会話コンテンツに基づいています。

  4. メタデータフィルターを使用したクエリ — (事前フィルタリングによるRetrieveMemoryRecordsセマンティック検索) または ListMemoryRecords (メタデータのみのフィルタリング) を使用して結果をスコープmetadataFiltersします。

  5. 時間の経過とともにスキーマを進化させる — 新しいインデックス付きキーを追加するか、フィルタリングのニーズが大きくなるにつれて戦略メタデータスキーマを変更します。

以降のセクションでは、各ステップについて詳しく説明します。

主要なコンセプト

インデックス付きメタデータキー

インデックス付きキーは、 のメモリリソースレベルで宣言されます CreateMemory (または後で を介して追加されますUpdateMemory)。インデックス付きキーは、高速クエリフィルタリング用に最適化された形式で保存されます。ListMemoryRecords および metadataFiltersの では、インデックス付きキーのみがクエリ可能ですRetrieveMemoryRecords

次の例では、2 つのインデックス付きキーを宣言します。

{ "indexedKeys": [ { "key": "priority", "type": "STRING" }, { "key": "tags", "type": "STRINGLIST" } ] }

サポートされているtype値: STRINGSTRINGLISTNUMBER

キーは一致する必要があります ^[a-zA-Z0-9\s._:/=+@-]*$ (最大 128 文字)。

インデックス付きキーを追加しても、既存のレコードはバックフィルされません。キーが宣言された後に作成または更新されたレコードのみが、そのキーのインデックスが作成されます。スキーマの経時的な進化の詳細については、「」を参照してくださいステップ 5: メタデータスキーマを進化させる

メタデータスキーマ (戦略ごと)

Memory Strategy は、オプションで で宣言されたメタデータスキーマを持つことができますmemoryRecordSchema.metadataSchema。メタデータスキーマは、メモリレコードを生成するときに会話コンテンツから抽出するメタデータを LLM に指示します。戦略のメタデータスキーマで定義されたキーのみが、イベント駆動型抽出中に結果のメモリレコードに入力されます。

スキーマの各エントリは、以下を定義します。

  • key — メタデータキー名。このキーがインデックス付きキーとしても宣言されている場合、抽出された値はフィルタリング可能です。インデックス付きキーでない場合、値はレコードに入力され、 GetMemoryRecord および ListMemoryRecordsレスポンスに表示されますが、フィルター式では使用できません。

  • type — 値タイプ (STRINGSTRINGLISTNUMBER)。

  • definition (必須) — フィールドが表す自然言語の説明。具体的に – 「優先度」の代わりに、顧客への影響に基づいて「発行優先度レベル」を記述します。値の範囲は、重大 (最も重大) から低 (最も重大) です。

  • llmExtractionInstruction (オプション) — LLM が値を抽出または解決する方法に関する追加のガイダンス。組み込み LATEST_VALUE (最新の値を保持) を使用するか、「ビジネスへの影響に基づいて分類する: 本番稼働に影響するサービス停止critical、パフォーマンスhighの低下、medium機能リクエスト、lowドキュメントや外観の問題に使用する」などのカスタム自然言語指示を提供できます。

  • validation (オプション) — LLM の出力を制御された値のセットに制限します。検証を行わないと、LLM は同じ概念"HIGH""High""high"、または を生成し、フィルターマッチングを中断する可能性があります。

次の例は、検証を含むメタデータスキーマエントリを示しています。

{ "metadataSchema": [ { "key": "priority", "type": "STRING", "extractionConfig": { "llmExtractionConfig": { "definition": "Issue priority level based on customer impact. Values range from critical (most severe) to low (least severe).", "llmExtractionInstruction": "LATEST_VALUE", "validation": { "stringValidation": { "allowedValues": ["critical", "high", "medium", "low"] } } } } } ] }

タイプ別の検証オプション:

タイプ 検証 説明

STRING

stringValidation.allowedValues

固定セットに制限する (最大 10 個の値、各最大 256 文字、一致^[a-zA-Z0-9\s._:/=+@-]*$)

STRINGLIST

stringListValidation.allowedValues

リストメンバーを固定セットに制限する (最大 10 個の値、各最大 256 文字、一致^[a-zA-Z0-9\s._:/=+@-]*$)

STRINGLIST

stringListValidation.maxItems

リスト内の最大項目数 (1~5)

NUMBER

numberValidation.minValue

最小許容値

NUMBER

numberValidation.maxValue

最大許容値

決定メタデータ (STRICTLY_CONSISTENT 抽出タイプ)

決定的なメタデータキーには、イベントの作成時にアプリケーションが既に知っている値が含まれています。これらの値は、変更せずに結果のメモリレコードに正確にコピーされます。departmentcompliance_level、 などの組織分類子は、LLM によって推測agent_idしないでください。LLM 推論は変動性をもたらします。たとえば、同じ会話が 1 つのレコード"eng"で生成され、別のレコード"Engineering"で生成されます。

これらのキーについては、メタデータスキーマエントリSTRICTLY_CONSISTENTextractionTypeを に設定します。イベントで指定された値は、抽出と統合によって変更されません。LLM はそのキーについて参照されません。

次の JSON は、 STRICTLY_CONSISTENTと の両方のLLM_INFERRED抽出タイプを持つメタデータスキーマを示しています。

{ "metadataSchema": [ { "key": "department", "type": "STRING", "extractionType": "STRICTLY_CONSISTENT" }, { "key": "compliance_level", "type": "STRING", "extractionType": "STRICTLY_CONSISTENT" }, { "key": "topic", "type": "STRING", "extractionType": "LLM_INFERRED", "extractionConfig": { "llmExtractionConfig": { "definition": "Primary topic of the conversation", "llmExtractionInstruction": "Identify the main topic discussed" } } } ] }

を省略するとextractionType、デフォルトは になりますLLM_INFERRED

抽出と統合の分離

STRICTLY_CONSISTENT キーは、LLM 推論をスキップするだけではありません。抽出中に決定論値でイベントをグループ化します。異なる値を持つイベントは個別に処理されます。統合は同じルールに従います。ある値グループのレコードが別のグループのレコードとマージされることはありません。

次の Python の例は、2 つの決定論的キー (department と ) を持つサポートセッションを示していますpriority

# Event 1: high-priority billing inquiry agentcore_client.create_event( memoryId="mem-support-abc123", actorId="customer-123", sessionId="session-escalation-001", payload=[{"conversational": {"role": "USER", "content": {"text": "I'm seeing duplicate charges on my invoice and it's blocking our deployment."}}}], metadata={ "department": {"stringValue": "billing"}, "priority": {"stringValue": "high"} } ) # Event 2: also high-priority billing (same deterministic values as Event 1) agentcore_client.create_event( memoryId="mem-support-abc123", actorId="customer-123", sessionId="session-escalation-001", payload=[{"conversational": {"role": "USER", "content": {"text": "The charges appeared after we upgraded from standard to enterprise tier last week."}}}], metadata={ "department": {"stringValue": "billing"}, "priority": {"stringValue": "high"} } ) # Event 3: high-priority engineering (same priority, different department) agentcore_client.create_event( memoryId="mem-support-abc123", actorId="customer-123", sessionId="session-escalation-001", payload=[{"conversational": {"role": "USER", "content": {"text": "Your team found a provisioning bug that triggered the duplicate charge."}}}], metadata={ "department": {"stringValue": "engineering"}, "priority": {"stringValue": "high"} } ) # Event 4: low-priority billing (same department as Events 1-2, different priority) agentcore_client.create_event( memoryId="mem-support-abc123", actorId="customer-123", sessionId="session-escalation-001", payload=[{"conversational": {"role": "USER", "content": {"text": "Also, can you update the billing contact email on file when you get a chance?"}}}], metadata={ "department": {"stringValue": "billing"}, "priority": {"stringValue": "low"} } )

システムは、すべての決定論的キー値の正確な組み合わせによってイベントをグループ化します。

  • イベント 1 と 2 は を共有しますdepartment=billing, priority=high。これらは一緒に抽出されます。

  • イベント 3 は で異なりますdepartment。を共有しているにもかかわらず、個別に抽出されますpriority=high

  • イベント 4 は で異なりますpriority。を共有しているにもかかわらず、個別に抽出されますdepartment=billing

イベントをグループ化するには、決定的なキー値がすべて一致する必要があります。department=billing AND を含むクエリは、緊急の重複料金の事実のみpriority=highを返します。他のイベントは別々のパーティションにあります。異なる値の組み合わせのレコードが統合中にマージされることはありません。

制約

制約 [Detail] (詳細)

戦略あたりの最大決定キー

3

キーのタイプ

STRING を指定してください

インデックスを作成する必要があります

キーはメモリの indexedKeys

いいえ extractionConfig

STRICTLY_CONSISTENT キーに を含めることはできませんextractionConfig。値は、LLM ではなくイベントから取得されます。

サポートされている戦略

セマンティック、ユーザー設定、およびエピソード戦略 (カスタムオーバーライドを含む)。概要戦略ではサポートされていません。

欠落した値

決定キーの値なしでイベントが到着した場合、そのキーはそのイベントのグループ化から除外され、結果のレコードには存在しません。

重要

として設定されるキーを変更すると、抽出と統合に使用されるグループ化STRICTLY_CONSISTENTが変更されます。前の設定で作成されたレコードは、新しい設定で作成されたレコードから分離されます。イベントを取り込む前に、決定的なキー設定を計画します。

インデックス付きキーとスキーマキーの相互作用

インデックス付きキーとスキーマキーの関係によって、メタデータの動作が決まります。

  • スキーマのインデックス付き + — キーは LLM によって抽出されたレコードに入力され、クエリ式でフィルタリングできます。これは、抽出とフィルタリングの両方を行うキーの最も一般的な設定です。

  • インデックス付き + スキーマにない — イベント駆動型抽出中、キーはレコードに入力されません。このキーのフィルタは、抽出されたレコードの結果を返しません。これらのキーを入力するには、バッチ APIs (BatchCreateMemoryRecords または BatchUpdateMemoryRecords) を使用します。

  • スキーマ + インデックスなし — LLM は値を抽出してレコードに入力し、 GetMemoryRecord および ListMemoryRecordsレスポンスに表示されます。ただし、フィルター式では使用できません。これはコンテキストエンリッチメントに役立ちます。 sentimentや などのメタデータsummary_notesは、インデックス化されたキー予算を消費することなく、ダウンストリームの消費のためにレコードをエンリッチします。

メタデータがイベントからメモリレコードに流れる方法

イベントメタデータはstringValueエントリのみを受け入れます。メモリレコードは、抽出中に LLM によって入力されるかstringValue、バッチ APIs を介して直接提供される stringListValue、、および numberValueタイプをサポートします。dateTimeValue タイプは、システム生成フィールド (x-amz-agentcore-memory-createdAt および ) 用に予約されていますx-amz-agentcore-memory-updatedAt。ストラテジーの で定義されたキーのみが抽出されたレコードに入力metadataSchemaされます。スキーマにないイベントメタデータキーは無視されます。エントリの制限については、「」を参照してくださいクォータ

システム生成メタデータ

すべてのメモリレコードにはこれらのシステムフィールドがあり、同じフィルター演算子でクエリできます。

フィールド タイプ 説明

x-amz-agentcore-memory-recordType

stringValue

メモリレコードのタイプ

x-amz-agentcore-memory-createdAt

dateTimeValue

レコード作成タイムスタンプ

x-amz-agentcore-memory-updatedAt

dateTimeValue

最終更新タイムスタンプを記録する

これらをインデックス付きキーとして宣言する必要はありません。これらは常にフィルタリングできます。これらのシステム生成dateTimeValueフィールドは BEFOREおよび AFTER演算子をサポートし、日時インデックス付きキーを宣言することなく、時間範囲クエリを有効にします。

前提条件

メタデータフィルタリングを設定する前に、以下を確認してください。

  • CreateMemory、、UpdateMemory、、、BatchCreateMemoryRecords、および CreateEvent ListMemoryRecords RetrieveMemoryRecordsを呼び出すアクセス許可を持つ AWS アカウント BatchUpdateMemoryRecords

  • Amazon Bedrock AgentCore アクセス

  • エージェントが最も必要とする 3~5 個のフィルターディメンション (部門、優先度、リージョン、プロジェクトなど) の明確なビュー

ステップ 1: インデックス付きキーとメタデータスキーマを使用してメモリを作成する

以下では、5 つのインデックス付きキーとメタデータスキーマを持つカスタマーサポートメモリを作成します。priorityagent_type、および sentimentは戦略のメタデータスキーマで定義され、LLM は会話コンテンツから値を抽出します。sentiment はスキーマにありますが、インデックス付きキーとして宣言されていないことに注意してください。LLM は会話から値を取得し、レコードに入力しますが、フィルター式では使用できません。 tags (STRINGLIST)、 channel (STRING)、 ticket_id (STRING) はインデックス付きキーとして宣言されますが、スキーマにはありません。イベント駆動型の抽出では入力されませんが、Batch APIsを介して指定できます。

aws bedrock-agentcore-control create-memory \ --name "CustomerSupportMemory" \ --event-expiry-duration 30 \ --indexed-keys '[ {"key": "priority", "type": "STRING"}, {"key": "agent_type", "type": "STRING"}, {"key": "tags", "type": "STRINGLIST"}, {"key": "channel", "type": "STRING"}, {"key": "ticket_id", "type": "STRING"} ]' \ --memory-strategies '[ { "semanticMemoryStrategy": { "name": "SupportSemanticStrategy", "description": "Captures support interaction details", "namespaceTemplates": ["support/{actorId}"], "memoryRecordSchema": { "metadataSchema": [ { "key": "priority", "type": "STRING", "extractionConfig": { "llmExtractionConfig": { "definition": "Issue priority level based on customer impact. Values range from critical (most severe) to low (least severe).", "llmExtractionInstruction": "LATEST_VALUE", "validation": { "stringValidation": { "allowedValues": ["critical", "high", "medium", "low"] } } } } }, { "key": "agent_type", "type": "STRING", "extractionConfig": { "llmExtractionConfig": { "definition": "Support agent classification.", "llmExtractionInstruction": "Prefer the most specialized agent type. Hierarchy: specialist > tier3 > tier2 > tier1 > bot." } } }, { "key": "sentiment", "type": "STRING", "extractionConfig": { "llmExtractionConfig": { "definition": "Customer sentiment during the interaction.", "llmExtractionInstruction": "LATEST_VALUE", "validation": { "stringValidation": { "allowedValues": ["positive", "neutral", "negative", "frustrated"] } } } } } ] } } } ]'

ステップ 2: 設定を確認する

を使用してGetMemory、インデックス付きキーとメタデータスキーマが受け入れられたことを確認します。

aws bedrock-agentcore-control get-memory --memory-id "<memory-id>"

ステップ 3: メタデータを使用してデータを取り込む

メタデータをメモリレコードに取り込むには、2 つのパスがあります。

イベント駆動型の取り込み

作成時にイベントにstringValueメタデータをアタッチします。LLM は、戦略のメタデータスキーマを使用して、生成されたメモリレコードにメタデータを抽出して入力します。戦略の で定義されたキーのみが結果のレコードに入力metadataSchemaされます。スキーマにないイベントメタデータキーは、抽出中に無視されます。

aws bedrock-agentcore create-event \ --memory-id "<memory-id>" \ --actor-id "customer-123" \ --session-id "session-001" \ --event-timestamp "$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ")" \ --metadata '{ "priority": {"stringValue": "high"}, "channel": {"stringValue": "email"}, "ticket_id": {"stringValue": "TKT-5001"} }' \ --payload '[ {"conversational": {"role": "USER", "content": {"text": "I have a billing issue that is blocking my production deployment"}}}, {"conversational": {"role": "ASSISTANT", "content": {"text": "I understand this is urgent. Let me escalate to our billing specialist team."}}} ]'

この例では、 priorityは戦略の にあるためmetadataSchema、その値はメモリレコードに伝達されます。 channelticket_idはスキーマにないため、抽出中は無視されます。LLM は、会話コンテンツから agent_type (エスカレーション"specialist"に基づいて) と sentiment (おそらく "frustrated") も推測します。これらのスキーマキーは、イベントメタデータとして提供されていなくても入力されます。

会話コンテンツからの暗黙的なメタデータ抽出

スキーマキーが値を生成するためにイベントメタデータは必要ありません。スキーマキーに元のイベントに一致するメタデータがない場合、LLM は会話コンテンツから完全に値を取得します。キーの definitionと を使用して値llmExtractionInstructionを決定します。これは、会話自体にのみ存在するディメンションに便利です。イベント作成時に発信者に指定する必要はありません。

ステップ 1 と同じカスタマーサポートメモリを使用すると、次のイベントにはメタデータがまったくありません。

aws bedrock-agentcore create-event \ --memory-id "<memory-id>" \ --actor-id "customer-789" \ --session-id "session-002" \ --event-timestamp "$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ")" \ --payload '[ {"conversational": {"role": "USER", "content": {"text": "My production deployment is down because of a billing hold on our account"}}}, {"conversational": {"role": "ASSISTANT", "content": {"text": "I understand the urgency. Let me connect you with our billing specialist team right away."}}} ]'

LLM は会話の内容を分析し、抽出されたメモリレコードに priority、、および の 3 つのスキーマキーをすべて入力します。sentimentただしagent_type、イベントメタデータとして何も指定されていません。

{ "content": {"text": "Customer reported a production outage caused by a billing hold. Escalated to billing specialist."}, "metadata": { "priority": {"stringValue": "critical"}, "agent_type": {"stringValue": "specialist"}, "sentiment": {"stringValue": "frustrated"} } }

検証ルールは引き続き適用されます。LLM の出力は、値がイベントメタデータまたはコンテンツ推論のいずれからのものであるかに関係なく、指定された許可された値に制限されます。

LLM がイベント間の競合を解決する方法

セッション内の複数のイベントが同じメタデータキーに対して異なる値を持つ場合、LLM は を使用しますllmExtractionInstruction。これにより、結果のメモリレコードに保持する値が決まります。

たとえば、最初のイベントに priority: "low"があり、後のイベントが にエスカレートするサポートセッションを考えてみましょうpriority: "critical"。LLM は、 命令に基づいてこれを解決します。

  • LATEST_VALUE (組み込み) — LLM は最新の値を保持します。この場合、メモリレコードは を取得しますpriority: "critical"

  • カスタム手順 — ドメイン固有のロジックを表現できます。例えば、「セッション中に報告された最も高い重要度を維持する」でも が生成されますが"critical"、別の理由で、最新のものだけでなく最も高い重要度になります。

もう 1 つの例: 命令agent_type「最も特殊なエージェントタイプを優先する」の 。階層: specialist > tier3 > tier2 > tier1 > bot"。セッションがボットで始まり、tier2 エージェントにエスカレートすると、メモリレコードは を取得しますagent_type: "tier2"

決定論的なメタデータの取り込み

として設定されたキーは、別の取り込みパスSTRICTLY_CONSISTENTに従います。イベントで指定する値は、 が結果のレコードに配置する値です。LLM 推論や競合解決はありません。

AgentCore Memory は、抽出前に決定論的なキー値でイベントをグループ化します。たとえば、タグ付けされたイベントdepartment: "engineering"は、タグ付けされたイベントとは別に処理されますdepartment: "finance"

統合はこれらのグループ内で動作します。を持つレコードは、 というラベルのレコードとマージcompliance_level: "hipaa"されませんcompliance_level: "standard"。これにより、決定論的なキーは以下に最適です。

  • コンプライアンス分離 - コンプライアンスレベルが異なるレコードが混在することはありません。

  • 組織ルーティング - 交差汚染のない部門範囲の取得。

  • マルチテナントサブフィルタリング - テナント固有の属性は、指定されたとおりに正確に保持されます。

イベントに決定キーの値がない場合、キーは結果のレコードには存在しません。

直接書き込みパス (BatchCreateMemoryRecords および BatchUpdateMemoryRecords) は抽出をバイパスします。STRICTLY_CONSISTENT 抽出タイプはそれらには影響しません。これらの APIs。

Batch APIsを使用した直接レコードの作成

ナレッジベースのインポート、セルフマネージド戦略、または事前処理されたコンテンツの場合は、 BatchCreateMemoryRecords (または BatchUpdateMemoryRecords) を使用してメタデータを明示的に指定します。これにより、LLM 抽出全体がバイパスされます。発信者はメタデータ値を制御します。

バッチ作成レコードでのメタデータの処理方法は、 を提供するかどうかによって異なりますmemoryStrategyId

  • memoryStrategyId - サービスは、入力メタデータをその戦略の に対してフィルタリングしますmemoryRecordSchema。スキーマで定義されたキーのみがレコードに保存されます。スキーマにないインデックス付きキーを含む他のすべてのキーは、サイレントに削除されます。これにより、スキーマで強制された整合性が得られ、バッチ作成されたレコードのメタデータシェイプがイベント駆動型の抽出によって生成されたレコードと同じになります。

  • なし memoryStrategyId — サービスは、すべてのメタデータキーをペイロードにそのままレコードに保存します。これには、インデックスが作成されたキー、戦略スキーマにあるキー、およびどちらもないキーが含まれます。ただし、インデックス付きキーのみがフィルタリング可能です。インデックスなしキーでフィルタリングしようとすると、 が返されますValidationException。インデックス化されていないキーは、引き続き GetMemoryRecordおよび ListMemoryRecordsレスポンスに表示されます。

次の例では、 なしでレコードを作成しmemoryStrategyId、提供されたすべてのメタデータを保存します。

aws bedrock-agentcore batch-create-memory-records \ --memory-id "<memory-id>" \ --records '[{ "requestIdentifier": "import-001", "namespaces": ["support/customer-456"], "content": {"text": "Customer prefers phone support for urgent billing issues"}, "timestamp": "2026-01-15T10:00:00Z", "metadata": { "priority": {"stringValue": "high"}, "agent_type": {"stringValue": "billing_agent"}, "channel": {"stringValue": "phone"}, "ticket_id": {"stringValue": "TKT-7890"} } }]'

スキーマの整合性を適用するには、 を含めますmemoryStrategyId。この場合、その戦略に存在するキーのみが保持memoryRecordSchemaされます。

aws bedrock-agentcore batch-create-memory-records \ --memory-id "<memory-id>" \ --records '[{ "requestIdentifier": "import-002", "namespaces": ["support/customer-456"], "memoryStrategyId": "<strategy-id>", "content": {"text": "Billing dispute resolved after account credit applied"}, "timestamp": "2026-01-16T14:00:00Z", "metadata": { "priority": {"stringValue": "medium"}, "agent_type": {"stringValue": "billing_agent"}, "channel": {"stringValue": "phone"} } }]'

2 番目の例では、戦略のスキーマが priorityagent_type、 のみを定義している場合sentimentchannelは保存されたレコードからサイレントに削除されます。

BatchUpdateMemoryRecords を使用したレコードの更新

BatchUpdateMemoryRecords は、 と同じmemoryStrategyIdメタデータフィルタリング動作に従いますBatchCreateMemoryRecords。次の の例では、既存のレコードのコンテンツとメタデータを更新します。

aws bedrock-agentcore batch-update-memory-records \ --memory-id "<memory-id>" \ --records '[{ "memoryRecordId": "<record-id>", "namespaces": ["support/customer-456"], "content": {"text": "Customer prefers phone support for urgent billing issues. Account credit applied."}, "metadata": { "priority": {"stringValue": "critical"}, "agent_type": {"stringValue": "billing_agent"}, "channel": {"stringValue": "phone"} } }]'

ステップ 4: メタデータフィルターを使用してクエリを実行する

メタデータフィルターは、ベクトル類似度検索の実行 (事前フィルタリング) 前に適用されます。これにより、候補セットが最初に減少します。その結果、K 最近傍 (KNN) 検索は、より小さくより関連性の高いサブセットで動作します。

Filter 構造

すべてのフィルターは{ left, operator, right }式です。

{ "left": { "metadataKey": "priority" }, "operator": "EQUALS_TO", "right": { "metadataValue": { "stringValue": "high" } } }

クエリごとに最大 5 つのフィルターを組み合わせることができます。AND ロジックには複数のフィルターが適用されます。

サポートされている演算子

オペレーター 適切な値が必要です 動作可能 [Description] (説明)

EQUALS_TO

はい

STRING、NUMBER

完全一致。

CONTAINS

はい

文字列リスト

STRINGLIST 内の任意の要素に、指定された文字列が完全一致として含まれるレコードを返します。

EXISTS

いいえ

すべてのタイプ

キーがレコードに存在する

NOT_EXISTS

いいえ

すべてのタイプ

キーがレコードにありません

GREATER_THAN

はい (numberValue)

NUMBER

比較より大きい数値

GREATER_THAN_OR_EQUALS

はい (numberValue)

NUMBER

数値greater-than-or-equal比較

LESS_THAN

はい (numberValue)

NUMBER

比較より小さい数値

LESS_THAN_OR_EQUALS

はい (numberValue)

NUMBER

less-than-or-equal比較

BEFORE

はい (dateTimeValue)

dateTimeValue

タイムスタンプは指定された値より前です

AFTER

はい (dateTimeValue)

dateTimeValue

タイムスタンプが指定された値の後

注: のイベントメタデータフィルターは、EXISTSNOT_EXISTS、および のみをサポートしEQUALS_TO、 のみListEventsをサポートしますstringValue

メタデータフィルター (セマンティック検索 + 事前フィルター) を使用して を取得する

ではRetrieveMemoryRecordsmetadataFiltersは 内にネストされますsearchCriteria。次の例では、セマンティック検索が「請求問題」と照合される前の現在の年の優先度の高いレコードに結果をスコープします。

aws bedrock-agentcore retrieve-memory-records \ --memory-id "<memory-id>" \ --namespace "support/customer-123" \ --search-criteria '{ "searchQuery": "billing issues", "topK": 10, "metadataFilters": [ { "left": {"metadataKey": "priority"}, "operator": "EQUALS_TO", "right": {"metadataValue": {"stringValue": "high"}} }, { "left": {"metadataKey": "x-amz-agentcore-memory-createdAt"}, "operator": "AFTER", "right": {"metadataValue": {"dateTimeValue": "2026-01-01T00:00:00Z"}} } ] }'

カスタムメタデータフィルターをシステム生成のタイムスタンプと組み合わせると、類似度検索を実行する前に、ビジネスの優先度と最新性という 2 つのディメンションに沿って候補が圧縮されます。

メタデータフィルターを含むリスト (セマンティック検索なし)

ListMemoryRecords は、セマンティック検索なしでメタデータフィルタリングを提供します。これは、特定のメタデータ基準に一致するレコードを列挙する必要がある場合に便利です。たとえば、顧客のすべての優先度の高いレコードを一覧表示したり、特定の日付以降に作成されたすべてのレコードをプルしたりできます。

ではListMemoryRecordsmetadataFiltersは最上位のパラメータです。

aws bedrock-agentcore list-memory-records \ --memory-id "<memory-id>" \ --namespace "support/customer-123" \ --metadata-filters '[ { "left": {"metadataKey": "priority"}, "operator": "EQUALS_TO", "right": {"metadataValue": {"stringValue": "high"}} }, { "left": {"metadataKey": "x-amz-agentcore-memory-createdAt"}, "operator": "AFTER", "right": {"metadataValue": {"dateTimeValue": "2026-01-20T00:00:00Z"}} } ]'

複数のフィルターを組み合わせる

このクエリは、特定のクライアント名前空間内の 2026 年Q3 四半期の株式ディスカッションの取得の範囲を絞り込みます。

{ "searchQuery": "portfolio rebalancing strategy", "topK": 10, "metadataFilters": [ { "left": {"metadataKey": "asset_class"}, "operator": "EQUALS_TO", "right": {"metadataValue": {"stringValue": "equities"}} }, { "left": {"metadataKey": "x-amz-agentcore-memory-createdAt"}, "operator": "AFTER", "right": {"metadataValue": {"dateTimeValue": "2026-07-01T00:00:00Z"}} }, { "left": {"metadataKey": "x-amz-agentcore-memory-createdAt"}, "operator": "BEFORE", "right": {"metadataValue": {"dateTimeValue": "2026-09-30T23:59:59Z"}} } ] }

タイムスタンプのフィルタ値は UTC (ISO 8601 形式) である必要があります。このサービスは、すべての保存されたタイムスタンプを比較前に UTC に正規化するため、常にフィルター値を UTC で表現します。

ステップ 5: メタデータスキーマを進化させる

AgentCore Memory はスキーマの進化をサポートしているため、ニーズの変化に応じてメタデータ設定を調整できます。

インデックス付きキーを追加する

新しいインデックス付きキーは、いつでもメモリに追加できます。

aws bedrock-agentcore-control update-memory \ --memory-id "<memory-id>" \ --add-indexed-keys '[ {"key": "customer_segment", "type": "STRING"} ]'

新しいキーは、受信イベントとメモリレコードですぐに使用可能になります。既存のレコードはバックフィルされません。新規または更新されたレコードのみが新しいキーを保持します。以前にインデックスが作成されたキーを削除することはできません。これにより、既存のデータのフィルタリング機能が誤って失われるのを防ぐことができます。

戦略のメタデータスキーマを変更する

戦略のメタデータスキーマのエントリは、自由に追加、削除、更新できます。これにより、LLM が今後の会話から抽出するメタデータが制御されます。

たとえば、既存の戦略に新しいresolution_typeフィールドを追加するには:

aws bedrock-agentcore-control update-memory \ --memory-id "<memory-id>" \ --memory-strategies '{ "modifyMemoryStrategies": [ { "memoryStrategyId": "<strategy-id>", "memoryRecordSchema": { "metadataSchema": [ { "key": "resolution_type", "type": "STRING", "extractionConfig": { "llmExtractionConfig": { "definition": "How the customer support issue was resolved", "validation": { "stringValidation": { "allowedValues": ["refund", "replacement", "escalation", "self-resolved"] } } } } } ] } } ] }'

LLM でそのフィールドを抽出する必要がなくなった場合は、戦略のメタデータスキーマからキーを削除することもできます。スキーマエントリを削除しても、新しいレコードの抽出は停止しますが、既存のレコードに既に存在するメタデータには影響しません。

既存のメモリレコードは、新しい LLM 抽出フィールドを遡及的に受信しません。ただし、通常のメモリライフサイクル中に古いメモリが新しいメモリと統合されると、統合レコードは現在のスキーマを使用して再抽出され、新しいメタデータフィールドが含まれます。

クォータ

[リソース] 制限

メモリあたりのインデックス付きキー

10

戦略あたりの STRICTLY_CONSISTENT キー

3

戦略あたりのメタデータスキーマエントリ

20

メモリレコードメタデータエントリ (ユーザー提供)

20

クエリあたりのフィルター

5

allowedValues 検証ルールごと

10

maxItems STRINGLIST検証用

5

definition / llmExtractionInstruction長さ

各 1000 文字

メタデータキーの長さ

128 文字

stringValue 長さ

256 文字

STRINGLIST メンバーの長さ

64 文字

ベストプラクティス

  • 取り出し品質に直接影響する 3~5 個のフィルターディメンションから始めます。各インデックス付きフィールドはストレージインフラストラクチャ容量を消費し、10 キーの制限はこれを反映します。取り出し品質に直接影響する 3~5 つのキーから開始し、具体的なニーズが発生したらさらに追加します。

  • 明確で具体的なdefinition文字列を記述します。は、 フィールドが表すものをdefinition記述します。「チケットの優先度」の代わりに、顧客への影響に基づいて「発行優先度レベル」を記述します。値の範囲は、重大 (最も重大) から低 (最も重大) です。」 詳細な抽出ロジックllmExtractionInstructionに を使用します。

  • で LLM 出力を制限しますvalidation.allowedValues検証を行わないと、LLM は同じ概念"HIGH""High""high"、または を生成し、フィルターマッチングを中断する可能性があります。

  • ドメインセマンティクスに一致する競合解決ルールを選択します。 LATEST_VALUEは安全なデフォルトですが、エスカレーションワークフローagent_typeの のようなフィールドでは、最も上位の値を保持するカスタム命令の方が正確です。

  • 会話コンテンツにはイベント駆動型パスを優先します。LLM で抽出と競合の解決を処理します。バッチ APIs は、正しいメタデータ値がわかっている一括インポート用に予約します。

  • 戦略レベルでスキーマを計画します。各戦略は独自の を持つことができmetadataSchema、異なる戦略が同じキーを異なる方法で抽出および処理できます。セマンティック戦略では、カスタム抽出手順を使用して会話コンテキストから優先度を分類できますが、概要戦略では、要約固有のメタデータに合わせて調整された別の定義を使用する場合があります。

  • バッチで作成されたレコードmemoryStrategyIdでは、意図的に を使用します。を含めるとmemoryStrategyId、サービスは入力メタデータをその戦略のスキーマ内のキーのみにフィルタリングします。他のすべてのキーはサイレントに削除されます。これを省略すると、ペイロード内のすべてのメタデータがそのまま保存されます。ユースケースに基づいて選択します。抽出によって生成されたレコードと一致するレコードのスキーマ強制整合性、または外部でメタデータを管理する一括インポートの完全制御。

  • コンテキストエンリッチメントには、インデックス化されていないスキーマキーを使用します。すべてのメタデータキーをフィルタリングできる必要はありません。インデックス付きキーとして宣言されていないスキーマキーは、抽出されたレコードに入力され、get/list レスポンスに表示されます。フィルター式では使用できません。これは、インデックス付きキー予算を消費せずにダウンストリーム消費のためにレコードsummary_notesを強化する sentimentや などのメタデータに役立ちます。

  • すでにわかっている値には決定的抽出を使用します。一部のキーは、department、、 tenant_tierなどの固定組織属性を表しますcompliance_scope。アプリケーションがイベント作成時にこれらの値を持っている場合は、 として設定しますSTRICTLY_CONSISTENT。すべてのイベントに 値を指定します。これにより、レコードの正確な値が保証され、LLM 抽出によって導入される可能性のある一貫性のない表現 ( "eng"と など"Engineering") が削除されます。感情やトピックなど、会話コンテンツから推測する必要があるディメンションLLM_INFERREDを予約します。

  • 決定論的なキースロットを早期に計画します。STRICTLY_CONSISTENTキーは 10 個のインデックス付きキースロットのいずれかを使用します。追加したインデックス付きキーは削除できません。決定論的メタデータを使用する場合は、スロットを予約します。

回避するアンチパターン

  • 説明やフルネームなどの高カーディナリティのフリーテキストフィールドをインデックス化しないでください。有用なフィルター境界を指定せずにインデックスを肥大化させます。

  • すべてのインタラクションで変化する値にメタデータを使用しないでください。メタデータは、安定した属性や徐々に変化する属性に最も効果的です。

  • テナント分離のためにメタデータだけに依存しないでください。名前空間を分離しないtenant_idメタデータフィールドは、見逃したフィルターを破壊するsecurity-through-conventionモデルです。には名前空間を使用しwho、、、 にはメタデータwhatwhenを使用しますhow urgent

  • 正確な値には LLM 抽出を使用しないでください。キーに特定の既知の値 ( departmentや などticket_id) を指定する必要がある場合は、STRICTLY_CONSISTENT抽出を使用するか、バッチ APIs。LLM 抽出は、同じ概念のバリエーションを生成する可能性があります。