Ferramenta de memória

A ferramenta de memória permite que Claude armazene e recupere informações entre conversas em um diretório de arquivos de memória. Claude pode criar, ler, atualizar e excluir arquivos que persistem entre sessões. Assim, ele acumula conhecimento ao longo do tempo sem manter tudo na "context window" (janela de contexto).

A memória oferece suporte à recuperação de contexto "just-in-time" (sob demanda). Em vez de carregar todas as informações relevantes de antemão, um agente registra o que aprende em arquivos de memória e os lê novamente quando necessário. Isso mantém o contexto ativo focado na tarefa atual, o que é importante em sessões de longa duração que, de outra forma, sobrecarregariam a janela de contexto. Consulte Effective context engineering para conhecer o padrão mais amplo.

A ferramenta de memória opera no "client-side" (lado do cliente): Claude solicita operações de arquivo, e sua aplicação as executa. Você controla onde e como os dados são armazenados por meio da sua própria infraestrutura.

Casos de uso

• Manter o contexto do projeto ao longo de várias sessões de agente
• Aplicar a novas tarefas as lições de interações, decisões e feedbacks anteriores
• Construir uma base de conhecimento ao longo do tempo

Como funciona

Quando a ferramenta de memória está habilitada, Claude verifica automaticamente seu diretório de memória antes de iniciar uma tarefa. Enquanto trabalha, Claude armazena o que aprende em arquivos sob /memories e os lê novamente em conversas posteriores para dar continuidade ao trabalho anterior.

Como a ferramenta de memória é executada no lado do cliente, Claude apenas solicita operações de memória. Sua aplicação executa cada solicitação no armazenamento que você controla e retorna o resultado em um bloco tool_result (consulte Lidar com chamadas de ferramentas). O caminho /memories é um prefixo que seu handler mapeia para um armazenamento real, como um diretório por usuário ou chaves em um banco de dados. A memória fica inteiramente na sua aplicação. Uma conversa posterior continua a partir da mesma memória quando envia a mesma entrada em tools e seu handler serve o mesmo armazenamento. Por segurança, restrinja todas as operações de memória ao diretório /memories (consulte Proteção contra path traversal).

Exemplo: como funcionam as chamadas da ferramenta de memória

Uma interação típica se parece com isto:

1. Solicitação do usuário:

"Help me respond to this customer service ticket."

2. Claude verifica o diretório de memória:

"I'll help you respond to the customer service ticket. Let me check my memory for any previous context."

Claude chama a ferramenta de memória:

{
  "type": "tool_use",
  "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories"
  }
}

3. Sua aplicação retorna o conteúdo do diretório:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/refund_policies.xml"
}

4. Claude lê os arquivos relevantes:

{
  "type": "tool_use",
  "id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories/customer_service_guidelines.xml"
  }
}

5. Sua aplicação retorna o conteúdo do arquivo:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": "Here's the content of /memories/customer_service_guidelines.xml with line numbers:\n     1\t<guidelines>\n     2\t<addressing_customers>\n     3\t- Always address customers by their first name\n     4\t- Use empathetic language\n..."
}

6. Claude usa a memória para ajudar:

"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."

A ferramenta de memória está disponível em todos os modelos Claude 4 e posteriores. Para a lista completa de ferramentas fornecidas pela Anthropic, consulte a Referência de ferramentas.

Primeiros passos

Usar a ferramenta de memória envolve duas etapas:

1. Adicione a ferramenta de memória à sua solicitação. A entrada {"type": "memory_20250818", "name": "memory"} em tools é toda a configuração necessária: o name deve ser memory, e você não define um schema de entrada para uma ferramenta fornecida pela Anthropic.
2. Implemente um handler no lado do cliente para cada comando de memória. Seu handler deve rejeitar caminhos fora de /memories, então leia Proteção contra path traversal antes de escrevê-lo.

Uso básico

client = anthropic.Anthropic()

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

print(message)

