If you’ve ever used ChatGPT or a similar AI chatbot, you know it types an answer back to you. That’s pretty amazing on its own. But what if an AI could do things, not just talk? What if it could manage complex tasks, remember crucial details across weeks of interactions, and always pull up the exact piece of information you need?
That’s where things get really interesting for businesses.
Imagine a customer support AI. A customer calls about a “billing issue.” Without good memory management, the AI might pull up technical support tickets, sales conversations about past receipts, or even unrelated billing disputes. All of these might sound similar to “billing issue,” but they’re not what the customer actually needs right now. This is the wall many AI teams hit as their agents accumulate more and more interaction history. Simple “similarity search” finds things that are semantically close, but it doesn’t scope the results to the exact dimensions you need – like issue type, status, or a specific time frame.
This is a problem of retrieval precision. The AI is trying its best, but it’s drowning in data.
Amazon Bedrock AgentCore Memory offers a solution. It’s a service that gives AI assistants a real ability to remember and recall information across conversations. Think of it like a highly organized filing cabinet for your AI.
Initially, AgentCore organizes memories into something called namespaces. Namespaces are like isolated folders. So, if you have data for client A and client B, you can put them in separate namespaces, say clients/client-123 and clients/client-456. This ensures your AI doesn’t accidentally pull up Client A’s sensitive information when talking to Client B. This is the foundational layer of separation, ensuring basic data privacy and organization.
But even within a client’s namespace, memories can grow vast. A financial advisor’s AI, for example, might have six months of interaction history for a single client. If the relationship manager asks the AI to recall “portfolio rebalancing discussions,” the namespace will correctly limit the search to that client. However, the results might still include conversations about different investment strategies, various time periods, and varying levels of urgency. The AI can’t easily distinguish a critical rebalancing conversation from last week from a routine check-in from three months ago. The information is semantically similar, but the context is entirely different.
This is where metadata filtering comes in. It’s a way to layer more specific filters on top of the basic namespace organization.
Think of it like this: a library has sections (namespaces). But within the “Business” section, you might want to find books published after 2020 that are specifically about marketing strategy and are marked as highly recommended. Metadata filtering allows your AI to do just that. It lets you scope retrieval not just by who the data is for (namespace), but by specific business dimensions like priority, department, or a precise date range, before the AI even starts its similarity search.
This makes a huge difference. In evaluations across a 151-question test set, using metadata filtering showed significant improvement. The overall question-answering accuracy rose from 40% to 64%. That’s a 24% jump.
The real magic happens with questions that depend on these specific contextual boundaries. For those, accuracy jumped dramatically, from a mere 16% to a much more useful 69%. That’s the difference between an AI that’s mostly guessing and one that’s reliably delivering accurate, context-aware answers.
This post will walk you through how metadata filtering works, explore some enterprise use cases, and share best practices for implementation.
Structuring Memories: Namespaces and Metadata
AgentCore Memory uses namespaces to organize and isolate memories. These are the primary entity boundaries. You can scope retrieval to a specific namespace, like clients/client-123/sessionABC or patients/patient-456. This prevents your agent from accidentally retrieving another client’s or patient’s data. Namespaces provide the foundational layer of separation.
When deployments scale, semantic search within a namespace hits limits. Consider that financial services agent again. When a relationship manager asks for “portfolio rebalancing discussions,” the namespace correctly scopes the search. But the results might span different investment strategies, time periods, and priority levels. The agent can’t distinguish a high-priority rebalancing conversation from last week from a routine inquiry three months ago. The information is semantically similar, but the context is entirely different.
Multi-tenant environments, where many customers share the same system, illustrate this layering clearly. Namespaces already provide full data separation between tenants. But within each tenant’s namespace, your IT helpdesk agents still need to filter ticket types before searching for resolution patterns. Namespaces handle the separation based on who the data belongs to. Metadata filtering handles the sub-grouping within those boundaries: the category, resolution status, date, priority, and tags.
Metadata in AgentCore Memory operates across both short-term and long-term memory. It follows a three-phase lifecycle: configuration, ingestion, and retrieval.
Metadata in short-term memory
At the short-term memory layer, you attach string-based key-value pairs to events. These tags add contextual information that isn’t necessarily part of the conversation itself but is critical for later retrieval. Short-term memory metadata supports these string-based key-value pairs, which can then be used for filtering. These tags carry forward into long-term memory during extraction and consolidation, where they become filterable dimensions.
Metadata in long-term memory
Long-term memory is where metadata truly shines. The three phases give you precise control over how structured context is declared, propagated, and queried. In short, you declare which keys matter during configuration. You attach or let the AI infer their values during ingestion, and then you filter on them during retrieval. When several events in a session carry the same key, AgentCore Memory merges them into one value using a resolution behavior you define.
Phase 1: Configuration
When you create a memory resource, you declare which metadata keys you want to index for fast filtering and retrieval across memory records. You define a metadata schema for each memory strategy. This instructs AgentCore Memory on how to extract and resolve metadata values.
Indexed keys are stored in a format optimized for query filtering. Non-indexed keys are stored alongside memory records for informational purposes.
Here’s how you might create a customer support memory resource with metadata configuration:
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"]
}
}
}
}
}
]
}
}
}]
)Each schema entry’s extractionConfig guides the large language model (LLM) during metadata extraction. The definition field describes what the field represents, while llmExtractionInstruction provides additional guidance and conflict resolution. The LATEST_VALUE operation provides recency-based resolution, while custom natural language instructions can also be used.
Phase 2: Ingestion
During ingestion, metadata values are attached to memory records. This can happen in a few ways:
- Explicitly provided: You can directly supply metadata when adding a memory record.
- Inferred by LLM: You can configure the system to use an LLM to extract metadata from the conversation content itself. This is where the
llmExtractionInstructionreally comes into play, telling the LLM what to look for and how to decide on a value if there are multiple possibilities. - Default values: If no value is provided or inferred, a default can be used.
When multiple events in a session carry the same metadata key, AgentCore Memory merges them based on your defined resolution behavior. For example, if a conversation starts with a “medium” priority ticket and later gets escalated to “high,” your configuration could ensure the memory record reflects the “high” priority.
Phase 3: Retrieval
This is where the power of metadata filtering becomes apparent. When a query comes in, you can specify filters based on the metadata you’ve configured and ingested.
For instance, if your AI needs to find recent, high-priority support tickets for a specific client, you would apply filters like priority=high and channel=phone along with the client’s namespace. The system first applies these metadata filters to narrow down the potential memory records. Only then does it perform the semantic similarity search on the reduced set of data.
This layered approach is far more efficient and accurate than a simple broad search.
Enterprise Use Cases
The combination of namespaces and metadata filtering unlocks several powerful enterprise applications:
- Customer Support Bots: As illustrated, this is a prime use case. Imagine a bot that can instantly pull up a customer’s recent, critical support tickets, their sentiment during those interactions, and the type of agent who handled them. This allows for faster resolution and more personalized support.
- Multi-Agent Systems: In complex workflows where multiple AI agents collaborate, namespaces can isolate each agent’s “knowledge base,” while metadata filtering allows them to share specific, relevant information with each other. For example, a sales agent might need to access completed order details from a fulfillment agent, but only for a specific product category and within the last quarter.
- Multi-Tenant Architectures: For SaaS providers, keeping tenant data separate is paramount. Namespaces handle the primary tenant isolation. Within a tenant’s data, metadata filtering can further segment information by user, subscription tier, or feature usage, enabling more tailored experiences and analytics for each tenant.
- Compliance and Auditing: By tagging memories with relevant compliance codes, dates, or approval statuses, organizations can more easily retrieve and verify information for audits or regulatory checks.
Best Practices for Implementation
To get the most out of metadata filtering:
- Define your key dimensions early: Think critically about the most important attributes for filtering your data. What information do your AI agents really need to distinguish between? Common ones include priority, status, date/time ranges, category, user ID, and type of interaction.
- Choose appropriate data types: Use
STRINGfor categorical data (like priority or agent type),NUMBERfor numerical values, andDATETIMEfor time-based filtering. This ensures efficient querying. - Leverage LLM extraction strategically: For fields where values can be varied or inferred (like sentiment or detailed issue descriptions), configuring LLM extraction can automate the tagging process. Be clear in your
llmExtractionInstructionto guide the model effectively. - Index for performance: Index the metadata keys that you will most frequently use for filtering. This speeds up retrieval significantly. For less common attributes, consider storing them as non-indexed for informational purposes.
- Start simple and iterate: You don’t need to index every possible attribute from day one. Begin with the most critical filters and expand your schema as your needs evolve and you gain more insights into how your agents are used.
The Bottom Line
The ability for AI agents to remember accurately and retrieve precisely is no longer a luxury; it’s a necessity for delivering intelligent, efficient, and trustworthy experiences. By moving beyond simple semantic similarity and embracing structured memory with namespaces and metadata filtering, businesses can unlock new levels of performance and reliability from their AI assistants. This layered approach ensures that the right information is surfaced at the right time, making AI a more powerful tool for decision-making and customer engagement.
Sources: aws.amazon.com