La memoria di Claude Code: cosa ricorda davvero e cosa no

La memoria di Claude Code non è soltanto il file CLAUDE.md che scrivi tu. La memoria automatica è l'insieme di note che Claude scrive da solo mentre lavora, salvate sul tuo computer fuori dal repository, ed è attiva di default. Il changelog ufficiale di Claude Code registra alla versione 2.1.228, dell'11 agosto 2026, una correzione che riguarda proprio quel materiale: la pulizia di sessione cancellava contenuti dentro la cartella di memoria di un progetto.

È il tipo di bug che si nota tardi, perché quelle note nessuno le ha scritte a mano e nessun sistema di versionamento le sta guardando. Il segnale che qualcosa è sparito non è un errore, è Claude che smette di sapere una cosa che sapeva la settimana prima.

Dove finisce la memoria di Claude Code

Ogni progetto ha la propria cartella in ~/.claude/projects/<project>/memory/, secondo la documentazione ufficiale di Claude Code. La parte <project> deriva dal repository git, quindi tutti i worktree e le sottocartelle dello stesso repository condividono una sola cartella di memoria. Dentro c'è MEMORY.md, che fa da indice, e accanto i file per argomento che Claude crea quando ha bisogno di dividere il materiale, con nomi come debugging.md o api-conventions.md.

All'avvio di ogni conversazione viene caricato solo l'indice, e nemmeno tutto: le prime 200 righe di MEMORY.md oppure i primi 25KB, a seconda di quale limite arriva prima. I file per argomento non entrano in sessione all'avvio, Claude li apre con i normali strumenti di lettura quando gli servono. Se l'indice supera la soglia la scrittura riesce lo stesso, ma Claude Code restituisce un errore che chiede di riscriverlo, perché tutto quello che sta oltre verrebbe buttato via al caricamento successivo.

La riga della documentazione che cambia davvero il modo di ragionare è un'altra: la memoria automatica è locale alla macchina, e i file non vengono condivisi fra macchine diverse né con gli ambienti cloud. Nessuna sincronizzazione, nessun backup, nessuna copia dall'altra parte. Quello che c'è dentro esiste in un posto solo, ed è un posto che non passa da git.

Cosa corregge la versione 2.1.228

Il changelog ufficiale di Claude Code, alla voce 2.1.228 dell'11 agosto 2026, corregge la pulizia di sessione che cancellava contenuti dentro la cartella di memoria di un progetto. Nella stessa versione c'è una seconda correzione della stessa famiglia: la pulizia in background della cache dei plugin eliminava la cache di un plugin quando la sua unica versione era un checkout di sviluppo collegato via symlink. Due routine di manutenzione che toccavano qualcosa che doveva restare.

Vale la pena guardarle insieme, perché descrivono una categoria precisa di difetto. Non sono crash e non producono un messaggio: sono cancellazioni silenziose di stato che sta fuori dal repository, e chi le subisce se ne accorge dal comportamento, non dai log. È la stessa dinamica dei bug che colpiscono le sessioni non presidiate, di cui ho scritto parlando di come far girare Claude Code in automatico: il difetto c'è, ma non arriva a nessuno.

Cosa tenere nella memoria automatica e cosa nel repository

La posizione che ho preso su questo è netta: la memoria automatica di Claude Code è una comodità, non una fonte di verità. Tutto quello che deve sopravvivere a un cambio di macchina, a un collega nuovo o a una cartella cancellata va scritto nel repository, dove è versionato e leggibile da chiunque. Alla memoria automatica resta il suo lavoro utile, che è ricordare le cose piccole che nessuno ha voglia di scrivere: il comando esatto per far girare i test, la trappola scoperta debuggando alle undici di sera, la preferenza corretta due volte di fila.

Le routine che scrivono su questo blog sono il caso limite che rende evidente la differenza. Girano come sessioni cloud schedulate, documentate in automazione-blog/cloud-agent/, e ogni mattina partono da un checkout appena clonato: per loro la memoria automatica non esiste, perché la documentazione dice esplicitamente che quei file non vengono condivisi con gli ambienti cloud. Tutto quello che devono sapere sta committato nel repository, il CLAUDE.md in radice e le regole di scrittura in .claude/skills/articolo/. Non è stata una scelta di eleganza, è l'unica che funziona quando la macchina cambia ogni giorno.

Quattro cose concrete da fare, in ordine di quanto costano.

1. Guarda cosa c'è dentro. Il comando /memory elenca i file di memoria e permette di aprire la cartella della memoria automatica, mentre /context mostra sotto la voce Memory files quali sono stati caricati davvero nella sessione in corso. Sono file markdown normali: si leggono, si correggono e si cancellano a mano.
2. Se un progetto contiene roba che non deve finire in note fuori dal repository, spegnila lì. Basta "autoMemoryEnabled": false nelle impostazioni di quel progetto, oppure CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 come variabile d'ambiente per disattivarla ovunque sulla macchina.
3. Se preferisci tenere la memoria in una cartella tua, magari dentro un percorso che salvi già, imposta autoMemoryDirectory nel settings.json. Il valore deve essere un percorso assoluto o iniziare con ~/, e quando lo metti nelle impostazioni di un progetto viene onorato solo dopo aver accettato il dialogo di fiducia per quella cartella.
4. Se ci tieni a quelle note, aggiorna. La 2.1.228 è la versione che chiude la cancellazione durante la pulizia di sessione, e il campo modified che marca la data di scrittura dentro i file di memoria richiede almeno la 2.1.214.

La stessa domanda si sposta di peso sugli agenti che costruite voi, dove però la memoria non ve la gestisce nessuno e va progettata: ne ho scritto guardando cosa mettere nella memoria di un agente AI e dove tenerla, perché le regole di igiene sono identiche e i posti dove finiscono i dati no.

Il punto che porto via da questa versione non è il bug. È che la memoria automatica ha spostato un pezzo di configurazione fuori dal progetto senza che nessuno lo decidesse, e le regole di igiene che valgono per il file CLAUDE.md e le skill non ci sono ancora arrivate. Chi sta mettendo un agente AI dentro un processo di lavoro farebbe bene a chiedersi la stessa cosa che vale per qualsiasi sistema: dove vive lo stato, chi lo può cancellare e cosa succede il giorno in cui sparisce. Le note di rilascio complete stanno sul changelog ufficiale di Claude Code, e il funzionamento della memoria è documentato nella pagina ufficiale sulla memoria.