Usando memória

As sessões da API de Agente são efêmeras por padrão. Quando uma sessão termina, tudo que o agente aprendeu é perdido. Os armazenamentos de memória permitem que o agente carregue aprendizados entre sessões: preferências do usuário, convenções de 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 Claude. Quando um ou mais armazenamentos de memória são anexados a uma sessão, o agente verifica automaticamente os armazenamentos antes de iniciar uma tarefa e registra aprendizados duráveis quando termina - nenhum prompt ou configuração adicional é necessário da sua parte.

Cada memória em um armazenamento pode ser acessada e editada diretamente via API ou Console, permitindo ajuste, importação e exportação de memórias.

Cada alteração em uma memória cria uma memory_version imutável para suportar auditoria e reversão de alterações de memória.

Criar um armazenamento de memória

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

store=$(curl -fsS https://api.anthropic.com/v1/memory_stores \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "name": "User Preferences",
  "description": "Per-user preferences and project context."
}
EOF
)
store_id=$(jq -r '.id' <<< "$store")
echo "$store_id"  # memstore_01Hx...

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

Pré-carregar com conteúdo (opcional)

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

Anexar memória a uma sessão

Os armazenamentos de memória são anexados no array resources[] da sessão.

Opcionalmente, inclua um prompt se quiser fornecer instruções específicas da sessão ao Claude sobre como usar este armazenamento de memória. Ele é fornecido ao Claude além do name e da description do armazenamento de memória, e é limitado a 4.096 caracteres.

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

Um máximo de 8 armazenamentos de memória são suportados por sessão. Anexe múltiplos armazenamentos quando diferentes partes da memória têm diferentes proprietários ou regras de acesso. Razões 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 dos aprendizados de leitura e escrita 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ê deseja arquivar em seu próprio cronograma.

Ferramentas de memória

Quando armazenamentos de memória são anexados a uma sessão, o agente ganha automaticamente acesso às ferramentas de memória. As interações do agente com os armazenamentos de memória são registradas como eventos agent.tool_use no fluxo de eventos.

Inspecionar e corrigir memória

Os armazenamentos de memória podem ser gerenciados diretamente via API. Use isso para criar fluxos de trabalho de revisão, corrigir memórias incorretas ou pré-carregar armazenamentos antes de qualquer execução de sessão.

Listar memórias

A listagem não retorna o conteúdo da memória, apenas os metadados do objeto. Use path_prefix para listas com escopo de diretório (inclua uma barra final: /notes/ corresponde a /notes/a.md mas não a /notes_backup/old.md).

Ler uma memória

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

Escrever um documento

Use memories.write para fazer upsert de um documento por caminho. Se nada existir no caminho, ele é criado; se um documento já existir lá, seu conteúdo é substituído. Para modificar um documento existente pelo ID mem_... (por exemplo, para renomear seu caminho ou aplicar com segurança uma edição de conteúdo), use memories.update em vez disso (veja Atualizar abaixo).

Criar somente se o caminho estiver livre

Passe precondition={"type": "not_exists"} para memories.write para torná-lo um guarda somente de criação. Se um documento já existir no caminho, a escrita retorna 409 memory_precondition_failed em vez de substituí-lo. Use isso ao pré-carregar um armazenamento e você quiser evitar sobrescrever conteúdo existente.

Para editar com segurança um documento existente (ler, modificar, escrever de volta sem sobrescrever uma alteração concorrente), use memories.update com uma precondição content_sha256 em vez disso. Veja Atualizar abaixo.

Atualizar

memories.update() modifica um documento existente pelo seu ID mem_.... Você pode alterar content, path (uma renomeação), ou ambos em uma única chamada.

Renomear para um caminho ocupado retorna 409 conflict. O chamador deve excluir ou renomear o bloqueador primeiro, ou passar precondition={"type": "not_exists"} para tornar a renomeação uma operação sem efeito se algo já existir no destino.

O exemplo abaixo renomeia um documento para um caminho de arquivo:

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

Para editar o conteúdo de um documento sem sobrescrever uma escrita concorrente, passe uma precondição content_sha256. A atualização só é aplicada se o hash armazenado ainda corresponder ao que você leu; em caso de incompatibilidade, retorna 409 memory_precondition_failed, momento em que você relê o documento e tenta novamente com o estado atualizado.

Excluir um documento

Opcionalmente, passe expected_content_sha256 para uma exclusão condicional.

Versões de memória

Cada mutação em uma memória cria uma versão de memória imutável (memver_...). As versões se acumulam durante o tempo de vida da memória pai e formam a superfície de auditoria e reversão subjacente. A chamada memories.retrieve ativa sempre retorna o cabeçalho atual; os endpoints de versão fornecem o histórico completo.

Uma nova versão é criada em cada mutação:

• O primeiro memories.write em um caminho cria uma versão com operation: "created".
• memories.update que altera content, path, ou ambos cria uma versão com operation: "modified".
• memories.delete cria uma versão com operation: "deleted".

Use os endpoints de versão para auditar qual usuário ou agente alterou o quê e quando, para inspecionar ou restaurar um snapshot anterior, e para remover conteúdo sensível do histórico com redact.

Listar versões

Liste metadados de versão paginados para um armazenamento, do mais recente para o mais antigo. Filtre por memory_id, operation (created, modified ou deleted), session_id, api_key_id, ou um intervalo de tempo created_at_gte/created_at_lte. A resposta de lista não inclui o corpo content; busque versões individuais com retrieve quando precisar do conteúdo completo.

Recuperar uma versão

Buscar uma versão individual retorna os mesmos campos da resposta de lista mais o corpo content completo.

Redigir uma versão

Redigir apaga o conteúdo de uma versão histórica enquanto preserva a trilha de auditoria (quem fez o quê, quando). Use para fluxos de trabalho de conformidade, como remoção de segredos vazados, PII ou solicitações de exclusão de usuários. Redigir limpa permanentemente content, content_sha256, content_size_bytes e path; todos os outros campos, incluindo o ator e os carimbos de data/hora, são preservados.