Usando a memória do agente

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

Visão geral

Um memory store é uma coleção de documentos de texto com escopo de workspace, otimizada para o Claude. Quando você anexa um store a uma sessão, ele é montado como um diretório dentro do sandbox da sessão. O agente o lê e escreve com as mesmas ferramentas de arquivo que usa para o restante do sistema de arquivos, e uma nota descrevendo cada montagem é adicionada automaticamente 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. Em sandboxes auto-hospedados, esse diretório não é uma montagem ao vivo. Em vez disso, o worker de ambiente do SDK baixa cada store anexado para o seu sandbox antes que as ferramentas do agente sejam executadas e mantém essa cópia sincronizada com o store.

Cada memória em um store é endereçada por um caminho e pode ser lida e editada diretamente pela API ou pelo Claude Console, permitindo ajustes, importação e exportação.

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

Criar um memory store

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

ant apply memory_store.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/memory_store.json
name: User Preferences
description: Per-user preferences and project context.

O id do memory store (memstore_...) é o que você passa ao anexar o store a uma sessão.

Preenchê-lo com conteúdo (opcional)

Pré-carregue um store com material de referência antes que qualquer agente seja executado:

client.beta.memory_stores.memories.create(
    store.id,
    path="/formatting_standards.md",
    content="All reports use GAAP formatting. Dates are ISO-8601...",
)

Anexar um memory store a uma sessão

Os memory stores são anexados no array resources[] da sessão quando a sessão é criada. Diferentemente dos recursos de arquivo, os memory stores 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. Você anexa memory stores da mesma forma para sessões em ambientes na nuvem e em ambientes auto-hospedados; ambientes auto-hospedados aceitam apenas recursos memory_store.

Opcionalmente, inclua instructions para fornecer orientação específica da sessão sobre como o agente deve usar este store. Elas são exibidas ao agente junto com o name e a description do store, 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.

session = client.beta.sessions.create(
    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.",
        }
    ],
)

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

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

Como o agente acessa a memória

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

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

Os memory stores podem ser gerenciados diretamente pela API. Use isso para construir fluxos de revisão, corrigir memórias ruins ou preencher stores antes que qualquer sessão seja executada.

Listar memórias

Liste as memórias em um store. Os resultados são retornados em uma ordem estável, definida pelo servidor.

• path_prefix restringe a lista a um diretório. Ele deve terminar com / e corresponde a segmentos de caminho inteiros, então path_prefix=/notes/ retorna /notes/todo.md, mas não /notes-archive/todo.md.
• depth controla a profundidade da listagem abaixo de path_prefix: omita-o (ou passe 0) para listar toda a subárvore, ou passe 1 para listar apenas os filhos imediatos. Outros valores retornam um erro 400.

page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for item in page.data:
    print(item.type, item.path)

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

Ler uma memória

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

retrieved = client.beta.memory_stores.memories.retrieve(
    mem.id,
    memory_store_id=store.id,
)
print(retrieved.content)

Consulte a referência de Recuperar uma memória para ver os parâmetros completos e o 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 = client.beta.memory_stores.memories.create(
    store.id,
    path="/preferences/formatting.md",
    content="Always use tabs, not spaces.",
)

Consulte a referência de Criar uma memória para ver os parâmetros completos e o 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:

client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id=store.id,
    path="/archive/2026_q1_formatting.md",
)

Consulte a referência de Atualizar uma memória para ver os parâmetros completos e o 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 divergência, releia a memória e tente novamente com o estado atualizado.

client.beta.memory_stores.memories.update(
    memory_id=mem.id,
    memory_store_id=store.id,
    content="CORRECTED: Always use 2-space indentation.",
    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)

Excluir uma memória

client.beta.memory_stores.memories.delete(
    mem.id,
    memory_store_id=store.id,
)

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

Auditar alterações de memória

Toda 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 redact.

As versões pertencem ao store (não à memória individual) e não são excluídas quando a própria memória é excluída, então a trilha de auditoria também cobre memórias excluídas, sujeita à retenção descrita abaixo. As versões são retidas por 30 dias após serem escritas; no entanto, as versões recentes de uma memória ativa 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 ativa 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, desde que a versão desejada ainda esteja retida).

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 pela API.

Listar versões

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

versions = client.beta.memory_stores.memory_versions.list(
    store.id,
    memory_id=mem.id,
)
for version in versions:
    print(f"{version.id}: {version.operation}")

version_id = versions.data[1].id

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

Recuperar uma versão

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

version = client.beta.memory_stores.memory_versions.retrieve(
    version_id,
    memory_store_id=store.id,
)
print(version.content)

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

Redigir uma versão

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

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) e depois redija a antiga.

client.beta.memory_stores.memory_versions.redact(
    version_id,
    memory_store_id=store.id,
)

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

Gerenciar memory stores

Além de create, os memory stores suportam retrieve, update, list, archive e delete.

Listar stores

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

for memory_store in client.beta.memory_stores.list(include_archived=True):
    print(memory_store.id, memory_store.name, memory_store.archived_at)

Consulte a referência de Listar memory stores para ver os parâmetros completos e o esquema de resposta.

Arquivar um store

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

client.beta.memory_stores.archive(store.id)

Consulte a referência de Arquivar um memory store para ver os parâmetros completos e o esquema de resposta.

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

Melhores práticas para gerenciamento de memória

Quando um store atinge seu limite de 10.000 memórias, as escritas em novas memórias falham: tanto chamadas diretas a memories.create quanto escritas de arquivo do agente em caminhos não mapeados. As 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 adequadamente caso o atinja.

• Use stores focados. Em vez de um grande store de uso geral, use stores menores construídos para fins específicos: um por usuário, um para conhecimento de domínio compartilhado e um para contexto específico do projeto. Cada store tem seu próprio limite de 10.000 memórias, então manter os stores com escopo definido reduz a chance de qualquer um deles encher.

• Condense ou faça a poda antes que o store encha. 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 store de saída separado, em vez de modificar o original. Migre suas sessões para esse store de saída e depois arquive ou exclua o original.

• Anexe um novo store quando fizer sentido. Se um store cresceu além do 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.