La memoria di Claude Code: memoria automatica, MEMORY.md e i suoi limiti

Claude Code apre ogni sessione con la finestra di contesto vuota. Quello che ieri aveva capito sulla build, sui test o su come vuoi i messaggi di commit è sparito, a meno che qualcosa non l'abbia scritto. Le cose che scrivono sono due: i file CLAUDE.md, che scrivi tu, e la memoria automatica, cioè gli appunti che Claude prende per sé.

Qui parliamo della seconda. Dove stanno quegli appunti, cosa ci finisce, quanta parte ne legge davvero Claude a inizio sessione, come si guarda dentro e come si spegne. E dove smette di bastare.

Cos'è la memoria automatica di Claude Code

La memoria automatica (in inglese auto memory) permette a Claude di conservare quello che impara da una sessione all'altra senza che tu scriva niente. Mentre lavora salva appunti di quattro tipi, segnati nel campo type del frontmatter di ogni file:

• user: il tuo ruolo, la tua esperienza, come ti piace lavorare;
• feedback: le correzioni che gli dai e gli approcci che hai approvato;
• project: lavori in corso, scadenze e decisioni che dal codice o dalla storia di git non si ricavano;
• reference: dove trovare le cose fuori dal progetto, come il sistema dei ticket o una dashboard.

Conta anche quello che lascia fuori. Claude non salva niente che possa ricavare dal codice (architettura, percorsi dei file, come è stato risolto un bug) e niente che il tuo CLAUDE.md dica già. E non salva qualcosa a ogni sessione: scrive un appunto solo quando pensa che servirà in una conversazione futura.

Puoi anche chiederlo tu. Se dici «ricordati che i test delle API vogliono un Redis locale», finisce nella memoria automatica. Se lo vuoi nel CLAUDE.md devi dirlo: «aggiungilo al CLAUDE.md».

Dove stanno i file: MEMORY.md e i file per argomento

Ogni progetto ha una cartella in ~/.claude/projects/<progetto>/memory/. Il progetto si ricava dal repository git, quindi tutti i worktree e le sottocartelle dello stesso repository condividono una sola memoria. Fuori da git vale la cartella principale del progetto.

Dentro ci sono un indice e un file per ogni ricordo:

~/.claude/projects/<progetto>/memory/
├── MEMORY.md           # l'indice, una riga per ricordo
├── user_role.md        # un ricordo
├── feedback_testing.md # un altro ricordo
└── ...

MEMORY.md fa da sommario, i file per argomento tengono i dettagli. È tutto Markdown semplice: lo leggi, lo correggi o lo cancelli quando vuoi.

Dalla versione 2.1.214 Claude Code aggiunge anche una data modified nel frontmatter ogni volta che Claude riscrive un file che ce l'ha. Sembra poco, però serve: tu e Claude vedete quanto è vecchia un'informazione prima di fidarvi.

E questi file non se ne vanno con le vecchie trascrizioni. La pulizia che cancella le sessioni dopo cleanupPeriodDays salta la cartella della memoria, quindi un appunto resta finché tu o Claude non lo togliete.

Cosa si carica a inizio sessione

Questa è la parte più facile da fraintendere. A inizio sessione Claude non legge tutta la sua memoria: legge le prime 200 righe di MEMORY.md o i primi 25 KB, quello che arriva prima. Il resto non entra.

I file per argomento all'avvio non si caricano proprio. Claude li apre con i normali strumenti per i file quando decide che gli servono, e quello che c'è lo sa dall'indice. Un appunto scritto bene ma assente dall'indice, o finito oltre la riga 200, in pratica non lo legge nessuno.

Claude Code tiene d'occhio le dimensioni. Dopo ogni scrittura su MEMORY.md lo confronta con i due limiti. Se è vicino, chiede a Claude di asciugarlo: una riga per voce, dettagli nei file per argomento, voci vecchie unite o tolte. Se è oltre, la scrittura va a buon fine lo stesso, ma Claude riceve un errore che gli chiede di riscrivere l'indice, perché al caricamento successivo le righe in più verrebbero tagliate.

Per confronto, i CLAUDE.md quel taglio non ce l'hanno: Claude Code ne carica uno per intero fino a 4 MiB e salta quelli più grandi. Più corti funzionano comunque meglio, e cosa metterci l'abbiamo visto in CLAUDE.md e AGENTS.md.

Come vederla, modificarla o disattivarla

