Il problema della memoria di Claude Code e come gli sviluppatori lo stanno risolvendo

Claude Code ha una memoria persistente integrata, ma ha un bug di troncamento silenzioso a 200 righe che fa dimenticare cose al tuo agente senza avvisarti. L’ecosistema di terze parti sta riempiendo i gap, e la disciplina di manutenzione della memoria è quello che separa chi ottiene valore da chi ottiene confusione.

Alcune sezioni con approfondimenti sono evidenziate in blu.

Perché ti dovrebbe interessare

Ogni volta che avvii una nuova sessione con Claude Code, riparti da zero. L’agente non ricorda cosa hai costruito ieri, i bug già risolti, o perché hai scelto un’architettura invece di un’altra. Ri-spieghi. Lui ri-chiede. Dieci minuti di overhead per ogni sessione, che in un anno di sviluppo quotidiano si sommano a 40-60 ore di puro spreco.

È il problema dell’“amnesia AI”, uno dei maggiori punti di attrito per chi usa agenti di coding. La buona notizia: Claude Code ora ha una memoria persistente integrata. La cattiva: il sistema ha un limite silenzioso che può farti perdere contesto senza che tu te ne accorga. E intanto, un ecosistema di soluzioni di terze parti sta esplodendo per colmare le lacune.

Vediamo come funziona la memoria integrata, dove si rompe, e cosa stanno costruendo gli sviluppatori per risolvere il problema.

Come funziona la memoria integrata di Claude Code

Dalla versione 2.1.59 (febbraio 2026), Claude Code viene distribuito con Auto Memory attiva di default. È un sistema basato su file con due livelli complementari: CLAUDE.md e Auto Memory vera e propria.

CLAUDE.md: le tue regole, scritte da te

Sono file Markdown che inserisci nel progetto per dire a Claude come lavorare. Pensali come la “costituzione” che Claude legge all’inizio di ogni sessione. Esistono in quattro ambiti:

Ambito	Posizione	Scopo
Organizzazione	`/Library/Application Support/ClaudeCode/CLAUDE.md`	Policy IT/DevOps
Progetto	`./CLAUDE.md` o `./.claude/CLAUDE.md`	Istruzioni condivise dal team
Utente	`~/.claude/CLAUDE.md`	Preferenze personali (tutti i progetti)
Locale	`./CLAUDE.local.md`	Preferenze specifiche del progetto (aggiungi a .gitignore)

Supportano la sintassi @path/to/import, la traversata dell’albero delle directory e regole con ambito di percorso in .claude/rules/.

Auto Memory: gli appunti di Claude, scritti da Claude

Qui diventa interessante. Claude salva automaticamente le cose che impara mentre lavori: correzioni dell’utente, insight di debug, comandi di build scoperti, decisioni architetturali. Il tutto è salvato in ~/.claude/projects/<project>/memory/ come indice MEMORY.md più file tematici come debugging.md, api-conventions.md o build-commands.md.

**Approfondimento:** Ogni memoria rientra in una di quattro categorie: **Utente** (con chi sto parlando?), **Feedback** (cosa devo ripetere o evitare?), **Progetto** (cosa sta succedendo ora?), e **Riferimento** (dove cerco X?). Ogni file di memoria usa frontmatter strutturato con nome, descrizione e tipo. Il design è deliberato: anche centinaia di memorie stanno in poche centinaia di token di contesto, perché l'indice è solo puntatori di una riga ai file tematici.

Auto Dream: il “sonno REM” per gli agenti AI

Lanciato insieme ad Auto Memory, Auto Dream esegue un passaggio di consolidamento in background. Legge le memorie attuali, scansiona le trascrizioni delle sessioni per correzioni e temi ricorrenti, poi consolida: converte le date relative in assolute, elimina i fatti contraddetti, pota le voci obsolete e mantiene l’indice sotto le 200 righe. Si attiva automaticamente dopo 24 ore e 5+ sessioni, oppure manualmente dicendo “dream” o “consolidate my memory files.”

