A ferramenta de memória permite que o Claude armazene e recupere informações entre conversas através de um diretório de arquivos de memória. O Claude pode criar, ler, atualizar e excluir arquivos que persistem entre sessões, permitindo que ele construa conhecimento ao longo do tempo sem manter tudo na janela de contexto. A ferramenta de memória opera do lado do cliente—você controla onde e como os dados são armazenados através de sua própria infraestrutura.
A ferramenta de memória está atualmente em beta. Para habilitá-la, use o cabeçalho beta context-management-2025-06-27 em suas solicitações de API.Por favor, entre em contato através do nosso formulário de feedback para compartilhar seu feedback sobre este recurso.

​
Casos de uso

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

​
Como funciona

Quando habilitado, o Claude verifica automaticamente seu diretório de memória antes de iniciar tarefas. O Claude pode criar, ler, atualizar e excluir arquivos no diretório /memories para armazenar o que aprende enquanto trabalha, então 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, o 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. Por 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 ao Claude para ajudar com uma tarefa, o Claude verifica automaticamente seu diretório de memória primeiro. Aqui está como uma interação típica se parece: 1. Solicitação do usuário: 
"Me ajude 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": "Directory: /memories\n- customer_service_guidelines.xml\n- 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": "<guidelines>\n<addressing_customers>\n- Always address customers by their first name\n- 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..."

​
Modelos suportados

A ferramenta de memória está disponível em:
  • Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)

​
Começando

Para usar a ferramenta de memória:
  1. Inclua o cabeçalho beta context-management-2025-06-27 em suas solicitações de API
  2. Adicione a ferramenta de memória à sua solicitação
  3. Implemente manipuladores do lado do cliente para operações de memória
Para lidar com operações da ferramenta de memória em sua aplicação, você precisa implementar manipuladores para cada comando de memória. Nossos SDKs fornecem auxiliares da ferramenta de memória que lidam com a interface da ferramenta—você pode criar uma subclasse de BetaAbstractMemoryTool (Python) ou usar betaMemoryTool (TypeScript) para implementar seu próprio backend de memória (baseado em arquivo, banco de dados, armazenamento em nuvem, arquivos criptografados, etc.).Para exemplos funcionais, veja:

​
Uso básico

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 2048,
        "messages": [
            {
                "role": "user",
                "content": "Estou trabalhando em um web scraper Python que continua travando com um erro de timeout. Aqui está a função problemática:\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\nPor favor, me ajude a debugar isso."
            }
        ],
        "tools": [{
            "type": "memory_20250818",
            "name": "memory"
        }]
    }'

​
Comandos da ferramenta

Sua implementação do lado do cliente precisa lidar com estes comandos da ferramenta de memória:

​
view

Mostra conteúdo do diretório ou conteúdo do arquivo com intervalos de linha opcionais: 
{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10]  // Opcional: visualizar linhas específicas
}

​
create

Criar ou sobrescrever um arquivo: 
{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Notas da reunião:\n- Discutimos cronograma do projeto\n- Próximos passos definidos\n"
}

​
str_replace

Substituir texto em um arquivo: 
{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Cor favorita: azul",
  "new_str": "Cor favorita: verde"
}

​
insert

Inserir texto em uma linha específica: 
{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Revisar documentação da ferramenta de memória\n"
}

​
delete

Excluir um arquivo ou diretório: 
{
  "command": "delete",
  "path": "/memories/old_file.txt"
}

​
rename

Renomear ou mover um arquivo/diretório: 
{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}

​
Orientação de prompting

Incluímos automaticamente esta instrução ao prompt do sistema quando a ferramenta de memória está incluída: 
IMPORTANTE: SEMPRE VISUALIZE SEU DIRETÓRIO DE MEMÓRIA ANTES DE FAZER QUALQUER OUTRA COISA.
PROTOCOLO DE MEMÓRIA:
1. Use o comando `view` de sua ferramenta `memory` para verificar progresso anterior.
2. ... (trabalhe na tarefa) ...
     - Conforme você progride, registre status / progresso / pensamentos etc em sua memória.
ASSUMA INTERRUPÇÃO: Sua janela de contexto pode ser redefinida a qualquer momento, então você corre o risco de perder qualquer progresso que não esteja registrado em seu diretório de memória.
Se você observar o 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 excluir 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 o Claude escreve na memória, por exemplo, “Apenas anote informações relevantes para <tópico> em seu sistema de memória.”

​
Considerações de segurança

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

​
Informações sensíveis

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

​
Tamanho de armazenamento de arquivo

Considere rastrear tamanhos de arquivos de memória e prevenir 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 o Claude paginar através do conteúdo.

​
Expiração de memória

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

​
Proteção contra travessia de caminho

Entradas de caminho maliciosas poderiam tentar acessar arquivos fora do diretório /memories. Sua implementação DEVE validar todos os caminhos para prevenir ataques de travessia de diretório.
Considere estas salvaguardas:
  • Valide que todos os caminhos começam com /memories
  • Resolva caminhos para sua forma canônica e verifique que permanecem dentro do diretório de memória
  • Rejeite caminhos contendo sequências como ../, ..\\, ou outros padrões de travessia
  • Observe sequências de travessia codificadas em URL (%2e%2e%2f)
  • Use utilitários de segurança de caminho integrados de sua linguagem (por exemplo, pathlib.Path.resolve() e relative_to() do Python)

​
Tratamento de erros

A ferramenta de memória usa os mesmos padrões de tratamento de erros que a ferramenta de editor de texto. Erros comuns incluem arquivo não encontrado, erros de permissão e caminhos inválidos.