Structured memory filtering with metadata in AgentCore Memory

# 示例代码保持原样不翻译

response = agentcore_client.create_memory(
    name="CustomerSupportMemory",
    eventExpiryDuration=30,
    indexedKeys=[
        {"key": "priority", "type": "STRING"},
        {"key": "agent_type", "type": "STRING"},
        {"key": "channel", "type": "STRING"},
        {"key": "ticket_id", "type": "STRING"}
    ],
    memoryStrategies=[{
            "semanticMemoryStrategy": {
                "name": "SupportSemanticStrategy",
                "description": "Captures support interaction details",
                "namespaces": ["support/{actorId}"],
                "memoryRecordSchema": {
                    "metadataSchema": [
                        {
                            "key": "priority",
                            "type": "STRING",
							"extractionType": "STRICTLY_CONSISTENT",
                            "extractionConfig": {
                                "llmExtractionConfig": {
                                    "definition": "Issue priority level based on customer impact.",
                                    "llmExtractionInstruction": "LATEST_VALUE",
                                    "validation": {
                                        "stringValidation": {
                                            "allowedValues": ["critical", "high", "medium", "low"]
                                        }
                                    }
                                }
                            }
                        },
                        {
                            "key": "agent_type",
                            "type": "STRING",
							"extractionType": "STRICTLY_CONSISTENT",
                            "extractionConfig": {
                                "llmExtractionConfig": {
                                    "definition": "Support agent classification.",
                                    "llmExtractionInstruction": "Prefer the most specialized agent type. Hierarchy: specialist > tier3 > tier2 > tier1 > bot."
                                }
                            }
                        },
                        {
                            "key": "sentiment",
                            "type": "STRING",
							"extractionType": "STRICTLY_CONSISTENT",
                            "extractionConfig": {
                                "llmExtractionConfig": {
                                    "definition": " Customer sentiment during the interaction. ",
                                    "llmExtractionInstruction": "Classify the overall customer sentiment based on tone and language used.",
                                    "validation": {
                                        "stringValidation": {
                                            "allowedValues": ["positive", "neutral", "negative", "frustrated"]
                                        }
                                    }
                                }
                            }
                        }
                    ]
                }
            }
    }]
)

"metadataSchema": [
    {
        "key": "department",
        "type": "STRING",
        "extractionType": "STRICTLY_CONSISTENT"
    },
    {
        "key": "priority",
        "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"
            }
        }
    }
]

# 事件 1：初始账单咨询
agentcore_client.create_event(
    memoryId="mem-support-abc123",
    actorId="customer-123",
    sessionId="session-escalation-001",
    payload=[{"conversational": {"role": "USER",
                "content": {"text": "我在企业计划的上个月发票中看到了重复收费。"}}}],
    metadata={"department": {"stringValue": "billing"}, "priority": {"stringValue": "high"}}
)

# 事件 2：仍处于账单上下文
agentcore_client.create_event(
    memoryId="mem-support-abc123",
    actorId="customer-123",
    sessionId="session-escalation-001",
    payload=[{"conversational": {"role": "USER",
                "content": {"text": "这些费用是在我们上周从标准版升级到企业版后出现的。"}}}],
    metadata={"department": {"stringValue": "billing"}, "priority": {"stringValue": "high"}}
)

# 事件 3：升级至工程部门（技术根本原因）
agentcore_client.create_event(
    memoryId="mem-support-abc123",
    actorId="customer-123",
    sessionId="session-escalation-001",
    payload=[{"conversational": {"role": "USER",
                "content": {"text": "你们团队发现了一个配置错误，在层级迁移期间触发了重复收费。"}}}],
    metadata={"department": {"stringValue": "engineering"}, "priority": {"stringValue": "high"}}
)

# 初始接触事件
agentcore_client.create_event(
    memoryId="mem-support-abc123",
    actorId="customer-123",
    sessionId="session-001",
    eventTimestamp="2024-01-23T10:00:00Z",
    payload=[{
            "conversational": {
                "role": "USER",
                "content": {"text": "I have a question about my bill"}
            }
    }],
    metadata={
        "priority": {"stringValue": "medium"},
        "channel": {"stringValue": "email"},
        "ticket_id": {"stringValue": "TKT-5001"}
    }
)

