Strumento di memoria

Lo strumento di memoria consente a Claude di archiviare e recuperare informazioni tra le 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.

Questo è il primitivo chiave per il recupero del contesto just-in-time: piuttosto che caricare tutte le informazioni rilevanti in anticipo, gli agenti archiviano ciò che imparano in memoria e lo recuperano su richiesta. Questo mantiene il contesto attivo focalizzato su ciò che è attualmente rilevante, critico per i flussi di lavoro di lunga durata dove caricare tutto in una volta comporterebbe il superamento della finestra di contesto. Vedi Effective context engineering per il modello più ampio.

Lo strumento di memoria opera 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 ha 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à 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 assistenza clienti."

2. Claude controlla la directory di memoria:

"Ti aiuterò a rispondere al ticket di assistenza clienti. Fammi 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": "Ecco i file e le directory fino a 2 livelli di profondità in /memories, escludendo elementi nascosti e 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": "Ecco il contenuto di /memories/customer_service_guidelines.xml con numeri di riga:\n     1\t<guidelines>\n     2\t<addressing_customers>\n     3\t- Rivolgersi sempre ai clienti per nome\n     4\t- Usare un linguaggio empatico\n..."
}

6. Claude usa la memoria per aiutare:

"In base alle tue linee guida di assistenza clienti, posso aiutarti a formulare una risposta. Per favore condividi i dettagli del ticket..."

Per il supporto del modello, vedi il Riferimento degli strumenti.

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

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 come necessario per il tuo caso d'uso.

view

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

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10] // Opzionale: visualizza righe specifiche
}

Valori di ritorno

Per directory: Restituisci un elenco che mostra file e directory con le loro dimensioni:

Ecco i file e le directory fino a 2 livelli di profondità in {path}, escludendo elementi nascosti e node_modules:
{size}    {path}
{size}    {path}/{filename1}
{size}    {path}/{filename2}

• Elenca 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 dimensione e percorso

Per file: Restituisci il contenuto del file con un'intestazione e numeri di riga:

Ecco il contenuto di {path} con numeri di riga:
{line_numbers}{tab}{content}

Formattazione del numero di riga:

• Larghezza: 6 caratteri, allineati a destra con spaziatura
• Separatore: Carattere di tabulazione tra numero di riga e contenuto
• Indicizzazione: 1-indicizzato (la prima riga è la riga 1)
• Limite di riga: I file con più di 999.999 righe dovrebbero restituire un errore: "File {path} exceeds maximum line limit of 999,999 lines."

Esempio di output:

Ecco il contenuto di /memories/notes.txt con numeri di riga:
     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

• File già esiste: "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

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

• 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 ricorsivamente.

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

• Origine non esiste: "Error: The path {old_path} does not exist"
• Destinazione già esiste: Restituisci un errore (non sovrascrivere): "Error: The destination {new_path} already exists"

Gestione della directory

Rinomina la directory.

Guida al prompting

Questa istruzione viene automaticamente inclusa nel prompt di sistema quando lo strumento di memoria è abilitato:

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, prova sempre a 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 nella tua memoria solo informazioni rilevanti per <topic>."

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 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 rimangano all'interno della directory di memoria
• Rifiuta i percorsi contenenti sequenze come ../, ..\\, o altri modelli di attraversamento
• Guarda le 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.

Integrazione della modifica del contesto

Lo strumento di memoria si accoppia con la modifica del contesto per gestire conversazioni di lunga durata. Per i dettagli, vedi Context editing.

Utilizzo con Compaction

Lo strumento di memoria può anche essere accoppiato con compaction, che fornisce il riassunto lato server del contesto di conversazione più vecchio. Mentre la modifica del contesto cancella risultati di strumenti specifici lato client, la compaction riassume automaticamente l'intera conversazione lato server quando si avvicina al limite della finestra di contesto.

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

Modello di sviluppo software multi-sessione

Per i progetti software di lunga durata che si estendono su più sessioni di agenti, i file di memoria devono essere inizializzati deliberatamente, non solo scritti ad hoc man mano che il lavoro progredisce. Il modello sottostante trasforma la memoria in un meccanismo di recupero strutturato, in modo che ogni nuova sessione possa riprendere esattamente da dove l'ultima ha lasciato.

Come funziona

1. Sessione di inizializzazione: La prima sessione configura gli artefatti di memoria prima che inizi qualsiasi lavoro sostanziale. Questo include un registro di progresso (tracciamento di ciò che è stato fatto e cosa viene dopo), una lista di controllo delle funzionalità (definizione dell'ambito del lavoro), e un riferimento a qualsiasi script di avvio o inizializzazione di cui il progetto ha bisogno.

2. Sessioni successive: Ogni nuova sessione si apre leggendo quegli artefatti di memoria. Questo recupera lo stato completo del progetto in secondi, senza bisogno di ri-esplorare la base di codice o ritracciare decisioni precedenti.

3. Aggiornamento di fine sessione: Prima che una sessione termini, aggiorna il registro di progresso con ciò che è stato completato e cosa rimane. Questo assicura che la sessione successiva abbia un punto di partenza accurato.

Principio chiave

Lavora su una funzionalità alla volta. Contrassegna una funzionalità come completa solo dopo che la verifica end-to-end conferma che funziona, non solo dopo che il codice è stato scritto. Questo mantiene il registro di progresso affidabile e previene che l'espansione dell'ambito si componga tra le sessioni.

Passaggi successivi