Organizando a memória de agentes em escala: padrões de namespace no AgentCore Memory

O problema central: memória sem organização é memória inútil

Quem já trabalhou com agentes de IA sabe que persistir contexto entre sessões é um dos desafios mais práticos do desenvolvimento. Não basta armazenar informações — é preciso organizá-las de forma que possam ser recuperadas com precisão, no momento certo, pela entidade certa. Sem isso, o agente traz contexto irrelevante, mistura dados de usuários diferentes ou expõe informações que não deveriam ser acessíveis.

Para endereçar exatamente esse problema, a AWS publicou um guia técnico detalhado sobre o design de namespaces no Amazon Bedrock AgentCore Memory. Se você ainda não conhece o serviço, vale começar pela introdução ao AgentCore Memory antes de mergulhar nos padrões avançados.

O que são namespaces no AgentCore Memory?

Namespaces são caminhos hierárquicos que organizam os registros de memória de longo prazo dentro de um recurso de memória do AgentCore. A analogia mais direta é com estruturas de diretórios em um sistema de arquivos: cada registro fica armazenado em um caminho específico, e esse caminho determina como ele será recuperado e quem poderá acessá-lo.

Por exemplo, as preferências de um usuário podem ficar em /actor/customer-123/preferences/, enquanto o resumo de uma sessão específica fica em /actor/customer-123/session/session-789/summary/. Com essa estrutura, é possível recuperar memórias com exatamente o nível de granularidade necessário.

Se você já trabalhou com chaves de partição no Amazon DynamoDB ou com estruturas de prefixo no Amazon Simple Storage Service (Amazon S3), o raciocínio é o mesmo: antes de definir a estrutura, você precisa pensar nos padrões de acesso. As perguntas fundamentais são:

Quem precisa acessar essas memórias — um único usuário ou todos os usuários de um agente?
Qual granularidade de recuperação é necessária — resumos por sessão ou preferências acumuladas ao longo do tempo?
Quais são os limites de isolamento — a memória de um usuário pode ser visível para outro?

A principal diferença em relação a uma chave de partição é que namespaces suportam recuperação hierárquica além do match exato. É possível consultar em qualquer nível da hierarquia, não apenas na folha.

Templates de namespace e resolução dinâmica

Ao criar um recurso de memória, o namespace é definido por meio do campo namespaceTemplate dentro de cada configuração de estratégia. Três variáveis pré-definidas estão disponíveis para composição dinâmica:

{actorId} — resolve para o identificador do ator nos eventos processados
{sessionId} — resolve para o identificador da sessão
{memoryStrategyId} — resolve para o identificador da estratégia

Veja um exemplo de criação de recurso de memória com templates de namespace:

response = agentcore_client.create_memory(
    name="CustomerSupportMemory",
    description="Memory for customer support agents",
    eventExpiryDuration=30,
    memoryStrategies=[
        {
            "semanticMemoryStrategy": {
                "name": "customer-facts",
                "namespaceTemplate": "/actor/{actorId}/facts/"
            }
        },
        {
            "summaryMemoryStrategy": {
                "name": "session-summaries",
                "namespaceTemplate": "/actor/{actorId}/session/{sessionId}/summary/"
            }
        }
    ]
)

Quando eventos chegam com actorId=customer-456 e sessionId=session-789, os namespaces resolvidos ficam:

/actor/customer-456/facts/
/actor/customer-456/session/session-789/summary/

Padrões de design por estratégia de memória

Cada tipo de estratégia de memória tem necessidades de escopo diferentes. A AWS detalha os padrões recomendados para cada caso.

1. Memória semântica e preferências: escopo por ator

A memória semântica captura fatos e conhecimentos extraídos de conversas — por exemplo, “a empresa do cliente tem 500 funcionários”. A memória de preferências captura escolhas e estilos — por exemplo, “o usuário prefere Python para desenvolvimento”. Ambas acumulam valor ao longo do tempo e são relevantes em qualquer sessão futura.

Para esses casos, o namespace deve ser escopado ao ator:

/actor/{actorId}/facts/
/actor/{actorId}/preferences/

Com esse design, fatos e preferências de um usuário ficam consolidados em um único namespace, independentemente de qual sessão os originou. O motor de consolidação do AgentCore Memory mescla memórias relacionadas dentro do mesmo namespace.

