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
)