Usando memória de agente

As sessões da API Managed Agents são efêmeras por padrão. Quando uma sessão termina, tudo o que o agente aprendeu desaparece. 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 escreve aprendizados duráveis quando termina - nenhum prompt ou configuração adicional é necessária do seu lado.

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 versão de memória imutável para suportar auditoria e reversão de alterações de memória.

Criar um armazenamento de memória

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

store = client.beta.memory_stores.create(
    name="User Preferences",
    description="Per-user preferences and project context.",
)
print(store.id)  # memstore_01Hx...

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

Preencha-o com conteúdo (opcional)

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

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

Anexar um armazenamento de 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. É fornecido ao Claude além do name e description do armazenamento de memória, e é limitado a 4.096 caracteres.

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

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "memory_store",
            "memory_store_id": store.id,
            "access": "read_write",
            "prompt": "User preferences and project context. Check before starting any task.",
        }
    ],
)

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 proprietários ou regras de acesso diferentes. 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-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 única, 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 a ferramentas de memória. As interações do agente com armazenamentos de memória são registradas como eventos agent.tool_use no fluxo de eventos.

Visualizar e editar memórias

Os armazenamentos de memória podem ser gerenciados diretamente via API. Use isso para construir fluxos de trabalho de revisão, corrigir memórias ruins ou preencher armazenamentos antes de qualquer execução de sessão.

Listar memórias

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

page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for memory in page.data:
    print(
        f"{memory.path}  ({memory.size_bytes} bytes, sha={memory.content_sha256[:8]})"
    )

Ler uma memória

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

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

Criar uma memória

Use memories.write para fazer upsert de uma memória por caminho. Se nada existir no caminho, ela é criada; se uma memória já existir lá, seu conteúdo é substituído. Para mutar uma memória existente por mem_... ID (por exemplo, para renomear seu caminho ou aplicar com segurança uma edição de conteúdo), use memories.update (veja Atualizar uma memória abaixo).

mem = client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use tabs, not spaces.",
)

Escritas seguras (concorrência otimista)

Passe precondition={"type": "not_exists"} para memories.write para torná-lo uma proteção somente de criação. Se uma memória já existir no caminho, a escrita retorna 409 memory_precondition_failed em vez de substituí-la. Use isso ao preencher um armazenamento e você quer evitar sobrescrever conteúdo existente.

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use 2-space indentation.",
    precondition={"type": "not_exists"},
)

Para editar com segurança uma memória existente (ler, modificar, escrever de volta sem sobrescrever uma alteração concorrente), use memories.update com uma precondição content_sha256. Veja Atualizar uma memória abaixo.

Atualizar uma memória

memories.update() modifica uma memória existente por seu mem_... ID. 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 deletar ou renomear o bloqueador primeiro, ou passar precondition={"type": "not_exists"} para tornar a renomeação uma operação nula se algo já existir no destino.

O exemplo abaixo renomeia uma memória para um caminho de arquivo:

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

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

Para editar o conteúdo de uma memória sem sobrescrever uma escrita concorrente, passe uma precondição content_sha256. A atualização só se aplica se o hash armazenado ainda corresponder ao que você leu; em caso de incompatibilidade, retorna 409 memory_precondition_failed, ponto em que você relê a memória e tenta novamente contra 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},
)

Deletar uma memória

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

Opcionalmente passe expected_content_sha256 para uma exclusão condicional.

Auditar alteraçõ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 a vida útil da memória pai e formam a superfície de auditoria e reversão subjacente. A chamada memories.retrieve ao vivo sempre retorna o head atual; os endpoints de versão fornecem o histórico completo.

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

• O primeiro memories.write para 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

Listar metadados de versão paginados para um armazenamento, mais recentes primeiro. Filtrar 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 da lista não inclui o corpo content; busque versões individuais com retrieve quando precisar do conteúdo completo.

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

Recuperar uma versão

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

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

Redacionar uma versão

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

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