Claude Code Memory: guida al contesto persistente

Ogni sessione di Claude Code inizia allo stesso modo: nessuna memoria di ieri. Passi venti minuti a spiegare il flusso di autenticazione della tua API lunedì, e martedì lo stai spiegando di nuovo, perché niente nel funzionamento del modello lo porta avanti da solo. Quel divario è la correzione più richiesta che sentiamo dai team che usano Claude Code ogni giorno, ed è anche la più fraintesa, perché "dai a Claude una memoria" non è una singola funzionalità. Sono quattro meccanismi con lavori, costi e modi di fallire diversi.

Questa guida li mette in ordine: cosa risolve davvero ciascun livello, cosa appartiene a quale, come configurare una skill di memoria come claude-mem, e la matematica dei token che spiega perché ricordare è economico mentre riscoprire gli stessi fatti ogni sessione non lo è.

Il problema del giorno della marmotta

Un modello linguistico non ha stato tra una chiamata API e l'altra. Ogni messaggio che invii include l'intera conversazione fino a quel punto, e quando quella conversazione finisce, finisce anche tutto ciò che il modello "sapeva" del tuo progetto. Apri una nuova sessione domani e sei di nuovo a una lavagna vuota, a prescindere da quali file capitano a stare su disco.

Andrebbe bene se le sessioni fossero brevi e autonome. Non lo sono. Il lavoro vero si estende su più giorni: correggi un bug lunedì, lo stesso pattern compare in un file diverso giovedì, e l'agente non ha modo di collegare i due se qualcosa fuori dalla conversazione non ha portato avanti quella connessione. Ogni sessione senza di essa paga una tassa di riscoperta: leggere gli stessi file, reimparare le stesse convenzioni, occasionalmente ripetere un errore già corretto.

La correzione non è una finestra di contesto più grande. Le finestre di contesto sono già grandi, e il problema non è la capacità, è la continuità. Quello che vuoi è un posto fuori dalla conversazione dove fatti e decisioni sopravvivono, più un modo per Claude di ricaricare la fetta giusta di quel posto quando conta. Questa è la memoria, e Claude Code ti dà quattro modi per costruirla.

I quattro livelli della memoria di Claude

Il primo livello è CLAUDE.md: fatti di progetto statici che scrivi una volta, che si caricano per intero all'inizio di ogni sessione. Il secondo livello è l'auto-memoria, una cartella di file che Claude scrive da solo, accumulando fatti nel tempo senza che tu li scriva a mano. Il terzo livello sono le skill di memoria, che catturano e comprimono il contesto di sessione automaticamente e lo re-iniettano più tardi. Il quarto livello è l'opzione low-tech: un semplice file di note che l'agente legge e aggiorna perché glielo hai detto tu.

Non sono opzioni in competizione. Risolvono problemi diversi, e la maggior parte delle configurazioni serie ne fa girare due o tre insieme.

Livello 1: CLAUDE.md, fatti statici che si caricano sempre

CLAUDE.md è il meccanismo di memoria più vecchio e semplice di Claude Code. È un file markdown che Claude Code trova risalendo dalla tua directory di lavoro, e si carica per intero, ogni sessione, prima che tu digiti qualsiasi cosa. Questo lo rende il posto giusto per fatti che sono veri quasi sempre: come eseguire i test, quale gestore di pacchetti usa il repo, quale cartella è legacy e off-limits.

È il posto sbagliato per qualsiasi cosa che cambia spesso o si applica occasionalmente, perché "si carica per intero, ogni sessione" è anche il suo costo. Un CLAUDE.md da 3.000 righe sono circa 30.000 token tassati su ogni richiesta, che quella richiesta ne abbia bisogno o no. Copriamo l'aritmetica completa e un esempio annotato reale nella nostra guida alle best practice di CLAUDE.md; la versione breve è che CLAUDE.md vuole fatti stabili, non un log che cresce.

È anche lì che CLAUDE.md finisce la strada. È statico: lo scrivi, Claude lo legge, e aggiornarlo è una faccenda manuale che devi ricordarti di fare. I prossimi tre livelli esistono per gestire fatti che si accumulano da soli.

Livello 2: auto-memoria e cartelle di memoria

