Tutorial 10: I Checkpoint — Il Tasto Annulla dell'IA

Tutorial 10: I Checkpoint — Il Tasto Annulla dell’IA

Ti ricordi quella sensazione di sprofondo quando ti accorgi di aver appena cancellato qualcosa di importante? Magari un file su cui avevi lavorato per ore, o una modifica alla configurazione che ha mandato tutto in tilt. Nel mondo reale non esiste un Ctrl+Z per il tuo filesystem. Ma in Hermes Agent sì — e si chiama checkpoint.

Pensali come ai punti di salvataggio in un videogioco. Prima che il tuo agente AI faccia qualcosa di rischioso — come sovrascrivere un file o eseguire un comando distruttivo — può fare un’istantanea rapida del tuo progetto. Se qualcosa va storto, puoi tornare a quell’istantanea con un solo comando. È come avere un tasto annulla per l’intero progetto.

Attivare la Rete di Sicurezza

La verità sincera: i checkpoint sono attivabili manualmente in Hermes v2. La maggior parte degli utenti non ne ha mai bisogno, e lo spazio di archiviazione può crescere nel tempo. Ma se stai lavorando su qualcosa di importante, sono un vero salvavita.

Hai due modi per attivarli:

Per sessione (solo per una chat):

hermes chat --checkpoints

Globalmente (in ~/.hermes/config.yaml):

checkpoints:
  enabled: true

Tutto qui. Una volta attivati, Hermes crea automaticamente un’istantanea del tuo progetto prima di qualsiasi operazione distruttiva.

Cosa Attiva un Checkpoint?

Hermes è intelligente su quando creare le istantanee. Tiene d’occhio:

• Operazioni sui file — come write_file e patch
• Comandi terminale distruttivi — come rm, mv, sed -i, truncate, e persino git reset o git clean

La parte migliore? Crea al massimo un checkpoint per directory per turno, quindi le tue sessioni lunghe non genereranno centinaia di istantanee.

Tornare Indietro: I Comandi Slash

Quando sei in una sessione di chat, /rollback è il tuo migliore amico:

Comando	Cosa fa
/rollback	Mostra tutti i checkpoint con le statistiche delle modifiche
/rollback <N>	Ripristina il checkpoint N, mantenendo le tue modifiche manuali
/rollback <N> --all	Ripristino completo — sovrascrive anche le tue modifiche manuali
/rollback diff <N>	Anteprima delle modifiche tra il checkpoint N e ora
/rollback <N> <file>	Ripristina solo un file dal checkpoint N

Il /rollback <N> predefinito è furbo — mantiene tutte le modifiche che hai fatto a mano, annullando solo ciò che ha fatto l’agente. Se vuoi una pulizia totale, usa --all.

Gestire lo Store dal Terminale

Fuori dalla chat, hai comandi CLI per ispezionare e gestire i tuoi checkpoint:

hermes checkpoints              # Mostra dimensione, progetti, dettagli
hermes checkpoints status       # Come sopra
hermes checkpoints list         # Alias per status
hermes checkpoints prune        # Pulisce orfani e dati obsoleti
hermes checkpoints clear        # Elimina tutto (chiede conferma prima)
hermes checkpoints clear-legacy # Rimuove vecchi archivi di migrazione v1

Come Funziona Sotto il Cofano

Ti starai chiedendo: “Questo interferisce con il mio vero repo git?” No. Hermes mantiene uno “store ombra” separato in ~/.hermes/checkpoints/store/. Il tuo .git del progetto reale non viene mai toccato.

Tutti i tuoi progetti condividono questo unico store, e poiché git è content-addressable, i file che compaiono in più progetti vengono salvati una sola volta. È sorprendentemente efficiente.

Regolare le Impostazioni

Puoi controllare quanto spazio di archiviazione usano i checkpoint:

checkpoints:
  enabled: true
  max_snapshots: 20           # Checkpoint massimi per progetto
  max_total_size_mb: 500      # Limite massimo totale dello store
  max_file_size_mb: 10        # Salta file più grandi di questo
  auto_prune: true            # Pulizia automatica delle voci vecchie
  retention_days: 7           # Mantieni le voci per 7 giorni
  min_interval_hours: 24      # Pulisci al massimo una volta al giorno

La funzione di auto-pruning è intelligente — pulisce le voci vecchie all’avvio ma non elimina mai le voci “orfane” (progetti le cui cartelle non vengono trovate). Questo perché una cartella mancante potrebbe semplicemente significare che un disco esterno non è ancora montato. Per la pulizia degli orfani, dovrai eseguire hermes checkpoints prune manualmente.

Il Tasto Annulla del Tuo Progetto

I checkpoint ti danno la fiducia per lasciare che il tuo agente AI lavori liberamente, sapendo che puoi sempre tornare indietro nel tempo. Che tu stia rifattorizzando codice, sperimentando con le configurazioni, o semplicemente cercando tranquillità, vale la pena attivarli.

Provali nella tua prossima sessione con hermes chat --checkpoints. Potresti non aver mai bisogno di fare rollback — ma se dovesse servire, sarai felice che ci siano.