Memory Fundamentals

A foundation model has no memory. Each call to it is a clean slate — the model sees only what you put in the prompt for that invocation and nothing from the last one. The illusion of a conversation that "remembers" is something you construct by replaying prior turns back into the context window on every call. Do nothing, and your agent greets a returning user as a stranger.

Naively, you solve this by hand: stand up a database, serialize turns, write retrieval queries, and — for anything smarter than a transcript replay — run your own extraction jobs to distill durable facts ("the user is vegetarian", "their account ID is 456") out of raw chat. That is real infrastructure to build, secure, and operate.

AgentCore Memory is the managed answer to agent statelessness. It is a fully managed service that gives agents the ability to remember past interactions for context-aware, personalized conversations. Two properties make it broadly usable:

• Framework-agnostic and model-agnostic — it is plain API/SDK calls, so it works whether your agent runs on Strands, LangGraph, CrewAI, or bare boto3, and regardless of which model you call.
• Consumed via two API planes — a control plane for managing the memory resource and a data plane for reading and writing memory at runtime (covered below).

Crucially, Memory does not run inside your agent the way a library would. It is a separate AWS resource your code talks to over the network — which is exactly why it survives a session ending, a microVM being torn down, or a deploy that replaces your Runtime.

Like Runtime, Memory splits cleanly into a control plane (manage the resource) and a data plane (use it at runtime). The boto3 client names are different, and getting them wrong is a common first error.

A clean way to remember it: you create a memory resource once (control plane, an admin/deploy-time action), then your agent writes and reads against it on every turn (data plane, the hot path).

import boto3

# Control plane — manage the memory resource (admin / deploy-time)
control = boto3.client("bedrock-agentcore-control")

# Data plane — write/read memory at runtime (the hot path)
data = boto3.client("bedrock-agentcore")

The Python SDK gives you a higher-level wrapper, bedrock_agentcore.memory.MemoryClient, that wraps both planes behind one object so you are not juggling two clients. We use raw boto3 here to make the plane split explicit; later lessons in this module use the SDK.

from bedrock_agentcore.memory import MemoryClient

client = MemoryClient(region_name="us-east-1")  # spans control + data planes

Memory holds two fundamentally different kinds of data. Internalizing the difference is the single most important takeaway of this lesson.

Short-term memory is the turn-by-turn record of raw interaction events within a session. Properties:

• Raw — what was actually said, not a derived insight.
• Synchronous — written immediately; once CreateEvent returns, the event is there.
• Immutable — events are not edited in place.
• Scoped by actorId + sessionId — a given actor's events live under a given session.
• Written via CreateEvent; read via ListEvents or the SDK helper get_last_k_turns.

Long-term memory is the set of insights the service automatically extracts across sessions — preferences, facts, per-session summaries, episodes. Properties:

• Derived — these are memory records, not raw turns.
• Asynchronous — produced by a background pipeline after you write events, not on the spot.
• Cross-session — the whole point is to carry knowledge from one session into the next.
• Produced only by configured memory strategies and organized by namespace.
• Retrieved via RetrieveMemoryRecords (data plane) / the SDK's retrieve_memories.

A mental model that keeps these straight:

  create_event(...)          short-term: raw turns you WRITE  (synchronous)
        |
        |  async extraction pipeline (only if strategies attached)
        v
  retrieve_memory_records()  long-term: insights the SERVICE extracts (eventual)

Short-term is the transcript; long-term is what the agent learned from transcripts over time.

Because long-term extraction runs asynchronously, there is a delay between writing an event and being able to retrieve the insight derived from it. Write a turn, immediately call retrieve_memory_records, and you will often get nothing back — the extraction pipeline simply has not run yet. Engineers new to Memory routinely misread this as a bug.

As of writing, extraction typically lands in roughly 20-40 seconds (a [VOLATILE] figure — episodic strategies can take longer, and you should verify against the live docs rather than treat this as a contract). Retrieval latency itself is fast (on the order of a few hundred milliseconds, also a [VOLATILE] figure), so the lag you observe is extraction time, not query time.

The practical consequence is that you must design for eventual consistency. Two patterns:

import time

