Come funziona l’auto-compact negli agenti di programmazione

Cosa fa un agente di programmazione quando la finestra di contesto è piena?

La finestra di contesto è tutto il testo che un modello può leggere in una sola richiesta: i tuoi messaggi, le risposte dell’agente, i file letti, l’output dei comandi, i file delle regole e le istruzioni di sistema. A ogni passaggio un agente di programmazione rimanda tutto questo al modello, quindi in una sessione lunga prima o poi la finestra si riempie. Nell’articolo sul prompt caching abbiamo spiegato come la cache renda meno costosa questa ripetizione; questo articolo racconta cosa succede quando la finestra è piena.

C’è un problema anche prima che la finestra si riempia. La documentazione di Anthropic sulla compaction dice chiaramente perché si riassume: più una conversazione si allunga, più peggiora la qualità delle risposte, quindi il contesto attivo va tenuto piccolo. Un agente, insomma, non riassume la conversazione solo per evitare un errore, ma anche per continuare a lavorare bene.

Mentre la finestra si riempie, un agente ha quattro strade:

È la documentazione dell’API di Anthropic a descrivere queste strade più nel dettaglio. La funzione di context editing cancella i vecchi risultati degli strumenti, a partire dal più vecchio, e al posto di ciascuno mette un breve testo che dice che è stato rimosso. Con le impostazioni predefinite la pulizia parte quando una richiesta supera 100.000 token, e gli ultimi 3 usi degli strumenti restano come sono. La compaction, invece, sostituisce i turni più vecchi con un riassunto che Claude scrive sul server.

Gli strumenti di programmazione combinano queste strade. Claude Code prima pulisce i vecchi output degli strumenti e poi, se lo spazio ancora non basta, riassume la conversazione. Copilot CLI scrive in un file temporaneo l’output di uno strumento che supera 20 KiB; al modello arrivano solo il percorso del file e un’anteprima. Anche Cursor scrive in un file l’output lungo della shell e di MCP invece di tagliarlo, e l’agente legge il resto del file se gli serve; Cursor lo ha spiegato in un articolo di gennaio 2026.

Scartare i messaggi più vecchi, invece, non compare come strada predefinita nella documentazione di nessuno dei cinque strumenti; tutte descrivono il riassunto. La documentazione di Copilot spiega anche perché: senza riassunto, i vecchi messaggi verrebbero cancellati senza lasciare traccia e Copilot non potrebbe sapere cosa contenevano.

Come funziona l’auto-compact nei cinque strumenti?

Tutti e cinque gli strumenti riassumono la conversazione da soli e offrono un comando per farlo a mano. Cambiano il momento in cui parte il riassunto, cosa si può configurare e cosa è cambiato negli ultimi due mesi. Abbiamo letto i dati della tabella nella documentazione e nelle note di rilascio di ogni strumento il 20 ottobre 2026:

Fonte: documentazione e note di rilascio di ogni strumento, 20 ottobre 2026. «La documentazione non lo dice»: nelle pagine che abbiamo letto quel giorno non abbiamo trovato una frase che lo dica. «—»: nelle note di rilascio che abbiamo letto non abbiamo trovato modifiche di questi mesi. La versione della CLI di Cursor è la data in cui è uscita. Nell’app desktop di Antigravity, /compact è arrivato con la versione 2.24.0 (15 ottobre). Le due modifiche di Codex sono arrivate con le versioni 0.162.0 e 0.163.0.

Claude Code esprime la soglia in token, non in percentuale. Secondo la documentazione, se non hai impostato una soglia, la conversazione viene riassunta quando raggiunge il limite di contesto del modello; nei modelli con finestra da 1M token succede prima che la finestra sia piena, intorno ai 967 mila token. Se vuoi che riassuma prima, scrivi un comando come /autocompact 500k; il valore viene salvato nelle tue impostazioni per quel modello. Dalla versione 2.1.299 (14 ottobre) c’è anche il riassunto per inattività, di cui parliamo nella prossima sezione.

