Ferramenta de memória

A ferramenta de memória permite que Claude armazene e recupere informações entre conversas através de um diretório de arquivo de memória. Claude pode criar, ler, atualizar e deletar arquivos que persistem entre sessões, permitindo que ele construa conhecimento ao longo do tempo sem manter tudo na janela de contexto.

Este é o primitivo chave para recuperação de contexto just-in-time: em vez de carregar todas as informações relevantes antecipadamente, agentes armazenam o que aprendem em memória e o recuperam sob demanda. Isso mantém o contexto ativo focado no que é atualmente relevante, crítico para fluxos de trabalho de longa duração onde carregar tudo de uma vez sobrecarregaria a janela de contexto. Veja Engenharia de contexto eficaz para o padrão mais amplo.

A ferramenta de memória opera no lado do cliente: você controla onde e como os dados são armazenados através de sua própria infraestrutura.

Casos de uso

• Manter contexto do projeto em múltiplas execuções de agente
• Aprender com interações, decisões e feedback anteriores
• Construir bases de conhecimento ao longo do tempo
• Permitir aprendizado entre conversas onde Claude melhora em fluxos de trabalho recorrentes

Como funciona

Quando ativada, Claude verifica automaticamente seu diretório de memória antes de iniciar tarefas. Claude pode criar, ler, atualizar e deletar arquivos no diretório /memories para armazenar o que aprende enquanto trabalha, depois referenciar essas memórias em conversas futuras para lidar com tarefas similares de forma mais eficaz ou continuar de onde parou.

Como esta é uma ferramenta do lado do cliente, Claude faz chamadas de ferramenta para executar operações de memória, e sua aplicação executa essas operações localmente. Isso lhe dá controle completo sobre onde e como a memória é armazenada. Para segurança, você deve restringir todas as operações de memória ao diretório /memories.

Exemplo: Como funcionam as chamadas da ferramenta de memória

Quando você pede a Claude para ajudar com uma tarefa, Claude verifica automaticamente seu diretório de memória primeiro. Aqui está o que uma interação típica parece:

1. Solicitação do usuário:

"Ajude-me a responder a este ticket de atendimento ao cliente."

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

"Vou ajudá-lo a responder ao ticket de atendimento ao cliente. Deixe-me verificar minha memória para qualquer contexto anterior."

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": "Aqui estão os arquivos e diretórios até 2 níveis de profundidade em /memories, excluindo itens ocultos e node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/refund_policies.xml"
}

4. Claude lê 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": "Aqui está o conteúdo de /memories/customer_service_guidelines.xml com números de linha:\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:

"Com base em suas diretrizes de atendimento ao cliente, posso ajudá-lo a elaborar uma resposta. Por favor, compartilhe os detalhes do ticket..."

Para suporte de modelo, veja a Referência de ferramentas.

Começando

Para usar a ferramenta de memória:

1. Adicione a ferramenta de memória à sua solicitação
2. Implemente manipuladores do lado do cliente para operações de memória

