---
title: Strumento memoria
url: https://platform.claude.com/docs/it/agents-and-tools/tool-use/memory-tool
description: Consenti a Claude di archiviare e recuperare informazioni tra le conversazioni implementando le operazioni sui file dello strumento di memoria nella tua applicazione.
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). Archiviazione della memoria lato client in cui controlli tu la conservazione dei dati.
  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
---

Lo strumento di memoria consente a Claude di archiviare e recuperare informazioni tra le conversazioni in una directory di file di memoria. Claude può creare, leggere, aggiornare ed eliminare file che persistono tra le sessioni, costruendo conoscenza nel tempo senza mantenere tutto nella “context window” (finestra di contesto).

La memoria supporta il recupero del contesto “just-in-time” (al momento del bisogno). Invece di caricare in anticipo tutte le informazioni rilevanti, un agente registra ciò che apprende nei file di memoria e li rilegge su richiesta. Questo mantiene il contesto attivo focalizzato sull’attività corrente, il che è importante per le sessioni di lunga durata che altrimenti sovraccaricherebbero la finestra di contesto. Consulta [Context engineering efficace](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) per il modello più generale.

Lo strumento di memoria opera lato client: Claude richiede operazioni sui file e la tua applicazione le esegue. Controlli dove e come vengono archiviati i dati attraverso la tua infrastruttura.