# Write a turn (short-term, synchronous — available immediately)
data.create_event(
    memoryId="mem-123",
    actorId="customer-456",
    sessionId="session-789",
    payload=[{"conversational": {"content": {"text": "I'm vegetarian"}, "role": "USER"}}],
)

# DON'T expect the extracted long-term record to exist yet:
recs = data.retrieve_memory_records(
    memoryId="mem-123",
    namespace="/customer-support/customer-456/preferences/",
    searchCriteria={"searchQuery": "dietary preference", "topK": 5},
)
# recs may be empty here — extraction hasn't run

1. Don't gate the current turn on freshly extracted long-term memory. Within a session, replay short-term events (synchronous, always current) for immediate context; lean on long-term records for what was learned in earlier sessions.
2. In tutorials and tests, wait. AWS sample code adds a time.sleep(...) between writing and retrieving so the extraction pipeline can run. That is fine for a demo, but never put a fixed sleep on a user's critical path in production — poll or simply accept that the freshest facts surface a beat later.

You provision a memory with CreateMemory on the control plane. The parameters you will reach for first:

• name, description — human-facing labels.
• eventExpiryDuration — how long raw short-term events are kept, in days. Minimum 7, maximum 365; the SDK defaults to 90 (a [VOLATILE] default — verify the live SDK).
• memoryStrategies (boto3) / strategies (SDK) — the extraction strategies that enable long-term memory (next lesson). Omit them for a short-term-only memory.
• memoryExecutionRoleArn — required when a strategy needs to call a Bedrock model on your behalf (overrides / self-managed).
• encryptionKeyArn — a customer-managed KMS key (CMK) is optional; otherwise a service-managed key is used.

A freshly created memory is not usable instantly — it transitions CREATING -> ACTIVE (or FAILED). Poll GetMemory until status is ACTIVE before writing events.

import boto3, time

control = boto3.client("bedrock-agentcore-control")

# Short-term-only memory: NO strategies attached -> nothing will be extracted
resp = control.create_memory(
    name="ShoppingSupportAgentMemory",
    description="Raw event log for the shopping support agent",
    eventExpiryDuration=90,   # days; min 7, max 365 (SDK default 90 — verify live)
)
memory_id = resp["memory"]["id"]

# Poll until the resource is ACTIVE before using the data plane
while control.get_memory(memoryId=memory_id)["memory"]["status"] != "ACTIVE":
    time.sleep(5)

Retention applies to raw events (short-term). Long-term memory records are governed separately — they are billed per record stored per month and persist independently of the event-expiry window, which is why a memory can "remember" a preference long after the conversation that revealed it has aged out of the event log.

With an ACTIVE memory you are on the data plane. The two core verbs are create_event (write short-term) and retrieve_memory_records (read long-term).

An event carries one or more messages. Each conversational message has a role — one of USER, ASSISTANT, TOOL, or OTHER — and text content. This is short-term, synchronous, and immutable: once the call returns, the turn is durably logged.

data = boto3.client("bedrock-agentcore")

# WRITE: short-term event (synchronous, immutable)
data.create_event(
    memoryId="mem-123",
    actorId="customer-456",
    sessionId="session-789",
    payload=[
        {"conversational": {"content": {"text": "What's a good vegetarian dinner?"}, "role": "USER"}},
        {"conversational": {"content": {"text": "How about a chickpea curry?"}, "role": "ASSISTANT"}},
    ],
)

# READ: long-term records by namespace + semantic search (eventual)
recs = data.retrieve_memory_records(
    memoryId="mem-123",
    namespace="/customer-support/customer-456/preferences/",
    searchCriteria={"searchQuery": "food the user likes", "topK": 5},
)

Note the asymmetry that traces straight back to short-term vs long-term:

• Writes are keyed by actorId + sessionId — short-term events belong to a session.
• Reads of long-term memory are keyed by a namespace and a semantic searchQuery, returning the top-K most relevant extracted records — not raw turns. (Namespaces and their template variables are covered in the data-model lesson.)

To read back the raw transcript instead of extracted insights, you use ListEvents or the SDK's get_last_k_turns — the short-term path, which is always synchronous and current.