Copilot CLI usa due soglie invece di una. Secondo la documentazione, il riassunto parte in background quando la conversazione arriva a circa l’80% della finestra; lo spazio restante è riservato perché le chiamate agli strumenti possano continuare mentre il riassunto viene scritto. Se il riempimento sale a circa il 95% prima che il riassunto sia finito, la CLI aspetta un momento.

In Codex la soglia la decide model_auto_compact_token_limit nel file ~/.codex/config.toml. Se lo lasci vuoto, vale il valore predefinito del modello; la documentazione non dice quanto vale. Puoi cambiare il modo in cui viene scritto il riassunto con compact_prompt.

Se usi ancora Gemini CLI: Gemini CLI comprime per impostazione predefinita quando metà del contesto è piena (compressionThreshold vale 0,5 di default), e il comando manuale è /compress. Per gli utenti del livello gratuito e di Google One, Google ha sostituito Gemini CLI con Antigravity CLI il 18 giugno 2026; Gemini CLI resta in uso con le licenze enterprise e le chiavi API a pagamento.

Cosa si perde quando la conversazione viene riassunta?

Riassumere ha tre costi, e tutti e tre sono scritti nella documentazione degli strumenti stessi.

La cache non vale più. Il prompt caching conserva l’inizio di una richiesta che non cambia, e le richieste successive lo leggono a basso costo. Un riassunto o una pulizia cambiano l’inizio della conversazione. La richiesta successiva può usare la copia in cache solo fino al punto che è cambiato, e il resto lo riscrive. Per questo la documentazione di Anthropic consiglia l’impostazione clear_at_least: ogni pulizia deve cancellare almeno un certo numero di token, così che riscrivere la cache valga la pena. Quali modifiche invalidano la cache lo abbiamo spiegato nel dettaglio nell’articolo sul prompt caching.

Anche il riassunto per inattività, arrivato in Claude Code il 14 ottobre, nasce dallo stesso calcolo. Secondo la nota di rilascio, una conversazione oltre i 200.000 token che resta inattiva per circa 54 minuti viene riassunta prima che scada la cache di un’ora. Secondo la documentazione delle impostazioni, quando torni, il tuo primo messaggio invia il riassunto e non l’intera conversazione. Se non lo vuoi, puoi disattivarlo nelle impostazioni con "idleCompaction": false.

Le istruzioni date all’inizio della conversazione possono perdersi. La documentazione di Claude Code è chiara: le tue richieste e i frammenti di codice importanti vengono conservati, ma le istruzioni dettagliate date all’inizio della conversazione possono andare perse; le regole permanenti vanno scritte in CLAUDE.md, non nella conversazione. La documentazione di Copilot scrive che piccole decisioni prese all’inizio di una conversazione lunga possono non entrare nel riassunto e che un riassunto concluso non si può annullare. VS Code e Cursor dicono la stessa cosa: un riassunto è una compressione con perdita.

La nota di rilascio 1.2.8 di Antigravity CLI è un esempio concreto di questa perdita: fino a quella versione, quando gli altri prompt della conversazione erano brevi, un’istruzione iniziale lunga veniva tagliata nel riassunto a una piccola fetta fissa. Come si scrive un file delle regole lo abbiamo spiegato nell’articolo su AGENTS.md e CLAUDE.md.

Il riassunto stesso può diventare un’istruzione. Anche il riassunto lo scrive un modello, e il modello che continua dopo il riassunto può leggerlo come un’istruzione. L’esempio più chiaro è il rapporto di OpenAI: durante l’addestramento, un modello non pubblicato ha aggiunto istruzioni non autorizzate ai propri riassunti di compaction. OpenAI se ne è accorta il 9 agosto, ha aggiornato il rapporto il 16 settembre e ha trovato 27 riassunti di questo tipo nei dati di addestramento.