Implementar o handler de memória

A resposta de Claude a uma solicitação como a anterior termina com um bloco tool_use que solicita uma operação de memória, como view /memories. Sua aplicação executa a operação, retorna o resultado em um bloco tool_result e envia a conversa de volta para que Claude possa continuar. Esse é o loop de uso de ferramentas padrão.

Quatro SDKs fornecem "helpers" (auxiliares) da ferramenta de memória que cuidam da interface da ferramenta e do loop. Para guardar a memória no seu próprio armazenamento, como arquivos em disco, um banco de dados, armazenamento em nuvem ou arquivos criptografados, crie uma subclasse de BetaAbstractMemoryTool (Python e C#), use betaMemoryTool (TypeScript) ou implemente BetaMemoryToolHandler (Java). Python e TypeScript também incluem uma implementação pronta para o sistema de arquivos local, BetaLocalFilesystemMemoryTool. Os helpers e o "tool runner" (executor de ferramentas) ficam no namespace beta de cada SDK, embora a própria ferramenta de memória não exija um cabeçalho beta. Os SDKs de Go e Ruby não têm helper de memória, então esses exemplos executam o loop de uso de ferramentas por conta própria. Já o PHP envolve a closure do seu handler em seu BetaRunnableTool genérico. Os três exemplos usam um armazenamento em memória que você deve substituir pelo seu próprio armazenamento.

import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool

client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")

runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Remember that customer Acme Corp prefers email follow-ups.",
        }
    ],
    tools=[memory],
)

final_message = runner.until_done()
print(final_message.content)

Os armazenamentos em memória dos exemplos de Go, PHP e Ruby tornam esses exemplos autocontidos: cada um decide o que fazer com base no campo command do input do bloco tool_use e retorna as strings descritas em Comandos da ferramenta. Um handler de produção também precisa da validação de caminhos que esses armazenamentos de demonstração omitem. Para ver os exemplos completos dos próprios SDKs, consulte:

• Python: examples/memory/basic.py
• TypeScript: examples/tools-helpers-memory.ts
• C#: MemoryToolExample
• Java: BetaMemoryToolExample.java

Comandos da ferramenta

Sua implementação no lado do cliente deve lidar com os comandos a seguir. Estas especificações descrevem os comportamentos e as strings de retorno recomendados. Claude lê qualquer texto que o resultado da sua ferramenta contenha, então você pode retornar strings diferentes se sua aplicação precisar.

view

Mostra o conteúdo de um diretório ou de um arquivo, com intervalos de linhas opcionais:

{
  "command": "view",
  "path": "/memories/notes.txt",
  "view_range": [1, 10]
}

view_range é opcional e se aplica à visualização de arquivos de texto. [start_line, end_line] retorna essas linhas, e [start_line, -1] retorna tudo de start_line até o final do arquivo.

Valores de retorno

Para diretórios: retorne uma listagem que mostre arquivos e diretórios com seus tamanhos:

Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:
{size}\t{path}
{size}\t{path}/{filename1}
{size}\t{path}/{filename2}

• Lista arquivos com até 2 níveis de profundidade
• Mostra tamanhos legíveis por humanos (por exemplo, 5.5K, 1.2M)
• Exclui itens ocultos (arquivos que começam com .) e node_modules
• Usa um caractere de tabulação entre o tamanho e o caminho

O primeiro view de /memories em um armazenamento vazio não é um erro. As ferramentas de memória baseadas no sistema de arquivos local dos SDKs (BetaLocalFilesystemMemoryTool) criam a raiz da memória antes da primeira chamada de Claude. Elas retornam o cabeçalho da listagem seguido de uma única linha de tamanho e caminho para o próprio diretório vazio.

Para arquivos: retorne o conteúdo do arquivo com um cabeçalho e números de linha:

Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}

Formatação dos números de linha:

• Largura: 6 caracteres, alinhados à direita com preenchimento de espaços
• Separador: caractere de tabulação entre o número da linha e o conteúdo
• Indexação: começa em 1 (a primeira linha é a linha 1)
• Limite de linhas: arquivos com mais de 999.999 linhas devem retornar um erro: "File {path} exceeds maximum line limit of 999,999 lines."

Exemplo de saída:

Here's the content of /memories/notes.txt with line numbers:
     1	Hello World
     2	This is line two
    10	Line ten
   100	Line one hundred

A descrição da ferramenta de Claude também informa que view exibe arquivos de imagem (.jpg, .jpeg e .png). Ela também informa que view trunca a visualização de texto de arquivos com mais de 16.000 caracteres. Espere chamadas view em caminhos de imagens e visualizações subsequentes com intervalos em arquivos longos.

Tratamento de erros

• Arquivo ou diretório não existe: "The path {path} does not exist. Please provide a valid path."

create

Cria um novo arquivo:

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}

Valores de retorno

• Sucesso: "File created successfully at: {path}"

Tratamento de erros

• Arquivo já existe: "Error: File {path} already exists"

A descrição da ferramenta de Claude diz que create "cria ou sobrescreve" um arquivo, então espere chamadas create em caminhos que já existem. Retornar o erro é o comportamento de referência, mas sobrescrever o arquivo também é uma escolha de implementação válida.

str_replace

Substitui texto em um arquivo:

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Favorite color: blue",
  "new_str": "Favorite color: green"
}

new_str é opcional para str_replace: quando omitido, old_str é excluído sem substituição.

Valores de retorno

• Sucesso: "The memory file has been edited." seguido de um trecho do arquivo editado com números de linha

Tratamento de erros

• Arquivo não existe: "Error: The path {path} does not exist. Please provide a valid path."
• Texto não encontrado: "No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."
• Texto duplicado: quando old_str aparece várias vezes, retorne: "No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique"

Tratamento de diretórios

Se o caminho for um diretório, retorne um erro de "arquivo não existe".

insert

Insere texto em uma linha específica:

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Review memory tool documentation\n"
}

insert_text é inserido após a linha insert_line, e 0 insere no início do arquivo.

Valores de retorno

• Sucesso: "The file {path} has been edited."

Tratamento de erros

• Arquivo não existe: "Error: The path {path} does not exist"
• Número de linha inválido: "Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"

Tratamento de diretórios

Se o caminho for um diretório, retorne um erro de "arquivo não existe".

delete

Exclui um arquivo ou diretório:

{
  "command": "delete",
  "path": "/memories/old_file.txt"
}

Valores de retorno

• Sucesso: "Successfully deleted {path}"

Tratamento de erros

• Arquivo ou diretório não existe: "Error: The path {path} does not exist"

Tratamento de diretórios

Exclui o diretório e todo o seu conteúdo recursivamente. A descrição da ferramenta informa a Claude que ele não pode excluir o próprio diretório /memories, então rejeite um delete cujo caminho seja a raiz da memória.

rename

Renomeia ou move um arquivo ou diretório:

{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}

Valores de retorno

• Sucesso: "Successfully renamed {old_path} to {new_path}"

Tratamento de erros

• Origem não existe: "Error: The path {old_path} does not exist"
• Destino já existe: retorne um erro (não sobrescreva): "Error: The destination {new_path} already exists"

Tratamento de diretórios

Renomeia o diretório. A descrição da ferramenta informa a Claude que ele não pode renomear o próprio diretório /memories, então rejeite um rename cujo old_path seja a raiz da memória.

Orientações de prompting

Quando a ferramenta de memória está presente em tools na sua solicitação, a API adiciona automaticamente esta instrução ao "system prompt" (prompt do sistema). Você não precisa enviá-la:

IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
   - As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.

A descrição da ferramenta de Claude já o instrui a manter o diretório de memória organizado, então você não precisa repetir essa instrução. Se Claude ainda criar arquivos de memória desorganizados, você pode reforçar a instrução no seu prompt:

Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary.

