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, consentendogli di costruire conoscenze 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 un'interazione tipica:

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": "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:

"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 Opus 4.6 (claude-opus-4-6)
• 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)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• 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)

Iniziare

Per utilizzare lo strumento di memoria:

1. Aggiungi lo strumento di memoria alla tua richiesta
2. 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" \
    --data '{
        "model": "claude-opus-4-6",
        "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. Mentre queste specifiche descrivono i comportamenti consigliati con cui Claude ha più familiarità, puoi modificare la tua implementazione e restituire stringhe secondo necessità per il tuo caso d'uso.

view

Mostra il contenuto della directory o il contenuto del file con intervalli di righe opzionali:

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10]  // Optional: view specific lines
}

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}    {path}
{size}    {path}/{filename1}
{size}    {path}/{filename2}

• Elenca i file fino a 2 livelli di profondità
• Mostra dimensioni leggibili dall'uomo (ad esempio, 5.5K, 1.2M)
• Esclude elementi nascosti (file che iniziano con .) e node_modules
• Usa il carattere di tabulazione tra la dimensione e il percorso

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 del numero di riga:

• Larghezza: 6 caratteri, allineati a destra con spaziatura
• Separatore: Carattere di tabulazione tra il numero di riga e il contenuto
• Indicizzazione: 1-indicizzato (la prima riga è la riga 1)
• Limite di righe: I file con più di 999.999 righe devono restituire un errore: "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 hundred

Gestione degli errori

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

• Il file esiste già: "Error: File {path} already exists"

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"
}

Valori di ritorno

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

Gestione degli errori

• Il 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 della directory

Se il percorso è una directory, restituisci un errore "file non esiste".

insert

Inserisci il testo in una riga specifica:

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

Valori di ritorno

• Successo: "The file {path} has been edited."

Gestione degli errori

• Il 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 della directory

Se il percorso è una directory, restituisci un errore "file non esiste".

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/directory non esiste: "Error: The path {path} does not exist"

Gestione della directory

Elimina la directory e tutto il suo contenuto in modo ricorsivo.

rename

Rinomina o sposta un file/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

• L'origine non esiste: "Error: The path {old_path} does not exist"
• La destinazione esiste già: Restituisci un errore (non sovrascrivere): "Error: The destination {new_path} already exists"

Gestione della directory

Rinomina la directory.

Guida al prompting

Includiamo automaticamente questa istruzione nel prompt di sistema quando lo strumento di memoria è incluso:

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.

Se osservi che Claude 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 in memoria solo le informazioni rilevanti per <topic>."

Considerazioni sulla sicurezza

Ecco importanti considerazioni sulla 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 la prevenzione della crescita eccessiva dei file. Considera l'aggiunta di un numero massimo di caratteri che il comando di lettura della memoria può restituire e consenti a Claude di impaginare 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 del percorso

Considera queste misure di sicurezza:

• 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)
• Usa le utility di sicurezza del percorso integrate del tuo linguaggio (ad esempio, pathlib.Path.resolve() e relative_to() di Python)

Gestione degli errori

Lo strumento di memoria utilizza modelli di gestione degli errori simili allo strumento editor di testo. Vedi le sezioni dei singoli comandi dello strumento sopra per messaggi di errore dettagliati e comportamenti. Gli errori comuni includono file non trovato, errori di permesso, percorsi non validi e corrispondenze di testo duplicate.

Utilizzo con Context Editing

Lo strumento di memoria può essere combinato con context editing, che cancella automaticamente i risultati degli strumenti precedenti 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 quando 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 degli strumenti
2. Man mano che il contesto cresce e si avvicina alla tua soglia, Claude riceve un avvertimento
3. Claude riassume le modifiche apportate finora in un file di memoria (ad esempio, /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 modifiche erano 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 utilizzare entrambe le funzioni insieme:

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[...],
    tools=[
        {"type": "memory_20250818", "name": "memory"},
        # Your other tools
    ],
    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"]}]
}

Utilizzo con Compaction

Lo strumento di memoria può anche essere abbinato a compaction, che fornisce il riassunto lato server del contesto della conversazione precedente. Mentre context editing cancella risultati specifici degli strumenti lato client, compaction riassume automaticamente l'intera conversazione lato server quando si avvicina al limite della finestra di contesto.

Per flussi di lavoro agentici di lunga durata, considera l'utilizzo di entrambi: compaction mantiene il contesto attivo gestibile senza bookkeeping lato client, e la memoria persiste le informazioni importanti attraverso i confini di compaction in modo che nulla di critico vada perso nel riassunto.