# Episodic memory strategy
<a name="episodic-memory-strategy"></a>

 **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
<a name="episodic-memory-strategy-namespaces"></a>

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
<a name="memory-episodic-retrieve-episodes"></a>

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
<a name="memory-episodic-prompt"></a>

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
<a name="episode-extraction-instructions"></a>

```
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 <conversation></conversation> tags
- Each turn will be marked with <turn_[id]></turn_[id]> 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 <previous_[k]_turns></previous_[k]_turns> 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
<a name="episode-extraction-output-schema"></a>

```
You MUST provide a separate <summary> block for EACH conversation turn. Number them sequentially:

<summary>
<summary_turn>
<turn_id>
The id of the turn that matches the input, e.g. 0, 1, 2, etc.
</turn_id>
<situation>
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
</situation>
<intent>
The assistant's primary goal for this specific interaction—what the assistant aimed to accomplish in this turn
</intent>
<action>
Briefly describe which actions were taken or specific tools were used, what input arguments or parameters were provided to each tool.
</action>
<thought>
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
</thought>
<assessment_assistant>
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
</assessment_assistant>
<assessment_user>
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.
</assessment_user>
</summary_turn>

<summary_turn>
<turn_id>...</turn_id>
<situation>...</situation>
<intent>...</intent>
<action>...</action>
<thought>...</thought>
<assessment_assistant>...</assessment_assistant>
<assessment_user>...</assessment_user>
</summary_turn>

... continue for all turns ...

<summary_turn>
<turn_id>...</turn_id>
<situation>...</situation>
<intent>...</intent>
<action>...</action>
<thought>...</thought>
<assessment_assistant>...</assessment_assistant>
<assessment_user>...</assessment_user>
</summary_turn>
</summary>

Attention: Only output 1-2 sentences for each field. Be concise and avoid lengthy explanations.
Make sure the number of <summary_turn> is the same as the number of turns in the conversation.<
```

## Episode consolidation instructions
<a name="episode-generation-instructions"></a>

```
You are an expert conversation analyst. Your task is to analyze and summarize conversations between a user and an AI assistant provided within <conversation_turns></conversation_turns> 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
<a name="episode-generation-output-schema"></a>

```
# Output Format:

Provide your analysis using the following structured XML format:
<summary>
<situation>
Brief description of the context and circumstances that prompted this conversation—what led the user to seek assistance at this moment
</situation>
<intent>
The user's primary goal, the specific problem they wanted to solve, or the concrete outcome they sought to achieve
</intent>
<assessment>
[Yes/No] — Whether the user's goal was successfully achieved
</assessment>
<justification>
Brief justification for your assessment based on key moments from the conversation
</justification>
<reflection>
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>
</summary>
```

## Reflection generation instructions
<a name="reflection-generation-instructions"></a>

```
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 <id> 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 <id> 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
<a name="reflection-generation-output-schema"></a>

```
<attention>
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.
</attention>

# Output Format:

<reflections>
<reflection>
<operator>[add or update]</operator>
<id>[ID of existing reflection being expanded - only include this field if operator is "update"]</id>
<title>[Clear, descriptive title - keep same/similar to original when updating]</title>
<use_cases>
[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]
</use_cases>
<hints>
[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]
</hints>
<confidence>[0.1 to 1.0]</confidence>
</reflection>
</reflections>
```