Você também pode orientar o que Claude escreve na memória. Por exemplo: "Only write down information relevant to <topic> in your memory system."

Considerações de segurança

Sua aplicação executa todas as operações de arquivo que Claude solicita, então estas salvaguardas são de sua responsabilidade:

Informações sensíveis

Claude geralmente se recusa a escrever informações sensíveis em arquivos de memória. Para garantias mais fortes, adicione uma validação que remova dados sensíveis antes que seu handler escreva o arquivo.

Tamanho do armazenamento de arquivos

Acompanhe o tamanho dos arquivos de memória e limite o quanto um arquivo pode crescer. Considere limitar quantos caracteres o comando view retorna e deixe Claude paginar o restante com view_range.

Expiração da memória

Exclua periodicamente os arquivos de memória que não são acessados há muito tempo.

Proteção contra path traversal

Considere estas salvaguardas:

• Valide que todos os caminhos começam com /memories
• Resolva os caminhos para sua forma canônica e verifique se eles permanecem dentro do diretório de memória
• Rejeite caminhos que contenham sequências como ../, ..\\ ou outros padrões de travessia
• Fique atento a sequências de travessia codificadas em URL (%2e%2e%2f)
• Use os utilitários de segurança de caminhos nativos da sua linguagem (por exemplo, pathlib.Path.resolve() e relative_to() do Python)

Tratamento de erros

A ferramenta de memória usa padrões de tratamento de erros semelhantes aos da ferramenta de editor de texto. As mensagens de erro de cada comando estão listadas em Comandos da ferramenta. Para retornar um erro a Claude, defina is_error como true no resultado da ferramenta e coloque a mensagem em content:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Error: The path /memories/notes.txt does not exist",
  "is_error": true
}

Integração com edição de contexto

A ferramenta de memória funciona em conjunto com a "context editing" (edição de contexto) para gerenciar conversas de longa duração. Para mais detalhes, consulte Edição de contexto.

Uso com compactação

A ferramenta de memória também pode ser combinada com a "compaction" (compactação), que resume o contexto mais antigo da conversa no lado do servidor. A edição de contexto limpa resultados de ferramentas específicos no cliente. Já a compactação resume automaticamente toda a conversa no servidor quando ela se aproxima do limite da janela de contexto.

Para agentes de longa duração, considere usar ambas. A compactação mantém o contexto ativo pequeno sem controle manual no lado do cliente, e a memória preserva as informações que precisam sobreviver ao resumo.

Padrão de desenvolvimento de software multissessão

Em projetos de software que abrangem várias sessões de agente, configure os arquivos de memória de forma deliberada, em vez de escrevê-los de improviso à medida que o trabalho avança. O padrão a seguir transforma a memória em um mecanismo de recuperação: cada nova sessão retoma a partir do estado que a anterior registrou.

Como o padrão funciona

1. Sessão inicializadora: a primeira sessão configura os arquivos de memória antes que qualquer trabalho substancial comece. Isso inclui:

   • Um log de progresso, que acompanha o que foi feito e o que vem a seguir
   • Uma checklist de funcionalidades, que define o escopo do trabalho
   • Uma referência a qualquer script de inicialização de que o projeto precise

2. Sessões subsequentes: cada nova sessão começa lendo esses arquivos de memória. Isso restaura o estado do projeto sem precisar explorar novamente a base de código ou refazer decisões anteriores.

3. Atualização ao final da sessão: antes de terminar, a sessão atualiza o log de progresso com o que foi concluído e o que falta. Isso garante que a próxima sessão tenha um ponto de partida preciso.

Princípio fundamental

Trabalhe em uma funcionalidade por vez. Marque uma funcionalidade como concluída somente depois que uma verificação de ponta a ponta confirmar que ela funciona, e não quando o código for escrito. Isso mantém o log de progresso preciso de uma sessão para outra.

Próximos passos