Vale notar que quando o namespace inclui o sessionId no caminho dos fatos (como /actor/{actorId}/{sessionId}/facts/), o motor de consolidação não consegue enxergar registros de sessões diferentes — e os fatos nunca são mesclados. Por isso, para memórias que devem persistir entre sessões, o escopo por ator é o padrão correto.

Em alguns casos, um administrador pode precisar recuperar informações de múltiplos atores. Para isso, a AWS sugere inverter a estrutura, colocando o identificador do ator como filho do tipo de memória:

/customer-issues/{actorId}/
/sales/{actorId}/

Com essa estrutura invertida, uma consulta com namespacePath="/customer-issues/" retorna problemas reportados por todos os clientes, enquanto uma consulta com namespace="/customer-issues/customer-123/" retorna apenas os dados daquele ator específico.

2. Memória de resumo: escopo por sessão

A memória de resumo cria narrativas das conversas, capturando pontos principais e decisões. Em vez de alimentar todo o histórico de uma conversa na janela de contexto do modelo de linguagem (LLM), o agente pode recuperar um resumo compacto que preserva as informações essenciais com muito menos tokens.

Como resumos estão intrinsecamente ligados a uma conversa específica, o namespace deve incluir o identificador da sessão: /actor/{actorId}/session/{sessionId}/summary/. Assim, cada sessão tem seu próprio resumo, mas todos ficam organizados sob o ator para recuperação cruzada quando necessário.

3. Memória episódica: escopo por sessão com hierarquia de reflexão

A memória episódica captura rastros completos de raciocínio — o objetivo, os passos executados, os resultados e as reflexões. Como cada episódio representa o que aconteceu em uma interação específica, ele deve ser escopado à sessão, de forma similar aos resumos.

Reflexões são insights transversais, armazenados em um nível pai. Elas generalizam aprendizados entre sessões — por exemplo, “quando uma restrição de classe tarifária bloqueia uma modificação, busque voos alternativos imediatamente em vez de apenas explicar a política”. O namespace das reflexões deve ser um subcaminho do namespace dos episódios:

Episódios: /actor/{actorId}/session/{sessionId}/episodes/
Reflexões: /actor/{actorId}/

Padrões de recuperação de memória

O AgentCore Memory oferece três APIs principais para recuperação de memória de longo prazo.

Busca semântica com RetrieveMemoryRecords

Esse é o método primário durante interações do agente. Ele retorna as memórias semanticamente relevantes para uma consulta, com base em significado — não em correspondência exata de texto.

# Retrieve memories relevant to the current user query
memories = agentcore_client.retrieve_memory_records(
    memoryId="mem-12345abcdef",
    namespace="/actor/customer-123/facts/",
    searchCriteria={
        "searchQuery": "What cloud migration approach is the customer using?",
        "topK": 5
    }
)

A consulta de busca pode vir diretamente da pergunta do usuário ou ser gerada pelo próprio LLM do agente para cenários mais complexos. No segundo caso, há um custo adicional de latência.

Listagem direta com ListMemoryRecords

Usado quando é necessário enumerar memórias dentro de um namespace específico — por exemplo, exibir as preferências armazenadas de um usuário em uma interface, auditar o que existe ou executar operações em lote.

# List all memories in a specific namespace
records = agentcore_client.list_memory_records(
    memoryId="mem-12345abcdef",
    namespace="/actor/customer-123/preferences/"
)

Acesso e exclusão diretos com GetMemoryRecord e DeleteMemoryRecord

Quando o ID específico de um registro é conhecido (por exemplo, a partir de uma listagem anterior), é possível acessá-lo ou removê-lo diretamente. Esses métodos são úteis para fluxos de gerenciamento de memória que permitem aos usuários visualizar, corrigir ou excluir registros específicos pela interface da aplicação.

# Get a specific memory record
record = agentcore_client.get_memory_record(
    memoryId="mem-12345abcdef",
    memoryRecordId="rec-abc123"
)

# Delete a specific memory record
agentcore_client.delete_memory_record(
    memoryId="mem-12345abcdef",
    memoryRecordId="rec-abc123"
)

namespace vs. namespacePath: match exato versus recuperação hierárquica