La trappola delle 200 righe

Qui arriva la limitazione critica che la documentazione non pubblicizza in modo prominente: MEMORY.md ha un limite di troncamento silenzioso a 200 righe. Arrivi a 201 e le memorie cadono silenziosamente dal fondo dell’indice. Nessun errore. Nessun avviso. Claude non sa cosa non sa.

**Approfondimento:** Il meccanismo di recupero stesso è un collo di bottiglia. A ogni turno, Claude Code fa una chiamata API separata a Claude Sonnet solo per determinare quali file di memoria sono rilevanti. Scansiona tutti i nomi file e le descrizioni, invia quel manifesto a Sonnet e gli chiede di sceglierne 5. È un passaggio di rilevanza semantica, ma funziona su nomi file e descrizioni di una riga, non su embedding o ricerca vettoriale. Cinque file per turno, massimo.

La modalità di fallimento a cascata è reale: Claude scrive un test che colpisce un endpoint instabile perché quella memoria è stata troncata. Chiede di nuovo della policy di PR review perché quella memoria è stata troncata. Contraddice una decisione architetturale concordata mesi fa perché quella memoria è stata troncata. Non sta allucinando. Non è rotto. Ha solo dimenticato, e non ha modo di dirtelo.

Il codice sorgente include una funzione memoryFreshnessText() che avvisa delle memorie più vecchie di un giorno. Ma si attiva solo per le memorie effettivamente caricate. Le memorie troncate non vengono mai caricate, quindi nessun avviso viene mai generato.

La trappola della conferma

**Approfondimento:** Una delle osservazioni più interessanti dalla comunità è quella che è stata chiamata la "trappola della conferma": i sistemi di memoria AI sono facili da correggere ma difficili da confermare. La tua directory di memoria finisce con 10 regole che dicono "evita X" e zero regole che dicono "preferisci Y." Il risultato è un agente cauto ma non bravo. Sa cosa non fare, ma non cosa fare.

La soluzione è consapevole: quando Claude fa una buona scelta, dillo esplicitamente. “Sì, era l’approccio giusto” attiva l’archiviazione in memoria proprio come farebbe una correzione. Richiede sforzo deliberato, ma senza di esso la memoria del tuo agente diventa una lista unilaterale di fallimenti.

L’ecosistema di terze parti

I limiti del sistema integrato hanno generato un ecosistema vibrante di alternative e integrazioni. Ecco le principali:

Beads (21K stelle GitHub): un tracker di issue basato su Dolt, progettato per agenti AI, non per umani. È essenzialmente “Jira, ma per AI.” Memorizza grafi di lavoro strutturati e consapevoli delle dipendenze fuori dalla finestra di contesto. Setup minimo: bd init nel tuo progetto, e Claude fa il resto.
mem0: sostituisce la memoria basata su file con un vector store. Le memorie vengono embeddate, il recupero usa la similarità degli embedding. Nessun limite di 200 righe, nessun limite di 5 file, nessun troncamento silenzioso. Ideale per codebase grandi con 200+ voci di memoria.
MemClaw: risolve l’isolamento tra progetti. Ogni progetto ha il suo workspace isolato. Zero contaminazione incrociata. Critico per freelance e agenzie che lavorano su più clienti.
Framework personalizzati: molti sviluppatori costruiscono i propri con database vettoriali (ChromaDB, Pinecone, pgvector), schemi SQLite personalizzati, o directory di memoria strutturate con recupero programmatico. Il pattern è costante: parti col sistema integrato, raggiungi il limite, costruisci qualcosa che scala.

Il gap della condivisione tra team

**Approfondimento:** Auto Memory vive in `~/.claude/`, non nel repository. Non si sincronizza tra macchine. I colleghi non ottengono nessun contesto appreso. Questa è probabilmente la lacuna più grande del sistema attuale. Il codice sorgente contiene un feature flag `TEAMMEM` per memorie con ambito di team, con separazione privato/team dove le convenzioni di progetto vanno nella memoria di team e le preferenze personali restano private, ma non è ancora stato rilasciato.

