Pular para o conteúdo principal

Memória e Edição de Contexto

Avançado

Um agente de execução longa tem dois inimigos: ele esquece o que aprendeu no momento em que a conversa termina, e sua janela de contexto enche com saídas de ferramentas obsoletas até transbordar. A Anthropic fornece uma primitiva para cada um — a memory tool (persistência) e a edição de contexto (poda) — e elas são projetadas para serem usadas juntas.

What you'll learn
  • O que é a memory tool — um armazenamento de arquivos do lado do cliente em /memories que você implementa, não a Anthropic
  • Os seis comandos que seu handler deve responder: view, create, str_replace, insert, delete, rename
  • Por que a validação de path-traversal é inegociável quando você a integra
  • Como a edição de contexto limpa automaticamente resultados de ferramentas antigos quando o contexto ultrapassa um limite de tokens
  • Como combinar ambos sob um único cabeçalho beta, e as armadilhas com caching e ordenação

Dois problemas, duas ferramentas​

Mantenha as duas ideias separadas na sua cabeça:

  • Memory tool = persistência entre sessões. Claude lê e escreve arquivos; você os armazena.
  • Edição de contexto = poda dentro de uma sessão. A API descarta resultados de ferramentas obsoletos do prompt antes que ele chegue ao Claude.

Esta página combina com Prompt Caching e com a economia de tokens para o lado de custo, e com Engenharia de Contexto e harnesses de agentes de execução longa para o porquê.

Vocabulário de memória e contexto
Pressione Enter ou Espaço para virar o cartão. Use as setas esquerda e direita para navegar entre os cartões.Termo exibido.
1 / 5

A memory tool é uma ferramenta que você implementa​

Isto confunde as pessoas: habilitar a memory tool não lhe dá armazenamento hospedado pela Anthropic. É uma ferramenta do lado do cliente. Claude emite chamadas de ferramenta como view ou create; sua aplicação as executa contra qualquer backend que você escolher — arquivos locais, um banco de dados, blobs criptografados, armazenamento em nuvem — e retorna o resultado. Você é dono de onde os bytes ficam (e é também por isso que ela é elegível para Zero-Data-Retention).

Quando a ferramenta está habilitada, a Anthropic injeta uma instrução de sistema dizendo ao Claude para verificar seu diretório de memória antes de fazer qualquer outra coisa, e para registrar o progresso enquanto trabalha, de modo que nada se perca se o contexto for reiniciado.

Passo 1 — habilitar a ferramenta​

Adicione a ferramenta à sua requisição. A string de tipo é a versão datada memory_20250818.

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "Help me respond to this support ticket."}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)

