Usando memória de agente

Cada sessão de Managed Agents começa com um contexto novo por padrão. Quando uma sessão termina, qualquer estado que o agente tenha construído é perdido. Os "memory stores" (armazenamentos de memória) permitem que o agente carregue informações entre sessões: preferências do usuário, convenções do projeto, erros anteriores e contexto de domínio.



Visão geral

Um armazenamento de memória é uma coleção de documentos de texto com escopo de workspace, otimizada para o Claude. Quando você anexa um armazenamento a uma sessão, ele é montado como um diretório dentro do sandbox da sessão. O agente lê e escreve nele com as mesmas ferramentas de arquivo que usa para o restante do sistema de arquivos, e uma nota descrevendo cada montagem é automaticamente adicionada ao prompt do sistema, informando ao agente onde procurar. O conjunto de ferramentas do agente é necessário para essas interações; certifique-se de habilitá-lo durante a criação do agente.

Cada memória em um armazenamento é endereçada por um caminho e pode ser lida e editada diretamente através da API ou do Console, permitindo ajustes, importação e exportação.

Cada alteração em uma memória cria uma versão de memória imutável, fornecendo uma trilha de auditoria e recuperação pontual para tudo o que o agente escreve.



Criar um armazenamento de memória

Dê ao armazenamento um name e uma description. A descrição é passada ao agente, informando o que o armazenamento contém.

store_id=$(ant beta:memory-stores create \
  --name "User Preferences" \
  --description "Per-user preferences and project context." \
  --transform id --raw-output)

O id do armazenamento de memória (memstore_...) é o que você passa ao anexar o armazenamento a uma sessão.



Preencher com conteúdo (opcional)

Pré-carregue um armazenamento com material de referência antes de qualquer execução do agente:

ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/formatting_standards.md" \
  --content "All reports use GAAP formatting. Dates are ISO-8601..." \
  > /dev/null



Anexar um armazenamento de memória a uma sessão

Armazenamentos de memória são anexados no array resources[] da sessão quando a sessão é criada. Diferentemente de recursos de arquivo e repositório, armazenamentos de memória só podem ser anexados no momento da criação da sessão; adicionar ou remover um de uma sessão em execução não é suportado.

Opcionalmente, inclua instructions para fornecer orientações específicas da sessão sobre como o agente deve usar esse armazenamento. Elas são mostradas ao agente junto com o name e a description do armazenamento, e são limitadas a 4.096 caracteres.

Você também pode configurar access. O padrão é read_write (mostrado explicitamente no exemplo a seguir), mas read_only também é suportado.

ant beta:sessions create <<YAML
agent: $agent_id
environment_id: $environment_id
resources:
  - type: memory_store
    memory_store_id: $store_id
    access: read_write
    instructions: User preferences and project context. Check before starting any task.
YAML

Um máximo de 8 armazenamentos de memória é suportado por sessão. Anexe múltiplos armazenamentos quando diferentes partes da memória tiverem diferentes proprietários ou regras de acesso. Motivos comuns:

• Material de referência compartilhado: um armazenamento somente leitura anexado a muitas sessões (padrões, convenções, conhecimento de domínio), mantido separado do armazenamento de leitura e escrita próprio de cada sessão.
• Mapeamento para a estrutura do seu produto: um armazenamento por usuário final, por equipe ou por projeto, enquanto compartilha uma única configuração de agente.
• Ciclos de vida diferentes: um armazenamento que sobrevive a qualquer sessão individual, ou um que você queira arquivar em seu próprio cronograma.



Como o agente acessa a memória

