Lo strumento di memoria consente a Claude di memorizzare e recuperare informazioni attraverso le conversazioni tramite una directory di file di memoria. Claude può creare, leggere, aggiornare ed eliminare file che persistono tra le sessioni, permettendogli di costruire conoscenza nel tempo senza mantenere tutto nella finestra di contesto. Lo strumento di memoria opera lato client—controlli dove e come i dati vengono memorizzati attraverso la tua infrastruttura.
Lo strumento di memoria è attualmente in beta. Per abilitarlo, usa l’header beta context-management-2025-06-27 nelle tue richieste API.Ti preghiamo di contattarci attraverso il nostro modulo di feedback per condividere il tuo feedback su questa funzionalità.

​
Casi d’uso

  • Mantenere il contesto del progetto attraverso multiple esecuzioni dell’agente
  • Imparare da interazioni passate, decisioni e feedback
  • Costruire basi di conoscenza nel tempo
  • Abilitare l’apprendimento cross-conversazione dove Claude migliora nei flussi di lavoro ricorrenti

​
Come funziona

Quando abilitato, Claude controlla automaticamente la sua directory di memoria prima di iniziare i compiti. Claude può creare, leggere, aggiornare ed eliminare file nella directory /memories per memorizzare ciò che impara mentre lavora, poi fare riferimento a quei ricordi in conversazioni future per gestire compiti simili più efficacemente o riprendere da dove aveva lasciato. Poiché questo è uno strumento lato client, Claude effettua chiamate di strumento per eseguire operazioni di memoria, e la tua applicazione esegue quelle operazioni localmente. Questo ti dà controllo completo su dove e come la memoria viene memorizzata. Per sicurezza, dovresti limitare tutte le operazioni di memoria alla directory /memories.

​
Esempio: Come funzionano le chiamate dello strumento di memoria

Quando chiedi a Claude di aiutarti con un compito, Claude controlla automaticamente prima la sua directory di memoria. Ecco come appare un’interazione tipica: 1. Richiesta dell’utente: 
"Aiutami a rispondere a questo ticket del servizio clienti."
2. Claude controlla la directory di memoria: 
"Ti aiuterò a rispondere al ticket del servizio clienti. Lascia che controlli la mia memoria per qualsiasi contesto precedente."
Claude chiama lo strumento di memoria: 
{
  "type": "tool_use",
  "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories"
  }
}
3. La tua applicazione restituisce i contenuti della directory: 
{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Directory: /memories\n- customer_service_guidelines.xml\n- 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 i contenuti del file: 
{
  "type": "tool_result",
  "tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": "<guidelines>\n<addressing_customers>\n- Always address customers by their first name\n- Use empathetic language\n..."
}
6. Claude usa la memoria per aiutare: 
"Basandomi sulle tue linee guida del servizio clienti, posso aiutarti a creare una risposta. Per favore condividi i dettagli del ticket..."

​
Modelli supportati

Lo strumento di memoria è disponibile su:
  • Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)

​
Iniziare

Per usare lo strumento di memoria:
  1. Includi l’header beta context-management-2025-06-27 nelle tue richieste API
  2. Aggiungi lo strumento di memoria alla tua richiesta
  3. Implementa gestori lato client per le operazioni di memoria
Per gestire le operazioni dello strumento di memoria nella tua applicazione, devi implementare gestori per ogni comando di memoria. I nostri SDK forniscono helper dello strumento di memoria che gestiscono l’interfaccia dello strumento—puoi sottoclassare BetaAbstractMemoryTool (Python) o usare betaMemoryTool (TypeScript) per implementare il tuo backend di memoria (basato su file, database, cloud storage, file crittografati, ecc.).Per esempi funzionanti, vedi:

​
Uso di base

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 2048,
        "messages": [
            {
                "role": "user",
                "content": "Sto lavorando su un web scraper Python che continua a crashare con un errore di timeout. Ecco la funzione problematica:\n\n```python\ndef fetch_page(url, retries=3):\n    for i in range(retries):\n        try:\n            response = requests.get(url, timeout=5)\n            return response.text\n        except requests.exceptions.Timeout:\n            if i == retries - 1:\n                raise\n            time.sleep(1)\n```\n\nPer favore aiutami a debuggare questo."
            }
        ],
        "tools": [{
            "type": "memory_20250818",
            "name": "memory"
        }]
    }'

