---
title: Ferramenta de memória
url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/memory-tool
description: Permita que Claude armazene e recupere informações entre conversas implementando as operações de arquivo da ferramenta de memória em sua aplicação.
---

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](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) 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.

<Note>
  Entre em contato pelo [formulário de feedback](https://forms.gle/YXC2EKGMhjN1c4L88) para compartilhar sua opinião sobre este recurso.
</Note>

<Note>
  Para saber como a "zero data retention" (retenção zero de dados), ou ZDR, se aplica a este recurso, consulte [API e retenção de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention).
</Note>

## 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls)). 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/memory-tool#path-traversal-protection)).

### 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:**

```text wrap
"Help me respond to this customer service ticket."
```

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

```text wrap
"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:

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

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

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```text wrap
"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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference).

## 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/memory-tool#path-traversal-protection) antes de escrevê-lo.

## Uso básico

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "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"
      }]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 2048
  tools:
    - type: memory_20250818
      name: memory
  messages:
    - role: user
      content: Help me respond to this customer service ticket.
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const anthropic = new Anthropic();

  const message = await anthropic.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" }]
  });

  console.log(message);
  ```

  ```csharp C#
  var client = new AnthropicClient();

  var message = await client.Messages.Create(
      new()
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 2048,
          Messages =
          [
              new()
              {
                  Role = Role.User,
                  Content = "Help me respond to this customer service ticket.",
              },
          ],
          Tools = [new MemoryTool20250818()],
      }
  );

  Console.WriteLine(message);
  ```

  ```go Go
  client := anthropic.NewClient()

  message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 2048,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Help me respond to this customer service ticket.")),
  	},
  	Tools: []anthropic.ToolUnionParam{
  		{OfMemoryTool20250818: &anthropic.MemoryTool20250818Param{}},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(message)
  ```

  ```java Java
  import com.anthropic.models.messages.MemoryTool20250818;
  // ...
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(2048L)
      .addTool(MemoryTool20250818.builder().build())
      .addUserMessage("Help me respond to this customer service ticket.")
      .build();

    Message message = client.messages().create(params);
    IO.println(message);
  ```

  ```php PHP
  $client = new Client();

  $message = $client->messages->create(
      model: Model::CLAUDE_OPUS_5_5,
      maxTokens: 2048,
      messages: [
          [
              'role' => 'user',
              'content' => 'Help me respond to this customer service ticket.',
          ],
      ],
      tools: [new MemoryTool20250818],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: Anthropic::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"
      }
    ]
  )
  puts message
  ```
</CodeGroup>

## 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls) padrão.

Quatro SDKs fornecem "helpers" (auxiliares) 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 guardar a memória no 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`. Os helpers e o "tool runner" (executor de ferramentas) 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.