Cada armazenamento anexado é montado dentro do sandbox da sessão como um diretório em /mnt/memory/. O nome do diretório é o nome de exibição do armazenamento sanitizado para um slug seguro para sistema de arquivos (convertido para minúsculas; sequências de caracteres não alfanuméricos tornam-se um único hífen), então um armazenamento chamado "Demo Memory" é montado em /mnt/memory/demo-memory/. O caminho exato é retornado no campo mount_path do recurso de armazenamento de memória da sessão; leia-o de lá em vez de construí-lo você mesmo. O agente lê e escreve no armazenamento com o conjunto de ferramentas do agente padrão. Escritas sob o caminho de montagem são persistidas de volta no armazenamento e permanecem sincronizadas entre sessões que o compartilham; escritas em qualquer outro caminho sob /mnt/memory/ vão para o espaço temporário local do contêiner e são perdidas quando a sessão termina. Uma breve descrição de cada montagem (nome de exibição, caminho de montagem, modo de acesso, description do armazenamento e quaisquer instructions) é automaticamente adicionada ao prompt do sistema.

O access é aplicado no nível do sistema de arquivos: uma montagem read_only rejeita escritas, enquanto escritas em uma montagem read_write produzem versões de memória atribuídas à sessão.

As leituras e escritas do agente aparecem no fluxo de eventos como eventos comuns agent.tool_use e agent.tool_result para qualquer ferramenta que tenha tocado a montagem.



Visualizar e editar memórias

Armazenamentos de memória podem ser gerenciados diretamente através da API. Use isso para construir fluxos de revisão, corrigir memórias incorretas ou preencher armazenamentos antes de qualquer execução de sessão.



Listar memórias

Liste as memórias em um armazenamento, opcionalmente filtradas por path_prefix para navegar por um caminho como um diretório:

ant beta:memory-stores:memories list \
  --memory-store-id "$store_id" \
  --path-prefix "/" --order-by path --depth 2

Consulte a referência de Listar memórias para parâmetros completos e esquema de resposta.



Ler uma memória

Buscar uma memória individual retorna o conteúdo completo.

ant beta:memory-stores:memories retrieve \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id"

Consulte a referência de Recuperar uma memória para parâmetros completos e esquema de resposta.



Criar uma memória

memories.create cria uma memória em um determinado path. A criação não sobrescreve; para alterar uma memória existente, use memories.update.

