Strumento memoria

Lo strumento memoria ("memory tool") 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, accumulando conoscenza nel tempo senza mantenere tutto nella "context window" (finestra di contesto).

La memoria supporta il recupero del contesto just-in-time. Invece di caricare tutte le informazioni rilevanti in anticipo, un agente registra ciò che apprende nei file di memoria e li rilegge su richiesta. Questo mantiene il contesto attivo concentrato sul compito corrente, il che è importante per le sessioni di lunga durata che altrimenti sovraccaricherebbero la finestra di contesto. Consulta Effective context engineering per il pattern più ampio.

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

Casi d'uso

• Mantenere il contesto del progetto tra più sessioni dell'agente
• Applicare le lezioni apprese da interazioni, decisioni e feedback passati a nuovi compiti
• Costruire una base di conoscenza nel tempo

Come funziona

Quando lo strumento memoria è abilitato, Claude controlla automaticamente la sua directory di memoria prima di iniziare un compito. 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 memoria è lato client, Claude richiede soltanto le operazioni di memoria. La tua applicazione esegue ogni richiesta su uno storage che controlli e restituisce il risultato in un blocco tool_result (vedi Gestire le chiamate agli strumenti). 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 continua 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 (vedi Protezione dal path traversal).

Esempio: come funzionano le chiamate allo strumento memoria

Un'interazione tipica si presenta così:

1. Richiesta dell'utente:

"Help me respond to this customer service ticket."

2. Claude controlla la directory di memoria:

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

Claude chiama lo strumento memoria:

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

3. La tua applicazione restituisce il contenuto della directory:

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

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

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

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

Lo strumento memoria è disponibile su tutti i modelli Claude 4 e successivi. Per l'elenco completo degli strumenti forniti da Anthropic, consulta il Riferimento degli strumenti.

Per iniziare

L'uso dello strumento memoria richiede due passaggi:

1. Aggiungi lo strumento memoria alla tua richiesta. La voce tools {"type": "memory_20250818", "name": "memory"} è l'intera configurazione: il name deve essere memory e non devi definire 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 prima di scriverlo.

Utilizzo di base

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "Help me respond to this customer service ticket.",
        }
    ],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)

Implementa 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, quindi rinvia la conversazione in modo che Claude possa continuare: il ciclo standard di uso degli strumenti.

Quattro SDK forniscono helper per lo strumento memoria che gestiscono l'interfaccia dello strumento e il ciclo. Estendi BetaAbstractMemoryTool (Python e C#), usa betaMemoryTool (TypeScript) o implementa BetaMemoryToolHandler (Java) per supportare la memoria con il tuo storage, come file su disco, un database, cloud storage o file crittografati. Python e TypeScript includono anche un'implementazione pronta all'uso basata sul filesystem locale, BetaLocalFilesystemMemoryTool. Le interfacce degli helper e del tool runner risiedono nel namespace beta di ciascun SDK anche se lo strumento memoria in sé non richiede un header beta. Gli SDK Go e Ruby non hanno un helper per la memoria, quindi quegli esempi eseguono da soli il ciclo di uso degli strumenti, e PHP avvolge la closure del tuo handler nel suo generico BetaRunnableTool. Tutti e tre usano un archivio in memoria che sostituirai con il tuo storage.

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",
    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)

Gli archivi in memoria negli esempi Go, PHP e Ruby li mantengono autonomi: ciascuno effettua il dispatch sul campo command nell'input del blocco tool_use e restituisce le stringhe descritte in Comandi dello strumento. Un handler di produzione necessita anche della validazione dei percorsi che questi archivi dimostrativi omettono. Per gli esempi completi degli SDK stessi, consulta:

• Python: examples/memory/basic.py
• TypeScript: examples/tools-helpers-memory.ts
• C#: MemoryToolExample
• Java: 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 qualsiasi testo contenuto nel risultato dello 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:

{
  "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 loro dimensioni:

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

Il primo view di /memories su un archivio vuoto non è un errore. Gli strumenti memoria basati sul filesystem locale degli SDK (BetaLocalFilesystemMemoryTool) creano la radice della memoria prima della prima chiamata di Claude e restituiscono l'intestazione dell'elenco seguita da una singola riga dimensione-e-percorso per la directory vuota stessa.

Per i file: Restituisci il contenuto del file con un'intestazione e i numeri di riga:

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 numero di riga e contenuto
• Indicizzazione: a base 1 (la prima riga è la riga 1)
• Limite di righe: I file con più di 999.999 righe devono restituire un errore: "File {path} exceeds maximum line limit of 999,999 lines."

Esempio di output:

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 file 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 successive visualizzazioni per intervallo di 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:

{
  "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 dice che create "crea o sovrascrive" un file, quindi aspettati chiamate create su percorsi già esistenti. Restituire l'errore è il comportamento di riferimento, e sovrascrivere invece è una scelta di implementazione valida.

str_replace

Sostituisce del testo in un file:

{
  "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 frammento 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 appare 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 "il file non esiste".

insert

Inserisce del testo in una riga specifica:

{
  "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 "il file non esiste".

delete

Elimina un file o una directory:

{
  "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 dice a Claude che non può eliminare la directory /memories stessa, quindi rifiuta un delete il cui percorso è la radice della memoria.

rename

Rinomina o sposta un file o una directory:

{
  "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 dice a Claude che non può rinominare la directory /memories stessa, quindi rifiuta un rename il cui old_path è la radice della memoria.

Indicazioni per il prompting

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

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 dice già di mantenere organizzata la directory di memoria, quindi non devi ripetere quell'istruzione. Se Claude crea comunque file di memoria disordinati, puoi rafforzarla nel tuo prompt:

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 guidare 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 protezioni sono tua responsabilità:

Informazioni sensibili

Claude di solito rifiuta di scrivere informazioni sensibili nei file di memoria. Per garanzie più forti, 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 un file può crescere. Considera di limitare quanti caratteri restituisce il comando view, e lascia che Claude sfogli 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

Considera queste protezioni:

• Valida 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 pattern 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 memoria usa pattern di gestione degli errori simili a quelli dello strumento editor di testo. I messaggi di errore di ciascun comando sono elencati in Comandi dello strumento. Per restituire un errore a Claude, imposta is_error su true nel risultato dello strumento e inserisci il messaggio in content:

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

Integrazione con il context editing

Lo strumento memoria si abbina al "context editing" (modifica del contesto) per gestire conversazioni di lunga durata. Per i dettagli, consulta Context editing.

Utilizzo con la compattazione

Lo strumento memoria può anche essere abbinato alla compattazione ("compaction"), che riassume lato server il contesto più vecchio della conversazione. Il context editing cancella specifici risultati 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, considera di usare entrambi: la compattazione mantiene piccolo il contesto attivo senza contabilità lato client, e la memoria preserva le informazioni che devono sopravvivere al riassunto.

Pattern di sviluppo software multisessione

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

Come funziona il pattern

1. Sessione di inizializzazione: La prima sessione imposta i file di memoria prima che inizi qualsiasi lavoro sostanziale. Questo include un registro dei progressi (che traccia cosa è stato fatto e cosa 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 si apre 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. Segna una funzionalità come completata solo dopo che una verifica end-to-end conferma che funziona, non quando il codice è scritto. Questo mantiene accurato il registro dei progressi da una sessione all'altra.

Prossimi passi