Memory
The harness automatically persists conversation state in AgentCore Memory. On every invocation, the conversation is saved, scoped by session ID (and additionally by actor ID, if provided). On subsequent invocations with the same session ID, the agent’s history is loaded from Memory before it reasons - it remembers what happened in previous turns, even after the underlying microVM session has expired. You do not need to pass previous messages yourself; just send the new message.
How memory works
-
Short-term memory captures raw events (messages, tool calls) within a session. This is what gives the agent continuity across turns.
-
Long-term memory extracts durable knowledge via configurable strategies (semantic, summarization, user preference, episodic, or custom) and makes them retrievable via semantic search in later sessions.
-
Actor ID identifies the entity interacting with the agent (a user, another agent, or a system). Memory events are scoped by actorId + sessionId, so each actor has isolated memory. Long-term retrieval uses actorId as a template variable in namespace paths (e.g.
/summary/{actorId}/{sessionId}/), mapping to the configured memory strategies.
Managed memory (default)
By default, the harness provisions an AgentCore Memory instance automatically with sensible defaults (semantic + summarization strategies, 30-day event expiry). You don’t need to create or configure anything - memory just works.
To customize the managed memory at create time:
Example
Managed memory is fully managed by the harness:
-
Strategy configuration is controlled through
UpdateHarness. You can still read/write events and query records directly through the Memory APIs. -
Managed memory cannot be deleted directly through the Memory APIs. To turn managed memory into a regular AgentCore memory resource, you can disassociate it from the harness in two ways:
-
Use
UpdateHarnessto switch to BYO (agentCoreMemoryConfiguration) or disabled. -
Pass
deleteManagedMemory=falseon deletion to disassociate instead -DeleteHarnesscascade-deletes the managed memory by default.
-
Available strategies
| Strategy | Description |
|---|---|
|
|
Extracts factual knowledge from conversations, retrievable via semantic search. |
|
|
Creates running summaries of conversations, scoped by actor and session. |
|
|
Captures user preferences and settings expressed during conversations. |
|
|
Records significant events and experiences as discrete episodes. |
Add existing memory (BYO)
If you need advanced configuration beyond what managed memory provides - custom namespace templates, KMS encryption, or shared memory across multiple harnesses - attach an existing AgentCore Memory instance instead.
Example
Disable memory
To disable memory entirely:
aws bedrock-agentcore-control update-harness \ --harness-id "MyHarness-UuFdkQoXSL" \ --memory '{"optionalValue": {"disabled": {}}}'
Per-user memory scoping with actor ID
Pass actorId at invoke time to scope memory to a specific user. Each actor gets isolated short-term and long-term memory:
response = client.invoke_harness( harnessArn=HARNESS_ARN, runtimeSessionId=SESSION_ID, actorId="user-123", messages=[{"role": "user", "content": [{"text": "What do you remember about my preferences?"}]}], )
Long-term memory retrieval
When a harness has active memory strategies (managed or BYO), retrieval works automatically - the harness derives a retrieval configuration from the Memory instance’s active strategies. On each invocation, the agent queries relevant long-term memories and injects them into the conversation context before reasoning.
Default behavior:
-
Retrieval is configured automatically with default parameters (
topK=10,relevanceScore=0.2) for each active strategy’s namespace. -
No manual configuration needed for either managed or BYO memory.
Override the defaults: If you explicitly provide a retrievalConfig in the BYO memory configuration, your values take priority and no automatic derivation occurs. This lets you customize which namespaces are queried, adjust topK or relevanceScore, or disable retrieval for specific strategies.
aws bedrock-agentcore-control update-harness \ --harness-id "MyHarness-UuFdkQoXSL" \ --memory '{"optionalValue": {"agentCoreMemoryConfiguration": {"arn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:memory/MyMemory-abc123", "retrievalConfig": {"/facts/{actorId}/": {"topK": 5, "relevanceScore": 0.5, "strategyId": "FactExtractor-abc123"}}}}}'
Important
If you update your BYO Memory instance’s strategies (add or remove) after attaching it to a harness, call UpdateHarness to refresh the retrieval configuration. For managed memory, strategy changes through UpdateHarness refresh the configuration automatically.
Context truncation
When conversation history grows beyond the model’s context window, the harness applies a truncation strategy. Configure this on the harness or override per invocation.
-
sliding_window(default) - keeps the most recent N messages. Simple and predictable. -
summarization- compresses older messages into a summary, preserving more context in fewer tokens. -
none- no truncation. Use only if you manage context size yourself.
aws bedrock-agentcore-control update-harness \ --harness-id "MyHarness-UuFdkQoXSL" \ --truncation '{"strategy": "sliding_window", "slidingWindowConfig": {"numMessages": 30}}'
Learn more: AgentCore Memory, create a memory store, long-term memory strategies.
Related topics
-
Models and instructions - configure models and system prompts
-
Environment and filesystem - environment, filesystem, and custom containers
-
Skills - attach skills from Git, S3, or AWS Skills
-
Security and access controls - execution role policies for memory access
