---
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.
featureMetadata:
  status: stable
  zdr:
    eligibility: eligible
    note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). Armazenamento de memória no lado do cliente, em que você controla a retenção de dados.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: stable
    Amazon Bedrock: stable
    Amazon Bedrock (bedrock-runtime): stable
    Claude Platform on AWS: stable
    Claude Models on Google Cloud (Anthropic managed): stable
    Claude Models on Google Cloud (Google managed): stable
    Microsoft Foundry: stable
---

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](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 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>
  Use o [formulário de feedback](https://forms.gle/YXC2EKGMhjN1c4L88) para compartilhar seu feedback sobre este recurso.
</Note>

## 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](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 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](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 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](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: 2026-10-21" \
    -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 UserMessageParam { 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 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls) 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.

<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;
  using Model = Anthropic.Models.Messages.Model;

  var client = new AnthropicClient();

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

  var runner = client.Beta.Messages.ToolRunner(
      new MessageCreateParams
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          Messages =
          [
              new BetaUserMessageParam
              {
                  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/v2"
  )

  // 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 seu conteúdo.
  # Use seu próprio armazenamento em produção.
  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 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](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 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, 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:

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

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

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

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

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

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

```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`, portanto 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`, 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:

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

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

<Warning>
  Um caminho malicioso como `/memories/../../secrets.env` pode alcançar arquivos fora do diretório `/memories`. Sua implementação deve validar cada caminho em cada comando para impedir 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 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](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 edição de contexto para gerenciar conversas de longa duração. Para 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 [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. 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.

<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 [Harnesses eficazes para agentes de longa duração](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>

## Disponibilidade

Ferramenta de memória está disponível em todos os modelos e é elegível para retenção zero de dados e prontidão para HIPAA.

### Suporte da API

#### [Messages API](https://platform.claude.com/docs/pt-BR/build-with-claude/working-with-messages)

* Disponibilidade: Disponível

| Status     | Modelos                                                                    |
| ---------- | -------------------------------------------------------------------------- |
| Disponível | [Todos os modelos](https://platform.claude.com/docs/pt-BR/models/overview) |

### Tratamento de dados

[Visão geral do tratamento de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#feature-eligibility)

| Item     | Retenção zero de dados                                                                                                                                       | HIPAA    |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| Status   | Elegível (exclui [Modelos cobertos](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)) | Elegível |
| Detalhes | Armazenamento de memória no lado do cliente, em que você controla a retenção de dados.                                                                       | —        |

Endpoints aplicáveis:

* `/v1/messages` com a ferramenta `memory`