Specify long-term memory organization with namespaces

When you create an AgentCore Memory, use a namespace to specify where the long-term memories for a memory strategy are logically grouped. Every time a new long-term memory is extracted using the memory strategy, it is saved under the namespace you set. This means that all long-term memories are scoped to their specific namespace, keeping them organized and preventing any mix-ups with other users or sessions. You should use a hierarchical format separated by forward slashes / . This helps keep memories organized clearly. As needed, you can choose to use the following pre-defined variables within braces in the namespace based on your application’s organization needs:

For example, if you define the following namespace as the input to your strategy when creating an AgentCore Memory:

/strategy/{memoryStrategyId}/actor/{actorId}/session/{sessionId}/

After memory creation, this namespace might look like:

/strategy/summarization-93483043/actor/actor-9830m2w3/session/session-9330sds8

A namespace can have different levels of granularity. The following examples use built-in variables only:

Granular at the session level

/strategy/{memoryStrategyId}/actor/{actorId}/session/{sessionId}/

Granular at the actor level across sessions

/strategy/{memoryStrategyId}/actor/{actorId}/

Granular at the strategy level across actors

/strategy/{memoryStrategyId}/

Global across all strategies

/

For even more granular organization, you can add custom namespace variables to represent additional dimensions such as tenant, team, or environment.

For example code, see Enable long-term memory.

Custom namespace variables

In addition to the built-in variables (actorId, sessionId, memoryStrategyId), you can define custom namespace variables to represent your application’s unique organizational dimensions, such as company, organization, team, or environment. With custom variables, you can scope long-term memories along arbitrary hierarchies without creating duplicate strategies or overloading the built-in variables.

For example, a multi-tenant application might need memories scoped by organizations:

/org/{orgname}/team/{teamname}/actor/{actorId}/session/{sessionId}/

You define the custom variables when creating or updating an existing memory resource using the namespaceKeys parameter, and supply their values at runtime through the extractionConfig.namespaceVariables field in the CreateEvent operation.

Define namespace keys

When you create or update a memory resource, use the namespaceKeys parameter to declare your custom variable keys and optional validation rules. Each key must:

You can define up to 5 namespace keys per memory resource, and up to 5 custom variables per namespaceTemplate.

Keep the following in mind when defining namespace keys:

For each key, you can optionally specify validation rules that constrain the values accepted at runtime:

When you specify both allowedValues and regexPattern, the service enforces both rules (logical AND).

The following example shows how to create a memory resource with custom namespace variables and validation:

aws bedrock-agentcore-control create-memory \
    --name "MultiTenantAgentMemory" \
    --description "Memory for a multi-tenant AI agent" \
    --event-expiry-duration 10 \
    --memory-strategies '[
        {
            "semanticMemoryStrategy": {
                "name": "TenantScopedStrategy",
                "namespaceTemplates": ["/org/{orgname}/team/{teamname}/actor/{actorId}/session/{sessionId}/"]
            }
        }
    ]' \
    --namespace-keys '[
        {"key": "orgname", "validation": {"allowedValues": ["acme", "globex", "initech"]}},
        {"key": "teamname", "validation": {"regexPattern": "^[a-z][a-z0-9-]*$"}}
    ]'

Supply namespace values at runtime

When you create an event using the CreateEvent operation, pass the custom namespace variable values in the extractionConfig.namespaceVariables field:

aws bedrock-agentcore create-event \
    --memory-id "MultiTenantAgentMemory-n29sh5ka8r" \
    --actor-id "user123" \
    --session-id "session67" \
    --event-timestamp "$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ")" \
    --payload '[
        {
            "conversational": {
                "content": {"text": "I need help debugging my application."},
                "role": "USER"
            }
        }
    ]' \
    --extraction-config '{
        "namespaceVariables": {
            "orgname": "acme",
            "teamname": "engineering"
        }
    }'

The service substitutes these values into the namespace templates during long-term memory extraction.

Update namespace keys

When you update namespace keys with the UpdateMemory operation, the namespaceKeys value fully replaces the existing set. To safely update, retrieve the current keys with GetMemory, apply your changes, and submit the complete list.

Keep the following constraints in mind:

# Get the current memory configuration
current = control_client.get_memory(memoryId="MultiTenantAgentMemory-n29sh5ka8r")
existing_keys = current['memory'].get('namespaceKeys', [])

# Add a new key while preserving existing ones
existing_keys.append({
    'key': 'category',
    'validation': {
        'allowedValues': ['backend', 'frontend', 'data']
    }
})

# Update with the full set
control_client.update_memory(
    memoryId="MultiTenantAgentMemory-n29sh5ka8r",
    namespaceKeys=existing_keys
)

Restrict write-path access with IAM condition keys

You can create IAM policies that use the bedrock-agentcore:namespaceVariable/<variableName> condition key to control which custom namespace variable values a caller can use when creating events. With this condition key, you can enforce tenant isolation at the write path.

The condition key follows the pattern bedrock-agentcore:namespaceVariable/<key> where <key> is the namespace variable name defined in namespaceKeys.

The following policy allows the caller to create events only when orgname is set to acme, and explicitly denies requests when orgname is set to globex:

{
"Version":"2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCreateEventForAcme",
      "Effect": "Allow",
      "Action": "bedrock-agentcore:CreateEvent",
      "Resource": "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/memory_id",
      "Condition": {
        "StringEquals": {
          "bedrock-agentcore:namespaceVariable/orgname": "acme"
        }
      }
    },
    {
      "Sid": "DenyCreateEventForGlobex",
      "Effect": "Deny",
      "Action": "bedrock-agentcore:CreateEvent",
      "Resource": "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/memory_id",
      "Condition": {
        "StringEquals": {
          "bedrock-agentcore:namespaceVariable/orgname": "globex"
        }
      }
    }
  ]
}

The following table shows how IAM evaluates requests based on whether a condition key is present in the policy and whether the request provides the namespace variable:

Restrict read-path access with IAM

You can create IAM policies to restrict memory read access by the scopes you define, such as actor, session, and namespace. Use the scopes as context keys in your IAM policies.

The following policy restricts access to retrieving memories to a specific namespace or records under a particular namespacePath hierarchy. In this example, the policy allows access only to memories with exact namespaces such as summaries/agent1/ OR with namespaces under the following namespacePath hierarchy with summaries/agent1/ , such as summaries/agent1/session1/ or summaries/agent1/session2/.

{
"Version":"2012-10-17",
  "Statement": [
    {
      "Sid": "SpecificNamespaceAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:RetrieveMemoryRecords"
      ],
      "Resource": "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/memory_id",
      "Condition": {
        "StringEquals": {
          "bedrock-agentcore:namespace": "summaries/agent1/"
        }
      }
    },
    {
      "Sid": "SpecificNamespacePathAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:RetrieveMemoryRecords"
      ],
      "Resource": "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/memory_id",
      "Condition": {
        "StringLike": {
          "bedrock-agentcore:namespacePath": "summaries/agent1/*"
        }
      }
    }
  ]
}