# 在策略上定义的模式键
"metadataSchema": [
    {"key": "domain", "type": "STRING", "definition": "讨论的主要技术领域。。"},
    {"key": "tags", "type": "STRINGLIST", "definition": "引用的AWS服务。。"},
    {"key": "priority", "type": "NUMBER", "definition": "重要性等级1到10。。"}
]

# 创建无元数据的事件
agentcore_client.create_event(
    memoryId="mem-abc123",
    actorId="user-1",
    sessionId="session-001",
    payload=[{"conversational": {"role": "USER",
                "content": {"text": "如何在两个账户之间设置VPC对等连接？"}}}]

    # 无元数据参数
)

{
    "content": {"text": "用户询问如何在两个AWS账户之间设置VPC对等连接。"},
    "metadata": {
        "domain": {"stringValue": "Networking"},
        "tags": {"stringListValue": ["VPC"]},
        "priority": {"numberValue": 7.0}
    }
}

agentcore_client.batch_create_memory_records(
    memoryId="mem-support-abc123",
    records=[{
            "requestIdentifier": "import-001",
            "namespaces": ["support/customer-456"],
            "content": {"text": "客户倾向于通过电话解决紧急账单问题"},
            "timestamp": "2024-01-15T10:00:00Z",
            "metadata": {
                "priority": {"stringValue": "high"},
                "agent_type": {"stringValue": "billing_agent"},
                "channel": {"stringValue": "phone"},
                "ticket_id": {"stringValue": "TKT-7890"}
            }
    }]
)

在您的记忆记录中元数据已建立索引并填充后，现在可以结合语义搜索与元数据过滤器来限定搜索结果范围。AgentCore Memory采用预过滤架构：元数据过滤器会在向量相似性搜索执行前应用。这首先缩小候选集范围，使K近邻（KNN）搜索能在更小且更相关的子集上运行。请注意下方示例中，结果先限定为仅包含今年的高优先级记录，再与"billing issues"进行语义匹配。

请注意如何通过自定义元数据过滤器与系统生成的时间戳结合，在相似性搜索执行前沿两个维度（业务优先级和时间新鲜度）压缩候选集。AgentCore Memory提供多种操作符以覆盖常见查询模式。

AgentCore Memory还会使用x-amz-agentcore-memory-*前缀添加服务生成的元数据字段，您可以通过相同过滤操作符查询这些字段，从而支持无需自定义时间戳键的时域查询。

#### 为什么时间过滤能带来最大的准确率提升

在我们的实验中，带有时间约束的查询在使用元数据过滤后显示出最大的准确率提升。使用BEFORE和AFTER操作符的结构化DATETIME过滤可将其转换为确定性索引查找，避免歧义。

对于非搜索类检索，ListMemoryRecords提供不带语义搜索的元数据过滤功能。这在需要枚举符合特定元数据条件的记录而非查找语义相似内容时非常有用。例如，您可以列出某个客户的高优先级记录，或提取标记为特定部门的记录。

以下示例列出特定日期后创建的高优先级记录：

## 企业应用场景

以下示例展示元数据过滤如何解决跨行业常见的企业检索挑战。

### 多租户SaaS应用

### 医疗健康与合规敏感领域

如果您的医疗AI代理需要跨多个部门管理患者互动，类似 patients/patient-123 的命名空间已为每位患者的记忆提供隔离。但在单个患者命名空间内，对“用药史”的广泛搜索会返回所有部门的结果：心脏病学、内分泌学和初级护理。通过索引 department、record_type、severity 和 symptoms 等元数据键，您的代理可以在患者命名空间内沿多个临床维度缩小检索范围。

症状 STRINGLIST 上的 CONTAINS 操作符会检查列表是否包含指定值，从而将检索范围限定到特定临床指标。

在合规性方面，元数据过滤有助于满足监管要求：