Uso básico

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n    for i in range(retries):\n        try:\n            response = requests.get(url, timeout=5)\n            return response.text\n        except requests.exceptions.Timeout:\n            if i == retries - 1:\n                raise\n            time.sleep(1)\n```\n\nPlease help me debug this.",
        }
    ],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)

Comandos de ferramenta

Sua implementação do lado do cliente precisa lidar com esses comandos da ferramenta de memória. Embora essas especificações descrevam os comportamentos recomendados com os quais Claude está mais familiarizado, você pode modificar sua implementação e retornar strings conforme necessário para seu caso de uso.

view

Mostra conteúdo de diretório ou conteúdo de arquivo com intervalos de linha opcionais:

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10] // Opcional: visualizar linhas específicas
}

Valores de retorno

Para diretórios: Retorne uma listagem que mostra arquivos e diretórios com seus tamanhos:

Aqui estão os arquivos e diretórios até 2 níveis de profundidade em {path}, excluindo itens ocultos e node_modules:
{size}    {path}
{size}    {path}/{filename1}
{size}    {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 começando com .) e node_modules
• Usa caractere de tabulação entre tamanho e caminho

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

Aqui está o conteúdo de {path} com números de linha:
{line_numbers}{tab}{content}

Formatação de número de linha:

• Largura: 6 caracteres, alinhados à direita com preenchimento de espaço
• Separador: Caractere de tabulação entre número de linha e conteúdo
• Indexação: 1-indexada (primeira linha é linha 1)
• Limite de linha: 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:

Aqui está o conteúdo de /memories/notes.txt com números de linha:
     1	Hello World
     2	This is line two
    10	Line ten
   100	Line one hundred

Tratamento de erros

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

create

Criar 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"

str_replace

Substituir texto em um arquivo:

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

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ório

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

insert

Inserir texto em uma linha específica:

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

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ório

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

delete

Deletar um arquivo ou diretório:

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

Valores de retorno

• Sucesso: "Successfully deleted {path}"

Tratamento de erros

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

Tratamento de diretório

Deleta o diretório e todo seu conteúdo recursivamente.

rename

Renomear ou mover um arquivo/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ório

Renomeia o diretório.

Orientação de prompting

Esta instrução é automaticamente incluída no prompt do sistema quando a ferramenta de memória está ativada:

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.

Se você observar Claude criando arquivos de memória desorganizados, você pode incluir esta instrução:

Nota: ao editar sua pasta de memória, sempre tente manter seu conteúdo atualizado, coerente e organizado. Você pode renomear ou deletar arquivos que não são mais relevantes. Não crie novos arquivos a menos que seja necessário.

Você também pode orientar o que Claude escreve em memória. Por exemplo: "Escreva apenas informações relevantes para <topic> em seu sistema de memória."

Considerações de segurança

Aqui estão preocupações de segurança importantes ao implementar seu armazenamento de memória:

Informações sensíveis

Claude geralmente se recusa a escrever informações sensíveis em arquivos de memória. No entanto, você pode querer implementar validação mais rigorosa que remova informações potencialmente sensíveis.

Tamanho de armazenamento de arquivo

Considere rastrear tamanhos de arquivo de memória e evitar que arquivos cresçam muito. Considere adicionar um número máximo de caracteres que o comando de leitura de memória pode retornar, e deixe Claude paginar através do conteúdo.

Expiração de memória

Considere limpar periodicamente arquivos de memória que não foram acessados em um tempo estendido.

Proteção contra traversal de caminho

Considere essas salvaguardas:

• Valide que todos os caminhos começam com /memories
• Resolva 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 traversal
• Observe sequências de traversal codificadas em URL (%2e%2e%2f)
• Use 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 similares à ferramenta de editor de texto. Veja as seções de comando de ferramenta individual acima para mensagens de erro detalhadas e comportamentos. Erros comuns incluem arquivo não encontrado, erros de permissão, caminhos inválidos e correspondências de texto duplicadas.

Integração de edição de contexto

A ferramenta de memória se emparelha com edição de contexto para gerenciar conversas de longa duração. Para detalhes, veja Edição de contexto.

Usando com Compactação

A ferramenta de memória também pode ser emparelhada com compactação, que fornece sumarização de contexto de conversa anterior no lado do servidor. Enquanto edição de contexto limpa resultados de ferramenta específicos no lado do cliente, compactação automaticamente sumariza a conversa inteira no lado do servidor quando se aproxima do limite da janela de contexto.

Para fluxos de trabalho agênticos de longa duração, considere usar ambos: compactação mantém o contexto ativo gerenciável sem contabilidade do lado do cliente, e memória persiste informações importantes através de limites de compactação para que nada crítico seja perdido no resumo.

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

Para projetos de software de longa duração que abrangem múltiplas sessões de agente, arquivos de memória precisam ser inicializados deliberadamente, não apenas escritos ad hoc conforme o trabalho progride. O padrão abaixo transforma memória em um mecanismo de recuperação estruturado, para que cada nova sessão possa continuar exatamente de onde a última parou.

Como funciona

1. Sessão inicializadora: A primeira sessão configura os artefatos de memória antes de qualquer trabalho substancial 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 recursos (definindo o escopo do trabalho), e uma referência a qualquer script de inicialização ou inicialização que o projeto precisa.

2. Sessões subsequentes: Cada nova sessão abre lendo esses artefatos de memória. Isso recupera o estado completo do projeto em segundos, sem precisar re-explorar a base de código ou retomar 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 completado e o que permanece. Isso garante que a próxima sessão tenha um ponto de partida preciso.

Princípio chave

Trabalhe em um recurso por vez. Apenas marque um recurso como completo após verificação de ponta a ponta confirmar que funciona, não apenas após o código ser escrito. Isso mantém o log de progresso confiável e evita que scope creep se agrave entre sessões.

Próximos passos