Strumento memoria

Lo strumento 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 memoria opera lato client—controlli dove e come i dati vengono memorizzati attraverso la tua infrastruttura.

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 memoria

Quando chiedi a Claude di aiutarti con un compito, Claude controlla automaticamente prima la sua directory di memoria. Ecco come appare una tipica interazione:

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 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 memoria è disponibile su:

• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)

Iniziare

Per usare lo strumento memoria:

1. Includi l'header beta context-management-2025-06-27 nelle tue richieste API
2. Aggiungi lo strumento memoria alla tua richiesta
3. Implementa gestori lato client per le operazioni di memoria

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 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 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 memoria è incluso:

IMPORTANTE: VISUALIZZA SEMPRE LA TUA DIRECTORY DI MEMORIA PRIMA DI FARE QUALSIASI ALTRA COSA.
PROTOCOLLO 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'archiviazione 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 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 accessibili per un tempo esteso.

Protezione attraversamento percorso

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 attraversamento
• Fai attenzione alle sequenze di attraversamento codificate URL (%2e%2e%2f)
• Usa le utilità di sicurezza percorso integrate del tuo linguaggio (ad es., pathlib.Path.resolve() e relative_to() di Python)

Gestione degli errori

Lo strumento 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.

Uso con Context Editing

Lo strumento memoria può essere combinato con context editing, che cancella automaticamente i vecchi risultati degli strumenti quando il contesto della conversazione cresce oltre una soglia configurata. Questa combinazione abilita flussi di lavoro agentici a lungo termine che altrimenti eccederebbero i limiti di contesto.

Come funzionano insieme

Quando il context editing è abilitato e la tua conversazione si avvicina alla soglia di cancellazione, Claude riceve automaticamente una notifica di avviso. Questo spinge Claude a preservare qualsiasi informazione importante dai risultati degli strumenti nei file di memoria prima che quei risultati vengano cancellati dalla finestra di contesto.

Dopo che i risultati degli strumenti vengono cancellati, Claude può recuperare le informazioni memorizzate dai file di memoria quando necessario, trattando effettivamente la memoria come un'estensione del suo contesto di lavoro. Questo permette a Claude di:

• Continuare flussi di lavoro complessi e multi-step senza perdere informazioni critiche
• Fare riferimento a lavoro e decisioni passate anche dopo che i risultati degli strumenti sono rimossi
• Mantenere contesto coerente attraverso conversazioni che eccederebbero i tipici limiti di contesto
• Costruire una base di conoscenza nel tempo mantenendo la finestra di contesto attiva gestibile

Esempio di flusso di lavoro

Considera un progetto di refactoring del codice con molte operazioni sui file:

1. Claude effettua numerose modifiche ai file, generando molti risultati di strumenti
2. Mentre il contesto cresce e si avvicina alla tua soglia, Claude riceve un avviso
3. Claude riassume le modifiche fatte finora in un file di memoria (ad es., /memories/refactoring_progress.xml)
4. Il context editing cancella automaticamente i risultati degli strumenti più vecchi
5. Claude continua a lavorare, facendo riferimento al file di memoria quando ha bisogno di ricordare quali modifiche sono già state completate
6. Il flusso di lavoro può continuare indefinitamente, con Claude che gestisce sia il contesto attivo che la memoria persistente

Configurazione

Per usare entrambe le funzionalità insieme:

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=4096,
    messages=[...],
    tools=[
        {
            "type": "memory_20250818",
            "name": "memory"
        },
        # I tuoi altri strumenti
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {
                    "type": "input_tokens",
                    "value": 100000
                },
                "keep": {
                    "type": "tool_uses",
                    "value": 3
                }
            }
        ]
    }
)

Puoi anche escludere le chiamate dello strumento memoria dall'essere cancellate per assicurarti che Claude abbia sempre accesso alle operazioni di memoria recenti:

context_management={
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "exclude_tools": ["memory"]
        }
    ]
}