- **HIPAA**：部门级过滤确保心内科医生的查询仅检索心内科相关记录，降低出现无关临床数据的风险。
- **GDPR**：对 x-amz-agentcore-memory-createdAt 的元数据过滤可识别超出保留期限的记录。您可通过 DeleteMemoryRecord 或命名空间级删除处理数据删除。
- **SOC 2**：系统生成的时间戳提供可验证的追溯记录，证明检索范围正确。您还可以对 data_classification 键（值如 PII、confidential 或 general）进行索引，实现敏感性感知检索。

### 基于优先级的客户支持路由

如果您的支持组织需要处理成千上万的工单，就需要能够根据紧急程度和升级状态对上下文进行优先级排序的代理。元数据通过结合自定义元数据过滤器与系统时间戳过滤器，支持“查找过去30天内的高优先级账单记录”等检索模式。在实时会话中，代理可以快速提取最相关的高优先级上下文，而无需浏览已解决的低优先级问题。当工单从低级升级为关键问题时，合并规则会将元数据与最新升级状态保持一致，而非初始分类。

### 金融服务与时间精度

金融数据本质上具有时间敏感性。“Q3投资组合讨论”的查询必须返回特定于Q3的记录，而非其他季度的记录。财富管理代理可以通过DATETIME过滤与自定义元数据结合，实现精确检索范围，帮助您避免其他资产类别和时间段的干扰：

### 多代理系统与内存协调

随着代理系统逐渐成熟并变得更为普及，元数据在多个代理如何通过共享内存层进行协作和协调方面变得至关重要。

- **代理来源追踪**：在多代理工作流中，了解哪个代理创建了某条记忆对于建立信任、调试和路由至关重要。通过索引source_agent、agent_role和workflow_step等关键字段，监督代理可以筛选出特定代理存储的记忆。例如，您可以在客户命名空间内通过source_agent:"billing_agent"过滤，回答“上一次会话中账单代理得出了什么结论？”

- **代理限定的内存可见性**：在多代理流水线（分诊机器人→一级代理→专家代理）中，可通过元数据控制每个代理可检索的记忆范围。分诊机器人写入的记忆会标记workflow_step:"triage"。处理升级请求的专家代理可通过workflow_step:"triage"筛选来了解初始分类，或通过agent_role:"tier1"筛选来查看已尝试的解决方案，避免重复工作。agent_role的自定义llmExtractionInstruction会将记忆整合为体现最高专业水平处理的结果，而非仅显示最近一次操作。

- 在检索增强生成（RAG）管道中实现元数据门控检索：检索代理通过 source_type: "knowledge_base" 过滤以实现事实依据，个性化代理通过 interaction_type: "preference" 过滤以获取用户特定上下文，安全代理通过 content_flag: "reviewed" 过滤以获取经过审核的内容。三个代理查询相同命名空间但获得完全不同的结果集，而无需管理多个内存存储。

## 元数据模式演进

生产环境中的内存系统并非静态，元数据模式需要随着所服务的应用程序同步演进。AgentCore Memory 通过仅添加的更新模型支持模式演进。您可以根据需要向现有内存资源添加新的索引元数据键：

新键立即可用于新事件和内存记录。现有记录不会自动获得新字段，但随着旧记忆与新记忆合并时，它们会自然获取新元数据。您无法删除已索引的键，这有助于防止现有数据的过滤能力意外丢失。您可以自由添加、删除或修改策略级元数据模式中非索引键，以适应不断变化的提取需求。

## 最佳实践

从代理所需的过滤维度入手。避免一开始就索引所有可能的元数据字段。每个索引字段都会占用一个索引键配额，并在写入和读取路径上增加成本：写入时需要更多处理工作，读取时需要进行查询压缩。建议从3到5个直接影响检索质量的键开始，随着具体需求出现再逐步添加。

编写清晰具体的定义。定义字段和 llmExtractionInstruction 共同构成LLM接收的元数据提取主要指令。不要写成“工单的优先级”，而应写成“基于客户影响的优先级级别。服务中断影响生产环境时使用'critical'，性能下降时使用'high'，功能请求使用'medium'，文档或界面问题使用'low'”。