mem=$(ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/preferences/formatting.md" \
  --content "Always use tabs, not spaces." \
  --format json)
mem_id=$(jq -r '.id' <<< "$mem")
mem_sha=$(jq -r '.content_sha256' <<< "$mem")

Consulte a referência de Criar uma memória para parâmetros completos e esquema de resposta.



Atualizar uma memória

memories.update modifica uma memória existente por ID. Você pode alterar content, path (uma renomeação) ou ambos. O exemplo renomeia uma memória para um caminho de arquivo morto:

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --path "/archive/2026_q1_formatting.md" \
  > /dev/null

Consulte a referência de Atualizar uma memória para parâmetros completos e esquema de resposta.



Edições de conteúdo seguras (concorrência otimista)

Para evitar sobrescrever uma escrita concorrente, passe uma pré-condição content_sha256. A atualização só é aplicada se o hash do conteúdo armazenado ainda corresponder ao que você leu; em caso de incompatibilidade, releia a memória e tente novamente com o estado atualizado.

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --content "CORRECTED: Always use 2-space indentation." \
  --precondition "{type: content_sha256, content_sha256: $mem_sha}" \
  > /dev/null



Excluir uma memória

ant beta:memory-stores:memories delete \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  > /dev/null

Consulte a referência de Excluir uma memória para parâmetros completos e esquema de resposta.



Auditar alterações de memória

Cada mutação em uma memória cria uma versão de memória imutável (memver_...). Use os endpoints de versão para auditar quem alterou o quê e quando, para inspecionar ou restaurar um snapshot anterior e para remover conteúdo sensível do histórico com redação.

As versões pertencem ao armazenamento (não à memória individual) e sobrevivem mesmo depois que a própria memória é excluída, então a trilha de auditoria permanece completa. As versões são retidas por 30 dias; no entanto, as versões recentes são sempre mantidas independentemente da idade, então memórias que mudam com pouca frequência podem reter histórico além de 30 dias. A chamada memories.retrieve ao vivo sempre retorna a versão mais recente; os endpoints de versão fornecem o histórico retido.

Não há um endpoint dedicado de restauração; para reverter, recupere a versão desejada e escreva seu content de volta com memories.update (ou memories.create se a memória pai tiver sido excluída, porque as versões sobrevivem ao seu pai).

Versões de memória anteriores podem ser excluídas após 30 dias. Para preservar o histórico de memória por mais tempo, exporte as versões através da API.



Listar versões

Liste o histórico de versões de um armazenamento, da mais recente para a mais antiga. O exemplo filtra para o histórico de uma única memória:

versions=$(ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json)
jq -r '.data[] | "\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -r '.data[1].id' <<< "$versions")

Consulte a referência de Listar versões de memória para parâmetros completos e esquema de resposta.



Recuperar uma versão

Buscar uma versão individual retorna os mesmos campos que a resposta de listagem, além do corpo completo de content.

ant beta:memory-stores:memory-versions retrieve \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Consulte a referência de Recuperar uma versão de memória para parâmetros completos e esquema de resposta.



Redigir uma versão

A redação remove conteúdo de uma versão histórica enquanto preserva a trilha de auditoria (quem fez o quê, quando). Use-a para fluxos de conformidade, como remover segredos vazados, PII ou solicitações de exclusão de usuário.

Uma versão que é o head atual de uma memória ativa não pode ser redigida. Escreva uma nova versão primeiro (ou exclua a memória), depois redija a antiga.

ant beta:memory-stores:memory-versions redact \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Consulte a referência de Redigir uma versão de memória para parâmetros completos e esquema de resposta.



Gerenciar armazenamentos de memória

Além de create, os armazenamentos de memória suportam retrieve, update, list, archive e delete.



Listar armazenamentos

Liste os armazenamentos no workspace. Armazenamentos arquivados são excluídos por padrão; passe include_archived: true para incluí-los.

ant beta:memory-stores list --include-archived

Consulte a referência de Listar armazenamentos de memória para parâmetros completos e esquema de resposta.



Arquivar um armazenamento

Arquivar torna um armazenamento somente leitura e impede que ele seja anexado a novas sessões. O arquivamento é unidirecional; não há como desarquivar.

ant beta:memory-stores archive --memory-store-id "$store_id"

Consulte a referência de Arquivar um armazenamento de memória para parâmetros completos e esquema de resposta.

Para remover permanentemente um armazenamento junto com todas as suas memórias e versões, use memory_stores.delete.



Melhores práticas para gerenciamento de memória

Quando um armazenamento atinge seu limite de 2.000 memórias, escritas em novas memórias falham: tanto chamadas diretas de memories.create quanto escritas de arquivo do agente em caminhos não mapeados. Memórias existentes permanecem legíveis e editáveis. As práticas a seguir ajudam você a ficar bem abaixo do limite e a se recuperar de forma elegante se atingi-lo.

• Use armazenamentos focados. Em vez de um grande armazenamento de uso geral, use armazenamentos menores e específicos — um por usuário, um para conhecimento de domínio compartilhado e um para contexto específico do projeto. Cada armazenamento tem seu próprio limite de 2.000 memórias, então manter os armazenamentos com escopo definido reduz a chance de qualquer um deles ficar cheio.

• Condense ou limpe antes que o armazenamento fique cheio. Exclua memórias obsoletas ou redundantes com memories.delete. Você também pode executar uma sessão de dreaming, que consolida conteúdo fragmentado em um novo armazenamento de saída separado, em vez de modificar o original. Mude suas sessões para esse armazenamento de saída e, em seguida, arquive ou exclua o original.

• Anexe um novo armazenamento quando fizer sentido. Se um armazenamento cresceu além de seu escopo útil, anexe um novo para conteúdo novo e anexe o original com acesso read_only. O agente pode ler de ambos enquanto escreve apenas no novo.

• Limite o acesso de escrita quando apropriado. Sessões que apenas leem material de referência compartilhado não precisam de read_write. Manter o acesso de escrita restrito às sessões que realmente adicionam novas memórias facilita rastrear de onde vem o crescimento.