Ferramenta de memória

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

A memória dá suporte à recuperação de contexto sob demanda. Em vez de carregar todas as informações relevantes antecipadamente, um agente registra o que aprende em arquivos de memória e os lê de volta quando necessário. Isso mantém o contexto ativo focado na tarefa atual, o que é importante para sessões de longa duração que, de outra forma, sobrecarregariam a janela de contexto. Consulte Engenharia de contexto eficaz para entender o padrão mais amplo.

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



Casos de uso

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



Como funciona

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

Como a ferramenta de memória é do lado do cliente, o 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 o armazenamento real, como um diretório por usuário ou chaves em um banco de dados. A memória reside inteiramente em sua aplicação. Uma conversa posterior continua a partir da mesma memória quando envia a mesma entrada 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. O 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."

O 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. O 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. O 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

A ferramenta de memória está disponível de forma geral na Messages API: nenhum cabeçalho beta é necessário. Usá-la requer duas etapas:

1. Adicione a ferramenta de memória à sua solicitação. A entrada tools {"type": "memory_20250818", "name": "memory"} é toda a configuração: o name deve ser memory, e você não define um esquema de entrada para uma ferramenta fornecida pela Anthropic.
2. Implemente um handler do 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-4-8",
    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 do 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 e retorna o resultado em um bloco tool_result, depois envia a conversa de volta para que o Claude possa continuar: o loop de uso de ferramentas padrão.

Quatro SDKs fornecem helpers da ferramenta de memória que lidam com a interface da ferramenta e o loop. Crie uma subclasse de BetaAbstractMemoryTool (Python e C#), use betaMemoryTool (TypeScript) ou implemente BetaMemoryToolHandler (Java) para dar suporte à memória com seu próprio armazenamento, como arquivos em disco, um banco de dados, armazenamento em nuvem ou arquivos criptografados. Python e TypeScript também incluem uma implementação pronta de sistema de arquivos local, BetaLocalFilesystemMemoryTool. As interfaces de helper e tool-runner residem no namespace beta de cada SDK, embora a ferramenta de memória em si esteja disponível de forma geral. 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, e o PHP encapsula sua closure de handler em seu BetaRunnableTool genérico. Todos os três usam um armazenamento em memória que você substitui 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-4-8",
    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 nos exemplos de Go, PHP e Ruby os mantêm autocontidos: cada um faz o dispatch com base no campo command no 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 caminho que esses armazenamentos de demonstração omitem. Para 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 do lado do cliente deve lidar com os seguintes comandos. Estas especificações descrevem os comportamentos e strings de retorno recomendados: o 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 do diretório ou o conteúdo do arquivo com intervalos de linhas opcionais:

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

view_range é opcional e se aplica a visualizações 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 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 de sistema de arquivos local dos SDKs (BetaLocalFilesystemMemoryTool) criam a raiz de memória antes da primeira chamada do Claude e retornam o cabeçalho da listagem seguido por 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 de 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: Indexado a partir de 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 do Claude também diz que view exibe arquivos de imagem (.jpg, .jpeg e .png) e trunca a visualização de texto de arquivos com mais de 16.000 caracteres. Espere chamadas de view em caminhos de imagem e visualizações subsequentes com intervalos de 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 do Claude diz que create "cria ou sobrescreve" um arquivo, então espere chamadas de create em caminhos que já existem. Retornar o erro é o comportamento de referência, e sobrescrever em vez disso é 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 por 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 ao Claude que ele não pode excluir o próprio diretório /memories, então rejeite um delete cujo caminho seja a raiz de 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 ao Claude que ele não pode renomear o próprio diretório /memories, então rejeite um rename cujo old_path seja a raiz de memória.



Orientação de prompting

Quando a ferramenta de memória está presente em tools da sua solicitação, a API adiciona automaticamente esta instrução ao 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 do Claude já o instrui a manter o diretório de memória organizado, então você não precisa repetir essa instrução. Se o Claude ainda criar arquivos de memória desorganizados, você pode reforçar isso 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 o Claude escreve na memória. Por exemplo: "Escreva apenas informações relevantes para <topic> no seu sistema de memória."



Considerações de segurança

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



Informações sensíveis

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



Tamanho do armazenamento de arquivos

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



Expiração de memória

Exclua periodicamente arquivos de memória que não foram 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 permanecem dentro do diretório de memória
• Rejeite caminhos contendo 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 caminho integrados 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 ao 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 combina com a edição de contexto para gerenciar conversas de longa duração. Para detalhes, consulte Edição de contexto.



Uso com compactação

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

Para agentes de longa duração, considere usar ambos: a compactação mantém o contexto ativo pequeno sem contabilidade do lado do cliente, e a memória preserva as informações que devem sobreviver à sumarização.



Padrão de desenvolvimento de software multi-sessão

Para projetos de software que abrangem várias sessões de agente, configure os arquivos de memória deliberadamente em vez de escrevê-los de forma ad hoc conforme 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 última registrou.



Como o padrão funciona

1. Sessão inicializadora: A primeira sessão configura os arquivos de memória antes de qualquer trabalho substantivo começar. Isso inclui um log de progresso (rastreando o que foi feito e o que vem a seguir), uma lista de verificação de funcionalidades (definindo o escopo do trabalho) e uma referência a qualquer script de inicialização 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 reexplorar a base de código ou refazer decisões anteriores.

3. Atualização de fim de sessão: Antes de uma sessão terminar, ela atualiza o log de progresso com o que foi concluído e o que resta. 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 apenas após a verificação de ponta a ponta confirmar que ela funciona, não quando o código é escrito. Isso mantém o log de progresso preciso de sessão para sessão.



Próximos passos