选择与领域语义匹配的合并规则。LATEST_VALUE 是大多数字段的安全默认值，但并非总是正确。在支持升级流程的 agent_type 中，应保留最资深的代理类型而非最新类型。自定义合并指令可以表达这种领域逻辑。

通过验证规则约束LLM输出。在验证字段中定义 allowedValues 以强制使用受控词汇表。如果没有验证，LLM可能会为相同概念生成“High”、“high”、“HIGH”或“critical”等不一致值，导致下游过滤匹配失败。

为事件驱动路径设计元数据。对于在事件发生时已知且在会话内保持不变的键（如部门或租户等级），将元数据附加到事件，让 AgentCore Memory 通过提取自动处理冲突解决和合并。将直接批量API路径保留给需要批量导入和预处理内容的场景，此时您已经知道正确的元数据值。

在策略层面规划元数据模式。每个记忆策略可以拥有独立的元数据模式，使不同策略能够以不同方式提取和处理相同键。语义策略可能使用自定义提取指令从对话上下文中分类优先级，而摘要策略可能使用针对摘要特定元数据优化的定义。这种灵活性支持按策略优化元数据处理，同时不损害共享的索引键基础设施。

在批量创建记录时要谨慎使用memoryStrategyId。当在批量创建请求中包含memoryStrategyId时，服务会将输入元数据过滤为该策略模式中的键，其他键会被静默丢弃。这有助于强制保持与提取生成记录的一致性。如果省略该参数，负载中的元数据将原样存储。根据使用场景选择：对于应与提取记录保持一致的记录使用模式强制一致性，或对于需要外部管理元数据的批量导入使用完全控制。

使用非索引模式键进行上下文丰富。并非每个元数据键都需要可过滤。未声明为索引键的模式键仍会填充到提取记录中，并在get和list响应中可见，但无法用于过滤表达式。这对于需要丰富记录以供下游使用（如情感、摘要备注或来源URL）的元数据非常有用，同时不会消耗索引键配额。将索引键保留给需要主动过滤的维度。

对已知值使用确定性提取。如果某个键代表在事件创建时代理已知的固定组织属性（如部门、租户层级或合规范围），请将其配置为STRICTLY_CONSISTENT并在每个事件中提供。这可确保结果记录中的精确值，并消除LLM提取可能引入的归一化偏差（如“eng”与“Engineering”的差异）。将llmExtractionConfig保留给必须从对话内容中推断的维度（如情感或主题）。

避免以下反模式：

- 不要对描述或全名等高基数自由文本字段进行索引，这些字段会膨胀索引但不提供有用的过滤边界。

- 不要使用元数据存储每次交互都会变化的值；元数据最适合用于稳定或缓慢变化的属性。

- 不要仅通过元数据实现命名空间隔离。没有命名空间隔离的tenant_id元数据字段是一种依赖惯例的安全模型，任何遗漏的过滤都会导致该模型失效。

## 结论

AgentCore Memory中的元数据过滤解决了根本的检索挑战。命名空间已通过用户、租户或项目等主要实体隔离记忆。在命名空间作用域之上叠加结构化元数据过滤，可以在相似性匹配运行前将代理的检索范围缩小到精确的上下文边界，从而显著提高准确性，并为合规性、基于优先级的上下文管理和细粒度组织过滤提供实用基础。基于LLM的提取避免了手动标记的负担，而可配置的提取指令则能在大规模场景中处理元数据传播和冲突解决。

要开始使用，请确定三到五个对您的使用案例的检索质量影响最直接的过滤维度。首先使用虚拟内存资源进行概念验证（PoC），以测试相关策略，然后根据具体需求扩展模式。以下资源提供实际操作指南：

- Amazon Bedrock AgentCore 文档：  
- AgentCore Memory 代码示例：  
- 关于 Amazon Bedrock AgentCore Memory 的博客：构建上下文感知代理  

## 关于作者  
'"`