​
Comandi dello strumento

La tua implementazione lato client deve gestire questi comandi dello strumento di memoria:

​
view

Mostra i contenuti della directory o i contenuti del file con intervalli di righe opzionali: 
{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10]  // Opzionale: visualizza righe specifiche
}

​
create

Crea o sovrascrivi un file: 
{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Note della riunione:\n- Discussa timeline del progetto\n- Prossimi passi definiti\n"
}

​
str_replace

Sostituisci testo in un file: 
{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Colore preferito: blu",
  "new_str": "Colore preferito: verde"
}

​
insert

Inserisci testo a una riga specifica: 
{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Rivedere documentazione strumento di memoria\n"
}

​
delete

Elimina un file o directory: 
{
  "command": "delete",
  "path": "/memories/old_file.txt"
}

​
rename

Rinomina o sposta un file/directory: 
{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}

​
Guida al prompting

Includiamo automaticamente questa istruzione al prompt di sistema quando lo strumento di memoria è incluso: 
IMPORTANTE: VISUALIZZA SEMPRE LA TUA DIRECTORY DI MEMORIA PRIMA DI FARE QUALSIASI ALTRA COSA.
PROTOCOLLO DI MEMORIA:
1. Usa il comando `view` del tuo strumento `memory` per controllare i progressi precedenti.
2. ... (lavora sul compito) ...
     - Mentre fai progressi, registra stato / progressi / pensieri ecc nella tua memoria.
ASSUMI INTERRUZIONE: La tua finestra di contesto potrebbe essere resettata in qualsiasi momento, quindi rischi di perdere qualsiasi progresso che non è registrato nella tua directory di memoria.
Se osservi Claude creare file di memoria disordinati, puoi includere questa istruzione:
Nota: quando modifichi la tua cartella di memoria, cerca sempre di mantenere il suo contenuto aggiornato, coerente e organizzato. Puoi rinominare o eliminare file che non sono più rilevanti. Non creare nuovi file a meno che non sia necessario.
Puoi anche guidare ciò che Claude scrive in memoria, ad es., “Scrivi solo informazioni rilevanti a <argomento> nel tuo sistema di memoria.”

​
Considerazioni di sicurezza

Ecco importanti preoccupazioni di sicurezza quando implementi il tuo archivio di memoria:

​
Informazioni sensibili

Claude di solito rifiuterà di scrivere informazioni sensibili nei file di memoria. Tuttavia, potresti voler implementare una validazione più rigorosa che rimuove informazioni potenzialmente sensibili.

​
Dimensione dell’archivio file

Considera di tracciare le dimensioni dei file di memoria e prevenire che i file crescano troppo. Considera di aggiungere un numero massimo di caratteri che il comando di lettura della memoria può restituire, e lascia che Claude pagini attraverso i contenuti.

​
Scadenza della memoria

Considera di cancellare periodicamente i file di memoria che non sono stati acceduti per un tempo esteso.

​
Protezione da path traversal

Input di percorso malevoli potrebbero tentare di accedere a file fuori dalla directory /memories. La tua implementazione DEVE validare tutti i percorsi per prevenire attacchi di directory traversal.
Considera queste salvaguardie:
  • Valida che tutti i percorsi inizino con /memories
  • Risolvi i percorsi alla loro forma canonica e verifica che rimangano all’interno della directory di memoria
  • Rifiuta percorsi contenenti sequenze come ../, ..\\, o altri pattern di traversal
  • Fai attenzione alle sequenze di traversal codificate URL (%2e%2e%2f)
  • Usa le utilità di sicurezza dei percorsi integrate del tuo linguaggio (ad es., pathlib.Path.resolve() e relative_to() di Python)

​
Gestione degli errori

Lo strumento di memoria usa gli stessi pattern di gestione degli errori dello strumento editor di testo. Gli errori comuni includono file non trovato, errori di permesso e percorsi non validi.