Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
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 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 in 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. Tu controlli dove e come i dati vengono archiviati attraverso la tua infrastruttura.
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 si limita a richiedere le 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 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 store. Per sicurezza, limita tutte le operazioni di memoria alla directory /memories (consulta Protezione dal path traversal).
Un'interazione tipica appare 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.
Lo strumento di memoria è generalmente disponibile sulla Messages API: non è richiesto alcun header beta. Usarlo richiede due passaggi:
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./memories, quindi leggi Protezione dal path traversal prima di scriverlo.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)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 classico ciclo di tool-use.
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 superfici degli helper e del 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 tool-use autonomamente, e PHP avvolge la closure del tuo handler nel suo generico BetaRunnableTool. Tutti e tre usano uno store 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 store in memoria negli esempi Go, PHP e Ruby li rendono 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 store dimostrativi omettono. Per gli esempi completi degli SDK stessi, consulta:
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 del tuo strumento, quindi puoi restituire stringhe diverse se la tua applicazione lo richiede.
Mostra il contenuto di una directory o il contenuto 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.
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}5.5K, 1.2M).) e node_modulesIl 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 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:
"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 hundredLa descrizione dello strumento di Claude indica anche che view visualizza i 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 con intervallo di file lunghi.
"The path {path} does not exist. Please provide a valid path."Crea un nuovo file:
{
"command": "create",
"path": "/memories/notes.txt",
"file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}"File created successfully at: {path}""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.
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 una sostituzione.
"The memory file has been edited." seguito da un estratto del file modificato con i numeri di riga"Error: The path {path} does not exist. Please provide a valid path.""No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."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"Se il percorso è una directory, restituisci un errore "file does not exist".
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.
"The file {path} has been edited.""Error: The path {path} does not exist""Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"Se il percorso è una directory, restituisci un errore "file does not exist".
Elimina un file o una directory:
{
"command": "delete",
"path": "/memories/old_file.txt"
}"Successfully deleted {path}""Error: The path {path} does not exist"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 root della memoria.
Rinomina o sposta un file o una directory:
{
"command": "rename",
"old_path": "/memories/draft.txt",
"new_path": "/memories/final.txt"
}"Successfully renamed {old_path} to {new_path}""Error: The path {old_path} does not exist""Error: The destination {new_path} already exists"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 della memoria.
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 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."
La tua applicazione esegue ogni operazione sui file richiesta da Claude, quindi queste misure di sicurezza sono tua responsabilità:
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.
Tieni traccia delle dimensioni dei file di memoria e imposta un limite alla crescita di un file. Valuta di limitare quanti caratteri restituisce il comando view e lascia che Claude scorra il resto con view_range.
Elimina periodicamente i file di memoria a cui non si accede da molto tempo.
Considera queste misure di sicurezza:
/memories../, ..\\ o altri pattern di traversal%2e%2e%2f)pathlib.Path.resolve() e relative_to() di Python)Lo strumento di 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
}Lo strumento di memoria si abbina alla modifica del contesto per gestire conversazioni di lunga durata. Per i dettagli, consulta Modifica del contesto.
Lo strumento di memoria può anche essere abbinato alla compattazione, che riassume lato server il contesto più vecchio della conversazione. La modifica del contesto 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, valuta di usare entrambi: la compattazione mantiene piccolo il contesto attivo senza contabilità lato client, e la memoria preserva le informazioni che devono sopravvivere alla sintesi.
Per i progetti software che si estendono su più sessioni dell'agente, configura i file di memoria in modo deliberato 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.
Sessione di inizializzazione: La prima sessione configura i file di memoria prima che inizi qualsiasi lavoro sostanziale. Questo include un registro dei progressi (che traccia ciò che è stato fatto e 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.
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 le decisioni precedenti.
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.
Lavora su una funzionalità alla volta. Contrassegna una funzionalità come completata solo dopo che la verifica end-to-end conferma che funziona, non quando il codice è scritto. Questo mantiene il registro dei progressi accurato da una sessione all'altra.
Esegui comandi shell in una sessione bash persistente.
Gestisci automaticamente il contesto della conversazione man mano che cresce con la modifica del contesto.
Compattazione del contesto lato server per gestire conversazioni lunghe che si avvicinano ai limiti della finestra di contesto.
Directory degli strumenti forniti da Anthropic e riferimento per le proprietà opzionali di definizione degli strumenti.
Was this page helpful?