長期記憶體的結構化中繼資料

Amazon Bedrock AgentCore 記憶體中的中繼資料篩選可讓您將結構化屬性新增至長期記憶體記錄。您可以使用這些屬性來縮小擷取期間傳回的記錄範圍。命名空間已依主要實體 （使用者、租戶、病患、用戶端） 隔離記憶體。不過，在單一命名空間中，廣泛的語意搜尋會傳回所有接近意義的內容。使用中繼資料篩選，您只能擷取符合特定屬性值的結果。例如，您只能擷取高優先順序的記錄、只擷取特定部門的記錄，或只擷取指定時間範圍內建立的記錄。

透過中繼資料篩選，您可以：

開始使用

設定中繼資料篩選包含五個步驟：

後續各節會詳細說明每個步驟。

重要概念

索引中繼資料金鑰

索引鍵會在 中的記憶體資源層級宣告 CreateMemory（或稍後透過 新增UpdateMemory)。索引鍵會以針對快速查詢篩選最佳化的格式儲存。只有索引鍵可在 ListMemoryRecords和 metadataFilters的 中查詢RetrieveMemoryRecords。

下列範例宣告兩個索引鍵：

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

支援type的值：STRING、STRINGLIST、NUMBER。

金鑰必須相符 ^[a-zA-Z0-9\s._:/=+@-]*$（最多 128 個字元）。

新增索引鍵不會回填現有的記錄。只有宣告金鑰之後建立或更新的記錄，才會針對該金鑰編製索引。如需隨時間發展結構描述的詳細資訊，請參閱 步驟 5：發展中繼資料結構描述。

中繼資料結構描述 （每個策略）

記憶體策略可以選擇性地在 中宣告中繼資料結構描述memoryRecordSchema.metadataSchema。中繼資料結構描述會告知 LLM 在產生記憶體記錄時要從對話內容擷取哪些中繼資料。在事件驅動擷取期間，只會在產生的記憶體記錄上填入策略中繼資料結構描述中定義的索引鍵。

結構描述中的每個項目定義：

下列範例顯示具有驗證的中繼資料結構描述項目：

{
  "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"]
            }
          }
        }
      }
    }
  ]
}

依類型區分的驗證選項：

確定性中繼資料 (STRICTLY_CONSISTENT 擷取類型）

確定性中繼資料索引鍵包含應用程式在建立事件時已知的值。這些值會完全複製到產生的記憶體記錄，無需修改。LLM agent_id不應推斷 department、 compliance_level或 等組織分類器。LLM 推論引入可變性。例如，相同的對話可以在"eng"一個記錄和另一個記錄"Engineering"上產生。

對於這些金鑰，請在中繼資料結構描述項目STRICTLY_CONSISTENT中將 extractionType設定為 。事件上提供的值會透過擷取和合併傳播不變。該金鑰不會參考 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 範例顯示具有兩個決定性金鑰 (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"}
    }
)

系統會依所有決定性索引鍵值的確切組合來分組事件：

所有決定性索引鍵值必須符合才能分組的事件。具有 department=billing AND 的查詢只會priority=high傳回緊急重複收費事實。其他事件位於不同的分割區中。來自不同值組合的記錄絕不會在合併期間合併。

Constraints

索引鍵和結構描述金鑰如何互動

索引索引鍵與結構描述索引鍵之間的關係會決定中繼資料的行為：

中繼資料如何從事件流向記憶體記錄

事件中繼資料僅接受stringValue項目。記憶體記錄支援 stringValue、 stringListValue和 numberValue類型 — 在擷取期間由 LLM 填入，或透過批次 APIs直接提供。dateTimeValue 類型會保留給系統產生的欄位 (x-amz-agentcore-memory-createdAt 和 x-amz-agentcore-memory-updatedAt)。只有策略 中定義的索引鍵metadataSchema會填入擷取的記錄 - 不會忽略不在結構描述中的事件中繼資料索引鍵。如需項目限制，請參閱 配額。

系統產生的中繼資料

每個記憶體記錄都有這些系統欄位，可使用相同的篩選條件運算子進行查詢：

您不需要將這些宣告為索引鍵，它們一律可供篩選。這些系統產生的dateTimeValue欄位支援 BEFORE和 AFTER運算子，啟用時間範圍查詢，而不需要您宣告日期時間索引鍵。

先決條件