<CodeGroup exclude="shell">
  ```python Python
  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)
  ```

  ```typescript TypeScript
  import Anthropic from "@anthropic-ai/sdk";
  import { betaMemoryTool } from "@anthropic-ai/sdk/helpers/beta/memory";
  import { BetaLocalFilesystemMemoryTool } from "@anthropic-ai/sdk/tools/memory/node";

  const client = new Anthropic();

  const backend = await BetaLocalFilesystemMemoryTool.init("./memory");
  const memory = betaMemoryTool(backend); // or pass your own handlers object

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

  const finalMessage = await runner;
  console.log(finalMessage.content);
  ```

  ```csharp C#
  using Anthropic;
  using Anthropic.Helpers.Beta;
  using Anthropic.Models.Beta.Messages;

  var client = new AnthropicClient();

  // Sua subclasse de BetaAbstractMemoryTool
  var memory = new FilesystemMemoryTool("./memories");

  var runner = client.Beta.Messages.ToolRunner(
      new MessageCreateParams
      {
          Model = Anthropic.Models.Messages.Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          Messages =
          [
              new()
              {
                  Role = Role.User,
                  Content = "Remember that customer Acme Corp prefers email follow-ups.",
              },
          ],
      },
      [memory],
      maxIterations: 10
  );

  var finalMessage = await runner.RunUntilDoneAsync();
  Console.WriteLine(finalMessage);
  ```

  ```go Go
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"
  	"slices"
  	"sort"
  	"strings"

  	"github.com/anthropics/anthropic-sdk-go"
  )

  // Um armazenamento em memória que mapeia caminhos de arquivos de memória para seus conteúdos.
  // Em produção, use seu próprio armazenamento.
  var store = map[string]string{}

  type memoryCommand struct {
  	Command    string `json:"command"`
  	Path       string `json:"path"`
  	FileText   string `json:"file_text"`
  	OldStr     string `json:"old_str"`
  	NewStr     string `json:"new_str"`
  	InsertLine int    `json:"insert_line"`
  	InsertText string `json:"insert_text"`
  	OldPath    string `json:"old_path"`
  	NewPath    string `json:"new_path"`
  }

  func executeMemory(raw json.RawMessage) string {
  	var cmd memoryCommand
  	if err := json.Unmarshal(raw, &cmd); err != nil {
  		return "Error: invalid memory command"
  	}
  	switch cmd.Command {
  	case "view":
  		if content, ok := store[cmd.Path]; ok {
  			lines := strings.Split(strings.TrimSuffix(content, "\n"), "\n")
  			for i, line := range lines {
  				lines[i] = fmt.Sprintf("%6d\t%s", i+1, line)
  			}
  			return fmt.Sprintf("Here's the content of %s with line numbers:\n%s", cmd.Path, strings.Join(lines, "\n"))
  		}
  		if cmd.Path == "/memories" {
  			listing := []string{"1.0K\t/memories"}
  			for path := range store {
  				listing = append(listing, "1.0K\t"+path)
  			}
  			sort.Strings(listing[1:])
  			return fmt.Sprintf("Here're the files and directories up to 2 levels deep in %s, excluding hidden items and node_modules:\n%s", cmd.Path, strings.Join(listing, "\n"))
  		}
  		return fmt.Sprintf("The path %s does not exist. Please provide a valid path.", cmd.Path)
  	case "create":
  		store[cmd.Path] = cmd.FileText
  		return "File created successfully at: " + cmd.Path
  	case "str_replace":
  		content, ok := store[cmd.Path]
  		if !ok || !strings.Contains(content, cmd.OldStr) {
  			return fmt.Sprintf("No replacement was performed, old_str `%s` did not appear verbatim in %s.", cmd.OldStr, cmd.Path)
  		}
  		store[cmd.Path] = strings.Replace(content, cmd.OldStr, cmd.NewStr, 1)
  		return "The memory file has been edited."
  	case "insert":
  		content, ok := store[cmd.Path]
  		if !ok {
  			return fmt.Sprintf("Error: The path %s does not exist", cmd.Path)
  		}
  		lines := strings.Split(content, "\n")
  		if cmd.InsertLine < 0 || cmd.InsertLine > len(lines) {
  			return fmt.Sprintf("Error: Invalid `insert_line` parameter: %d. It should be within the range of lines of the file: [0, %d]", cmd.InsertLine, len(lines))
  		}
  		lines = slices.Insert(lines, cmd.InsertLine, strings.TrimSuffix(cmd.InsertText, "\n"))
  		store[cmd.Path] = strings.Join(lines, "\n")
  		return fmt.Sprintf("The file %s has been edited.", cmd.Path)
  	case "delete":
  		if _, ok := store[cmd.Path]; !ok {
  			return fmt.Sprintf("Error: The path %s does not exist", cmd.Path)
  		}
  		delete(store, cmd.Path)
  		return "Successfully deleted " + cmd.Path
  	case "rename":
  		if _, ok := store[cmd.OldPath]; !ok {
  			return fmt.Sprintf("Error: The path %s does not exist", cmd.OldPath)
  		}
  		if _, ok := store[cmd.NewPath]; ok {
  			return fmt.Sprintf("Error: The destination %s already exists", cmd.NewPath)
  		}
  		store[cmd.NewPath] = store[cmd.OldPath]
  		delete(store, cmd.OldPath)
  		return fmt.Sprintf("Successfully renamed %s to %s", cmd.OldPath, cmd.NewPath)
  	default:
  		return "Error: unknown command " + cmd.Command
  	}
  }

  func main() {
  	client := anthropic.NewClient()
  	tools := []anthropic.ToolUnionParam{{OfMemoryTool20250818: &anthropic.MemoryTool20250818Param{}}}
  	messages := []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Remember that customer Acme Corp prefers email follow-ups.")),
  	}

  	for {
  		message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  			Model:     anthropic.ModelClaudeOpus5_5,
  			MaxTokens: 1024,
  			Messages:  messages,
  			Tools:     tools,
  		})
  		if err != nil {
  			log.Fatal(err)
  		}
  		if message.StopReason != anthropic.StopReasonToolUse {
  			for _, block := range message.Content {
  				if block.Type == "text" {
  					fmt.Println(block.Text)
  				}
  			}
  			break
  		}
  		results := []anthropic.ContentBlockParamUnion{}
  		for _, block := range message.Content {
  			if block.Type == "tool_use" {
  				results = append(results, anthropic.NewToolResultBlock(block.ID, executeMemory(block.Input), false))
  			}
  		}
  		messages = append(messages, message.ToParam(), anthropic.NewUserMessage(results...))
  	}
  }
  ```

  ```java Java
  import com.anthropic.client.AnthropicClient;
  import com.anthropic.client.okhttp.AnthropicOkHttpClient;
  import com.anthropic.helpers.BetaMemoryToolHandler;
  import com.anthropic.helpers.BetaToolRunner;
  import com.anthropic.models.beta.messages.BetaMemoryTool20250818;
  import com.anthropic.models.beta.messages.BetaMessage;
  import com.anthropic.models.beta.messages.MessageCreateParams; // beta package, not models.messages
  import com.anthropic.models.beta.messages.ToolRunnerCreateParams;
  import com.anthropic.models.messages.Model;
  import java.nio.file.Path;

  void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    // Sua implementação de BetaMemoryToolHandler dos seis comandos de memória
    BetaMemoryToolHandler handler = new FileSystemMemoryToolHandler(Path.of("memories"));

    MessageCreateParams createParams = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(1024L)
      .addTool(BetaMemoryTool20250818.builder().build())
      .addUserMessage("Remember that customer Acme Corp prefers email follow-ups.")
      .build();

    ToolRunnerCreateParams runnerParams = ToolRunnerCreateParams.builder()
      .betaMemoryToolHandler(handler)
      .initialMessageParams(createParams)
      .maxIterations(10)
      .build();

    BetaToolRunner runner = client.beta().messages().toolRunner(runnerParams);
    for (BetaMessage message : runner) {
      IO.println(message);
    }
  }
  ```

  ```php PHP
  <?php

  use Anthropic\Beta\Messages\BetaMemoryTool20250818;
  use Anthropic\Client;
  use Anthropic\Lib\Tools\BetaRunnableTool;
  use Anthropic\Messages\Model;

  $client = new Client();

  // Um armazenamento em memória que mapeia caminhos de arquivos de memória para seus conteúdos.
  // Use seu próprio armazenamento em produção.
  $store = [];

  $memory = new BetaRunnableTool(
      definition: new BetaMemoryTool20250818,
      run: function (array $input) use (&$store): string {
          $path = $input['path'] ?? '';
          switch ($input['command']) {
              case 'view':
                  if (isset($store[$path])) {
                      $numbered = [];
                      foreach (explode("\n", preg_replace('/\n\z/', '', $store[$path])) as $i => $line) {
                          $numbered[] = sprintf("%6d\t%s", $i + 1, $line);
                      }
                      return "Here's the content of {$path} with line numbers:\n" . implode("\n", $numbered);
                  }
                  if ($path === '/memories') {
                      $listing = ["1.0K\t/memories"];
                      foreach (array_keys($store) as $stored) {
                          $listing[] = "1.0K\t{$stored}";
                      }
                      return "Here're the files and directories up to 2 levels deep in {$path}, excluding hidden items and node_modules:\n" . implode("\n", $listing);
                  }
                  return "The path {$path} does not exist. Please provide a valid path.";
              case 'create':
                  $store[$path] = $input['file_text'];
                  return "File created successfully at: {$path}";
              case 'str_replace':
                  $position = strpos($store[$path] ?? '', $input['old_str']);
                  if ($position === false) {
                      return "No replacement was performed, old_str `{$input['old_str']}` did not appear verbatim in {$path}.";
                  }
                  $store[$path] = substr_replace($store[$path], $input['new_str'] ?? '', $position, strlen($input['old_str']));
                  return 'The memory file has been edited.';
              case 'insert':
                  if (!isset($store[$path])) {
                      return "Error: The path {$path} does not exist";
                  }
                  $lines = explode("\n", $store[$path]);
                  if ($input['insert_line'] < 0 || $input['insert_line'] > count($lines)) {
                      return "Error: Invalid `insert_line` parameter: {$input['insert_line']}. It should be within the range of lines of the file: [0, " . count($lines) . "]";
                  }
                  array_splice($lines, $input['insert_line'], 0, [preg_replace('/\n\z/', '', $input['insert_text'])]);
                  $store[$path] = implode("\n", $lines);
                  return "The file {$path} has been edited.";
              case 'delete':
                  if (!isset($store[$path])) {
                      return "Error: The path {$path} does not exist";
                  }
                  unset($store[$path]);
                  return "Successfully deleted {$path}";
              case 'rename':
                  if (!isset($store[$input['old_path']])) {
                      return "Error: The path {$input['old_path']} does not exist";
                  }
                  if (isset($store[$input['new_path']])) {
                      return "Error: The destination {$input['new_path']} already exists";
                  }
                  $store[$input['new_path']] = $store[$input['old_path']];
                  unset($store[$input['old_path']]);
                  return "Successfully renamed {$input['old_path']} to {$input['new_path']}";
              default:
                  return "Error: unknown command {$input['command']}";
          }
      },
  );

  $runner = $client->beta->messages->toolRunner(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Remember that customer Acme Corp prefers email follow-ups.']],
      model: Model::CLAUDE_OPUS_5_5,
      tools: [$memory],
      maxIterations: 10,
  );

  $finalMessage = $runner->runUntilDone();
  print_r($finalMessage->content);
  ```

  ```ruby Ruby
  require "anthropic"

  client = Anthropic::Client.new
  TOOLS = [{type: "memory_20250818", name: "memory"}].freeze

  # Um armazenamento em memória que mapeia caminhos de arquivos de memória para seus conteúdos.
  # Em produção, use seu próprio armazenamento.
  STORE = {}

  def execute_memory(input)
    path = input[:path]
    case input[:command]
    when "view"
      if STORE.key?(path)
        lines = STORE[path].chomp.split("\n", -1)
        lines = [""] if lines.empty?
        numbered = lines.each_with_index.map { |line, i| format("%6d\t%s", i + 1, line) }
        "Here's the content of #{path} with line numbers:\n#{numbered.join("\n")}"
      elsif path == "/memories"
        listing = ["1.0K\t/memories"] + STORE.keys.map { |stored| "1.0K\t#{stored}" }
        "Here're the files and directories up to 2 levels deep in #{path}, excluding hidden items and node_modules:\n#{listing.join("\n")}"
      else
        "The path #{path} does not exist. Please provide a valid path."
      end
    when "create"
      STORE[path] = input[:file_text]
      "File created successfully at: #{path}"
    when "str_replace"
      unless STORE.key?(path) && STORE[path].include?(input[:old_str])
        return "No replacement was performed, old_str `#{input[:old_str]}` did not appear verbatim in #{path}."
      end
      STORE[path] = STORE[path].sub(input[:old_str]) { input[:new_str].to_s }
      "The memory file has been edited."
    when "insert"
      return "Error: The path #{path} does not exist" unless STORE.key?(path)
      lines = STORE[path].split("\n", -1)
      lines = [""] if lines.empty?
      if input[:insert_line] < 0 || input[:insert_line] > lines.length
        return "Error: Invalid `insert_line` parameter: #{input[:insert_line]}. It should be within the range of lines of the file: [0, #{lines.length}]"
      end
      lines.insert(input[:insert_line], input[:insert_text].chomp)
      STORE[path] = lines.join("\n")
      "The file #{path} has been edited."
    when "delete"
      return "Error: The path #{path} does not exist" unless STORE.key?(path)
      STORE.delete(path)
      "Successfully deleted #{path}"
    when "rename"
      return "Error: The path #{input[:old_path]} does not exist" unless STORE.key?(input[:old_path])
      return "Error: The destination #{input[:new_path]} already exists" if STORE.key?(input[:new_path])
      STORE[input[:new_path]] = STORE.delete(input[:old_path])
      "Successfully renamed #{input[:old_path]} to #{input[:new_path]}"
    else
      "Error: unknown command #{input[:command]}"
    end
  end

  messages = [{role: "user", content: "Remember that customer Acme Corp prefers email follow-ups."}]
  loop do
    message = client.messages.create(
      model: Anthropic::Model::CLAUDE_OPUS_5_5,
      max_tokens: 1024,
      messages: messages,
      tools: TOOLS
    )
    unless message.stop_reason == :tool_use
      puts message.content
      break
    end
    tool_results = message.content.filter_map do |block|
      next unless block.type == :tool_use
      {type: "tool_result", tool_use_id: block.id, content: execute_memory(block.input)}
    end
    messages << {role: "assistant", content: message.content} << {role: "user", content: tool_results}
  end
  ```
</CodeGroup>

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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/memory-tool#tool-commands). Um handler de produção também precisa da [validação de caminhos](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/memory-tool#path-traversal-protection) que esses armazenamentos de demonstração omitem. Para ver os exemplos completos dos próprios SDKs, consulte:

* Python: [examples/memory/basic.py](https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py)
* TypeScript: [examples/tools-helpers-memory.ts](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/examples/tools-helpers-memory.ts)
* C#: [MemoryToolExample](https://github.com/anthropics/anthropic-sdk-csharp/tree/main/examples/MemoryToolExample)
* Java: [BetaMemoryToolExample.java](https://github.com/anthropics/anthropic-sdk-java/blob/main/anthropic-java-example/src/main/java/com/anthropic/example/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:

```json
{
  "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:

```text
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 de sistema de arquivos local, `BetaLocalFilesystemMemoryTool`, ela cria a raiz da memória antes da primeira chamada de Claude e retorna 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:

```text wrap
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:**

```text
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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```text wrap
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:

```text wrap
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

<Warning>
  Um caminho malicioso como `/memories/../../secrets.env` pode alcançar arquivos fora do diretório `/memories`. Sua implementação deve validar todos os caminhos em todos os comandos para evitar ataques de "directory traversal" (travessia de diretórios).
</Warning>

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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/text-editor-tool#handle-errors). As mensagens de erro de cada comando estão listadas em [Comandos da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/memory-tool#tool-commands). Para retornar um erro a Claude, defina `is_error` como `true` no resultado da ferramenta e coloque a mensagem em `content`:

```json
{
  "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](https://platform.claude.com/docs/pt-BR/build-with-claude/context-editing).

## Uso com compactação

A ferramenta de memória também pode ser combinada com a ["compaction" (compactação)](https://platform.claude.com/docs/pt-BR/build-with-claude/compaction), 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.

<Tip>
  Para um estudo de caso detalhado desse padrão na prática, incluindo o script inicializador, a estrutura do arquivo de progresso e a recuperação baseada em git, consulte [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents).
</Tip>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Ferramenta Bash" icon="terminal" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/bash-tool">
    Execute comandos de shell em uma sessão bash persistente.
  </Card>

  <Card title="Edição de contexto" icon="edit" href="https://platform.claude.com/docs/pt-BR/build-with-claude/context-editing">
    Gerencie automaticamente o contexto da conversa à medida que ele cresce com a edição de contexto.
  </Card>

  <Card title="Compactação" icon="stack" href="https://platform.claude.com/docs/pt-BR/build-with-claude/compaction">
    Compactação de contexto no lado do servidor para gerenciar conversas longas que se aproximam dos limites da janela de contexto.
  </Card>

  <Card title="Referência de ferramentas" icon="book" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference">
    Diretório de ferramentas fornecidas pela Anthropic e referência para propriedades opcionais de definição de ferramentas.
  </Card>
</CardGroup>