# How it works
AgentCore Memory provides a set of APIs that let your AI agents seamlessly store, retrieve, and utilize both short-term and long-term memory. The architecture is designed to separate the immediate context of a conversation from the persistent knowledge that should be retained over time.
**Topics**
+ [
# Memory terminology
](memory-terminology.md)
+ [
# Memory types
](memory-types.md)
+ [
# Memory strategies
](memory-strategies.md)
+ [
# Memory organization in AgentCore Memory
](memory-organization.md)
+ [
# Memory record streaming
](memory-record-streaming.md)
+ [
# Compare long-term memory with Retrieval-Augmented Generation
](memory-ltm-rag.md)
# Memory terminology
**AgentCore Memory**
The primary, top-level container for your agent’s memory resource. Each AgentCore Memory holds all the events and extracted insights for agents or applications.
**Memory strategy**
Memory strategies are configurable rules that determine how to process information from short-term memory into long-term memory. They determine what type of information is kept, turning raw conversations into structured and useful knowledge.
**Namespace**
A namespace is a structured path used to logically group and organize long-term memories. By defining a namespace in your memory strategy, you maintain that all extracted memories are organized under predictable paths, which aids in retrieval, filtering, and access control.
**Memory record**
A memory record is a structured unit of information within the memory resource. Each record is associated with a unique identifier and is stored within a specified namespace, allowing for organized retrieval and management.
**Session**
Represents a single, continuous interaction between a user and the agent, such as a customer support conversation. A unique `sessionId` is used to group all events within that conversation.
**Actor**
Represents the entity interacting with the agent. This can be a human user, another agent, or a system (software or hardware component) that initiates interactions with the agent. A unique `actorId` maintains that memory records are correctly associated with the individual or system.
**Event**
Event is the fundamental unit of short-term memory. It represents a discrete interaction or activity within a session, associated with a specific actor. Events are stored using the [CreateEvent](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CreateEvent.html) operation and are organized by `actorId` and `sessionId` . Each event is immutable and timestamped, capturing real-time data such as user messages, system actions, or tool invocations.
**Event metadata**
Event metadata refers to the supplementary information that provides context about an event in an AgentCore Memory. While not always explicitly required, metadata can enhance the organization and retrieval of events.
# Memory types
AgentCore Memory offers two types of memory that work together to create intelligent, context-aware AI agents:
**Topics**
+ [
## Short-term memory
](#short-term-memory)
+ [
## Long-term memory
](#memory-long-term-memory)
## Short-term memory
Short-term memory stores raw interactions that help the agent maintain context within a single session. For example, in a shopping website’s [customer support AI agent](memory-customer-scenario.md) , short-term memory captures the entire conversation history as a series of events. Each customer question and agent response is saved as a separate event (or in batches, depending on your implementation). This lets the agent reload the entire conversation as it happened, maintaining context even if the service restarts or the customer returns later to continue the same interaction seamlessly.
When a customer interacts with your agent, each interaction can be captured as an event using the [CreateEvent](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CreateEvent.html) operation. Events can contain various types of data, including conversational exchanges (questions, answers, instructions) or structured information (product details, order status). Each event is associated with a session via a session identifier ( `sessionId` ), which you can define or let the system generate by default. You can use the `sessionId` parameter in future requests to maintain conversation context.
To load previous sessions/conversations or enrich context, your agent needs to access the raw interactions with the customer. Imagine a customer returns to follow up on their product support case from last week. To provide seamless assistance, the agent uses [ListSessions](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_ListSessions.html) to locate their previous support interactions. Through [ListEvents](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_ListEvents.html) , it retrieves the conversation history, understanding the reported issue, troubleshooting steps attempted, and any temporary solutions discussed. The agent uses [GetEvent](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_GetEvent.html) to access specific information from key moments in past conversations. These operations work together to maintain support continuity across sessions, eliminating the need for customers to re-explain their issue or repeat troubleshooting steps already attempted.
### Event metadata
Event metadata lets you attach additional context information to your short-term memory events as key-value pairs. When creating events using the `CreateEvent` operation, you can include metadata that isn’t part of the core event content but provides valuable context for retrieval. For example, a travel booking agent can attach location metadata to events, making it easy to find all conversations that mentioned specific destinations. You can then use the `ListEvents` operation with metadata filters to efficiently retrieve events based on these attached properties, enabling your agent to quickly locate relevant conversation history without scanning through entire sessions. This capability is useful for agents that need to track and retrieve specific attributes across conversations, such as product categories in e-commerce, case types in customer support, or project identifiers in task management applications. Event metadata is not meant to store sensitive content, as it is not encrypted with customer managed key.
## Long-term memory
Long-term memory records store structured information extracted from raw agent interactions, which is retained across multiple sessions. Long-term memory preserves only the key insights such as summaries of the conversations, facts and knowledge, or user preferences. For example, if a customer tells the agent their preferred shoe brand during a conversation, the AI agent stores this as a long-term memory. Later, even in a different conversation, the agent can remember and suggest the shoe brand, making the interaction personalized and relevant.
Long-term memory generation is an asynchronous process that runs in the background and automatically extracts insights after raw conversation/context is stored in short-term memory via `CreateEvent` . This efficiently consolidates key information without interrupting live interactions. As part of the long-term memory generation, AgentCore Memory performs the following operations:
+ **Extraction** : Extracts information from raw interactions with the agent
+ **Consolidation** : Consolidates newly extracted information with existing information in the AgentCore Memory.
Once long-term memory records are generated, you can retrieve these extracted memories to enhance your agent’s responses. Extracted memories are stored as memory records and can be accessed using the [GetMemoryRecord](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_GetMemoryRecord.html) , [ListMemoryRecords](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_ListMemoryRecords.html) , or [RetrieveMemoryRecords](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_RetrieveMemoryRecords.html) operations. The `RetrieveMemoryRecords` operation is powerful as it performs a semantic search to find memory records that are most relevant to the query. For example, when a customer asks about running shoes, the agent can use semantic search to retrieve related memory records, such as customer’s preferred shoe size, favorite shoe brands, and previous shoe purchases. This lets the AI support agent provide highly personalized recommendations without requiring the customer to repeat information they’ve shared before.
# Memory strategies
In AgentCore Memory, you can add memory strategies to your memory resource. These strategies determine what types of information to extract from raw conversations. Strategies are configurations that intelligently capture and persist key concepts from interactions, sent as events in the [CreateEvent](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CreateEvent.html) operation. You can add strategies to the memory resource as part of [CreateMemory](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateMemory.html) or [UpdateMemory](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateMemory.html) operations. Once enabled, these strategies are automatically executed on raw conversation events associated with that memory resource to extract long-term memories.
If no strategies are specified, long-term memory records will not be extracted for that memory.
AgentCore Memory supports a variety of memory strategies:
**Topics**
+ [
## Built-in strategies
](#memory-built-in-strategies-desc)
+ [
## Built-in overrides
](#memory-built-in-overrides-desc)
+ [
## Self-managed strategies
](#memory-self-managed-strategies-desc)
+ [
# Built-in strategies
](built-in-strategies.md)
+ [
# Customize a built-in strategy or create your own strategy
](memory-custom-strategy.md)
+ [
# Self-managed strategy
](memory-self-managed-strategies.md)
## Built-in strategies
AgentCore handles all memory extraction and consolidation automatically with predefined algorithms.
+ AgentCore handles all memory extraction and consolidation automatically
+ No configuration required beyond basic trigger settings
+ Uses predefined algorithms optimized and benchmarked for common use cases
+ Suitable for standard conversational AI applications
+ Limited customization options
+ Higher cost for storage
## Built-in overrides
Extends built-in strategies with targeted customization while using an AgentCore managed extraction pipeline.
+ Extends built-in strategies with targetted customization
+ Allows modification of prompts while still using AgentCore managed extraction pipeline
+ Provides support for bedrock models (invoked in your account)
+ Lower cost for storage than built-ins
## Self-managed strategies
You have complete ownership of memory processing pipeline with custom extraction and consolidation algorithms.
+ Complete ownership of memory processing pipeline
+ Custom extraction and consolidation algorithms using any model, prompts, etc.
+ Full control over memory record schemas, namespaces etc.
+ Integration with external systems and databases
+ Requires infrastructure setup and maintenance
+ Lower cost for storage than built-in strategies
A single memory resource can be configured to utilize both built-in and custom strategies simultaneously, providing flexibility to address diverse memory requirements.
# Built-in strategies
AgentCore Memory provides built-in strategies to create memories. Each built-in strategy consists of steps to handle memory creation, including the following (different strategies employ different steps):
+ **Extraction** – Identifies useful insights from short-term memory to place into long-term memory as memory records.
+ **Consolidation** – Determines whether to write useful information to a new record or an existing record.
+ **Reflection** – Insights are generated across episodes.
Each step is defined by a system prompt, which is a combination of the following:
+ **Instructions** – Guide the LLM’s behavior. Can include step-by-step processing guidelines (how the model should reason and extract or consolidate information).
+ **Output schema** – How the model should present the result.
Each memory strategy provides a structured output format tailored to its purpose. The output is not uniform across strategies, because the type of information being stored and retrieved differs. This maintains that each memory type exposes only the fields most relevant to its strategy. You can find the output formats in the system prompts for each strategy.
You can combine multiple strategies when creating memories.
**Topics**
+ [
# Semantic memory strategy
](semantic-memory-strategy.md)
+ [
# User preference memory strategy
](user-preference-memory-strategy.md)
+ [
# Summary strategy
](summary-strategy.md)
+ [
# Episodic memory strategy
](episodic-memory-strategy.md)
# Semantic memory strategy
The semantic memory strategy is designed to identify and extract key pieces of factual information and contextual knowledge from conversational data. This lets your agent to build a persistent knowledge base about the entities, events, and key details discussed during an interaction.
**Steps in the strategy**
The semantic memory strategy includes the following steps:
+ **Extraction** – Identifies useful insights from short-term memory to place into long-term memory as memory records.
+ **Consolidation** – Determines whether to write useful information to a new record or an existing record.
**Note**
The semantic strategy processes only `USER` and `ASSISTANT` role messages during extraction. For more information about roles in agent conversations, see [Conversational](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_Conversational.html).
**Strategy output**
The semantic memory strategy returns facts as JSON objects, each representing a standalone personal fact about the user.
**Example of facts captured by this strategy**
+ An order number ( \$1XYZ-123 ) is associated with a specific support case.
+ A project’s deadline of October 25th.
+ The user is running version 2.1 of the software.
By referencing this stored knowledge, your agent can provide more accurate, context-aware responses, perform multi-step tasks that rely on previously stated information, and avoid asking users to repeat key details.
**Default namespace**
`/strategy/{memoryStrategyId}/actors/{actorId}/`
**Topics**
+ [
# System prompt for semantic memory strategy
](memory-system-prompt.md)
# System prompt for semantic memory strategy
The semantic strategy includes instructions and output schemas in the default prompts for the extraction and consolidation steps.
## Extraction instructions
```
You are a long-term memory extraction agent supporting a lifelong learning system. Your task is to identify and extract meaningful information about the users from a given list of messages.
Analyze the conversation and extract structured information about the user according to the schema below. Only include details that are explicitly stated or can be logically inferred from the conversation.
- Extract information ONLY from the user messages. You should use assistant messages only as supporting context.
- If the conversation contains no relevant or noteworthy information, return an empty list.
- Do NOT extract anything from prior conversation history, even if provided. Use it solely for context.
- Do NOT incorporate external knowledge.
- Avoid duplicate extractions.
IMPORTANT: Maintain the original language of the user's conversation. If the user communicates in a specific language, extract and format the extracted information in that same language.
```
## Extraction output schema
```
Your output must be a single JSON object, which is a list of JSON dicts following the schema. Do not provide any preamble or any explanatory text.
{
"description": "This is a standalone personal fact about the user, stated in a simple sentence.\\nIt should represent a piece of personal information, such as life events, personal experience, and preferences related to the user.\\nMake sure you include relevant details such as specific numbers, locations, or dates, if presented.\\nMinimize the coreference across the facts, e.g., replace pronouns with actual entities.",
"properties": {
"fact": {
"description": "The memory as a well-written, standalone fact about the user. Refer to the user's instructions for more information the prefered memory organization.",
"title": "Fact",
"type": "string"
}
},
"required": [
"fact"
],
"title": "SemanticMemory",
"type": "object"
}
```
## Consolidation instructions
```
You are a conservative memory manager that preserves existing information while carefully integrating new facts.
Your operations are:
- **AddMemory**: Create new memory entries for genuinely new information
- **UpdateMemory**: Add complementary information to existing memories while preserving original content
- **SkipMemory**: No action needed (information already exists or is irrelevant)
If the operation is "AddMemory", you need to output:
1. The `memory` field with the new memory content
If the operation is "UpdateMemory", you need to output:
1. The `memory` field with the original memory content
2. The update_id field with the ID of the memory being updated
3. An updated_memory field containing the full updated memory with merged information
## Decision Guidelines
### AddMemory (New Information)
Add only when the retrieved fact introduces entirely new information not covered by existing memories.
**Example**:
- Existing Memory: `[{"id": "0", "text": "User is a software engineer"}]`
- Retrieved Fact: `["Name is John"]`
- Action: AddMemory with new ID
### UpdateMemory (Preserve + Extend)
Preserve existing information while adding new details. Combine information coherently without losing specificity or changing meaning.
**Critical Rules for UpdateMemory**:
- **Preserve timestamps and specific details** from the original memory
- **Maintain semantic accuracy** - don't generalize or change the meaning
- Only enhance when new information genuinely adds value without contradiction
- Only enhance when new information is **closely relevant** to existing memories
- Attend to novel information that deviates from existing memories and expectations
- Consolidate and compress redundant memories to maintain information-density; strengthen based on reliability and recency; maximize SNR by avoiding idle words
**Example**:
- Existing: `[{"id": "1", "text": "Caroline attended an LGBTQ support group meeting that she found emotionally powerful."}]`
- Retrieved: `["Caroline found the support group very helpful"]`
- Action: UpdateMemory to `"Caroline attended an LGBTQ support group meeting that she found emotionally powerful and very helpful."`
**When NOT to update**:
- Information is essentially the same: "likes pizza" vs "loves pizza"
- Updating would change the fundamental meaning
- New fact contradicts existing information (use AddMemory instead)
- New fact contains new events with timestamps that differ from existing facts. Since enhanced memories share timestamps with original facts, this would create temporal contradictions. Use AddMemory instead.
### SkipMemory (No Change)
Use when information already exists in sufficient detail or when new information doesn't add meaningful value.
## Key Principles
- Conservation First: Preserve all specific details, timestamps, and context
- Semantic Preservation: Never change the core meaning of existing memories
- Coherent Integration: Lets enhanced memories read naturally and logically
```
## Consolidation output schema
```
## Response Format
Return only this JSON structure, using double quotes for all keys and string values:
```json
[
{
"memory": {
"fact": ""
},
"operation": "",
"update_id": "",
"updated_memory": {
"fact": ""
}
},
...
]
```
Only include entries with AddMemory or UpdateMemory operations. Return empty memory array if no changes are needed.
Do not return anything except the JSON format.
```
# User preference memory strategy
The `UserPreferenceMemoryStrategy` is designed to automatically identify and extract user preferences, choices, and styles from conversational data. This lets your agent to learn from interactions and builds a persistent, dynamic profile of each user over time.
**Steps in the strategy**
The user preference strategy includes the following steps:
+ **Extraction** – Identifies useful insights from short-term memory to place into long-term memory as memory records.
+ **Consolidation** – Determines whether to write useful information to a new record or an existing record.
**Note**
The user preference strategy processes only `USER` and `ASSISTANT` role messages during extraction. For more information about roles in agent conversations, see [Conversational](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_Conversational.html).
**Strategy output**
The user preference strategy returns JSON objects with context, preference, and categories, making it easier to capture user choices and decision patterns.
**Examples of insights captured by this strategy include:**
+ A customer’s preferred shipping carrier or shopping brand.
+ A developer’s preferred coding style or programming language.
+ A user’s communication preferences, such as a formal or informal tone.
By leveraging this strategy, your agent can deliver highly personalized experiences, such as offering tailored recommendations, adapting its responses to a user’s style, and anticipating needs based on past choices. This creates a more relevant and effective conversational experience.
**Default namespace**
`/strategy/{memoryStrategyId}/actors/{actorId}/`
**Topics**
+ [
# System prompt for user preference memory strategy
](memory-user-prompt.md)
# System prompt for user preference memory strategy
The user preference strategy includes instructions and output schemas in the default prompts for the extraction and consolidation steps.
## Extraction instructions
```
You are tasked with analyzing conversations to extract the user's preferences. You'll be analyzing two sets of data:
[Past conversations between the user and system will be placed here for context]
[The current conversation between the user and system will be placed here]
Your job is to identify and categorize the user's preferences into two main types:
- Explicit preferences: Directly stated preferences by the user.
- Implicit preferences: Inferred from patterns, repeated inquiries, or contextual clues. Take a close look at user's request for implicit preferences.
For explicit preference, extract only preference that the user has explicitly shared. Do not infer user's preference.
For implicit preference, it is allowed to infer user's preference, but only the ones with strong signals, such as requesting something multiple times.
```
## Extraction output schema
```
Extract all preferences and return them as a JSON list where each item contains:
1. "context": The background and reason why this preference is extracted.
2. "preference": The specific preference information
3. "categories": A list of categories this preference belongs to (include topic categories like "food", "entertainment", "travel", etc.)
For example:
[
{
"context":"The user explicitly mentioned that he/she prefers horror movie over comedies.",
"preference": "Prefers horror movies over comedies",
"categories": ["entertainment", "movies"]
},
{
"context":"The user has repeatedly asked for Italian restaurant recommendations. This could be a strong signal that the user enjoys Italian food.",
"preference": "Likely enjoys Italian cuisine",
"categories": ["food", "cuisine"]
}
]
Extract preferences only from . Extract preference ONLY from the user messages. You should use assistant messages only as supporting context. Only extract user preferences with high confidence.
Maintain the original language of the user's conversation. If the user communicates in a specific language, extract and format the extracted information in that same language.
Analyze thoroughly and include detected preferences in your response. Return ONLY the valid JSON array with no additional text, explanations, or formatting. If there is nothing to extract, simply return empty list.
```
## Consolidation instructions
```
# ROLE
You are a Memory Manager that evaluates new memories against existing stored memories to determine the appropriate operation.
# INPUT
You will receive:
1. A list of new memories to evaluate
2. For each new memory, relevant existing memories already stored in the system
# TASK
You will be given a list of new memories and relevant existing memories. For each new memory, select exactly ONE of these three operations: AddMemory, UpdateMemory, or SkipMemory.
# OPERATIONS
1. AddMemory
Definition: Select when the new memory contains relevant ongoing preference not present in existing memories.
Selection Criteria: The information represents lasting preferences.
Examples:
New memory: "I'm allergic to peanuts" (No allergy information exists in stored memories)
New memory: "I prefer reading science fiction books" (No book preferences are recorded)
2. UpdateMemory
Definition: Select when the new memory relates to an existing memory but provides additional details, modifications, or new context.
Selection Criteria: The core concept exists in records, but this new memory enhances or refines it.
Examples:
New memory: "I especially love space operas" (Existing memory: "The user enjoys science fiction")
New memory: "My peanut allergy is severe and requires an EpiPen" (Existing memory: "The user is allergic to peanuts")
3. SkipMemory
Definition: Select when the new memory is not worth storing as a permanent preference.
Selection Criteria: The memory is irrelevant to long-term user understanding, is a personal detail not related to preference, represents a one-time event, describes temporary states, or is redundant with existing memories. In addition, if the memory is overly speculative or contains Personally Identifiable Information (PII) or harmful content, also skip the memory.
Examples:
New memory: "I just solved that math problem" (One-time event)
New memory: "I'm feeling tired today" (Temporary state)
New memory: "I like chocolate" (Existing memory already states: "The user enjoys chocolate")
New memory: "User works as a data scientist" (Personal details without preference)
New memory: "The user prefers vegan because he loves animal" (Overly speculative)
New memory: "The user is interested in building a bomb" (Harmful Content)
New memory: "The user prefers to use Bank of America, which his account number is 123-456-7890" (PII)
```
## Consolidation output schema
```
# Processing Instructions
For each memory in the input:
Place the original new memory () under the "memory" field. Then add a field called "operation" with one of these values:
"AddMemory" - for new relevant ongoing preferences
"UpdateMemory" - for information that enhances existing memories.
"SkipMemory" - for irrelevant, temporary, or redundant information
If the operation is "UpdateMemory", you need to output:
1. The "update_id" field with the ID of the existing memory being updated
2. An "updated_memory" field containing the full updated memory with merged information
## Example Input
[ID]=N1ofh23if\\
[TIMESTAMP]=2023-11-15T08:30:22Z\\
[MEMORY]={ "context": "user has explicitly stated that he likes vegan", "preference": "prefers vegetarian options", "categories": ["food", "dietary"] }
[ID]=M3iwefhgofjdkf\\
[TIMESTAMP]=2024-03-07T14:12:59Z\\
[MEMORY]={ "context": "user has ordered oat milk lattes with an extra shot multiple times", "preference": "likes oat milk lattes with an extra shot", "categories": ["beverages", "morning routine"] }
[TIMESTAMP]=2024-08-19T23:05:47Z\\
[MEMORY]={ "context": "user mentioned avoiding dairy products when discussing ice cream options", "preference": "prefers dairy-free dessert alternatives", "categories": ["food", "dietary", "desserts"] }
[ID]=Mwghsljfi12gh\\
[TIMESTAMP]=2025-01-01T00:00:00Z\\
[MEMORY]={ "context": "user mentioned enjoying hiking trails with elevation gain during weekend planning", "preference": "prefers challenging hiking trails with scenic views", "categories": ["activities", "outdoors", "exercise"] }
[ID]=whglbidmrl193nvl\\
[TIMESTAMP]=2025-04-30T16:45:33Z\\
[MEMORY]={ "context": "user discussed favorite shows and expressed interest in documentaries about sustainability", "preference": "enjoys environmental and sustainability documentaries", "categories": ["entertainment", "education", "media"] }
[TIMESTAMP]=2025-09-12T03:27:18Z\\
[MEMORY]={ "context": "user researched trips to coastal destinations with public transportation options", "preference": "prefers car-free travel to seaside locations", "categories": ["travel", "transportation", "vacation"] }
[ID]=P4df67gh\\
[TIMESTAMP]=2026-02-28T11:11:11Z\\
[MEMORY]={ "context": "user has mentioned enjoying coffee with breakfast multiple times", "preference": "prefers starting the day with coffee", "categories": ["beverages", "morning routine"] }
[ID]=Q8jk12lm\\
[TIMESTAMP]=2026-07-04T19:45:01Z\\
[MEMORY]={ "context": "user has stated they typically wake up around 6:30am on weekdays", "preference": "has an early morning schedule on workdays", "categories": ["schedule", "habits"] }
[TIMESTAMP]=2026-12-25T22:30:59Z\\
[MEMORY]={ "context": "user mentioned they didn't sleep well last night and felt tired today", "preference": "feeling tired and groggy", "categories": ["sleep", "wellness"] }
## Example Output
[{
"memory":{
"context": "user mentioned avoiding dairy products when discussing ice cream options",
"preference": "prefers dairy-free dessert alternatives",
"categories": ["food", "dietary", "desserts"]
},
"operation": "UpdateMemory",
"update_id": "N1ofh23if",
"updated_memory": {
"context": "user has explicitly stated that he likes vegan and mentioned avoiding dairy products when discussing ice cream options",
"preference": "prefers vegetarian options and dairy-free dessert alternatives",
"categories": ["food", "dietary", "desserts"]
}
},
{
"memory":{
"context": "user researched trips to coastal destinations with public transportation options",
"preference": "prefers car-free travel to seaside locations",
"categories": ["travel", "transportation", "vacation"]
},
"operation": "AddMemory",
},
{
"memory":{
"context": "user mentioned they didn't sleep well last night and felt tired today",
"preference": "feeling tired and groggy",
"categories": ["sleep", "wellness"]
},
"operation": "SkipMemory",
}]
Like the example, return only the list of JSON with corresponding operation. Do NOT add any explanation.
```
# Summary strategy
The `SummaryStrategy` is responsible for generating condensed, real-time summaries of conversations within a single session. It captures key topics, main tasks, and decisions, providing a high-level overview of the dialogue.
**Steps in the strategy**
The summary strategy includes the following steps:
+ **Consolidation** – Determines whether to write useful information to a new record or an existing record.
**Strategy output**
The summary strategy returns XML-formatted output, where each `` tag represents a distinct area of the user’s memory. XML lets multiple topics to be captured and organized in a single summary while preserving clarity.
A single session can have multiple summary chunks, each representing a portion of the conversation. Together, these chunks form the complete summary for the entire session.
These summary chunks can be retrieved using the [ListMemoryRecords](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_ListMemoryRecords.html) operation with namespace filter, or you can also perform semantic search over the summary chunks using the [RetrieveMemoryRecords](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_RetrieveMemoryRecords.html) operation to retrieve only the relevant summary chunks for your query.
**Examples of insights captured by this strategy include:**
+ A summary of a support interaction, such as "The user reported an issue with order \$1XYZ-123 , and the agent initiated a replacement."
+ The outcome of a planning session, like "The team agreed to move the project deadline to Friday."
By referencing this summary, an agent can quickly recall the context of a long or complex conversation without needing to re-process the entire history. This is essential for maintaining conversational flow and for efficiently managing the context window of the foundation model.
**Default namespace**
`/strategy/{memoryStrategyId}/actor/{actorId}/session/{sessionId}/`
**Note**
`sessionId` is a required parameter for summary namespace since summaries are generated and maintained at session level.
**Topics**
+ [
# System prompt for summary strategy
](memory-summary-prompt.md)
# System prompt for summary strategy
The semantic strategy includes instructions and an output schema in the default system prompt for a single consolidation step.
## Consolidation instructions
There are no consolidation instructions for built-in summary strategy.
## Consolidation output schema
```
You are a summary generator. You will be given a text block, a concise global summary, and a detailed summary you previous generated.
- Given the contexts(e.g. global summary, detailed previous summary), your goal is to generate
(1) a concise global summary keeping in main target of the conversation, such as the task and the requirements.
(2) a detailed delta summary of the given text block, without repeating the historical detailed summary.
- The previous summary is a context for you to understand the main topics.
- You should only output the delta summary, not the whole summary.
- The generated delta summary should be as concise as possible.
- Summarize with the same language as the given text block.
- If the messages are in a specific language, summarize with the same language.
When you generate global summary you ALWAYS follow the below guidelines:
- The global summary should be concise and to the point, only keep the most important information such as the task and the requirements.
- If there is no new high-level information, do not change the global summary. If there is new tasks or requirements, update the global summary.
- The global summary will be pure text wrapped by tag.
- The global summary should be no exceed specified word count limit.
- Tracking the size of the global summary by calculating the number of words. If the word count reaches the limit, try to compress the global summary.
When you generate detailed delta summaries you ALWAYS follow the below guidelines:
- Each summary MUST be formatted in XML format.
- You should cover all important topics.
- The summary of the topic should be place between .
- Only include information that are explicitly stated or can be logically inferred from the conversation.
- Consider the timestamps when you synthesize the summary.
- NEVER start with phrases like 'Here's the summary...', provide directly the summary in the format described below.
The XML format of each summary is as it follows:
$Word Count
The total word count of the existing global summary is $Total Word Count.
The word count limit for global summary is $Word Count Limit.
Since we exceed/do not exceed the word count limit, I need to condense the existing global summary/I don't need to condense the existing global summary.
...
...
...
```
**Note**
Built-in strategies may use cross-region inference for optimal performance and availability.
Built-in strategies may use [cross-region inference](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) . Bedrock will automatically select the optimal region within your geography to process your inference request, maximizing available compute resources and model availability, and providing the best customer experience. There’s no additional cost for using cross-region inference.
# Episodic memory strategy
**Episodic memory** captures meaningful slices of user and system interactions so applications can recall context in a way that feels focused and relevant. Instead of storing every raw event, it identifies important moments, summarizes them into compact records, and organizes them so the system can retrieve what matters without noise. This creates a more adaptive and intelligent experience by allowing models to understand how context has evolved over time.
Its strength comes from having structured context that spans many interactions, while remaining efficient to store, search, and update. Developers get a balance of freshness, accuracy, and long term continuity without needing to engineer their own summarization pipelines.
**Reflections** build on episodic records by analyzing past episodes to surface insights, patterns, and higher level conclusions. Instead of simply retrieving what happened, reflections help the system understand why certain events matter and how they should influence future behavior. They turn raw experience into guidance the application can use immediately, giving models a way to learn from history.
Their value comes from lifting information above individual moments, or episodes and creating durable knowledge that improves decision making, personalization, and consistency. This helps applications avoid repeating mistakes, adapt more quickly to user preferences, and behave in a way that feels coherent over long periods.
Customers should use episodic memory in any scenario where understanding a sequence of past interactions improves quality, as well as scenarios where long term improvement matters. Ideal use cases include customer support conversations, agent driven workflows, code assistants that rely on session history, personal productivity tools, troubleshooting or diagnostic flows, and applications that need context grounded in real prior events rather than static profiles.
When you invoke the episodic strategy, AgentCore automatically detects episode completion within conversations and processes events into structured episode records.
**Steps in the strategy**
The episodic memory strategy includes the following steps:
+ **Extraction** – Analyzes in-progress episode and determine if episode is complete.
+ **Consolidation** – When an episode is complete, combines extractions into single episode.
+ **Reflection** – Insights are generated across episodes.
**Strategy output**
The episodic memory strategy returns XML-formatted output for both episodes and reflections. Each episode is broken down into a situation, intent, assessment, justification, and episode-level reflection. As the interaction proceeds, the episode is analyzed turn-by-turn. You can use this information to better understand the order of operations and tool use.
**Examples of episodes captured by this strategy**
+ A code deployment interaction where the agent selected specific tools, encountered an error, and successfully resolved it using an alternative approach.
+ An appointment rescheduling task that captured the user’s intent, the agent’s decision to use a particular tool, and the successful outcome.
+ A data processing workflow that documented which parameters led to optimal performance for a specific data type.
The episodic strategy includes memory extraction and consolidation steps (shared with other strategies). In addition, the episodic strategy also generates reflections, which analyze episodes in the background as interactions take place. Reflections consolidate across multiple episodes to extract broader insights that identify successful strategies and patterns, potential improvements, common failure modes, and lessons learned that span multiple interactions.
**Examples of reflections include**
+ Identifying which tool combinations consistently lead to successful outcomes for specific task types.
+ Recognizing patterns in failed attempts and the approaches that resolved them.
+ Extracting best practices from multiple successful episodes with similar scenarios.
The following image schematizes the episodic memory strategy:
![\[Schema of episodic memory strategy.\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/memory/episodic-memory-strategy.png)
By referencing stored episodes, your agent can retrieve relevant past experiences through semantic search and review reflections to avoid repeating failed approaches and to adapt successful strategies to new contexts. This strategy is useful for agents that benefit from identifying patterns, need to continually update information, maintain consistency across interactions, and require context and reasoning rather than static knowledge to make decisions.
**Topics**
+ [
## Namespaces
](#episodic-memory-strategy-namespaces)
+ [
## How to best retrieve episodes to improve agentic performance
](#memory-episodic-retrieve-episodes)
+ [
# System prompts for episodic memory strategy
](memory-episodic-prompt.md)
## Namespaces
When you create a memory with the episodic strategy, you define namespaces under which to store episodes and reflections.
**Note**
Regardless of the namespace you choose to store episodes in, episodes are always created from a single session.
Episodes are commonly stored in one of the following namespaces:
+ `/strategy/{memoryStrategyId}/` – Store episodes at the strategy level. Episodes that have different actors or that come from different sessions, but that belong to the same strategy, are stored in the same namespace.
+ `/strategy/{memoryStrategyId}/actor/{actorId}/` – Store all episodes at the actor level. Episodes that come from different sessions, but that belong to the same actor, are stored in the same namespace.
+ `/strategy/{memoryStrategyId}/actor/{actorId}/session/{sessionId}/` – Store all episodes at the session level. Episodes that belong to the same session are stored in the same namespace.
Reflections must match the same namespace pattern as episodes, but reflections can be less nested. For example, if your episodic namespace is `/strategy/{memoryStrategyId}/actor/{actorId}/` , you can use the following namespaces for reflections:
+ `/strategy/{memoryStrategyId}/actor/{actorId}/` – Insights will be extracted across all episodes for an actor.
+ `/strategy/{memoryStrategyId}/` – Insights will be extracted across all episodes and across all actors for the strategy.
**Important**
Because reflections can span multiple actors within the same memory resource, consider the privacy implications of cross-actor analysis when retrieving reflections. Consider using [guardrails in conjunction with memory](https://github.com/awslabs/amazon-bedrock-agentcore-samples/tree/main/01-tutorials/04-AgentCore-memory/03-advanced-patterns/01-guardrails-integration) or reflecting at the actor level if this is a concern.
## How to best retrieve episodes to improve agentic performance
There are multiple ways to utilize episodic memory:
+ Within your agent code
+ When starting a new task, configure your agent to perform a query asking for the most similar episodes and reflections. Also query for relevant episodes and reflection subsequently based on some logic.
+ When creating short-term memories with [CreateEvent](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateEvent.html) , including `TOOL` results will yield optimal results.
+ For similar successful episodes, linearize the turns within the episode and feed only this to the agent so it focuses on the main steps
+ Manually
+ Look at your reflections or unsuccessful episodes, and consider whether some issues could be solved with updates to your agent code
When performing retrievals, note that memory records are indexed based on "intent" for episodes and "use case" for reflection.
For other memory strategies, memory records are generated on a regular basis throughout an interaction. Episodic memory records, by contrast, will only be generated once AgentCore Memory detects a completed episode. If an episode is not complete, it will take longer to generate because the systems waits to see if the conversation is continued.
# System prompts for episodic memory strategy
The episodic memory strategy includes instructions and output schemas in the default prompts for episode extraction, episode consolidation, and reflection generation.
**Topics**
+ [
## Episode extraction instructions
](#episode-extraction-instructions)
+ [
## Episode extraction output schema
](#episode-extraction-output-schema)
+ [
## Episode consolidation instructions
](#episode-generation-instructions)
+ [
## Episode consolidation output schema
](#episode-generation-output-schema)
+ [
## Reflection generation instructions
](#reflection-generation-instructions)
+ [
## Reflection generation output schema
](#reflection-generation-output-schema)
## Episode extraction instructions
```
You are an expert conversation analyst. Your task is to analyze multiple turns of conversation between a user and an AI assistant, focusing on tool usage, input arguments, and reasoning processes.
# Analysis Framework:
## 1. Context Analysis
- Examine all conversation turns provided within tags
- Each turn will be marked with tags
- Identify the circumstances and context that the assistant is responding to in each interaction
- Try to identify or recover the user's overall objective for the entire conversation, which may go beyond the given conversation turns
- When available, incorporate context from tags to understand the user's broader objectives from provided conversation history
## 2. Assistant Analysis (Per Turn)
For EACH conversation turn, analyze the assistant's approach by identifying:
- **Context**: The circumstances and situation the assistant is responding to, and how the assistant's goal connects to the user's overall objective (considering previous interactions when available)
- **Intent**: The assistant's primary goal for this specific conversation turn
- **Action**: Which specific tools were used with what input arguments and sequence of execution. If no tools were used, describe the concrete action/response the assistant took.
- **Reasoning**: Why these tools were chosen, how arguments were determined, and what guided the decision-making process. If no tools were used, explain the reasoning behind the assistant's action/response.
## 3. Outcome Assessment (Per Turn)
For EACH turn, using the next turn's user message:
- Determine whether the assistant successfully achieved its stated goal
- Evaluate the effectiveness of the action taken —- what worked well and what didn't
- Assess whether the user's overall objective has been satisfied, remains in progress, or is evolving
**Do not include any PII (personally identifiable information) or user-specific data in your output.**
```
## Episode extraction output schema
```
You MUST provide a separate block for EACH conversation turn. Number them sequentially:
The id of the turn that matches the input, e.g. 0, 1, 2, etc.
A brief description of the circumstances and context that the assistant is responding to in this turn, including the user's overall objective (which may go beyond this specific turn) and any relevant history from previous interactions
The assistant's primary goal for this specific interaction—what the assistant aimed to accomplish in this turn
Briefly describe which actions were taken or specific tools were used, what input arguments or parameters were provided to each tool.
Briefly explain why these specific tools or actions were chosen for this task, how the input arguments were determined (whether from the user's explicit request or inferred from context), what constraints or requirements influenced the approach, and what information guided the decision-making process
Start with Yes or No — Whether the assistant successfully achieved its stated goal for this turn
Then add a brief justification based on the relevant context
Yes or No - Whether this turn represents the END OF THE CONVERSATION EPISODE (the user's current inquiry has concluded). Then add a brief explanation by considering messages in the next turns: 1. If this turn represents the END OF THE CONVERSATION EPISODE (the user's current inquiry has concluded), then Yes (it is a clear signal that the user's inquiry has concluded). 2. If the user is continuing with new questions or shifting to other task, then Yes (it is a clear signal that the user is finished with the current task and is ready to move on to the next task). 3. If the user is asking for clarification or more information for the current task, indicating that the user's inquiry is in progress, then No (it is a clear signal that the user's inquiry is not yet concluded). 4. If there is no next turn and there is no clear signal showing that the user's inquiry has concluded, then No.
...
...
...
...
...
...
...
... continue for all turns ...
...
...
...
...
...
...
...
Attention: Only output 1-2 sentences for each field. Be concise and avoid lengthy explanations.
Make sure the number of is the same as the number of turns in the conversation.<
```
## Episode consolidation instructions
```
You are an expert conversation analyst. Your task is to analyze and summarize conversations between a user and an AI assistant provided within tags.
# Analysis Objectives:
- Provide a comprehensive summary covering all key aspects of the interaction
- Understand the user's underlying needs and motivations
- Evaluate the effectiveness of the conversation in meeting those needs
# Analysis Components:
Examine the conversation through the following dimensions:
**Situation**: The context and circumstances that prompted the user to initiate this conversation—what was happening that led them to seek assistance?
**Intent**: The user's primary goal, the problem they wanted to solve, or the outcome they sought to achieve through this interaction.
**Assessment**: A definitive evaluation of whether the user's goal was successfully achieved.
**Justification**: Clear reasoning supported by specific evidence from the conversation that explains your assessment.
**Reflection**: Key insights from the sequence of turns, focusing on patterns in tool usage, reasoning processes, and decision-making. Identify effective tool selection and argument patterns, reasoning or tool choices to avoid, and actionable recommendations for similar situations.
```
## Episode consolidation output schema
```
# Output Format:
Provide your analysis using the following structured XML format:
Brief description of the context and circumstances that prompted this conversation—what led the user to seek assistance at this moment
The user's primary goal, the specific problem they wanted to solve, or the concrete outcome they sought to achieve
[Yes/No] — Whether the user's goal was successfully achieved
Brief justification for your assessment based on key moments from the conversation
Synthesize key insights from the sequence of turns, focusing on patterns in tool usage, reasoning processes, and decision-making that led to success or failure. Identify effective tool selection and argument patterns that worked well, reasoning or tool choices that should be avoided.
```
## Reflection generation instructions
```
You are an expert at extracting actionable insights from agent task execution trajectories to build reusable knowledge for future tasks.
# Task:
Analyze the provided episodes and their reflection knowledge, and synthesize new reflection knowledge that can guide future scenarios.
# Input:
- **Main Episode**: The primary trajectory to reflect upon (context, goal, and execution steps)
- **Relevant Episodes**: Relevant trajectories that provide additional context and learning opportunities
- **Existing Reflection Knowledge**: Previously generated reflection insights from related episodes (each with an ID) that can be synthesized or expanded upon
# Reflection Process:
## 1. Pattern Identification
- First, review the main episode's user_intent (goal), description (context), turns (actions and thoughts), and reflection/finding (lessons learned)
- Then, review the relevant episodes and identify NEW patterns across episodes
- Review existing reflection knowledge to understand what's already been learned
- When agent system prompt is available, use it to understand the agent's instructions, capabilities, constraints, and requirements
- Finally, determine if patterns update existing knowledge or represent entirely new insights
## 2. Knowledge Synthesis
For each identified pattern, create a reflection entry with:
### Operator
Specify one of the following operations:
- **add**: This is a completely new reflection that addresses patterns not covered by existing reflection knowledge. Do NOT include an field.
- **update**: This reflection is an updated/improved version of an existing reflection from the input. ONLY use "update" when the new pattern shares the SAME core concept or title as an existing reflection. Include the existing reflection's ID in the field.
- Length constraint: If updating would make the combined use_cases + hints exceed 300 words, create a NEW reflection with "add" instead. Split the pattern into a more specific, focused insight rather than growing the existing one indefinitely.
### ID (only for "update" operator)
If operator is "update", specify the ID of the existing reflection that this new reflection expands upon. This ID comes from the existing reflection knowledge provided in the input.
### Title
Concise, descriptive name for the insight (e.g., "Error Recovery in API Calls", "Efficient File Search Strategies").
- When updating, keep the same title or a very similar variant to indicate it's the same conceptual pattern.
- When adding due to length constraint: Use a more specific variant of the title that narrows the scope (e.g., "Error Recovery in API Calls" → "Error Recovery in API Rate Limiting Scenarios")
### Applied Use Cases
Briefly describe when this applies, including:
- The types of goals (based on episode user_intents) where this insight helps
- The problems or challenges this reflection addresses
- Trigger conditions that signal when to use this knowledge
**When updating an existing reflection (within length limit):** Summarize both the original use cases and the new ones into create a comprehensive view.
### Concrete Hints
Briefly describe actionable guidance based on the identified patterns. Examples to include:
- Tool selection and usage patterns from successful episodes
- What worked well and what to avoid (from failures)
- Decision criteria for applying these patterns
- Specific reasoning details and context that explain WHY these patterns work
**When updating an existing reflection (within length limit):** If the new episodes reveal NEW hints, strategies, or patterns not in the existing reflection, ADD them to this section. Summarize both the original hints and the new ones into create a comprehensive view.
### Confidence Score
Score from 0.1 to 1.0 (0.1 increments) indicating how useful this will be for future agents:
- Higher (0.8-1.0): Clear actionable patterns that consistently led to success/failure
- Medium (0.4-0.7): Useful insights but context-dependent or limited evidence
- Lower (0.1-0.3): Tentative patterns that may not generalize well
When updating, adjust the confidence score based on the additional evidence from new episodes.
## 3. Synthesis Guidelines
- **When updating (within length limits)**:
- Keep the update concise - integrate new insights efficiently without verbose repetition
- DO NOT lose valuable information from the original reflection
- **When a reflection becomes too long**: Split it into more specific, focused reflections
- Each new reflection should be self-contained and focused on a specific sub-pattern
- Focus on **transferable** knowledge, not task-specific details
- Emphasize **why** certain approaches work, not just what was done
- Include both positive patterns (what to do) and negative patterns (what to avoid)
- If the existing reflection knowledge already covers the patterns well and no new insights emerge, generate fewer or no new reflections
```
## Reflection generation output schema
```
Aim for high-quality reflection entries that either add new learnings or update existing reflection knowledge.
- Keep reflections focused and split them into more specific patterns when they grow too long.
- Keep the use_cases and hints focused: Aim for 100-200 words.
- If it's growing beyond this, consider if you should create a new, more specific reflection instead.
# Output Format:
[add or update]
[ID of existing reflection being expanded - only include this field if operator is "update"]
[Clear, descriptive title - keep same/similar to original when updating]
[Briefly describe the types of goals (from episode user_intents), problems addressed, trigger conditions. When updating: combine original use cases and new ones from recent episodes]
[Briefly describe tool usage patterns, what works, what to avoid, decision criteria, reasoning details. When updating: combine original hints and new insights from recent episodes]
[0.1 to 1.0]
```
# Customize a built-in strategy or create your own strategy
For advanced or domain-specific use cases, you can create a built-in with overrides strategy to gain fine-grained control over the long-term memory process. Built-in with overrides strategies let you override the default behavior of the built-in strategies by providing your own instructions and selecting a specific foundation model for the extraction and consolidation steps.
## When to use a built-in with overrides strategy
Choose a built-in with overrides strategy when you need to tailor the memory logic to your specific requirements. Common use cases include:
+ **Domain-specific extraction:** Constraining the strategy to extract only certain types of information. For example, capturing a user’s food and dietary preferences while ignoring their preferences for clothing.
+ **Controlling granularity:** Adjusting the level of detail in the extracted memory. For example, instructing the summary strategy to only save high-level key points rather than a detailed narrative.
+ **Model selection:** Using a specific foundation model that is better suited for your particular domain or task, such as a model fine-tuned for financial or legal text.
## How to customize a strategy
To override a built-in strategy with a custom configuration, you specify the configuration when you use the [CreateMemory](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateMemory.html) operation or the [UpdateMemory](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateMemory.html) operation. You can override the following:
+ The instructions in the system prompt (however, the output schema remains the same). To create an effective custom prompt, you should first understand the default prompts. For more information, see the system prompt section for each [built-in strategy](built-in-strategies.md).
+ The Amazon Bedrock model with which to invoke the prompt. For more information, see [Add or remove access to Amazon Bedrock foundation models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) . For more information about obtaining sufficient Amazon Bedrock capacity, see [Amazon Bedrock capacity for built-in with overrides strategies](bedrock-capacity.md).
The following table shows the steps you can override for each memory strategy:
| Strategy | Steps you can override |
| --- | --- |
| Semantic | Extraction Consolidation |
| Summary | Consolidation |
| User preference | Extraction Consolidation |
| Episodic | Extraction Consolidation Reflection |
**Note**
You can also override with a self-managed strategy. For more information, see [Self-managed strategy](memory-self-managed-strategies.md).
## How to customize a strategy
For example, you can modify the extraction instruction for semantic memory strategy to add new instructions when customizing it.
**Built-in semantic memory strategy instructions**
The following shows the built-in instructions for the semantic memory strategy:
```
You are a long-term memory extraction agent supporting a lifelong learning system. Your
task is to identify and extract meaningful information about the users from a given
list of messages.
Analyze the conversation and extract structured information about the user according to
the schema below. Only include details that are explicitly stated or can be logically
inferred from the conversation.
- Extract information ONLY from the user messages. You should use assistant messages
only as supporting context.
- If the conversation contains no relevant or noteworthy information, return an empty
list.
- Do NOT extract anything from prior conversation history, even if provided. Use it
solely for context.
- Do NOT incorporate external knowledge.
- Avoid duplicate extractions.
IMPORTANT: Maintain the original language of the user's conversation. If the user
communicates in a specific language, extract and format the extracted information
in that same language.
```
You could append a new rule to these instructions, such as:
```
- Focus exclusively on extracting facts related to travel and booking preferences.
```
or edit an existing rule such as:
```
IMPORTANT: Always extract memories in English irrespective of the original language of the user's conversation.
```
## Best practices for customization
+ **Build upon existing instructions:** We strongly recommend you use the built-in strategies instructions as a starting point. The base structure and instructions are critical to the memory functionality. You should add your task-specific guidance to the existing instructions rather than writing entirely new ones from scratch.
+ **Provide clear instructions:** The content of `appendToPrompt` replaces the default instructions in the system prompt. Make sure your instructions are logical and complete, as empty or poorly formed instructions can lead to undesirable results.
## Important considerations
To maintain the reliability of the memory pipeline, please adhere to the following guidelines:
+ **Do not modify schemas in prompts:** You should only add or modify instructions that guide *how* memories are extracted or consolidated. Do not attempt to alter the conversation or memory schema definitions within the prompt itself, as this can cause unexpected failures.
+ **Do not rename consolidation operations:** When customizing a consolidation prompt, do not change the operation names (e.g., `AddMemory` , `UpdateMemory` ). Altering these names will cause the long-term memory pipeline to fail.
+ **Output schema is not editable:** built-in with overrides strategies do not let you change the final output schema of the extracted or consolidated memory. The output schema that will be added to the system prompt for the built-in with overrides strategy will be same as the built-in strategies. For information about the output schemas, see the following:
+ [System prompt for semantic memory strategy](memory-system-prompt.md)
+ [System prompt for user preference memory strategy](memory-user-prompt.md)
+ [System prompt for summary strategy](memory-summary-prompt.md)
For full control over the end-to-end memory process, including the output schema, see [Self-managed strategy](memory-self-managed-strategies.md).
## Execution role
When using built-in with overrides strategies you are also required to provide a `memoryExecutionRoleArn` in the `CreateMemory` API. Bedrock Amazon Bedrock AgentCore will assume this role to call the bedrock models in your AWS account for extraction and consolidation.
**Note**
When using built-in with overrides strategies, the LLM usage for extraction and consolidation will be charged separately to your AWS account, and additional charges may apply.
# Self-managed strategy
A self-managed strategy in Amazon Bedrock AgentCore Memory gives you complete control over your memory extraction and consolidation pipelines. With a self-managed strategy, you can build custom memory processing workflows while leveraging Amazon Bedrock AgentCore for storage and retrieval.
A self-managed strategy in combination with the batch operations ( [BatchCreateMemoryRecords](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_BatchCreateMemoryRecords.html) , [BatchUpdateMemoryRecords](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_BatchUpdateMemoryRecords.html) , [BatchDeleteMemoryRecords](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_BatchDeleteMemoryRecords.html) ), let you directly ingest these extracted records into Amazon Bedrock AgentCore memory for search capabilities.
With self-managed strategies, you can:
+ Control pipeline invocation through configurable triggers
+ Integrate with external processing systems
+ Implement custom extraction and consolidation algorithms
+ Invoke any preferred model for extraction and consolidation
+ Define custom memory record schemas, namespaces, and so on.
+ Ingest extracted records into Amazon Bedrock AgentCore long term memory
**Topics**
+ [
## Create and use a self-managed strategy
](#use-self-managed-strategy)
+ [
## Prerequisites
](#prerequisites)
+ [
## Set up the infrastructure
](#setting-up-infrastructure)
+ [
## Create a self-managed strategy
](#creating-self-managed-strategy)
+ [
## Understanding payload delivery
](#understanding-payload-delivery)
+ [
## Build your custom pipeline
](#building-custom-pipeline)
+ [
## Test your implementation
](#testing-implementation)
+ [
## Best practices
](#best-practices)
## Create and use a self-managed strategy
Self-managed strategies follow a five-step process from trigger configuration to memory record storage.
1. **Configure triggers** : Define trigger conditions (message count, idle timeout, token count) that invoke your pipeline based on short-term memory events
1. **Receive notifications and payload delivery** : Amazon Bedrock AgentCore publishes notifications to your SNS topic and delivers conversation data to your S3 bucket when trigger conditions are met
1. **Extract memory records** : Your custom pipeline retrieves the payload and applies extraction logic to identify relevant memories
1. **Consolidate memory records** : Process extracted memories to remove duplicates and resolve conflicts with existing records
1. **Store memory records** : Use batch APIs to store processed memory records back into Amazon Bedrock AgentCore long-term memory
## Prerequisites
Before setting up self-managed strategies, verify you have:
+ An AWS account with appropriate permissions
+ Amazon Bedrock AgentCore access
+ Basic understanding of AWS IAM, Amazon S3, and Amazon SNS
## Set up the infrastructure
Create the required AWS resources including S3 bucket, SNS topic, and IAM role that Amazon Bedrock AgentCore needs to access your resources.
### Step 1: Create an S3 bucket
Create an S3 bucket in your account where Amazon Bedrock AgentCore will deliver batched event payloads.
**Important**
Configure a lifecycle policy to automatically delete objects after processing to control costs.
### Step 2: Create an SNS topic
Create an SNS topic for job notifications. Use FIFO topics if processing order within sessions is important for your use case.
### Step 3: Create an IAM role
Create an IAM role that Amazon Bedrock AgentCore can assume to access your resources.
**Trust policy**
Use the following trust policy:
```
{
"Version": "2012-10-17 ",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "bedrock-agentcore.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
**Permissions policy**
Use the following permissions policy:
```
{
"Version": "2012-10-17 ",
"Statement": [
{
"Sid": "S3PayloadDelivery",
"Effect": "Allow",
"Action": [
"s3:GetBucketLocation",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::your-agentcore-payloads-bucket",
"arn:aws:s3:::your-agentcore-payloads-bucket/*"
]
},
{
"Sid": "SNSNotifications",
"Effect": "Allow",
"Action": [
"sns:GetTopicAttributes",
"sns:Publish"
],
"Resource": "arn:aws:sns:us-east-1:123456789012:agentcore-memory-jobs"
}
]
}
```
**Additional KMS permissions (if using encrypted resources)**
If you use encrypted resources, add the following KMS permissions:
```
{
"Sid": "KMSPermissions",
"Effect": "Allow",
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "arn:aws:kms:us-east-1:123456789012:key/your-key-id"
}
```
## Create a self-managed strategy
Use the Amazon Bedrock AgentCore control plane APIs to create or update an AgentCore Memory with self-managed strategies.
### Required permissions
Your IAM user or role needs:
+ bedrock-agentcore:\$1 permissions
+ `iam:PassRole` permission for the execution role
### Create an AgentCore Memory with a self-managed strategy
Use the AWS SDK `CreateMemory` operation to create AgentCore Memory that has a self-managed strategy.
```
aws bedrock-agentcore-control create-memory \
--name "MyCustomMemory" \
--description "Memory with self-managed extraction strategy" \
--memory-execution-role-arn "arn:aws:iam::123456789012:role/AgentCoreMemoryRole" \
--event-expiry-duration 90 \
--memory-strategies '[
{
"customMemoryStrategy": {
"name": "SelfManagedExtraction",
"description": "Custom extraction strategy",
"configuration": {
"selfManagedConfiguration": {
"triggerConditions": [
{
"messageBasedTrigger": {
"messageCount": 6
}
},
{
"tokenBasedTrigger": {
"tokenCount": 1000
}
},
{
"timeBasedTrigger": {
"idleSessionTimeout": 30
}
}
],
"historicalContextWindowSize": 2,
"invocationConfiguration": {
"payloadDeliveryBucketName": "your-agentcore-payloads-bucket",
"topicArn": "arn:aws:sns:us-east-1:123456789012:agentcore-memory-jobs"
}
}
}
}
}
]'
```
## Understanding payload delivery
When trigger conditions are met, Amazon Bedrock AgentCore sends notifications and payloads using specific schemas.
### SNS notification message
```
{
"jobId": "unique-job-identifier",
"s3PayloadLocation": "s3://bucket/path/to/payload.json",
"memoryId": "your-memory-id",
"strategyId": "your-strategy-id"
}
```
### S3 payload structure
```
{
"requestId": "request-identifier",
"accountId": "123456789012",
"memoryId": "your-memory-id",
"actorId": "user-or-agent-id",
"sessionId": "conversation-session-id",
"strategyId": "your-strategy-id",
"startingTimestamp": 1634567890,
"endingTimestamp": 1634567920,
"currentContext": [
{
"role": "USER",
"content": {
"text": "User message content"
}
},
{
"role": "ASSISTANT",
"content": {
"text": "Assistant response"
}
}
],
"historicalContext": [
{
"role": "USER",
"content": {
"text": "User message content"
}
},
{
"role": "ASSISTANT",
"content": {
"text": "Previous assistant response"
}
},
{
"blob": "{}",
}
]
}
```
## Build your custom pipeline
This section demonstrates one approach to building a self-managed memory processing pipeline using AWS Lambda and SQS. This is just one example - you can implement your pipeline using any compute platform (EC2, ECS, Fargate), logic and processing framework that meets your requirements.
### Step 1: Set up compute
1. Create an SQS queue and subscribe it to your SNS topic
1. Create an AWS Lambda function to process notifications
1. Configure Lambda execution role permissions
### Step 2: Process the pipeline
The following example pipeline consists of four main components:
1. Notification handling - Processing SNS notifications and downloading S3 payloads
1. Memory extraction - Using bedrock models to extract relevant information from conversations
1. Memory consolidation - Deduplicating and merging extracted memories with existing records
1. Batch ingestion - Storing processed memories back into Amazon Bedrock AgentCore using batch APIs
## Test your implementation
1. **Create events** : Use the Amazon Bedrock AgentCore APIs to create conversation events ( `CreateEvent` )
1. **Monitor notifications** : Verify that your SNS topic receives notifications when triggers are met
1. **Validate processing** : Check that your Lambda function processes payloads correctly and extracts memory records
1. **Verify ingestion** : Use `list-memory-records` to confirm extracted memories are stored
### Example: Creating test events
```
aws bedrock-agentcore create-event \
--memory-id "your-memory-id" \
--actor-id "test-user" \
--session-id "test-session-1" \
--event-timestamp "2024-01-15T10:00:00Z" \
--payload '[{
"conversational": {
"content": {"text": "I prefer Italian restaurants with outdoor seating"},
"role": "USER"
}
}]'
```
### Example: Retrieving memory records
```
# List records by namespace
aws bedrock-agentcore list-memory-records \
--memory-id "your-memory-id" \
--namespace "/" # lists all records that match the namespace prefix
```
## Best practices
Follow these best practices for performance, reliability, cost optimization, and security when implementing self-managed strategies.
### Performance and reliability
+ **SLA sharing** : Long-term memory record generation SLA is shared between Amazon Bedrock AgentCore and your self-managed pipeline
+ **Error handling** : Implement proper retry logic and dead letter queues for failed processing
+ **Monitoring** : Set up CloudWatch logs, metrics, alarms for debugging and processing failures and latency. Also, check vended logs from Amazon Bedrock AgentCore for payload delivery failures
### Cost optimization
+ **S3 lifecycle policies** : Configure automatic deletion of processed payloads to control storage costs
+ **Right-sizing** : Choose appropriate compute memory and timeout settings based on your processing requirements
### Processing considerations
+ **Trigger optimization** : Configure trigger conditions based on your use case requirements - balance between processing efficiency and memory freshness by considering your application’s tolerance for latency versus processing costs.
+ **FIFO topics** : Use FIFO SNS topics when session ordering is critical (e.g., for summarization workflows)
+ **Memory consolidation** : Implement deduplication logic to prevent storing redundant or conflicting memory records, which reduces storage costs and improves retrieval accuracy
+ **Memory record organization** : Always include meaningful namespaces and strategy IDs when ingesting records to enable efficient categorization, filtering, and retrieval of memory records
### Security
+ **Least privilege** : Grant minimal required permissions to all IAM roles
+ **Encryption** : Use KMS encryption for S3 buckets and SNS topics containing sensitive data
# Memory organization in AgentCore Memory
You can set how short-term and long-term memories are organized in an AgentCore Memory. This lets you isolate memories by session and by actor. For long-term memory, you can also set a namespace to organize the extracted memories for a memory strategy.
+ **Actor** – Refers to entities such as end users or agent/user combinations. For example, in a coding support chatbot, the actor is usually the developer asking questions. Using the actor ID helps the system know which user the memory belongs to, keeping each user’s data separate and organized.
+ **Session** – A single conversation or interaction period between the user and the AI agent. It groups all related messages and events that happen during that conversation.
+ **Strategy** (Long-term memory only) – Shows which long-term memory strategy is being used. This strategy identifier is auto-generated when you [create](memory-create-a-memory-store.md) an AgentCore Memory.
## Short-term memory organization
When you create a short term memory event with [CreateEvent](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CreateEvent.html) , you specify a session ID ( `sessionId` ) and an actor ID ( `actorId` ) that uniquely identify the session and actor for the event. Later, you can retrieve events for a user or session by using [short-term memory operations](using-memory-short-term.md).
For example code, see [Step 3: Capture the conversation history](memory-customer-scenario.md#capture-conversation).
## Long-term memory organization
When you [create](memory-create-a-memory-store.md) or update an AgentCore Memory, you can optionally create one or more [memory strategies](memory-strategies.md) . Within a strategy, use a namespace to specify AgentCore Memory organizes [long-term memories](memory-types.md#memory-long-term-memory).
Every time AgentCore Memory extracts a new long-term memory with a memory strategy, the long-term memory is saved under the namespace you set. This means that all long-term memories are scoped to their specific namespace, keeping them organized and preventing any conflicts with other users or sessions. You should use a hierarchical format separated by forward slashes `/` , ending with a trailing slash. The trailing slash prevents prefix collisions in multi-tenant applications—for example, use `/actors/Alice/` instead of `/actors/Alice` . As needed, you can use the following pre-defined variables within braces in the namespace based on your application’s organization needs:
+ **actorId** – Identifies who the long-term memory belongs to.
+ **strategyId** – Shows which memory strategy is being used.
+ **sessionId** – Identifies which session or conversation the memory is from.
For example, if you define the following namespace as the input to your strategy when creating an AgentCore Memory:
```
/strategy/{memoryStrategyId}/actor/{actorId}/session/{sessionId}/
```
After memory creation, this namespace might look like:
```
/strategy/summarization-93483043/actor/actor-9830m2w3/session/session-9330sds8/
```
A namespace can have different levels of granularity:
**Most granular Level of organization**
`/strategy/{memoryStrategyId}/actor/{actorId}/session/{sessionId}/`
**Granular at the actor Level across sessions**
`/strategy/{memoryStrategyId}/actor/{actorId}/`
**Granular at the strategy Level across actors**
`/strategy/{memoryStrategyId}/`
**Global across all strategies**
`/`
For example code, see [Enable long-term memory](long-term-enabling-long-term-memory.md).
### Restrict access with IAM
You can create IAM policies to restrict memory access by the scopes you define, such as actor, session, and namespace. Use the scopes as context keys in your IAM polices.
The following policy restricts access to retrieving memories to a specific namespace prefix. In this example, the policy allows access only to memories in namespaces starting with `summaries/agent1/` , such as `summaries/agent1/session1/` or `summaries/agent1/session2/`.
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SpecificNamespaceAccess",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:RetrieveMemoryRecords"
],
"Resource": "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/memory_id",
"Condition": {
"StringLike": {
"bedrock-agentcore:namespace": "summaries/agent1/"
}
}
}
]
}
```
# Memory record streaming
Memory record streaming in Amazon Bedrock AgentCore Memory delivers real-time notifications when memory records are created, updated, or deleted. Instead of polling APIs to detect changes, you receive push-based events to a Kinesis Data Stream in your account, enabling event-driven architectures that react to memory record lifecycle changes as they occur.
With memory record streaming, you can:
+ Receive real-time events for memory record creation, updates, and deletion
+ Build event-driven architectures without polling APIs
+ Stream memory record data into data lakes for consolidation and profile management
+ Trigger downstream workflows when new insights are extracted
+ Track memory record state changes across agents and sessions
**Topics**
+ [
## How it works
](#memory-record-streaming-how-it-works)
+ [
## Stream event types
](#memory-record-streaming-event-types)
+ [
## Event schema
](#memory-record-streaming-event-schema)
+ [
## Prerequisites
](#memory-record-streaming-prerequisites)
+ [
## Set up streaming
](#memory-record-streaming-setup)
+ [
## Configure event content level
](#memory-record-streaming-content-level)
+ [
## Test your implementation
](#memory-record-streaming-test)
+ [
## Manage streaming configuration
](#memory-record-streaming-manage)
+ [
## Observability
](#memory-record-streaming-observability)
## How it works
Memory record streaming uses a push-based delivery model. When memory records change, events are automatically published to your Kinesis Data Stream.
Events are triggered by the following operations:
1. **Creation** – Asynchronous extraction from short-term memory events (via `CreateEvent` and memory strategies), or direct creation via `BatchCreateMemoryRecords` API
1. **Updates** – Direct modification via `BatchUpdateMemoryRecords` API
1. **Deletion** – Consolidation workflows (de-duplication/superseding), `DeleteMemoryRecord` API, or `BatchDeleteMemoryRecords` API
## Stream event types
The following table describes the supported stream event types and when they are triggered.
| Operation | Stream event type | Triggered by |
| --- | --- | --- |
| Create | `MemoryRecordCreated` | Long term memory extraction/consolidation, `BatchCreateMemoryRecords` API |
| Update | `MemoryRecordUpdated` | `BatchUpdateMemoryRecords` API |
| Delete | `MemoryRecordDeleted` | `BatchDeleteMemoryRecords` , `DeleteMemoryRecord` API, long term memory consolidation |
## Event schema
### MemoryRecordCreated / MemoryRecordUpdated
`MemoryRecordCreated` and `MemoryRecordUpdated` events share the same schema.
```
{
"memoryStreamEvent": {
"eventType": "",
"eventTime": "2026-03-06T16:45:00.000Z",
"memoryId": "",
"memoryRecordId": "",
"namespaces": [""],
"createdAt": 1736622300000,
"memoryStrategyId": "",
"memoryStrategyType": "",
"metadata": {},
"memoryRecordText": ""
}
}
```
The `memoryRecordText` field is only included when the content level on the stream delivery configuration is set to `FULL_CONTENT` . See [Configure event content level](#memory-record-streaming-content-level) for additional details.
### MemoryRecordDeleted
```
{
"memoryStreamEvent": {
"eventType": "MemoryRecordDeleted",
"eventTime": "2026-02-16T00:13:54.912530116Z",
"memoryId": "",
"memoryRecordId": ""
}
}
```
Deletion events contain only the memory and record identifiers, regardless of the configured content level.
## Prerequisites
Before setting up memory record streaming, verify you have:
+ An AWS account with appropriate permissions
+ Amazon Bedrock AgentCore access
+ Basic understanding of AWS IAM and Amazon Kinesis Data Streams
## Set up streaming
### Step 1: Create a Kinesis Data Stream
Create a Kinesis Data Stream in your account where Amazon Bedrock AgentCore will publish memory record lifecycle events.
You can create the stream using the AWS Console, CDK, CloudFormation, or the AWS CLI. If you enable Kinesis server-side encryption, note the KMS key ARN — you’ll need it for the IAM role permissions.
### Step 2: Set up a consumer
Set up a consumer to process events from your Kinesis Data Stream.
Grant your consumer `AmazonKinesisReadOnlyAccess` (or equivalent permissions) and add the Kinesis Data Stream as a trigger.
### Step 3: Create an IAM role
Create an IAM role that Amazon Bedrock AgentCore can assume to publish events to your Kinesis Data Stream.
Trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "bedrock-agentcore.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
Permissions policy:
For built-in memory strategies, the permissions policy looks like the following:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kinesis:PutRecords",
"kinesis:DescribeStream"
],
"Resource": "arn:aws:kinesis:::stream/"
}
]
}
```
For custom memory strategies, the permissions policy looks like the following:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kinesis:PutRecords",
"kinesis:DescribeStream"
],
"Resource": "arn:aws:kinesis:::stream/"
},
{
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel",
"bedrock:InvokeModelWithResponseStream"
],
"Resource": [
"arn:aws:bedrock:*::foundation-model/*",
"arn:aws:bedrock:*:*:inference-profile/*"
],
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "${aws:PrincipalAccount}"
}
}
}
]
}
```
If your Kinesis Data Stream uses server-side encryption, add the following to the permissions policy:
```
{
"Sid": "KMSPermissions",
"Effect": "Allow",
"Action": "kms:GenerateDataKey",
"Resource": "arn:aws:kms:::key/your-kinesis-data-stream-key-id"
}
```
### Step 4: Create a memory with streaming enabled
Use the `CreateMemory` API to create an Amazon Bedrock AgentCore Memory with a stream delivery resource. You must provide the `memoryExecutionRoleArn` when specifying a stream delivery resource.
```
aws bedrock-agentcore-control create-memory \
--name "MyStreamingMemory" \
--description "Memory with long term memory record streaming enabled" \
--event-expiry-duration 30 \
--memory-execution-role-arn "arn:aws:iam:::role/AgentCoreMemoryRole" \
--stream-delivery-resources '{
"resources": [
{
"kinesis": {
"dataStreamArn": "arn:aws:kinesis:::stream/",
"contentConfigurations": [
{
"type": "MEMORY_RECORDS",
"level": "FULL_CONTENT"
}
]
}
}
]
}'
```
### Step 5: Verify your streaming integration
When you create a memory with streaming enabled, Amazon Bedrock AgentCore Memory validates the configuration and permissions. Upon successful validation, a `StreamingEnabled` event is published to your Kinesis Data Stream.
Check your consumer for a validation event in the following format:
```
{
"memoryStreamEvent": {
"eventType": "StreamingEnabled",
"eventTime": "2026-03-03T19:27:08.344082626Z",
"memoryId": "",
"message": "Streaming enabled for memory resource: "
}
}
```
## Configure event content level
The `contentConfigurations` field controls what data is included in each event. You can choose between two content levels:
+ **METADATA\$1ONLY** : Stream events only include metadata fields ( `memoryId` , `memoryRecordId` , `namespaces` , `strategyId` , timestamps, and so on). Requires an API call to retrieve the full memory record content.
+ **FULL\$1CONTENT** : Stream events include all metadata fields plus the `memoryRecordText` field containing the memory record content.
Use `METADATA_ONLY` for lightweight event notifications where you only need to know that a change occurred. Use `FULL_CONTENT` when your downstream processing needs the memory record text without making additional API calls.
## Test your implementation
### Step 1: Create test events
Use the Data Plane APIs to generate memory record lifecycle events and verify they appear in your consumer.
Create events via short-term memory (triggers asynchronous extraction):
```
aws bedrock-agentcore create-event \
--memory-id "" \
--actor-id "test-user" \
--session-id "test-session-1" \
--event-timestamp "$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ")" \
--payload '[
{
"conversational": {
"content": {"text": "I prefer Italian restaurants with outdoor seating"},
"role": "USER"
}
},
{
"conversational": {
"content": {"text": "Noted! I will remember your preference for Italian restaurants with outdoor seating."},
"role": "ASSISTANT"
}
}
]'
```
Create records directly:
```
aws bedrock-agentcore batch-create-memory-records \
--memory-id "" \
--records '[
{
"requestIdentifier": "test-1",
"content": {"text": "User prefers window seats on flights"},
"namespaces": ["travel/test-user"],
"timestamp": "1729525989"
}
]'
```
### Step 2: Verify delivery
Check your consumer to confirm events are being received. You should see `MemoryRecordCreated` events for records created through either method.
You can also monitor delivery health using [Metrics](#memory-record-streaming-metrics) and [Logs](#memory-record-streaming-logs).
You can use the `ListMemoryRecords` API to cross-reference:
```
aws bedrock-agentcore list-memory-records \
--memory-id "" \
--namespace ""
```
## Manage streaming configuration
### Update streaming configuration
Use the `UpdateMemory` API to modify or remove the stream delivery resource.
Remove streaming:
```
aws bedrock-agentcore-control update-memory \
--region us-east-1 \
--memory-id "" \
--stream-delivery-resources '{"resources": []}'
```
### Change content level
```
aws bedrock-agentcore-control update-memory \
--memory-id "" \
--stream-delivery-resources '{
"resources": [
{
"kinesis": {
"dataStreamArn": "arn:aws:kinesis:us-east-1::stream/",
"contentConfigurations": [
{
"type": "MEMORY_RECORDS",
"level": "METADATA_ONLY"
}
]
}
}
]
}'
```
## Observability
Amazon Bedrock AgentCore Memory vends CloudWatch metrics and logs to your AWS account, giving you visibility into the health and status of memory record stream delivery.
### Metrics
Metrics are published to your account under the `AWS/Bedrock-AgentCore` namespace.
| Metric | Description |
| --- | --- |
| `StreamPublishingSuccess` | The number of memory record events successfully published to your Kinesis Data Stream. |
| `StreamPublishingFailure` | The number of memory record events that failed to publish to your Kinesis Data Stream. |
| `StreamUserError` | The number of events that failed due to customer-side configuration issues, such as missing IAM permissions or an invalid KMS key state. |
All metrics are emitted as `Count` units with the following dimensions:
| Dimension | Value | Description |
| --- | --- | --- |
| Operation | `MemoryStreamEvent` | The streaming operation type. |
| Resource | Memory ARN | The ARN of the memory resource (for example, `arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/memory-123` ). |
### Logs
Amazon Bedrock AgentCore Memory vends logs to your account when terminal (non-retryable) publishing failures occur.
| Field | Description |
| --- | --- |
| `log` | Error message describing the failure. |
| `streamArn` | The target Kinesis Data Stream ARN. |
| `errorCode` | The specific error code. |
| `errorMessage` | A human-readable description of the error. |
| `eventType` | The stream event type ( `MemoryRecordCreated` , `MemoryRecordUpdated` , or `MemoryRecordDeleted` ). |
| `memoryRecordId` | The identifier of the affected memory record. |
# Compare long-term memory with Retrieval-Augmented Generation
[Long-term memory](memory-types.md#memory-long-term-memory) in Amazon Bedrock AgentCore Memory serves as persistent storage for session-specific context, enabling agents to maintain continuity and personalization across interactions. Use long-term memory to store user preferences, past decisions, conversation history, and behavioral patterns that help agents adapt and feel personal without repeatedly requesting the same information. This memory type is ideal for tracking who the user is, what has happened in previous sessions, and maintaining state across multi-step workflows.
Retrieval-Augmented Generation (RAG) complements long-term memory by providing access to authoritative, current information from large-scale repositories. Use these system to retrieve up-to-date documentation, technical specifications, policies, and domain expertise that may be too large or volatile for long-term storage. RAG ensures factual accuracy by pulling directly from curated sources at query time, making it ideal for accessing what authoritative sources say right now. One option for integrating RAG into your agent is to use an Amazon Bedrock Knowledge Base. For more information, see [Retrieve data and generate AI responses with Amazon Bedrock Knowledge Bases](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) in the *Amazon Bedrock user guide*.
The key distinction lies in their complementary roles: long-term memory handles personal context and session continuity, while RAG provides current factual knowledge and domain expertise. Long-term memory answers "who is the user and what happened before," while RAG answers "what do trusted sources say currently." This separation allows agents to maintain personal relationships with users while ensuring access to accurate, authoritative information.
By using long-memory and RAG together, your agent can deliver both personalized experiences through remembered context and reliable information through real- time knowledge retrieval. To your customers, your agents are both familiar and factually grounded.