Il livello intermedio è una cartella di memoria, spesso ~/.claude/memory/ o un equivalente locale al progetto, dove Claude scrive note strutturate su ciò che impara e le rilegge all'inizio delle sessioni future. A differenza di CLAUDE.md, nessuno scrive a mano la maggior parte di queste voci. L'agente decide che qualcosa vale la pena ricordare, una decisione che hai preso, una preferenza che hai dichiarato, un fatto che ha dovuto scavare per trovare, e lo archivia con struttura sufficiente per recuperarlo dopo.

Qui vive la skill Memory Management, ed è la skill con il punteggio più alto in questa categoria su SkillProof: 9,2 su 10. L'abbiamo eseguita per una settimana intera di sessioni vere, non una singola demo, e ha retto sotto uso reale. Claude ha richiamato in modo affidabile decisioni e preferenze di progetto che aveva archiviato, e la precisione del richiamo è rimasta alta anche man mano che l'archivio cresceva, la parte che di solito si rompe per prima nelle implementazioni ingenue.

Ciò che separa questo livello da CLAUDE.md è che è selettivo anche in entrata quanto lo è in uscita. Una skill di memoria ben costruita indicizza cosa ha archiviato e tira fuori la fetta rilevante per il task attuale, così l'archivio può crescere fino a migliaia di voci senza che ogni sessione paghi per tutte quante.

Livello 3: skill di memoria, claude-mem e cattura automatica

Il terzo livello porta l'idea oltre. Invece che Claude decida a metà conversazione cosa vale la pena salvare, una skill dedicata cattura l'intera sessione automaticamente, la comprime, e re-inietta il contesto rilevante nella prossima. Claude-mem è l'esempio più chiaro di questo pattern. Il suo pitch è "contesto persistente tra le sessioni per ogni agente": osserva cosa fa il tuo agente durante una sessione, comprime quell'attività con un passaggio di riassunto AI, e fa emergere la versione compressa la prossima volta che è rilevante, attraverso Claude Code e, secondo la sua stessa documentazione, diversi altri runtime di agenti.

Dobbiamo essere onesti su dove si trova nei nostri test. Claude-mem è emersa dal nostro crawler GitHub con 85.685 stelle, motivo per cui è in coda per un test completo invece di portare già un verdetto; non pubblichiamo un punteggio finché non abbiamo installato una skill pulita e fatta girare contro lavoro vero, la stessa barra che Memory Management ha già superato. Quello che possiamo dire ora è architetturale: la cattura automatica rimuove il momento in cui altrimenti ti fermeresti a decidere, a metà sessione, se qualcosa vale la pena ricordare. La skill decide per te. Se regge per una settimana intera su una macchina pulita è a cosa serve la coda di test.

Livello 4: file semplici come memoria

L'ultimo livello non ha bisogno di nessuna skill: un semplice file markdown, di solito chiamato qualcosa come notes.md o progress.md, che chiedi a Claude di leggere all'inizio di una sessione e aggiornare alla fine. Nessuna indicizzazione, nessuna cattura automatica, nessun punteggio. Sei tu il sistema di memoria; il file è solo dove lo scrivi.

Questo livello è sottovalutato perché sembra troppo semplice per contare. Non lo è. Per un progetto in solitaria con un solo contributore e una manciata di fili in corso, un file di note che mantieni davvero batte un sistema di memoria automatico che non guardi mai. Il modo di fallire sta interamente su di te, però: nessuno lo sfoltisce, nessuno segnala contraddizioni, e cresce in un muro di testo con gli stessi punti ciechi di qualsiasi documento non mantenuto. Funziona esattamente tanto bene quanto la tua disciplina nell'aggiornarlo, non di più.

Cosa appartiene dove: la tabella delle decisioni

Tipo di memoria	Adatto per	Si carica	Manutenzione
CLAUDE.md	Fatti stabili e sempre veri (comandi di build, convenzioni, insidie)	Per intero, ogni sessione	Manuale, modifica a mano
Auto-memoria / cartella di memoria	Decisioni e preferenze che si accumulano nel tempo	Selettivamente, al recupero	Per lo più automatica (gestita dalla skill)
Skill di memoria (claude-mem)	Contesto di sessione completo, catturato senza che tu decida cosa conta	Compresso, iniettato quando rilevante	Cattura automatica, revisione occasionale
File di note semplice	Progetti in solitaria, fili semplici in corso	Manuale, dici tu a Claude di leggerlo	Interamente manuale

