How memory works Managed memory Add existing memory (BYO)Disable memory Per-user memory scoping with actor ID Long-term memory retrieval Context truncation Related topics

Memory

When memory is enabled, the harness persists conversation state in AgentCore Memory. On subsequent invocations with the same session ID, the agent loads the stored history before it reasons.

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

When you create a harness directly with the service API and omit the memory configuration, the service provisions managed memory. The AgentCore CLI uses the same default: new CLI harnesses use managed memory unless you pass --memory with the disabled or existing mode.

Memory charges

There is no additional charge for the harness itself. Managed Memory incurs standard AgentCore Memory charges for short-term events, stored long-term memory records, and retrieval requests. To avoid persistent Memory charges, disable Memory when you create the harness. For more information, see Understand harness costs and Amazon Bedrock AgentCore pricing.

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 UpdateHarness to switch to BYO (agentCoreMemoryConfiguration) or disabled.
- Pass deleteManagedMemory=false on deletion to disassociate instead - DeleteHarness cascade-deletes the managed memory by default.

Available strategies

Strategy	Description
`SEMANTIC`	Extracts factual knowledge from conversations, retrievable via semantic search.
`SUMMARIZATION`	Creates running summaries of conversations, scoped by actor and session.
`USER_PREFERENCE`	Captures user preferences and settings expressed during conversations.
`EPISODIC`	Records significant events and experiences as discrete episodes.

Add existing memory (BYO)

If you need configuration that managed memory does not provide, such as custom namespace templates or one memory shared by multiple harnesses, attach an existing AgentCore Memory instance instead. Managed memory already accepts encryptionKeyArn for a customer-managed KMS key. You cannot change the key after creation.

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-abc1234567", "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", "config": {"slidingWindow": {"messagesCount": 30}}}'

Learn more: AgentCore Memory, create a memory store, long-term memory strategies.