Passa al contenuto principale

Memoria e Context Editing

Avanzato

Un agente a lunga esecuzione ha due nemici: dimentica ciò che ha imparato nel momento in cui la conversazione finisce, e la sua finestra di contesto si riempie con output di strumenti ormai obsoleti finché non trabocca. Anthropic fornisce una primitiva per ciascun problema — il memory tool (persistenza) e il context editing (potatura) — e sono progettati per essere usati insieme.

What you'll learn
  • Cos'è il memory tool — un archivio di file lato client in /memories che implementi tu, non Anthropic
  • I sei comandi a cui deve rispondere il tuo handler: view, create, str_replace, insert, delete, rename
  • Perché la validazione contro il path-traversal è irrinunciabile quando lo colleghi
  • Come il context editing cancella automaticamente i vecchi risultati degli strumenti quando il contesto supera una soglia di token
  • Come combinare entrambi sotto un unico header beta, e le insidie con caching e ordinamento

Due problemi, due strumenti​

Tieni le due idee separate nella tua testa:

  • Memory tool = persistenza tra le sessioni. Claude legge e scrive file; tu li memorizzi.
  • Context editing = potatura all'interno di una sessione. L'API rimuove i risultati degli strumenti ormai obsoleti dal prompt prima che raggiunga Claude.

Questa pagina si accompagna a Prompt Caching e alla token economy per il lato costi, e a Context Engineering e agli harness per agenti a lunga esecuzione per il perché.

Vocabolario di memoria e contesto
Premi Invio o Spazio per girare la carta. Usa le frecce sinistra e destra per spostarti tra le carte.Termine mostrato.
1 / 5

Il memory tool è uno strumento che implementi tu​

Questo manda in confusione: abilitare il memory tool non ti fornisce uno storage ospitato da Anthropic. È uno strumento lato client. Claude emette chiamate di strumento come view o create; la tua applicazione le esegue contro il backend che scegli — file locali, un database, blob crittografati, cloud storage — e restituisce il risultato. Sei tu il proprietario di dove risiedono i byte (motivo per cui è anche idoneo allo Zero-Data-Retention).

Quando lo strumento è abilitato, Anthropic inietta un'istruzione di sistema che dice a Claude di controllare la sua directory di memoria prima di fare qualsiasi altra cosa, e di registrare i progressi mentre lavora in modo che nulla vada perso se il contesto si azzera.

Passo 1 — abilita lo strumento​

Aggiungi lo strumento alla tua richiesta. La stringa del tipo è la versione datata memory_20250818.

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "Help me respond to this support ticket."}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)

Gli SDK ufficiali forniscono helper per la memoria così non devi implementare a mano l'interfaccia dello strumento — fai il subclass di BetaAbstractMemoryTool (Python, C#), usa betaMemoryTool (TypeScript), oppure implementa BetaMemoryToolHandler (Java). Ti offrono un hook pulito dove collegare il tuo storage.

Passo 2 — rispondi ai sei comandi​

Il tuo handler deve implementarli. Le stringhe che Claude si aspetta di ricevere sono specifiche — facci corrispondere in modo che il modello interpreti correttamente i risultati.