Leggi quella tabella per ciò che cambia, non per ciò che è comodo da configurare. Se un fatto sarebbe ancora vero tra sei mesi, appartiene a CLAUDE.md. Se è una decisione presa questa settimana che potrebbe contare di nuovo più avanti, appartiene alla memoria. Se non puoi prevedere cosa avrai bisogno di ricordare e non vuoi decidere sul momento, quello è il caso per la cattura automatica. Se niente di tutto ciò si applica, un file di note batte comunque il niente.

Configurare claude-mem, passo per passo

Il pattern generale per una skill di memoria a cattura automatica assomiglia a questo, usando claude-mem come esempio concreto:

1. Clona la skill. git clone https://github.com/thedotmack/claude-mem in una directory di lavoro, poi segui lo script di installazione del repo invece di copiare i file a mano. Le skill di memoria di solito hanno bisogno di registrare un hook, non solo di posizionare un SKILL.md.

2. Riavvia Claude Code. L'installazione tipicamente collega un hook di inizio o fine sessione così la cattura avviene senza che tu invochi nulla. Un riavvio è ciò che lo attiva.

3. Fai girare una sessione normale. Non testarla con un task giocattolo. Fai lavoro vero; il punto è vedere cosa decide valga la pena ricordare quando nessuno guarda per il test.

4. Avvia la sessione successiva e controlla cosa è tornato. Chiedi a Claude cosa ricorda del lavoro di ieri prima di dire qualsiasi altra cosa. Qualcosa di specifico e corretto significa che la cattura funziona. Qualsiasi cosa vaga o sbagliata significa controllare la configurazione prima di fidarti con qualcosa che conta.

