Memory scoping with namespaces

With Long-Term Memory, organization is managed through Namespaces, which are defined when setting memory strategy in a call to the CreateMemory operation or with the AgentCore console. This section details these concepts.

An actor refers to entity such as end users or agent/user combinations. For example, in a coding support chatbot, the actor is usually the developer asking questions. Using the actor ID helps the system know which user the memory belongs to, keeping each user's data separate and organized.

A session is usually a single conversation or interaction period between the user and the AI agent. It groups all related messages and events that happen during that conversation.

A namespace is used to logically group and organize long-term memories. It ensures data stays neat, separate, and secure.

With AgentCore Memory, you need to add a namespace when you define a memory strategy as part of CreateMemory operation. This namespace helps define where the long-term memory will be logically grouped. Every time a new long-term memory is extracted using this 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 below pre-defined variables within braces in the namespace based on your applications' organization needs:

• actorId – Identifies who the long-term memory belongs to, such as a user)

• strategyId – Shows which memory strategy is being used. This strategy identifier is auto-generated when you create a memory using CreateMemory operation.

• sessionId – Identifies which session or conversation the memory is from.

For example, if you define the following namespace as the input to your strategy in CreateMemory operation:

/strategy/{strategyId}/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:

Most granular Level of organization

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

Granular at the actor Level across sessions

/strategy/{strategyId}/actor/{actorId}

Granular at the strategy Level across actors

/strategy/{strategyId}

Global across all strategies

/

Restrict access with IAM

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

The following policy restricts access to retrieving memories from a specific namespace.

JSON

{
  "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"
        }
      }
    }
  ]
}