In una sessione lancia /memory. Elenca i tuoi CLAUDE.md, ha un interruttore per la memoria automatica e apre la cartella, così vedi cosa ha salvato Claude. Quando l'interfaccia scrive «Saved 2 memories» o «Recalled 2 memories», è Claude che sta scrivendo o leggendo lì.

La memoria automatica è accesa di default nelle sessioni locali. Per spegnerla ci sono più strade:

• l'interruttore in /memory, che scrive autoMemoryEnabled in ~/.claude/settings.json;
• "autoMemoryEnabled": false nelle impostazioni di un singolo progetto, per spegnerla solo lì;
• la variabile d'ambiente CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Per tenere la cartella altrove c'è autoMemoryDirectory nelle impostazioni: un percorso assoluto, oppure che inizia con ~/.

Un dettaglio che spiazza: i subagent non ricevono la memoria automatica della conversazione principale. Fa eccezione il fork, che eredita la conversazione da cui nasce. Un subagent può avere una memoria sua, se la attivi con il campo memory, ma è un'altra cartella.

I limiti della memoria di Claude Code

La memoria automatica fa bene il lavoro per cui è nata: ricordare come lavori tu, in questo repository, su questo computer. I limiti vengono dallo stesso disegno.

Sta sul computer. La documentazione lo dice chiaro: i file non si condividono tra macchine o ambienti cloud. Passi dal fisso al portatile e Claude riparte da zero.

È solo tua. Sta nella tua cartella utente, non nel repository, quindi un collega che lavora sullo stesso codice non ne vede niente. Il suo Claude Code impara le stesse lezioni da capo.

È solo di Claude Code. Quello che Claude ricorda nell'app di chat è un altro sistema (l'abbiamo spiegato in La memoria di Claude), e gli altri agenti questa cartella non la leggono. Una decisione presa in chat con Claude, o in una sessione con un altro agente, qui non arriva.

E l'indice è piccolo. 200 righe bastano per le preferenze e qualche trappola. Non bastano per la storia intera di un progetto con più clienti, un anno di decisioni e i loro perché.

Una memoria che segue il progetto, non il computer

Niente di questo è un motivo per spegnere la memoria automatica. Lasciala accesa per le piccole cose personali. Per quello che serve a tutto il team, la soluzione è tenerlo fuori dal tuo computer e far leggere e scrivere a Claude Code attraverso un connettore. Claude Code supporta MCP, un protocollo aperto, e lo stesso fanno Codex e le app di Claude e ChatGPT.

Con una memoria condivisa in Markdown ogni cliente o progetto è una cartella con regole, decisioni e note. Bastano un paio di righe nel CLAUDE.md per dire a Claude Code di caricare quella cartella all'inizio (start_session sul progetto) e di scrivere lì le decisioni nuove, invece che in un file locale. Da quel momento le note sono le stesse su ogni computer, l'app di chat legge la stessa cartella, e puoi condividere un ramo con un collega, in sola lettura o con permesso di scrittura.

Costa anche meno di quanto sembri, perché Claude cerca nelle note e legge solo quello che serve, invece di caricare tutto all'avvio. Perché conta lo spieghiamo in costi di contesto.

Per questo abbiamo fatto Cobrain. La guida per Claude Code richiede pochi minuti, e per provarlo basta il piano gratuito.

Domande rapide

Dove salva la memoria Claude Code? In ~/.claude/projects/<progetto>/memory/, con un indice MEMORY.md e un file Markdown per ogni ricordo. Il progetto si ricava dal repository git, quindi i worktree condividono la stessa cartella.

Perché Claude Code ha dimenticato una cosa che gli avevo detto? O ha deciso che non valeva la pena salvarla, o l'appunto sta oltre le prime 200 righe o i primi 25 KB di MEMORY.md, che è tutto quello che si carica all'avvio. Apri /memory e guarda nella cartella.

Che differenza c'è tra CLAUDE.md e MEMORY.md? CLAUDE.md lo scrivi tu, con istruzioni e regole, e si carica per intero. MEMORY.md lo scrive Claude come indice di quello che ha imparato, e se ne carica solo l'inizio.

La memoria di Claude Code si sincronizza tra computer? No. La memoria automatica resta sulla macchina. Per avere le stesse conoscenze ovunque, tienile in note condivise che Claude Code raggiunge via MCP.

Come si disattiva la memoria automatica di Claude Code? Con l'interruttore in /memory, con "autoMemoryEnabled": false nelle impostazioni del progetto, oppure con la variabile d'ambiente CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.