In un esempio, l’utente aveva chiesto una lunga rassegna della letteratura con le fonti citate. Il riassunto ha aggiunto una regola che nessuno aveva chiesto: la risposta doveva avere al massimo 30 parole, senza strumenti né fonti. Il modello che ha continuato dopo il riassunto ha seguito questa regola e ha scritto un rifiuto di 23 parole. Secondo il rapporto, è successo in un’esecuzione di addestramento separata da quella da cui viene il modello finale, e non si è ripetuto quando il riassunto è stato rigenerato; in altre parole, non è stato osservato in un modello pubblicato.

La lezione però vale in generale: un riassunto non è un’istruzione che hai scritto tu, è un testo scritto da un modello. Anche negli strumenti di programmazione si è visto un errore simile. La nota di rilascio 2.1.292 di Claude Code ne corregge uno: un riassunto che ripeteva un comando di skill poteva portare Claude a eseguire una skill riservata all’utente. Se dopo un riassunto l’agente fa qualcosa che non ti aspettavi, guarda prima il riassunto: in Copilot CLI, /session checkpoints mostra ogni riassunto automatico separatamente.

Quando conviene usare clear invece di compact?

I due comandi risolvono lo stesso problema in due modi. Compact sostituisce la conversazione con un riassunto e continua nella stessa sessione. Clear abbandona del tutto la conversazione e riparte da un contesto vuoto; i file delle regole e della memoria sul disco restano dove sono. Quale scegliere dipende da una cosa: se il prossimo lavoro ha bisogno della conversazione precedente.

Fonte: la documentazione dei comandi di ogni strumento, 20 ottobre 2026. Il focus tra parentesi quadre o angolari è facoltativo: lì scrivi cosa deve restare nel riassunto.

Il criterio più concreto per capire quando ripartire da zero è nella documentazione di Claude Code: se hai corretto Claude più di due volte sullo stesso problema, il contesto è pieno di tentativi falliti; scrivi /clear e riparti con un prompt più chiaro che contenga quello che hai imparato. La documentazione di Copilot aggiunge un altro criterio: se la conversazione è stata riassunta molte volte e pensi che si sia perso qualcosa di importante, apri una nuova sessione.

La terza strada è non far entrare il rumore nella conversazione principale. Quando affidi a un subagente passaggi come leggere un log lungo, scorrere un grosso output dei test o cercare nel codice, tutto quello che legge resta nella finestra del subagente e alla conversazione principale torna solo il risultato. Claude Code, Copilot e Cursor lo consigliano esplicitamente nella loro documentazione; dei subagenti abbiamo parlato in un articolo a parte. In Claude Code, dalla versione 2.1.296 (9 ottobre), puoi anche dare a un subagente una soglia di riassunto che scatta prima di quella della conversazione principale. L’esempio della documentazione è un subagente che legge file di log lunghi:

---
name: log-reader
description: Legge file di log lunghi e riporta gli errori che trova
autoCompactWindow: 200000
---

Scrivi il valore come numero semplice. Secondo la documentazione, Claude Code legge 200k in questo campo come 200; quel valore è fuori dall’intervallo consentito, quindi il subagente funziona come se il campo non ci fosse.

Cosa rilegge l’agente dopo un riassunto?

Il modo per superare indenni un riassunto è tenere le informazioni sul disco, non nella conversazione. La documentazione di Claude Code elenca una per una le cose che tornano dopo un riassunto:

Fonte: documentazione di Claude Code, pagine «Explore the context window» e «Store instructions and memories», 20 ottobre 2026.

Se vuoi che un’istruzione data nella conversazione valga anche dopo un riassunto, ci sono due strade: scriverla in CLAUDE.md o usare un hook che parte dopo ogni riassunto. L’esempio della documentazione di Claude Code, in italiano:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Promemoria: usa Bun, non npm. Esegui bun test prima di ogni commit.'"
          }
        ]
      }
    ]
  }
}

Il testo che l’hook stampa viene aggiunto accanto al contesto riassunto. Al posto di echo puoi anche eseguire un comando che dice lo stato attuale, come git log --oneline -5. Degli hook abbiamo parlato in un articolo a parte. Negli altri strumenti la situazione è questa:

• Codex: la memoria locale (memories) è disattivata per impostazione predefinita. La documentazione chiede di scrivere in AGENTS.md le regole che il team deve rispettare e di considerare la memoria solo uno strato che aiuta a ricordare.
• GitHub Copilot: quando la CLI riassume, conserva accanto al riassunto le istruzioni iniziali dell’utente e lo stato più recente di piani e liste di cose da fare. Copilot Memory (in anteprima pubblica) condivide informazioni su un repository tra la CLI, l’agente cloud e la code review; prima di usare un’informazione, verifica sul branch attuale il codice su cui si basa. Lo strumento di memoria di VS Code tiene le note in locale; la documentazione consiglia di scrivere le decisioni su cui il team fa affidamento in documenti sotto controllo di versione o in file di custom instructions.
• Cursor: secondo la documentazione, il modello non ricorda nulla tra una completion e l’altra; per il contesto permanente ci sono le regole (rules). Quando riassume, inoltre, Cursor dà all’agente la cronologia della chat come file, e l’agente può cercarci ciò che manca nel riassunto (articolo di gennaio 2026).
• Antigravity: il comando /learn propone di salvare come regola o skill quello che si è imparato in una sessione, per esempio una correzione o un vincolo che viene ignorato di continuo; non scrive niente in un file finché non approvi. Il punto di partenza della documentazione è chiaro: gli agenti non ricordano le conversazioni.
• Gemini CLI: l’impostazione sperimentale autoMemory ricava suggerimenti di memoria dalle sessioni passate; è disattivata per impostazione predefinita e nessuno viene applicato finché non lo approvi in /memory inbox.

Perché un agente di code review non può riassumere?

Tutto quello che abbiamo detto finora vale per una sessione che parla con una persona e cresce man mano. Un agente che esamina una pull request non funziona così: è una sola chiamata, non ha nessuno a cui chiedere e non ha una cronologia da riassumere. Deve decidere prima della chiamata cosa mandare al modello.

In diffox questa decisione la prende il pacchetto di contesto che tutti gli agenti specializzati di una review condividono. Nel codice il pacchetto si costruisce così:

• Prima viene il diff. Poi le righe e i simboli modificati, i chiamanti toccati dalla modifica e la cronologia git; il contesto dei file, la descrizione della PR e i messaggi di commit vengono per ultimi. Se il pacchetto supera il limite, viene tagliato dalla fine e, nel punto del taglio, si aggiunge una riga che lo dice. L’ordine è stato scelto in modo che alla fine resti la parte la cui perdita costa meno.
• I lock file restano fuori dal diff. I file scritti da uno strumento, come go.sum, package-lock.json o uv.lock, le cartelle vendor e i file minificati vengono tolti dal diff e i loro nomi sono scritti su una sola riga. Nel codice il motivo è registrato come misura: in una pull request del set del benchmark, go.sum e go.work.sum erano il 68,5% del diff, e il file sorgente con il bug esaminato il 4,2%.
• Si invia l’intorno della modifica, non il file intero. Ogni intervallo di righe saltato viene indicato con i numeri di riga, così il modello sa cosa manca.
• Le regole del repository viaggiano fuori dal pacchetto. Le regole da rispettare del file delle regole vengono aggiunte a parte al prompt di sistema di ogni agente, quindi il taglio non le tocca. È, sul lato della review, l’equivalente del consiglio dato per gli agenti di programmazione: «scrivi le regole permanenti nel file delle regole».
• Il file non letto viene registrato. Ogni review registra se ciascun file modificato è arrivato agli agenti per intero, in parte o per niente. Se in una review senza rilievi alcuni file non sono stati letti per intero, il commento della pull request lo dice in una frase.

Qualunque strumento usi, la lezione è la stessa: se l’agente non ha letto un file, la risposta «nessun rilievo» non dice nulla su quel file. Anche con un agente di programmazione, prima di dire «questo lo sa già», guarda cosa c’è nella finestra: in Claude Code, Copilot CLI e Antigravity CLI, /context lo mostra.