Strumento di memoria

Lo strumento di memoria consente a Claude di archiviare e recuperare informazioni tra conversazioni attraverso 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 funziona lato client: tu controlli dove e come i dati vengono archiviati attraverso la tua infrastruttura.

Casi d'uso

• Mantenere il contesto del progetto tra più esecuzioni di agenti
• Imparare dalle interazioni passate, dalle decisioni e dal feedback
• Costruire basi di conoscenza nel tempo
• Abilitare l'apprendimento tra conversazioni 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 archiviare ciò che impara mentre lavora, quindi fare riferimento a quei ricordi nelle conversazioni future per gestire compiti simili più efficacemente o riprendere da dove si era fermato.

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à il controllo completo su dove e come la memoria viene archiviata. Per la 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 la sua directory di memoria per primo. Ecco come appare una tipica interazione:

1. Richiesta dell'utente:

"Aiutami a rispondere a questo ticket di servizio clienti."

2. Claude controlla la directory di memoria:

"Ti aiuterò a rispondere al ticket di servizio clienti. Lasciami controllare 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 il contenuto 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 il contenuto 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 utilizza la memoria per aiutare:

"In base alle tue linee guida per il servizio clienti, posso aiutarti a formulare 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 Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)

Iniziare

Per utilizzare lo strumento di memoria:

1. Includi l'intestazione 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

Utilizzo 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": "I'\''m working on a Python web scraper that keeps crashing with a timeout error. Here'\''s the problematic function:\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\nPlease help me debug this."
            }
        ],
        "tools": [{
            "type": "memory_20250818",
            "name": "memory"
        }]
    }'

Comandi dello strumento

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

view

Mostra il contenuto della directory o il contenuto 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": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}

str_replace

Sostituisci il testo in un file:

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Favorite color: blue",
  "new_str": "Favorite color: green"
}

insert

Inserisci il testo in una riga specifica:

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Review memory tool documentation\n"
}

delete

Elimina un file o una 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 nel 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. Utilizza il comando `view` del tuo strumento `memory` per verificare il progresso precedente.
2. ... (lavora sul compito) ...
     - Man mano che fai progressi, registra lo stato / il progresso / i pensieri ecc nella tua memoria.
ASSUMI INTERRUZIONE: La tua finestra di contesto potrebbe essere ripristinata in qualsiasi momento, quindi rischi di perdere qualsiasi progresso non registrato nella tua directory di memoria.

Se osservi Claude che crea 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 se non necessario.

Puoi anche guidare ciò che Claude scrive in memoria, ad esempio, "Scrivi solo informazioni rilevanti a <topic> nel tuo sistema di memoria."

Considerazioni sulla 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 convalida più rigorosa che elimini le informazioni potenzialmente sensibili.

Dimensione dell'archiviazione dei file

Considera il tracciamento delle dimensioni dei file di memoria e previeni che i file crescano troppo. Considera l'aggiunta di 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 la cancellazione periodica dei file di memoria che non sono stati accessibili per un tempo prolungato.

Protezione dall'attraversamento di percorsi

Considera questi salvaguardie:

• Convalida che tutti i percorsi inizino con /memories
• Risolvi i percorsi nella loro forma canonica e verifica che rimangono all'interno della directory di memoria
• Rifiuta i percorsi contenenti sequenze come ../, ..\\, o altri modelli di attraversamento
• Stai attento alle sequenze di attraversamento codificate in URL (%2e%2e%2f)
• Utilizza le utility 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 utilizza gli stessi modelli di gestione degli errori dello strumento editor di testo. Gli errori comuni includono file non trovato, errori di permesso e percorsi non validi.

Utilizzo con Context Editing

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

Come funzionano insieme

Quando context editing è abilitato e la tua conversazione si avvicina alla soglia di cancellazione, Claude riceve automaticamente una notifica di avvertimento. 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 archiviate dai file di memoria ogni volta che necessario, trattando effettivamente la memoria come un'estensione del suo contesto di lavoro. Questo consente a Claude di:

• Continuare flussi di lavoro complessi e multi-step senza perdere informazioni critiche
• Fare riferimento al lavoro passato e alle decisioni anche dopo che i risultati degli strumenti vengono rimossi
• Mantenere un contesto coerente tra conversazioni che supererebbero i limiti di contesto tipici
• Costruire una base di conoscenza nel tempo mantenendo la finestra di contesto attiva gestibile

Flusso di lavoro di esempio

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

1. Claude effettua numerose modifiche ai file, generando molti risultati di strumenti
2. Man mano che il contesto cresce e si avvicina alla tua soglia, Claude riceve un avvertimento
3. Claude riassume i cambiamenti effettuati finora in un file di memoria (ad es. /memories/refactoring_progress.xml)
4. 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 cambiamenti erano già stati completati
6. Il flusso di lavoro può continuare indefinitamente, con Claude che gestisce sia il contesto attivo che la memoria persistente

Configurazione

Per utilizzare entrambe le funzioni insieme:

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=4096,
    messages=[...],
    tools=[
        {
            "type": "memory_20250818",
            "name": "memory"
        },
        # Your other tools
    ],
    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 di memoria dall'essere cancellate per assicurare che Claude abbia sempre accesso alle operazioni di memoria recenti:

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