I file CLAUDE.md e .claude/rules/ sono i livelli condivisibili dal team, ma richiedono manutenzione manuale. L’“effetto interesse composto” che rende la memoria così potente per sviluppatori solisti (dopo 50 sessioni, Claude inizia con un contesto equivalente a un mese di onboarding umano) non si trasferisce affatto ai team.

Cosa funziona nella pratica

Il pattern più efficace per progetti attivi combina tre file:

CLAUDE.md: regole stabili e decisioni architetturali (le scrivi tu)
MEMORY.md: conoscenza di progetto accumulata da Claude (le scrive Claude)
CONTEXT.md: note di passaggio di sessione (le scrivi tu o Claude tra le sessioni)

Un handoff di sessione ben strutturato in CONTEXT.md può ridurre il tempo di avvio da 10 minuti a 30 secondi:

# CONTEXT.md - Session Handoff
Ultima sessione: 11 aprile 2026

## Completato
- Implementato createNotification() in src/services/notifications.ts
- Aggiunta tabella notification_events (migrazione: 20260411_add_notifications)

## Aperto
- Invio email: servizio creato, non ancora collegato agli invii effettivi

## Prossima sessione: Inizia da qui
1. Collegare l'invio email di notifica tramite Resend
2. Costruire la pagina delle preferenze di notifica

Obsolescenza: il killer silenzioso

La memoria marcisce. Una memoria che dice “auth è in middleware/auth.ts” è sbagliata nel momento in cui qualcuno rinomina il file. La documentazione Anthropic raccomanda revisioni mensili della directory di memoria. Non è manutenzione opzionale. È un vincolo ingegneristico. Prima di raccomandare qualcosa basandoti sulla memoria, verifica: i percorsi dei file esistono ancora, i nomi delle funzioni sono ancora nel codice, i sistemi esterni sono ancora raggiungibili.

La regola è semplice: “La memoria dice che X esiste” non equivale a “X esiste ora.”

I dettagli tecnici

Da qui in poi si entra nel tecnico. Se ti interessa l’idea più dell’implementazione, puoi saltare direttamente alla conclusione.

Architettura del recupero delle memorie

A ogni turno di conversazione, Claude Code esegue questo flusso:

Legge l’indice MEMORY.md (max 200 righe)
Invia il manifesto di tutti i nomi file e descrizioni a Claude Sonnet
Sonnet seleziona i 5 file più rilevanti
Solo quei 5 file vengono caricati nel contesto della sessione

Il collo di bottiglia è il passo 2-3: la rilevanza semantica opera su nomi file e descrizioni di una riga, non su embedding vettoriali. Questo significa che la qualità del recupero dipende interamente da quanto bene i file di memoria sono nominati e descritti.

Auto Dream: meccanismo di consolidamento

Auto Dream si attiva quando si verificano entrambe le condizioni:

Sono passate 24+ ore dall’ultimo dream
Ci sono state 5+ sessioni dall’ultimo dream

Il processo esegue: conversione date relative → assolute, rimozione contraddizioni, potatura voci obsolete, mantenimento indice sotto 200 righe. Può anche essere invocato manualmente con “dream” o “consolidate my memory files.”

Il punto

Punti chiave:

La memoria persistente di Claude Code funziona, ma ha un troncamento silenzioso a 200 righe che fa perdere contesto senza avviso
Il recupero basato su nomi file (non embedding) limita la rilevanza a 5 file per turno
La mancanza di condivisione tra team è il gap più grande: l’effetto composto vale per sviluppatori solisti, non per i team
La manutenzione della memoria non è opzionale: le memorie obsolete sono peggio di nessuna memoria

La tecnologia della memoria AI c’è. La disciplina di mantenerla è quello che separa gli sviluppatori che ottengono rendimenti composti da quelli che ottengono confusione composta.