When constructing AI brokers, builders wrestle with organizing reminiscence throughout periods, which results in irrelevant context retrieval and safety vulnerabilities. AI brokers that keep in mind context throughout periods want greater than solely storage. They want organized, retrievable, and safe reminiscence. In Amazon Bedrock AgentCore Reminiscence, namespaces decide how long-term reminiscence information are organized, retrieved, and who can entry them. Getting the namespace design proper is crucial to constructing an efficient reminiscence system.
On this publish, you’ll discover ways to design namespace hierarchies, select the best retrieval patterns, and implement AWS Identification and Entry Administration (IAM)-based entry management for AgentCore Reminiscence. In the event you’re new to AgentCore Reminiscence, we advocate studying our introductory weblog publish first: Amazon Bedrock AgentCore Reminiscence: Constructing context-aware brokers.
What are namespaces?
Namespaces are hierarchical paths that arrange long-term reminiscence information inside an AgentCore Reminiscence useful resource. Consider them like listing paths in a file system. They supply logical construction, allow scoped retrieval, and help entry management.
When AgentCore Reminiscence extracts long-term reminiscence information out of your conversations, every reminiscence report is saved below a namespace. For instance, a consumer’s preferences may reside below /actor/customer-123/preferences/, whereas their session summaries is likely to be saved at /actor/customer-123/session/session-789/abstract/. With this construction, you may retrieve reminiscence information at precisely the best degree of granularity.
In the event you’ve labored with partition keys in Amazon DynamoDB or folder buildings in Amazon Easy Storage Service (Amazon S3), the psychological mannequin transfers properly. Simply as you assume by way of entry patterns earlier than selecting a partition key or designing your S3 folder hierarchy, it’s best to assume by way of your retrieval patterns earlier than designing your namespace construction. Decide:
- Who must entry these recollections: A single consumer? All customers of an agent?
- Granularity of retrieval you want: Is it per-session summaries? Cross-session preferences?
- Isolation boundaries that matter: Ought to one consumer’s recollections ever be seen to a different? Agent-scoped recollections?
The principle distinction from a partition key’s that namespaces help hierarchical retrieval along with actual match. You may question at every degree of the hierarchy, not solely on the leaf degree. You should use a well-designed namespace to retrieve recollections scoped to a single session, a single consumer throughout periods, or a broader grouping, from the identical reminiscence useful resource. Namespaces are logical groupings inside the similar underlying storage. They supply organizational construction and entry management, however long-term reminiscence information throughout totally different namespaces co-exist inside the similar reminiscence useful resource. Your hierarchy is your main software for organizing information for efficient retrieval patterns.
Namespace templates and determination
When making a reminiscence useful resource, you outline namespace templates utilizing the namespaceTemplate subject inside every technique configuration. Templates help three pre-defined variables:
- {actorId} – resolves to the actor identifier from the occasions being processed
- {sessionId} – resolves to the session identifier from the occasions
- {memoryStrategyId} – resolves to the technique identifier
Right here’s an instance of making a reminiscence useful resource with namespace templates:
response = agentcore_client.create_memory(
identify=”CustomerSupportMemory”,
description=”Reminiscence for buyer help brokers”,
eventExpiryDuration=30,
memoryStrategies=[
{
“semanticMemoryStrategy”: {
“name”: “customer-facts”,
“namespaceTemplate”: “/actor/{actorId}/facts/”
}
},
{
“summaryMemoryStrategy”: {
“name”: “session-summaries”,
“namespaceTemplate”: “/actor/{actorId}/session/{sessionId}/summary/”
}
}
]
)
When occasions arrive for actorId=customer-456 in sessionId=session-789, the resolved namespaces turn into:
- /actor/customer-456/info/
- /actor/customer-456/session/session-789/abstract/
Namespace design per reminiscence technique
Every reminiscence technique has totally different scoping wants, and the namespace design ought to replicate how that information will likely be accessed. Beneath are some frequent namespace design patterns for various reminiscence methods.
1. Semantic and consumer preferences: Actor-scoped
Semantic reminiscence captures info and data from conversations (for instance, “The shopper’s firm has 500 staff”). Consumer Choice Reminiscence captures selections and kinds (for instance, “Consumer prefers Python for improvement work”). Each reminiscence sorts accumulate over time and are related throughout periods. A truth discovered in January ought to nonetheless be retrievable in March. For these methods, scope the namespace to the actor:
/actor/{actorId}/info/
/actor/{actorId}/preferences/
This implies the info and preferences for a given consumer are consolidated below a single namespace, no matter which session they have been extracted from. The consolidation engine merges associated recollections inside the similar namespace. Take a look at determine 1 for an instance of how scoping impacts the consolidation logic.
The next diagram illustrates how actor-scoped semantic and desire recollections are organized:
Reminiscence Useful resource: CustomerSupportMemory
│
├── /actor/customer-123/
│ ├── info/
│ │ ├── “Firm has 500 staff throughout Seattle, Austin, Boston”
│ │ ├── “At the moment migrating from on-premises to cloud”
│ │ └── “Major contact is the VP of Engineering”
│ └── preferences/
│ ├── “Prefers electronic mail communication over cellphone”
│ └── “Normally prefers detailed technical explanations”
│
├── /actor/customer-456/
│ ├── info/
│ │ ├── “Startup with 20 staff”
│ │ └── “Utilizing serverless structure”
│ └── preferences/
│ └── “Prefers concise, high-level summaries”
In some use circumstances, an admin may must retrieve data throughout actors whereas conserving recollections organized per actor. For instance, a buyer help agent may must search for recognized points reported by different prospects, or a gross sales agent may want to search out related buyer profiles throughout its consumer base. For such circumstances, construction the namespace with the actor identifier as a baby of the reminiscence kind reasonably than because the dad or mum:
/customer-issues/{actorId}/
/gross sales/{actorId}/
With this inverted construction, you should utilize namespacePath=”/customer-issues/” to retrieve frequent points raised throughout all prospects, whereas nonetheless sustaining a per-actor group. A question scoped to namespace=”/customer-issues/customer-123/” returns solely that actor’s reported points, preserving isolation when wanted.
2. Abstract: Session-scoped
Abstract reminiscence creates working narratives of conversations, capturing details and choices. As a substitute of feeding a complete dialog historical past into the massive language mannequin’s (LLM) context window, you may retrieve a compact abstract that preserves the important thing data whereas considerably decreasing token utilization. As a result of summaries are inherently tied to a particular dialog, they need to embrace the session identifier:/actor/{actorId}/session/{sessionId}/abstract/This scoping signifies that every session will get its personal abstract, whereas nonetheless being organized below the actor for cross-session retrieval when wanted.
Reminiscence Useful resource: CustomerSupportMemory
│
├── /actor/customer-123/
│ ├── session/session-001/abstract/
│ │ └── “Buyer inquired about enterprise pricing, mentioned
│ │ implementation timeline, requested follow-up demo”
│ ├── session/session-002/abstract/
│ │ └── “Comply with-up on demo scheduling, confirmed Q3 timeline,
│ │ mentioned integration necessities with current CRM”
│ └── session/session-003/abstract/
│ └── “Technical deep-dive on API integration, reviewed
│ authentication choices, selected OAuth 2.0 strategy”
3. Episodic: Session-scoped with reflection hierarchy
Episodic reminiscence captures full reasoning traces, together with the purpose, steps taken, outcomes, and reflections. As a result of every episode represents what occurred throughout a particular interplay, episodes must be scoped to the session, much like summaries. For instance, a flight reserving agent may retailer an episode capturing the way it looked for flights, in contrast choices, dealt with a fare class restriction, and finally rebooked the client on another route. That episode belongs to the session the place it occurred. Reflections are cross-episode insights saved at a dad or mum degree. They generalize learnings throughout periods, as an illustration “when a fare class restriction blocks a modification, instantly seek for various flights reasonably than simply explaining the coverage.” The namespace for reflections should be a sub-path of the namespace for episodes:
Episodes: /actor/{actorId}/session/{sessionId}/episodes/
Reflections: /actor/{actorId}/
Retrieval patterns
Retrieval APIs
AgentCore Reminiscence gives three main retrieval APIs for long-term reminiscence, every suited to totally different entry patterns. Choosing the proper one is essential to constructing efficient brokers.
1. Semantic search with RetrieveMemoryRecords
Use RetrieveMemoryRecords to search out recollections which are semantically related to a question. That is the first retrieval technique throughout agent interactions, surfacing probably the most related recollections primarily based on which means, reasonably than actual textual content matching.
# Retrieve recollections related to the present consumer question
recollections = agentcore_client.retrieve_memory_records(
memoryId=”mem-12345abcdef”,
namespace=”/actor/customer-123/info/”,
searchCriteria={
“searchQuery”: “What cloud migration strategy is the client utilizing?”,
“topK”: 5
}
)
The search question can come from two sources:
- Immediately from the consumer question – Move the consumer’s query as-is when it naturally maps to the type of data saved in reminiscence. For instance, if the consumer asks “What’s my funds?”, that question works properly for retrieving desire or truth recollections.
- LLM-generated question – For extra complicated eventualities, have your agent’s LLM formulate a focused search question. That is helpful when the consumer’s uncooked enter doesn’t immediately map to saved recollections. For instance, if the consumer says “Assist me plan my subsequent journey,” the LLM may generate a search question like “journey preferences, vacation spot historical past, funds constraints” to retrieve probably the most related recollections. Notice that this provides latency.
2. Direct retrieval with ListMemoryRecords
Use ListMemoryRecords when it’s good to enumerate recollections inside a particular namespace akin to, displaying a consumer’s saved preferences in a console UI, auditing what recollections exist, or performing bulk operations.
# Record all recollections in a particular namespace
information = agentcore_client.list_memory_records(
memoryId=”mem-12345abcdef”,
namespace=”/actor/customer-123/preferences/”
)
3. GetMemoryRecord and DeleteMemoryRecord
When you recognize the precise reminiscence report ID (for instance, from a earlier checklist or retrieve name), use GetMemoryRecord for direct lookup or DeleteMemoryRecord to take away a particular reminiscence:
# Get a particular reminiscence report
report = agentcore_client.get_memory_record(
memoryId=”mem-12345abcdef”,
memoryRecordId=”rec-abc123″
)
# Delete a particular reminiscence report
agentcore_client.delete_memory_record(
memoryId=”mem-12345abcdef”,
memoryRecordId=”rec-abc123″
)
These are helpful for reminiscence administration workflows which are used to assist customers view, appropriate, or delete particular recollections by way of your software’s UI.
Namespace vs. NamespacePath: Precise match vs. hierarchical retrieval
AgentCore Reminiscence gives two distinct fields for scoping retrieval, and understanding the distinction is crucial for proper habits.
1. namespace — Precise match
The namespace subject performs an actual match. It returns solely reminiscence information saved at that exact namespace path.
# Returns ONLY information saved at /actor/customer-123/info/
information = agentcore_client.retrieve_memory_records(
memoryId=”mem-12345abcdef”,
namespace=”/actor/customer-123/info/”,
searchCriteria={
“searchQuery”: “cloud migration”,
“topK”: 5
}
)
That is the best selection when you recognize precisely which namespace you wish to question and want exact scoping. For instance, retrieving solely a consumer’s preferences with out pulling of their info or summaries.
2. namespacePath — Hierarchical retrieval
The namespacePath subject performs a hierarchical match, returning the reminiscence information whose namespace falls below the desired path.
# Returns information from
# /actor/customer-123/info/,
# /actor/customer-123/preferences/,
# /actor/customer-123/session/*/abstract/, and many others.
information = agentcore_client.retrieve_memory_records(
memoryId=”mem-12345abcdef”,
namespacePath=”/actor/customer-123/”,
searchCriteria={
“searchQuery”: “cloud migration”,
“topK”: 5
}
)
That is helpful while you wish to search throughout the consumer’s recollections no matter kind, or when constructing options like “present me all the pieces we find out about this buyer.” Notice that it’s vital that you simply assume by way of your isolation and retrieval patterns to be sure that tree traversal doesn’t expose unintended information.
When to make use of which
Situation
API
Discipline
Instance
1
Retrieve semantically related consumer preferences
RetrieveMemoryRecords
namespace
/actor/customer-123/preferences/
2
Retrieve a particular session abstract
ListMemoryRecords
namespace
/actor/customer-123/session/session-001/abstract/
3
Record all preferences for a consumer
ListMemoryRecords
namespace
/actor/customer-123/preferences/
4
Search throughout a consumer’s recollections
RetrieveMemoryRecords
namespacePath
/actor/customer-123/
5
Record summaries throughout periods for a consumer
ListMemoryRecords
namespacePath
/actor/customer-123/session/
Writing IAM insurance policies for namespace entry management
Namespaces combine with AWS Identification and Entry Administration (IAM) by way of situation keys that prohibit which namespaces a principal can embrace of their Reminiscence API requests.
1. Precise match insurance policies
Use StringEquals with the bedrock-agentcore:namespace situation key to limit entry to a particular namespace:
{
“Model”: “2012-10-17”,
“Assertion”: [
{
“Effect”: “Allow”,
“Action”: [
“bedrock-agentcore:RetrieveMemoryRecords”,
“bedrock-agentcore:ListMemoryRecords”
],
“Useful resource”: “arn:aws:bedrock-agentcore:us-east-1:123456789012:reminiscence/mem-12345abcdef”,
“Situation”: {
“StringEquals”: {
“bedrock-agentcore:namespace”: “/actor/${aws:PrincipalTag/userId}/preferences/”
}
}
}
]
}
This coverage makes certain {that a} consumer can solely retrieve recollections from their very own preferences namespace, utilizing the userId principal tag (injected) for dynamic scoping.
2. Hierarchical retrieval insurance policies
Use StringLike with the bedrock-agentcore:namespacePath situation key for hierarchical entry:
{
“Model”: “2012-10-17”,
“Assertion”: [
{
“Effect”: “Allow”,
“Action”: [
“bedrock-agentcore:RetrieveMemoryRecords”,
“bedrock-agentcore:ListMemoryRecords”
],
“Useful resource”: “arn:aws:bedrock-agentcore:us-east-1:123456789012:reminiscence/mem-12345abcdef”,
“Situation”: {
“StringLike”: {
“bedrock-agentcore:namespacePath”: “/actor/${aws:PrincipalTag/userId}/*”
}
}
}
]
}
With this, a consumer can carry out hierarchical retrieval throughout their namespaces (info, preferences, summaries) whereas serving to stop entry to different customers’ information.
Conclusion
Namespace design is foundational to constructing efficient reminiscence programs with AgentCore Reminiscence. Very like designing a key schema for a database or a prefix construction in object storage, considering by way of your entry patterns upfront helps you create a namespace hierarchy that helps exact retrieval, clear isolation between customers, and IAM-based entry management.The important thing takeaways:
- Suppose by way of your entry patterns and isolation boundaries earlier than developing with namespace templates
- Scope semantic and desire recollections to the actor (/actor/{actorId}/) for cross-session consolidation
- Scope summaries to the session (/actor/{actorId}/session/{sessionId}/) since they’re conversation-specific (the place wanted akin to summaries or episodes)
- Use namespace for actual match when you recognize the exact path, and namespacePath for hierarchical retrieval when it’s good to search throughout a subtree
- Use main and trailing slashes in namespace paths to maintain them constant and assist stop prefix collisions
- Use IAM situation keys (bedrock-agentcore:namespace and bedrock-agentcore:namespacePath) to regulate what namespaces could be requested
To get began, go to the next sources:
Concerning the authors
Noor Randhawa
Noor Randhawa is the Tech Lead for AgentCore Reminiscence at Amazon Internet Providers (AWS), constructing programs that allow builders to create clever, context-aware brokers powered by Reminiscence. He beforehand labored throughout Amazon Retail and AWS EKS, designing extremely scalable and distributed platforms.
Akarsha Sehwag
Akarsha Sehwag is a Generative AI Knowledge Scientist with AgentCore Reminiscence workforce. With over seven years of expertise in AI/ML product improvement, she has delivered enterprise-grade options for patrons throughout a variety of industries. Exterior of labor, she enjoys studying new issues and exploring the outside.
Piradeep Kandasamy
Piradeep Kandasamy is a Software program Improvement Supervisor for AgentCore Reminiscence. Over his profession at Amazon, he has constructed and scaled programs throughout Amazon Alexa, Amazon ECS, and AWS CloudFormation, bringing deep experience in distributed programs and large-scale cloud companies to his present work on reminiscence infrastructure for AI brokers.