<Note>
  Usa il [modulo di feedback](https://forms.gle/YXC2EKGMhjN1c4L88) per condividere il tuo feedback su questa funzionalità.
</Note>

## Casi d’uso

* Mantenere il contesto del progetto tra più sessioni dell’agente
* Applicare a nuove attività le lezioni apprese da interazioni, decisioni e feedback passati
* Costruire una base di conoscenza nel tempo

## Come funziona

Quando lo strumento di memoria è abilitato, Claude controlla automaticamente la propria directory di memoria prima di iniziare un’attività. Mentre lavora, Claude archivia ciò che apprende in file sotto `/memories` e li rilegge nelle conversazioni successive per continuare il lavoro precedente.

Poiché lo strumento di memoria è lato client, Claude si limita a richiedere operazioni di memoria. La tua applicazione esegue ogni richiesta sullo storage che controlli e restituisce il risultato in un blocco `tool_result` (consulta [Gestire le chiamate agli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/handle-tool-calls)). Il percorso `/memories` è un prefisso che il tuo handler mappa su uno storage reale, come una directory per utente o chiavi in un database. La memoria risiede interamente nella tua applicazione. Una conversazione successiva riprende dalla stessa memoria quando invia la stessa voce `tools` e il tuo handler serve lo stesso archivio. Per sicurezza, limita tutte le operazioni di memoria alla directory `/memories` (consulta [Protezione dal path traversal](https://platform.claude.com/docs/it/agents-and-tools/tool-use/memory-tool#path-traversal-protection)).

### Esempio: come funzionano le chiamate allo strumento di memoria

Un’interazione tipica si presenta così:

**1. Richiesta dell’utente:**

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

**2. Claude controlla la directory di memoria:**

```text wrap
"I'll help you respond to the customer service ticket. Let me check my memory for any previous context."
```

Claude chiama lo strumento di memoria:

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

**3. La tua applicazione restituisce il contenuto della directory:**

```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 legge i file rilevanti:**

```json
{
  "type": "tool_use",
  "id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories/customer_service_guidelines.xml"
  }
}
```

**5. La tua applicazione restituisce il contenuto del file:**

```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 la memoria per aiutare:**

```text wrap
"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."
```

Lo strumento di memoria è disponibile su tutti i modelli Claude 4 e successivi. Per l’elenco completo degli strumenti forniti da Anthropic, consulta il [Riferimento agli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference).

## Per iniziare

L’uso dello strumento di memoria richiede due passaggi:

1. Aggiungi lo strumento di memoria alla tua richiesta. La voce `tools` `{"type": "memory_20250818", "name": "memory"}` è l’intera configurazione: il `name` deve essere `memory` e non definisci uno schema di input per uno strumento fornito da Anthropic.
2. Implementa un handler lato client per ogni comando di memoria. Il tuo handler deve rifiutare i percorsi al di fuori di `/memories`, quindi leggi [Protezione dal path traversal](https://platform.claude.com/docs/it/agents-and-tools/tool-use/memory-tool#path-traversal-protection) prima di scriverlo.

## Utilizzo di base

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

## Implementare l’handler della memoria

La risposta di Claude a una richiesta come la precedente termina con un blocco `tool_use` che richiede un’operazione di memoria, come `view /memories`. La tua applicazione esegue l’operazione e restituisce il risultato in un blocco `tool_result`, poi rinvia la conversazione in modo che Claude possa continuare: il [ciclo di uso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/handle-tool-calls) standard.

Quattro SDK forniscono helper per lo strumento di memoria che gestiscono l’interfaccia dello strumento e il ciclo. Crea una sottoclasse di `BetaAbstractMemoryTool` (Python e C#), usa `betaMemoryTool` (TypeScript) o implementa `BetaMemoryToolHandler` (Java) per appoggiare la memoria al tuo spazio di archiviazione, come file su disco, un database, uno spazio di archiviazione cloud o file crittografati. Python e TypeScript includono anche un’implementazione pronta all’uso basata sul filesystem locale, `BetaLocalFilesystemMemoryTool`. Le interfacce dell’helper e del tool runner si trovano nel namespace beta del tuo SDK, anche se lo strumento di memoria in sé non richiede un header beta. Gli SDK Go e Ruby non hanno un helper per la memoria, quindi quegli esempi eseguono autonomamente il ciclo di uso degli strumenti, mentre PHP racchiude la closure del tuo handler nel suo `BetaRunnableTool` generico. Tutti e tre usano un archivio in memoria che sostituisci con il tuo spazio di archiviazione.

<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();

  // La tua sottoclasse di 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"
  )

  // Uno store in memoria che associa i percorsi dei file di memoria ai rispettivi contenuti.
  // Usa il tuo spazio di archiviazione in produzione.
  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();

      // La tua implementazione di BetaMemoryToolHandler dei sei comandi di memoria
      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();

  // Un archivio in memoria che associa i percorsi dei file di memoria ai rispettivi contenuti.
  // In produzione, usa il tuo sistema di archiviazione.
  $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

  # Uno store in memoria che associa i percorsi dei file di memoria ai rispettivi contenuti.
  # In produzione usa il tuo sistema di archiviazione.
  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>

Gli archivi in memoria negli esempi Go, PHP e Ruby li rendono autonomi: ciascuno smista in base al campo `command` nell’`input` del blocco `tool_use` e restituisce le stringhe descritte in [Comandi dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/memory-tool#tool-commands). Un handler di produzione necessita anche della [validazione dei percorsi](https://platform.claude.com/docs/it/agents-and-tools/tool-use/memory-tool#path-traversal-protection) che questi archivi dimostrativi tralasciano. Per gli esempi completi forniti dagli SDK, consulta:

* 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)

## Comandi dello strumento

La tua implementazione lato client deve gestire i seguenti comandi. Queste specifiche descrivono i comportamenti e le stringhe di ritorno consigliati: Claude legge qualunque testo contenga il risultato del tuo strumento, quindi puoi restituire stringhe diverse se la tua applicazione lo richiede.

### view

Mostra il contenuto di una directory o di un file, con intervalli di righe opzionali:

```json
{
  "command": "view",
  "path": "/memories/notes.txt",
  "view_range": [1, 10]
}
```

`view_range` è opzionale e si applica alle visualizzazioni di file di testo: `[start_line, end_line]` restituisce quelle righe, e `[start_line, -1]` restituisce tutto da `start_line` fino alla fine del file.

#### Valori di ritorno

**Per le directory:** restituisci un elenco che mostra file e directory con le relative dimensioni:

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

* Elenca i file fino a 2 livelli di profondità
* Mostra dimensioni leggibili (ad esempio, `5.5K`, `1.2M`)
* Esclude gli elementi nascosti (file che iniziano con `.`) e `node_modules`
* Usa un carattere di tabulazione tra la dimensione e il percorso

La prima `view` di `/memories` su un archivio vuoto non è un errore. Quando il tuo SDK include uno strumento di memoria basato sul filesystem locale, `BetaLocalFilesystemMemoryTool`, questo crea la radice della memoria prima della prima chiamata di Claude e restituisce l’intestazione dell’elenco seguita da una singola riga con dimensione e percorso per la directory vuota stessa.

**Per i file:** restituisci il contenuto del file con un’intestazione e i numeri di riga:

```text wrap
Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}
```

Formattazione dei numeri di riga:

* **Larghezza:** 6 caratteri, allineati a destra con riempimento di spazi
* **Separatore:** carattere di tabulazione tra il numero di riga e il contenuto
* **Indicizzazione:** a partire da 1 (la prima riga è la riga 1)
* **Limite di righe:** i file con più di 999.999 righe dovrebbero restituire un errore: `"File {path} exceeds maximum line limit of 999,999 lines."`

**Esempio di output:**

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

La descrizione dello strumento di Claude indica anche che `view` visualizza i file di immagine (`.jpg`, `.jpeg` e `.png`) e tronca la visualizzazione testuale dei file più lunghi di 16.000 caratteri. Aspettati chiamate `view` su percorsi di immagini e visualizzazioni successive con intervalli per i file lunghi.

#### Gestione degli errori

* **Il file o la directory non esiste:** `"The path {path} does not exist. Please provide a valid path."`

### create

Crea un nuovo file:

```json
{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}
```

#### Valori di ritorno

* **Successo:** `"File created successfully at: {path}"`

#### Gestione degli errori

* **Il file esiste già:** `"Error: File {path} already exists"`

La descrizione dello strumento di Claude indica che `create` “crea o sovrascrive” un file, quindi aspettati chiamate `create` su percorsi già esistenti. Restituire l’errore è il comportamento di riferimento, ma sovrascrivere è una scelta di implementazione valida.

### str\_replace

Sostituisce del testo in un file:

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

`new_str` è opzionale per `str_replace`: quando viene omesso, `old_str` viene eliminato senza sostituzione.

#### Valori di ritorno

* **Successo:** `"The memory file has been edited."` seguito da un estratto del file modificato con i numeri di riga

#### Gestione degli errori

* **Il file non esiste:** `"Error: The path {path} does not exist. Please provide a valid path."`
* **Testo non trovato:** ``"No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."``
* **Testo duplicato:** quando `old_str` compare più volte, restituisci: ``"No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique"``

#### Gestione delle directory

Se il percorso è una directory, restituisci un errore di tipo “il file non esiste”.

### insert

Inserisce del testo in una riga specifica:

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

`insert_text` viene inserito dopo la riga `insert_line`, e `0` inserisce all’inizio del file.

#### Valori di ritorno

* **Successo:** `"The file {path} has been edited."`

#### Gestione degli errori

* **Il file non esiste:** `"Error: The path {path} does not exist"`
* **Numero di riga non valido:** ``"Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"``

#### Gestione delle directory

Se il percorso è una directory, restituisci un errore di tipo “il file non esiste”.

### delete

Elimina un file o una directory:

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

#### Valori di ritorno

* **Successo:** `"Successfully deleted {path}"`

#### Gestione degli errori

* **Il file o la directory non esiste:** `"Error: The path {path} does not exist"`

#### Gestione delle directory

Elimina la directory e tutto il suo contenuto in modo ricorsivo. La descrizione dello strumento indica a Claude che non può eliminare la directory `/memories` stessa, quindi rifiuta una `delete` il cui percorso è la radice della memoria.

### rename

Rinomina o sposta un file o una directory:

```json
{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}
```

#### Valori di ritorno

* **Successo:** `"Successfully renamed {old_path} to {new_path}"`

#### Gestione degli errori

* **L’origine non esiste:** `"Error: The path {old_path} does not exist"`
* **La destinazione esiste già:** restituisci un errore (non sovrascrivere): `"Error: The destination {new_path} already exists"`

#### Gestione delle directory

Rinomina la directory. La descrizione dello strumento indica a Claude che non può rinominare la directory `/memories` stessa, quindi rifiuta una `rename` il cui `old_path` è la radice della memoria.

## Indicazioni per i prompt

Quando lo strumento di memoria è presente nei `tools` della tua richiesta, l’API aggiunge automaticamente questa istruzione al “system prompt” (prompt di sistema). Non devi inviarla tu:

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

La descrizione dello strumento di Claude gli indica già di mantenere organizzata la directory di memoria, quindi non devi ripetere questa istruzione. Se Claude crea comunque file di memoria disordinati, puoi rafforzarla nel tuo 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.
```

Puoi anche orientare ciò che Claude scrive in memoria. Ad esempio: “Only write down information relevant to \<topic> in your memory system.”

## Considerazioni sulla sicurezza

La tua applicazione esegue ogni operazione sui file richiesta da Claude, quindi queste misure di protezione sono tua responsabilità:

### Informazioni sensibili

Claude di solito si rifiuta di scrivere informazioni sensibili nei file di memoria. Per garanzie più solide, aggiungi una validazione che rimuova i dati sensibili prima che il tuo handler scriva il file.

### Dimensione dello storage dei file

Tieni traccia delle dimensioni dei file di memoria e limita quanto può crescere un file. Valuta di limitare il numero di caratteri restituiti dal comando `view` e lascia che Claude scorra il resto con `view_range`.

### Scadenza della memoria

Elimina periodicamente i file di memoria a cui non si accede da molto tempo.

### Protezione dal path traversal

<Warning>
  Un percorso dannoso come `/memories/../../secrets.env` può raggiungere file al di fuori della directory `/memories`. La tua implementazione deve validare ogni percorso in ogni comando per prevenire attacchi di “directory traversal” (attraversamento delle directory).
</Warning>

Considera queste misure di protezione:

* Verifica che tutti i percorsi inizino con `/memories`
* Risolvi i percorsi nella loro forma canonica e verifica che rimangano all’interno della directory di memoria
* Rifiuta i percorsi contenenti sequenze come `../`, `..\\` o altri schemi di traversal
* Fai attenzione alle sequenze di traversal codificate in URL (`%2e%2e%2f`)
* Usa le utilità di sicurezza dei percorsi integrate nel tuo linguaggio (ad esempio, `pathlib.Path.resolve()` e `relative_to()` di Python)

## Gestione degli errori

Lo strumento di memoria usa schemi di gestione degli errori simili a quelli dello [strumento editor di testo](https://platform.claude.com/docs/it/agents-and-tools/tool-use/text-editor-tool#handle-errors). I messaggi di errore di ciascun comando sono elencati in [Comandi dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/memory-tool#tool-commands). Per restituire un errore a Claude, imposta `is_error` su `true` nel risultato dello strumento e inserisci il messaggio in `content`:

```json
{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Error: The path /memories/notes.txt does not exist",
  "is_error": true
}
```

## Integrazione con la modifica del contesto

Lo strumento di memoria si abbina alla modifica del contesto per gestire conversazioni di lunga durata. Per i dettagli, consulta [Modifica del contesto](https://platform.claude.com/docs/it/build-with-claude/context-editing).

## Utilizzo con la compattazione

Lo strumento di memoria può anche essere abbinato alla [compattazione](https://platform.claude.com/docs/it/build-with-claude/compaction), che riassume lato server il contesto meno recente della conversazione. La modifica del contesto cancella risultati specifici degli strumenti sul client. La compattazione riassume automaticamente l’intera conversazione sul server quando la conversazione si avvicina al limite della finestra di contesto.

Per gli agenti di lunga durata, valuta di usarle entrambe: la compattazione mantiene ridotto il contesto attivo senza gestione lato client, e la memoria preserva le informazioni che devono sopravvivere al riassunto.

## Modello di sviluppo software multisessione

Per i progetti software che si estendono su più sessioni dell’agente, imposta deliberatamente i file di memoria invece di scriverli in modo estemporaneo man mano che il lavoro procede. Il seguente modello trasforma la memoria in un meccanismo di ripristino: ogni nuova sessione riprende dallo stato registrato dall’ultima.

### Come funziona il modello

1. **Sessione di inizializzazione:** la prima sessione imposta i file di memoria prima che inizi qualsiasi lavoro sostanziale. Ciò include un registro dei progressi (che tiene traccia di ciò che è stato fatto e di ciò che viene dopo), una checklist delle funzionalità (che definisce l’ambito del lavoro) e un riferimento a qualsiasi script di avvio o inizializzazione di cui il progetto ha bisogno.

2. **Sessioni successive:** ogni nuova sessione inizia leggendo quei file di memoria. Questo ripristina lo stato del progetto senza riesplorare la base di codice o ripercorrere le decisioni precedenti.

3. **Aggiornamento di fine sessione:** prima che una sessione termini, aggiorna il registro dei progressi con ciò che è stato completato e ciò che rimane. Questo garantisce che la sessione successiva abbia un punto di partenza accurato.

### Principio chiave

Lavora su una funzionalità alla volta. Contrassegna una funzionalità come completata solo dopo che una verifica end-to-end ne conferma il funzionamento, non quando il codice è scritto. Questo mantiene accurato il registro dei progressi da una sessione all’altra.

<Tip>
  Per un caso di studio dettagliato di questo modello in pratica, inclusi lo script di inizializzazione, la struttura del file dei progressi e il ripristino basato su Git, consulta [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents).
</Tip>

## Passaggi successivi

<CardGroup cols={2}>
  <Card title="Strumento bash" icon="terminal" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/bash-tool">
    Esegui comandi shell in una sessione bash persistente.
  </Card>

  <Card title="Modifica del contesto" icon="edit" href="https://platform.claude.com/docs/it/build-with-claude/context-editing">
    Gestisci automaticamente il contesto della conversazione man mano che cresce con la modifica del contesto.
  </Card>

  <Card title="Compattazione" icon="stack" href="https://platform.claude.com/docs/it/build-with-claude/compaction">
    Compattazione del contesto lato server per gestire conversazioni lunghe che si avvicinano ai limiti della finestra di contesto.
  </Card>

  <Card title="Riferimento agli strumenti" icon="book" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference">
    Directory degli strumenti forniti da Anthropic e riferimento per le proprietà opzionali della definizione degli strumenti.
  </Card>
</CardGroup>

## Disponibilità

La funzionalità Strumento memoria è disponibile su tutti i modelli e idonea per conservazione zero dei dati e preparazione HIPAA.

### Supporto API

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

* Disponibilità: Disponibile

| Stato       | Modelli                                                                |
| ----------- | ---------------------------------------------------------------------- |
| Disponibile | [Tutti i modelli](https://platform.claude.com/docs/it/models/overview) |

### Gestione dei dati

[Panoramica sulla gestione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention#feature-eligibility)

| Elemento | Conservazione zero dei dati                                                                                                                             | HIPAA  |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| Stato    | Idoneo (esclude [Modelli coperti](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)) | Idoneo |
| Dettagli | Archiviazione della memoria lato client in cui controlli tu la conservazione dei dati.                                                                  | —      |

Endpoint applicabili:

* `/v1/messages` con lo strumento `memory`
