Actors, Sessions, Events & Namespaces

Before you can design a clean memory layout you need the exact vocabulary. AgentCore Memory is not a free-form key-value store — it has a fixed object model, and every concept below maps to a real field name you will pass to the API.

Memory (the resource). The top-level container you create with CreateMemory on the bedrock-agentcore-control plane. It carries an id, an encryption setting (a customer-managed KMS key, or service-managed by default), an event-expiry duration, and the list of strategies attached to it. Its lifecycle status moves through:

CREATING  ->  ACTIVE  ->  (FAILED)

You must poll until the status is ACTIVE before writing events — control.get_memory(memoryId=...)['memory']['status']. A FAILED resource never becomes usable; delete and recreate it.

Actor (actorId). Who the memory is about — usually an end user, but it can be any principal you choose to model (a customer, a tenant, a device). You assign the value; AgentCore does not invent it.

Session (sessionId). A single bounded conversation for an actor. Short-term events are scoped by the pair actorId + sessionId — that pair is the addressing key for raw turn-by-turn history.

Event. The unit you write to the data plane via CreateEvent. An event contains one or more messages, and crucially events are immutable — you append, you never edit. That immutability is what makes the raw interaction log a trustworthy audit trail.

Message roles. Every message inside an event is tagged with exactly one role:

These roles matter downstream: several strategies only consume USER/ASSISTANT messages, while episodic extraction wants TOOL results included for best quality.

Branch. You can fork a conversation off an existing event by referencing its rootEventId, creating a parallel line of history (think "what-if" replays or A/B continuations) without mutating the original. List them with list_branches.

Memory record. A single long-term item — a derived insight (a fact, a preference, a summary, an episode) the service extracts asynchronously if you attached a strategy. Records are read with RetrieveMemoryRecords / retrieve_memories. No strategy means no records: you only ever get back the raw short-term events you wrote.

Strategy (memoryStrategyId). A configured extraction recipe attached to the Memory that tells AgentCore what to derive from raw events (semantic facts, summaries, user preferences, episodes). Each strategy owns one or more namespaces where its records land.

Namespaces apply to long-term memory only — they are the addressing scheme for the records a strategy produces. A namespace is a hierarchical, slash-delimited path that can contain template variables the service fills in at extraction time. The supported variables are:

You attach one or more namespace templates to each strategy when you create the Memory. At retrieval time you pass a concrete (substituted) namespace to RetrieveMemoryRecords to search within it.

control = boto3.client('bedrock-agentcore-control')
resp = control.create_memory(
    name="ShoppingSupportAgentMemory",
    memoryStrategies=[
        {'summaryMemoryStrategy': {
            'name': 'SessionSummarizer',
            # Summary records are session-scoped, so the template MUST include {sessionId}
            'namespaceTemplates': ['/summaries/{actorId}/{sessionId}/']}},
        {'userPreferenceMemoryStrategy': {
            'name': 'UserPreferenceExtractor',
            # Preferences live per actor, across all sessions
            'namespaceTemplates': ['/users/{actorId}/preferences/']}}])
# poll control.get_memory(memoryId=...)['memory']['status'] until 'ACTIVE'

When you later read records, you supply the resolved path:

data = boto3.client('bedrock-agentcore')
data.retrieve_memory_records(
    memoryId="mem-123",
    namespace="/customer-support/user-1/preferences/",
    searchCriteria={"searchQuery": "shipping address and contact preferences", "topK": 5})

Granularity is a design choice. The hierarchy lets you tune how narrowly records are partitioned, trading isolation against cross-context recall:

• Per-session — {actorId}/{sessionId}/ — tightest scope; records never bleed between conversations.
• Per-actor — {actorId}/ — durable knowledge about one user across all their sessions (the natural home for preferences).
• Per-strategy — /strategy/{memoryStrategyId}/... — partition by what kind of insight it is.
• Global — a fixed prefix with no variables — shared across everyone (use sparingly; it is a cross-actor blast radius).

Different built-in strategies have natural defaults: semantic facts default to roughly /strategy/{memoryStrategyId}/actors/{actorId}/, while the Summary strategy is session-scoped and its template requires {sessionId}.

This is the single most important syntactic detail in namespace design, and it bites people who skip it. Always end a namespace with a trailing slash.

Namespace matching for retrieval is prefix-based. Consider two sibling namespaces written without trailing slashes:

/users/{actorId}/preferences     <-- BAD: no trailing slash
/users/{actorId}/preferences-archive

Resolved for actorId = u-42, the first becomes /users/u-42/preferences. Because matching is by prefix, that string is also a prefix of /users/u-42/preferences-archive — so a search scoped to the first namespace can leak records from the second. The two namespaces collide.

Add the trailing slash and the collision disappears:

/users/{actorId}/preferences/          <-- GOOD
/users/{actorId}/preferences-archive/

Now /users/u-42/preferences/ is no longer a prefix of /users/u-42/preferences-archive/ (the slash makes them disjoint at that level). Every namespace template in this lesson's examples ends in / for exactly this reason — /summaries/{actorId}/{sessionId}/, /users/{actorId}/preferences/, /customer-support/user-1/preferences/.

The rule generalizes: treat the trailing slash as a hard convention on every template you write, the same way you'd always close a bracket. It costs one character and removes a whole class of silent cross-namespace leaks.

AgentCore exposes the same concept under two slightly different key names depending on which tool you use, and mixing them up produces validation errors that are easy to misread.

This mirrors a broader pattern in the Memory API where the SDK and the raw control plane disagree on field names — for example the SDK takes strategies= while boto3 takes memoryStrategies=. The fix is mechanical but you have to know it exists:

# Python SDK shape (note the PLURAL key, inside a strategy dict):
{'summaryMemoryStrategy': {
    'name': 'SessionSummarizer',
    'namespaceTemplates': ['/summaries/{actorId}/{sessionId}/']}}

# boto3 / console shape uses the SINGULAR key name for the same data.

If a create_memory call rejects your strategy with a ValidationException complaining about an unknown member, check the plural-vs-singular spelling of the namespace key before anything else — it is almost always this, not a problem with your path.

Because namespaces are paths, AgentCore lets you write IAM policies that restrict an agent's role to specific namespaces — the same way you'd scope an S3 policy to a key prefix. This is how you enforce, for example, that a per-tenant agent role can only retrieve records under that tenant's path.

Two condition keys make this work, used on actions such as bedrock-agentcore:RetrieveMemoryRecords:

An exact-match policy that allows retrieval from a single namespace and nothing else:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "bedrock-agentcore:RetrieveMemoryRecords",
    "Resource": "*",
    "Condition": {
      "StringEquals": {
        "bedrock-agentcore:namespace": "/users/u-42/preferences/"
      }
    }
  }]
}

A pattern-match policy that allows retrieval anywhere under a tenant prefix using the StringLike key:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "bedrock-agentcore:RetrieveMemoryRecords",
    "Resource": "*",
    "Condition": {
      "StringLike": {
        "bedrock-agentcore:namespacePath": "/tenants/acme/*"
      }
    }
  }]
}

The trailing-slash discipline from the previous section pays off directly here: because well-formed namespaces don't collide by prefix, a StringLike pattern like /tenants/acme/* won't accidentally grant access to /tenants/acme-corp/ records. Sloppy namespaces undermine your IAM as much as your retrieval.