Guided walkthrough1 of 6
  1. Elenca una directory (file fino a 2 livelli di profondità, con dimensioni leggibili dall'uomo) oppure restituisci il contenuto di un file con numeri di riga a base 1. view_range opzionale per leggere una porzione.

Una vera view della directory restituisce qualcosa di simile a questo — nota l'header letterale e le dimensioni separate da tabulazione, che il modello è addestrato a interpretare:

Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:
4.0K	/memories
1.5K	/memories/customer_service_guidelines.xml
2.0K	/memories/refund_policies.xml

Passo 3 — blinda i percorsi (non saltare questo passaggio)​

Il memory tool permette a un modello di emettere stringhe di percorso arbitrarie. Una conversazione avvelenata o un payload di prompt-injection può tentare di evadere da /memories e leggere o sovrascrivere file altrove sulla tua macchina. Tratta ogni percorso in ingresso come ostile.

Watch out
  • Rifiuta qualsiasi percorso che non si risolva all'interno di /memories.
  • Canonicalizza prima di controllare — in Python, Path(p).resolve() poi verifica che .relative_to(memories_root) non sollevi eccezioni.
  • Blocca ../, ..\, e il traversal codificato in URL come %2e%2e%2f.
  • Limita le dimensioni dei file e la lunghezza di lettura così che un agente fuori controllo non possa esaurire il disco o far esplodere il prompt successivo.

Questo validatore è tutto ciò che conta — fissalo e testalo prima di mettere in produzione qualsiasi altra cosa:

Protezione contro il path-traversal (Python)

from pathlib import Path

MEMORY_ROOT = Path("/srv/agent/memories").resolve()

def safe_path(requested: str) -> Path:
  # Map the model's /memories/... onto your real root, then prove containment.
  rel = requested.removeprefix("/memories").lstrip("/")
  candidate = (MEMORY_ROOT / rel).resolve()
  candidate.relative_to(MEMORY_ROOT)  # raises ValueError if it escaped
  return candidate

Il context editing evita che la finestra trabocchi​

La memoria risolve la dimenticanza. Il problema opposto — una finestra di contesto imbottita di vecchi blocchi tool_result di 40 ricerche web fa — è ciò che risolve il context editing. Una volta che il prompt supera una soglia di token, l'API cancella i risultati degli strumenti più vecchi (sostituendoli con un breve segnaposto in modo che Claude sappia che sono stati rimossi) prima che il prompt venga inviato al modello. Il tuo client mantiene l'intera cronologia, non editata; viene tagliato solo ciò che raggiunge il modello.

Si appoggia su un header beta:

anthropic-beta: context-management-2025-06-27

Lo configuri con un array context_management.edits. La strategia principale è clear_tool_uses_20250919:

message = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    betas=["context-management-2025-06-27"],
    messages=[...],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},  # start clearing past 30k
                "keep": {"type": "tool_uses", "value": 3},            # always keep the last 3
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                "exclude_tools": ["memory"],                          # never clear memory calls
                "clear_tool_inputs": False,                           # keep the call args, drop results
            }
        ]
    },
)

Cosa significano le manopole:

ParametroValore predefinitoCosa controlla
trigger100.000 token di inputQuando entra in azione la cancellazione
keep3 utilizzi di strumentiQuante coppie recenti di uso/risultato dello strumento sono sempre preservate
clear_at_leastnessunoToken minimi liberati per ogni attivazione — usalo così che un'invalidazione della cache valga davvero la pena
exclude_toolsnessunoStrumenti mai cancellati (es. memory, web_search)
clear_tool_inputsfalseSe rimuovere anche gli argomenti della chiamata dello strumento, non solo il risultato

La risposta ti dice cosa ha fatto, sotto context_management.applied_edits — es. cleared_tool_uses e cleared_input_tokens — così puoi registrare quanto è stato recuperato.

Esiste una strategia gemella, clear_thinking_20251015, che pota i vecchi blocchi di extended-thinking. Se le usi entrambe, elenca clear_thinking_20251015 per primo nell'array edits.

Pro tip
  • Cancellare i risultati degli strumenti invalida qualsiasi prefisso di prompt-cache nel punto di cancellazione — abbinalo a clear_at_least così paghi quell'invalidazione solo quando stai liberando una porzione significativa.
  • exclude_tools: ["memory"] è la mossa abituale: vuoi che le note dell'agente stesso persistano, non che vengano spazzate via insieme ai risultati di ricerca obsoleti.
  • Context editing (taglio lato client) e compaction (riassunto lato server) sono funzionalità diverse — per esecuzioni molto lunghe puoi sovrapporle entrambe.

Perché abbinarli — i numeri​

Usati insieme, le due funzionalità permettono a un agente di andare ben oltre una singola finestra di contesto: il context editing mantiene snella la finestra attiva, e tutto ciò che conta viene scritto in memoria prima che venga cancellato. Anthropic riporta che combinare la memoria con il context editing ha prodotto un miglioramento del 39% in una valutazione di ricerca agentica, e che il context editing da solo ha ridotto l'uso dei token dell'84% in un test di ricerca web da 100 turni.

Un pattern che funziona: il log di progetto multi-sessione​

L'uso più pulito della memoria è inizializzarla deliberatamente invece di scrivere file alla rinfusa:

Guided walkthrough1 of 4
  1. Prima di qualsiasi lavoro reale, scrivi un log di progresso, una checklist di funzionalità e una nota che punti a qualsiasi script di avvio di cui il progetto ha bisogno.

Metti alla prova la tua comprensione​

Check yourself

0/3
  1. Dove vengono effettivamente memorizzati i dati del memory tool?
  2. Cosa rimuove la strategia clear_tool_uses_20250919 del context editing?
  3. Perché devi validare ogni percorso che il memory tool riceve?

Fonti e approfondimenti​