5. Fissa una cadenza di revisione. La cattura automatica senza revisione si trasforma in accumulo automatico di rumore. Datti una fascia ricorrente di dieci minuti per scorrere cosa è stato archiviato (più su questo sotto l'igiene della memoria, più sotto).

Se preferisci partire da qualcosa già valutato, Memory Management è la strada manuale-ma-testata: installa la cartella della skill in ~/.claude/skills/, e crea la propria cartella di memoria al primo uso, senza bisogno di installare un hook separato.

L'economia in token della memoria

Ecco la matematica che rende la configurazione valere il costo. Diciamo che un fatto di progetto richiede 500 parole per essere spiegato da zero: la forma del tuo flusso di autenticazione, perché una certa tabella ha due chiavi esterne, cosa fa davvero lo script di deploy. Spiegato di nuovo in chat, sono circa 650 token di input ogni volta che lo rispieghi, oltre al tempo che passi a digitarlo e al tempo che Claude passa a ragionarci sopra in quel messaggio.

Archiviato in memoria invece, lo stesso fatto costa quei 650 token una volta, per scriverlo. Il recupero dopo costa una frazione di quello: un livello di memoria ben indicizzato tira fuori un riassunto compresso, spesso sotto i 100 token, solo quando il task attuale tocca quel fatto. Spiegalo in chat cinque volte nell'arco di un mese e hai speso circa 3.250 token per reinsegnare ciò che la memoria sarebbe costata 650 token per imparare e 500 in totale per richiamare cinque volte: un divario approssimativo di cinque a uno che si allarga più spesso quel fatto serve.

Confronta questo con lo stipare tutto in CLAUDE.md invece: un fatto rilevante una sessione su venti si carica comunque sulle altre diciannove, senza selettività per recuperare quel costo. Il preambolo fisso che la tua configurazione porta su ogni turno (CLAUDE.md, schemi di strumenti, iniezioni di memoria) compete direttamente con il tuo lavoro vero per spazio e attenzione. Lo abbiamo misurato più a fondo, con conteggi reali di token prima/dopo, nella nostra guida sui costi in token; la memoria è una voce in quel quadro più grande, spesso la correzione più economica rispetto a quanto risparmia.

Igiene della memoria: il rituale di revisione

Un sistema di memoria che si limita ad accumulare non è una funzionalità, è una perdita lenta. Le voci obsolete non falliscono rumorosamente; niente si rompe quando Claude richiama una decisione che hai invertito tre settimane fa. Semplicemente agisce in silenzio su informazioni obsolete, e tu bruci tempo di debug capendo perché l'agente è sicuro di sé ma sbagliato su qualcosa che sai di aver corretto.

Fai un passaggio mensile, dieci minuti, la stessa disciplina del rituale di revisione di CLAUDE.md che consigliamo altrove. Apri l'archivio di memoria. Per ogni voce che sembra portante, chiediti se è ancora vera, se una decisione che descrive è stata invertita da allora, e se è abbastanza specifica per agire. Elimina qualsiasi cosa fallisca. Un archivio di memoria di cui sei orgoglioso è più piccolo un anno dopo di quanto lo fosse tre mesi dopo; la crescita dovrebbe essere in precisione, non in volume.

Il trigger più affidabile per una revisione, però, non è il calendario. È il momento in cui Claude fa qualcosa di sbagliato a causa di una memoria obsoleta. Trattalo come un bug: correggi la voce nello stesso respiro dell'errore, non al tuo prossimo passaggio programmato.

Privacy: cosa viene catturato, dove finisce

Le skill di memoria leggono cosa succede nelle tue sessioni, quindi la domanda onesta è cosa viene catturato e dove finisce. Per la memoria basata su file, Memory Management, claude-mem e l'approccio a note semplici allo stesso modo, la risposta è di solito la stessa: tutto viene scritto in file di testo semplice sul tuo stesso disco, tipicamente sotto ~/.claude/ o una cartella di memoria locale al progetto, non su un server di terze parti. Niente lascia la tua macchina a meno che tu non committi quei file in un repo condiviso o una skill documenti esplicitamente una funzione di sincronizzazione remota.

Questa è una buona notizia per il controllo e una cattiva notizia se dai per scontato che sia automaticamente sicuro. Un file di memoria è un registro in chiaro di cosa hai lavorato, e può includere credenziali menzionate di passaggio, nomi di clienti, o dettagli architetturali che non vorresti in un repo pubblico. Leggi cosa c'è davvero in una cartella di memoria prima di committarla insieme al tuo codice, e prima di installare qualsiasi skill di memoria, controlla la sua sorgente per capire cosa significhi davvero "cattura tutto ciò che fa il tuo agente", incluso se anche l'output di comandi contenente segreti viene raccolto. La cattura automatica merita lo stesso scrutinio di qualsiasi strumento che legge il tuo terminale.

FAQ

Claude Code ha memoria persistente integrata?

Parzialmente. CLAUDE.md ti dà memoria statica sempre caricata pronta all'uso, ed è genuinamente integrata, nessuna installazione richiesta. Qualsiasi cosa oltre i fatti statici, memoria che si accumula, viene indicizzata, e viene recuperata selettivamente, attualmente arriva da una skill invece che da una funzionalità nativa.

Qual è la differenza tra CLAUDE.md e una skill di memoria?

CLAUDE.md si carica per intero, ogni sessione, e lo mantieni a mano. Una skill di memoria scrive e legge un archivio crescente selettivamente, tirando fuori solo ciò che è rilevante per il task attuale, e gran parte della scrittura avviene senza che tu la faccia manualmente. Usa CLAUDE.md per fatti che non cambiano mai; usa una skill di memoria per fatti che si accumulano.

Claude-mem è sicura da installare adesso?

Non possiamo ancora dare un verdetto. È nella nostra coda di test, non valutata, nonostante il suo grande seguito su GitHub. Installala come installeresti qualsiasi cosa non valutata: su un progetto in cui puoi permetterti di sperimentare per primo, e leggi la sorgente prima di fidarle sessioni sensibili.

Quanto costa in token far girare una skill di memoria?

Meno dell'alternativa in quasi tutti i casi. L'archiviazione in sé è quasi gratis dato che vive su disco, non nel contesto. Il recupero all'inizio della sessione tipicamente costa molto meno che rispiegare lo stesso fatto in chat, e il divario si allarga più volte quel fatto verrebbe altrimenti rispiegato.

Dovrei usare più di un livello di memoria contemporaneamente?

Sì, e la maggior parte delle configurazioni funzionanti lo fa: CLAUDE.md per fatti che non cambiano mai, più una skill di memoria o un file di note disciplinato per fatti che si accumulano. Trattali come complementari invece di sceglierne uno preferito. Il punto è abbinare ogni tipo di fatto al livello costruito per esso, non stabilirsi su un unico meccanismo per tutto.