O AgentCore Memory oferece dois campos distintos para escopar a recuperação, e entender a diferença é crítico para o comportamento correto do sistema.

O campo namespace realiza correspondência exata — retorna apenas os registros armazenados naquele caminho preciso. Já o campo namespacePath realiza correspondência hierárquica, retornando todos os registros cujo namespace esteja sob o caminho especificado.

A tabela abaixo, extraída do guia original, resume quando usar cada abordagem:

Recuperar preferências semanticamente relevantes: RetrieveMemoryRecords com namespace → /actor/customer-123/preferences/
Recuperar um resumo de sessão específica: ListMemoryRecords com namespace → /actor/customer-123/session/session-001/summary/
Listar todas as preferências de um usuário: ListMemoryRecords com namespace → /actor/customer-123/preferences/
Buscar em todas as memórias de um usuário: RetrieveMemoryRecords com namespacePath → /actor/customer-123/
Listar resumos de todas as sessões de um usuário: ListMemoryRecords com namespacePath → /actor/customer-123/session/

É importante pensar bem nos padrões de isolamento ao usar namespacePath, pois a travessia em árvore pode expor dados não intencionais se a hierarquia não estiver bem planejada.

Controle de acesso via IAM

Os namespaces se integram ao Gerenciamento de Identidade e Acesso (IAM) da AWS por meio de condition keys que restringem quais namespaces uma entidade pode incluir nas requisições à API de memória.

Políticas de match exato

Para restringir o acesso a um namespace específico, usa-se StringEquals com a condition key bedrock-agentcore:namespace:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:RetrieveMemoryRecords",
        "bedrock-agentcore:ListMemoryRecords"
      ],
      "Resource": "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/mem-12345abcdef",
      "Condition": {
        "StringEquals": {
          "bedrock-agentcore:namespace": "/actor/${aws:PrincipalTag/userId}/preferences/"
        }
      }
    }
  ]
}

Essa política garante que um usuário só consiga recuperar memórias do seu próprio namespace de preferências, usando a tag de principal userId para escopo dinâmico.

Políticas de recuperação hierárquica

Para acesso hierárquico, usa-se StringLike com a condition key bedrock-agentcore:namespacePath:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:RetrieveMemoryRecords",
        "bedrock-agentcore:ListMemoryRecords"
      ],
      "Resource": "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/mem-12345abcdef",
      "Condition": {
        "StringLike": {
          "bedrock-agentcore:namespacePath": "/actor/${aws:PrincipalTag/userId}/*"
        }
      }
    }
  ]
}

Com essa configuração, o usuário pode realizar recuperação hierárquica em seus próprios namespaces (fatos, preferências, resumos), enquanto o acesso aos dados de outros usuários é bloqueado.

Conclusão: design de namespace é fundação, não detalhe

O guia publicado pela AWS deixa claro que o design de namespaces é tão fundamental quanto o design de esquemas em um banco de dados. Pensar nos padrões de acesso e nos limites de isolamento antes de definir os templates de namespace é o que separa um sistema de memória eficaz de um que traz contexto errado ou expõe dados indevidamente.

Os pontos-chave do guia são:

Pense nos padrões de acesso e isolamento antes de criar os templates de namespace
Escope memórias semânticas e de preferências ao ator (/actor/{actorId}/) para consolidação entre sessões
Escope resumos e episódios à sessão (/actor/{actorId}/session/{sessionId}/), pois são específicos de cada conversa
Use namespace para match exato quando souber o caminho preciso, e namespacePath para recuperação hierárquica quando precisar buscar em uma subárvore
Use barras no início e no fim dos caminhos para manter consistência e evitar colisões de prefixo
Use as condition keys do IAM (bedrock-agentcore:namespace e bedrock-agentcore:namespacePath) para controlar quais namespaces podem ser acessados

Para aprofundar, a AWS disponibiliza a documentação de organização do AgentCore Memory, a documentação de organização de memória de longo prazo e o repositório de exemplos no GitHub.

Fonte

Organizing Agents’ memory at scale: Namespace design patterns in AgentCore Memory (https://aws.amazon.com/blogs/machine-learning/organizing-agents-memory-at-scale-namespace-design-patterns-in-agentcore-memory/)