Strumento di memoria

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, 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 focalizzato 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 di memoria opera lato client: Claude richiede operazioni sui file e la tua applicazione le esegue. Controlli dove e come i dati vengono archiviati attraverso la tua infrastruttura.



Casi d'uso

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



Come funziona

Quando lo strumento di 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 di memoria è lato client, Claude richiede solo 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). Il percorso /memories è un prefisso che il tuo handler mappa sullo 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 store. Per sicurezza, limita tutte le operazioni di memoria alla directory /memories (consulta Protezione dal path traversal).



Esempio: come funzionano le chiamate allo strumento di 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 di 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 di 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

Lo strumento di memoria è generalmente disponibile sulla Messages API: non è richiesto alcun header beta. Utilizzarlo 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 prima di scriverlo.



Utilizzo di base

client = anthropic.Anthropic()

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

print(message)



Implementare l'handler di memoria

La risposta di Claude a una richiesta come quella 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 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 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 helper e tool-runner risiedono nel namespace beta di ciascun SDK anche se lo strumento di memoria stesso è generalmente disponibile. Gli SDK Go e Ruby non hanno un helper di memoria, quindi quegli esempi eseguono il ciclo di uso degli strumenti autonomamente, e PHP avvolge la tua closure handler nel suo generico BetaRunnableTool. Tutti e tre usano uno store in memoria che sostituisci 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-4-8",
    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 store in memoria negli esempi Go, PHP e Ruby li mantengono autonomi: ciascuno esegue 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 store dimostrativi omettono. Per gli esempi completi degli SDK, 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 raccomandati: Claude legge qualsiasi testo contenuto nel risultato dello strumento, quindi puoi restituire stringhe diverse se la tua applicazione ne ha bisogno.



view

Mostra il contenuto della directory o il contenuto del 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 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 uno store vuoto non è un errore. Gli strumenti di memoria basati sul filesystem locale degli SDK (BetaLocalFilesystemMemoryTool) creano la root di 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 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 padding di spazi
• Separatore: Carattere di tabulazione tra numero di riga e contenuto
• Indicizzazione: Indicizzata 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."

Output di esempio:

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 dice anche che view visualizza file immagine (.jpg, .jpeg e .png) e tronca la visualizzazione testuale di file più lunghi di 16.000 caratteri. Aspettati chiamate view su percorsi di immagini e visualizzazioni successive con intervalli per file lunghi.



Gestione degli errori

• File o 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

• File già esistente: "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 che esistono già. Restituire l'errore è il comportamento di riferimento, e sovrascrivere invece è una scelta di implementazione valida.



str_replace

Sostituisce 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 una sostituzione.



Valori di ritorno

• Successo: "The memory file has been edited." seguito da uno snippet del file modificato con numeri di riga



Gestione degli errori

• 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 "file does not exist".



insert

Inserisce 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

• 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 "file does not exist".



delete

Elimina un file o una directory:

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



Valori di ritorno

• Successo: "Successfully deleted {path}"



Gestione degli errori

• File o directory non esiste: "Error: The path {path} does not exist"



Gestione delle directory

Elimina la directory e tutto il suo contenuto ricorsivamente. La descrizione dello strumento dice a Claude che non può eliminare la directory /memories stessa, quindi rifiuta un delete il cui percorso è la root di 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

• Sorgente non esiste: "Error: The path {old_path} does not exist"
• Destinazione già esistente: 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 root di memoria.



Indicazioni per il prompting

Quando lo strumento di memoria è presente nei tools della tua richiesta, l'API aggiunge automaticamente questa istruzione al prompt di sistema. Non è necessario 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 è necessario ripetere quell'istruzione. Se Claude crea comunque file di memoria disordinati, puoi rinforzarlo 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 che Claude richiede, quindi queste salvaguardie 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 può crescere un file. Considera di limitare quanti caratteri restituisce il 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

Considera queste salvaguardie:

• 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 utility 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 pattern di gestione degli errori simili allo strumento text editor. 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 di memoria si abbina al context editing per gestire conversazioni di lunga durata. Per i dettagli, consulta Context editing.



Utilizzo con la compaction

Lo strumento di memoria può anche essere abbinato alla compaction, che riassume il contesto della conversazione più vecchio lato server. Il context editing cancella risultati specifici degli strumenti sul client. La compaction riassume automaticamente l'intera conversazione sul server quando la conversazione si avvicina al limite della finestra di contesto.

Per agenti di lunga durata, considera di usare entrambi: la compaction mantiene piccolo il contesto attivo senza contabilità lato client, e la memoria preserva le informazioni che devono sopravvivere alla sintesi.



Pattern di sviluppo software multi-sessione

Per progetti software che si estendono su più sessioni dell'agente, configura 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 recupero: ogni nuova sessione riprende dallo stato registrato dall'ultima.



Come funziona il pattern

1. Sessione di inizializzazione: La prima sessione configura i file di memoria prima che inizi qualsiasi lavoro sostanziale. Questo include un log di avanzamento (che tiene traccia di 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 code base o ripercorrere decisioni precedenti.

3. Aggiornamento di fine sessione: Prima che una sessione termini, aggiorna il log di avanzamento 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 completa solo dopo che la verifica end-to-end conferma che funziona, non quando il codice è scritto. Questo mantiene accurato il log di avanzamento da sessione a sessione.



Passaggi successivi