設定中繼資料篩選之前，請確認您已：

步驟 1：使用索引鍵和中繼資料結構描述建立記憶體

以下內容使用五個索引鍵和中繼資料結構描述來建立客戶支援記憶體。priority、 agent_type和 sentiment 是在策略的中繼資料結構描述中定義 — LLM 會從對話內容中擷取其值。請注意，sentiment在結構描述中，但未宣告為索引鍵：LLM 從對話中衍生其值，並將其填入記錄，但無法在篩選條件表達式中使用。 tags(STRINGLIST)、 channel (STRING) 和 ticket_id(STRING) 會宣告為索引鍵，但不在結構描述中 — 它們不會在事件驅動擷取期間填入，但可以透過批次 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：使用中繼資料擷取資料

有兩種途徑可將中繼資料取得至記憶體記錄。

事件驅動的擷取

在建立時將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，因此其值會傳播至記憶體記錄。 channel和 ticket_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、 和 上填入所有三個結構描述索引鍵agent_type，sentiment即使沒有提供做為事件中繼資料：

{
  "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 會根據指示解決此問題：

另一個範例：agent_type使用「偏好最專業化的代理程式類型」指令的 。階層：專家 > 第 3 層 > 第 2 層 > 第 1 層 > 機器人"，如果工作階段從機器人開始並升級到第 2 層代理程式，則記憶體記錄會取得 agent_type: "tier2"。

確定性中繼資料擷取

設定為 的金鑰STRICTLY_CONSISTENT遵循不同的擷取路徑。您在事件上提供的值是落在產生的記錄上的值。沒有 LLM 推論，也沒有衝突解決方法。

AgentCore 記憶體會依事件的決定性索引鍵值來分組事件。例如，標記的事件department: "engineering"會與標記 的事件分開處理department: "finance"。

合併在這些群組中運作。具有 的記錄compliance_level: "hipaa"絕不會與標記為 的記錄合併compliance_level: "standard"。這使得確定性金鑰非常適合：

如果事件沒有決定性索引鍵的值，則產生的記錄上沒有索引鍵。

直接寫入路徑 (BatchCreateMemoryRecords 和 BatchUpdateMemoryRecords) 繞過擷取。STRICTLY_CONSISTENT 擷取類型對它們沒有影響。如同您為這些 APIs所做的，直接提供中繼資料。

使用批次 APIs建立直接記錄

對於知識庫匯入、自我管理策略或預先處理的內容，請使用 BatchCreateMemoryRecords（或 BatchUpdateMemoryRecords) 明確提供中繼資料。這完全略過 LLM 擷取 — 發起人控制中繼資料值。

在批次建立的記錄上處理中繼資料的方式，取決於您是否提供 memoryStrategyId：

下列範例會建立不含 的記錄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"}
    }
  }]'

在第二個範例中，如果策略的結構描述只定義 priority、 agent_type和 sentiment，channel則會從儲存的記錄無提示地捨棄 。

使用 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邏輯套用多個篩選條件。

支援的運算子

注意： 上的事件中繼資料篩選條件僅ListEvents支援 EXISTS、 NOT_EXISTS和 EQUALS_TO，僅支援 stringValue。

使用中繼資料篩選條件擷取 （語意搜尋 + 預先篩選）

在 上RetrieveMemoryRecords， metadataFilters 巢狀於 內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"}}
      }
    ]
  }'

在相似性搜尋執行之前，結合自訂中繼資料篩選條件與系統產生的時間戳記，會沿著兩個維度精簡候選集：業務優先順序和延遲。

具有中繼資料篩選條件的清單 （無語意搜尋）

ListMemoryRecords 提供中繼資料篩選，無需語意搜尋。當您需要列舉符合特定中繼資料條件的記錄時，這會很有用，例如列出客戶的所有高優先順序記錄，或提取特定日期之後建立的所有記錄。

在 上ListMemoryRecords， metadataFilters 是頂層參數：

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 記憶體支援結構描述演變，因此您可以在需求變更時調整中繼資料組態。

新增索引鍵

您可以隨時將新的索引鍵新增至記憶體：

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 擷取欄位。不過，在正常記憶體生命週期內，當較舊的記憶體與較新的記憶體合併時，會使用目前的結構描述重新擷取合併的記錄，並將包含新的中繼資料欄位。

配額

最佳實務

要避免的反模式