Os SDKs oficiais incluem helpers de memória para que você não precise montar a interface da ferramenta na mão — faça subclasse de BetaAbstractMemoryTool (Python, C#), use betaMemoryTool (TypeScript), ou implemente BetaMemoryToolHandler (Java). Eles lhe entregam um hook limpo onde você pluga seu armazenamento.

Passo 2 — responder aos seis comandos​

Seu handler deve implementar estes. As strings que o Claude espera de volta são específicas — combine com elas para que o modelo interprete os resultados corretamente.

Guided walkthrough1 of 6
  1. Liste um diretório (arquivos até 2 níveis de profundidade, com tamanhos legíveis por humanos) ou retorne o conteúdo de um arquivo com números de linha indexados a partir de 1. view_range opcional para ler uma fatia.

Um view real do diretório retorna algo como isto — note o cabeçalho literal e os tamanhos separados por tabulação, que o modelo é treinado para parsear:

Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:
4.0K	/memories
1.5K	/memories/customer_service_guidelines.xml
2.0K	/memories/refund_policies.xml

Passo 3 — proteja os paths (não pule isto)​

A memory tool permite que um modelo emita strings de path arbitrárias. Uma conversa envenenada ou um payload de prompt-injection pode tentar escapar de /memories e ler ou sobrescrever arquivos em outro lugar da sua máquina. Trate todo path recebido como hostil.

Watch out
  • Rejeite qualquer path que não resolva para dentro de /memories.
  • Canonicalize antes de verificar — em Python, Path(p).resolve() e então verifique que .relative_to(memories_root) não levanta exceção.
  • Bloqueie ../, ..\, e traversal codificado em URL como %2e%2e%2f.
  • Limite os tamanhos de arquivo e o comprimento de leitura para que um agente desgovernado não possa esgotar o disco ou explodir o próximo prompt.

Este validador é o jogo inteiro — fixe-o e teste-o antes de qualquer outra coisa entrar em produção:

Guarda contra path-traversal (Python)

from pathlib import Path

MEMORY_ROOT = Path("/srv/agent/memories").resolve()

def safe_path(requested: str) -> Path:
  # Map the model's /memories/... onto your real root, then prove containment.
  rel = requested.removeprefix("/memories").lstrip("/")
  candidate = (MEMORY_ROOT / rel).resolve()
  candidate.relative_to(MEMORY_ROOT)  # raises ValueError if it escaped
  return candidate

A edição de contexto evita que a janela transborde​

A memória resolve o esquecimento. O problema oposto — uma janela de contexto entupida com blocos tool_result antigos de 40 buscas web atrás — é o que a edição de contexto resolve. Assim que o prompt ultrapassa um limite de tokens, a API limpa os resultados de ferramentas mais antigos (substituindo-os por um placeholder curto para que o Claude saiba que foram removidos) antes que o prompt seja enviado ao modelo. Seu cliente mantém o histórico completo e não editado; apenas o que chega ao modelo é aparado.

Ela depende de um cabeçalho beta:

anthropic-beta: context-management-2025-06-27

Você a configura com um array context_management.edits. A estratégia principal é clear_tool_uses_20250919:

message = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    betas=["context-management-2025-06-27"],
    messages=[...],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},  # start clearing past 30k
                "keep": {"type": "tool_uses", "value": 3},            # always keep the last 3
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                "exclude_tools": ["memory"],                          # never clear memory calls
                "clear_tool_inputs": False,                           # keep the call args, drop results
            }
        ]
    },
)

O que os botões significam:

ParâmetroPadrãoO que controla
trigger100.000 tokens de entradaQuando a limpeza entra em ação
keep3 usos de ferramentaQuantos pares recentes de uso/resultado de ferramenta são sempre preservados
clear_at_leastnenhumMínimo de tokens liberados por ativação — use-o para que uma invalidação de cache realmente valha a pena
exclude_toolsnenhumFerramentas nunca limpas (ex.: memory, web_search)
clear_tool_inputsfalseSe também deve descartar os argumentos da chamada da ferramenta, não apenas o resultado

A resposta lhe diz o que ela fez, sob context_management.applied_edits — ex.: cleared_tool_uses e cleared_input_tokens — para que você possa registrar quanto foi recuperado.

Há uma estratégia irmã, clear_thinking_20251015, que poda blocos antigos de extended-thinking. Se você usar ambas, liste clear_thinking_20251015 primeiro no array edits.

Pro tip
  • Limpar resultados de ferramentas invalida qualquer prefixo de prompt-cache no ponto de limpeza — combine-o com clear_at_least para que você só pague essa invalidação quando estiver liberando um pedaço significativo.
  • exclude_tools: ["memory"] é a jogada usual: você quer que as próprias anotações do agente persistam, não que sejam varridas junto com resultados de busca obsoletos.
  • Edição de contexto (corte do lado do cliente) e compactação (sumarização do lado do servidor) são recursos diferentes — para execuções muito longas você pode combinar os dois.

Por que combiná-los — os números​

Usados juntos, os dois recursos permitem que um agente execute muito além de uma única janela de contexto: a edição de contexto mantém a janela viva enxuta, e tudo o que importa é escrito na memória antes de ser limpo. A Anthropic relata que combinar memória com edição de contexto deu uma melhoria de 39% em uma avaliação de busca agêntica, e que a edição de contexto sozinha cortou o uso de tokens em 84% em um teste de busca web de 100 turnos.

Um padrão que funciona: o log de projeto multi-sessão​

O uso mais limpo da memória é inicializá-la deliberadamente em vez de escrever arquivos de forma improvisada:

Guided walkthrough1 of 4
  1. Antes de qualquer trabalho real, escreva um log de progresso, um checklist de funcionalidades, e uma nota apontando para qualquer script de inicialização que o projeto precise.

Teste seu entendimento​

Check yourself

0/3
  1. Onde os dados da memory tool de fato são armazenados?
  2. O que a estratégia clear_tool_uses_20250919 da edição de contexto remove?
  3. Por que você deve validar todo path que a memory tool recebe?

Fontes e leitura adicional​