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, acumulando 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 antecipadamente, um agente registra o que aprende em arquivos de memória e os lê de volta sob demanda. 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 conhecer o padrão mais amplo.

A ferramenta de memória opera no 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 em 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, 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ê de volta em conversas posteriores para continuar o 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 em um 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 reside inteiramente na 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. 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 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 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, portanto 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 e retorna o resultado em um bloco tool_result, depois envia a conversa de volta para que 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 com o loop. Crie uma subclasse de BetaAbstractMemoryTool (Python e C#), use betaMemoryTool (TypeScript) ou implemente BetaMemoryToolHandler (Java) para apoiar a 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 baseada no sistema de arquivos local, BetaLocalFilesystemMemoryTool. As superfícies de helper e de tool runner ficam no namespace beta do seu 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, e o PHP envolve a closure do seu handler em seu BetaRunnableTool genérico. 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-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 nos exemplos de Go, PHP e Ruby os mantêm autocontidos: cada um despacha 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 caminhos 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 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, portanto 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 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 fim do arquivo.

Valores de retorno

Para diretórios: Retorne uma lista 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. Onde seu SDK inclui uma ferramenta de memória baseada no sistema de arquivos local, BetaLocalFilesystemMemoryTool, ela cria a raiz da memória antes da primeira chamada de Claude e retorna o cabeçalho da lista 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: 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 de 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 view em caminhos de imagens 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 de Claude diz que create “cria ou sobrescreve” um arquivo, portanto espere chamadas 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 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 aparecer 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, portanto 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, portanto rejeite um rename cujo old_path seja a raiz da memória.

Orientações de prompting

Quando a ferramenta de memória está presente no tools da 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á diz para manter o diretório de memória organizado, portanto você não precisa repetir essa instrução. Se Claude ainda criar arquivos de memória desorganizados, você pode reforçá-la 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 cada operação de arquivo que Claude solicita, portanto estas salvaguardas são 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 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 Claude paginar o restante com view_range.

Expiração da memória

Exclua periodicamente 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 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 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 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 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 a 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. 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 ambas: a compactação mantém o contexto ativo pequeno sem controle no lado do cliente, e a memória preserva as informações que precisam sobreviver à sumarização.

Padrão de desenvolvimento de software multissessã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 improvisada à 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 última 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 registro de progresso (acompanhando o que foi feito e o que vem a seguir), uma checklist de funcionalidades (definindo o escopo do trabalho) e uma referência a qualquer script de startup ou 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 explorar novamente 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 registro 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-chave

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

Próximos passos