Persist memory and filesystem

The harness persists state at two layers: conversation state in AgentCore Memory, and file state on the agent’s filesystem.

Memory. Attach an AgentCore Memory instance to the harness and every invocation saves the conversation automatically, 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, so 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.

Short-term memory captures raw events (messages, tool calls) within a session.
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.

Filesystem. If enabled, each session runs in a Firecracker microVM with a working filesystem. Files written during a session persist through the session’s lifetime. For state that needs to outlast a single session, mount S3-backed storage through AgentCore Runtime persistent filesystems.

Add memory

Example

AgentCore CLI

When you create a harness with agentcore create, long-term memory is enabled by default — the CLI creates a memory resource and wires it to the harness automatically. To skip it, pass --no-harness-memory:


# Create with memory (default)
agentcore create --name myagent

# Create without memory
agentcore create --name myagent --no-harness-memory

After creation, deploy to provision the memory resource:


agentcore deploy

To scope memory to a specific user, pass --actor-id at invoke time. Each actor gets isolated memory — the agent remembers that user’s context even across different sessions:


# Session 1: user Alice asks a question
agentcore invoke --harness research-agent \
  --session-id "$(uuidgen)" \
  --actor-id alice \
  "Research tropical vacations under $3k"

# Session 2 (new session): Alice's memory carries over
agentcore invoke --harness research-agent \
  --session-id "$(uuidgen)" \
  --actor-id alice \
  "What did we decide about the Portugal option?"

Continue a conversation within the same session by reusing the same session ID:


SESSION_ID="$(uuidgen)"
agentcore invoke --harness research-agent \
  --session-id "$SESSION_ID" \
  "Research tropical vacations under $3k"
agentcore invoke --harness research-agent \
  --session-id "$SESSION_ID" \
  "What did we decide about the Portugal option?"

AWS CLI/boto3

Create a memory instance:


aws bedrock-agentcore-control create-memory \
  --name "MyMemory" \
  --event-expiry-duration 30 \
  --description "Memory for my harness"

Attach it to the harness:


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"}}}'

Reuse the same runtimeSessionId across invocations and the agent recalls prior turns from Memory, even after the microVM session expires.

To scope memory to a specific user, pass actorId at invoke time:


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?"}]}],
)

The actorId determines whose memory is loaded. Long-term memory strategies (semantic, summarization, etc.) use the actorId to scope extracted knowledge - each actor gets their own isolated memory namespace. For more details on configuring long-term memory, see configuring long-term memory strategies.

Filesystem

Mount S3-backed persistent storage that survives session termination. Files written to the mount path persist across session restarts when using the same runtimeSessionId.

Example

Learn more: AgentCore Memory, create a memory store, long-term memory strategies, persistent filesystems on Runtime.

Persist memory and filesystem

Add memory

Example

Filesystem

Example

Related topics