Claude Code: la nuova auto-memory, come funziona davvero

Una delle aggiunte più utili degli ultimi mesi a Claude Code è la memoria persistente basata su file. Non è un database remoto, non è un servizio cloud: sono semplici file Markdown nella directory di progetto, che Claude legge e scrive in autonomia per ricordare informazioni utili da una sessione all’altra. In questa guida vediamo come funziona davvero, quando vale la pena lasciar fare a Claude, quando intervenire a mano e perché non va confusa con i task o con il file CLAUDE.md.

Cos’è e cosa non è

La auto-memory di Claude Code è una directory di file Markdown dentro al profilo locale, organizzata per progetto. Ogni voce è un singolo file con un blocco di metadati (nome, descrizione, tipo) e un corpo testuale che Claude consulta nei prompt successivi. C’è un file indice, MEMORY.md, che funziona da elenco navigabile: una riga per ogni voce, sempre caricato nel contesto.

Non è un sostituto del file CLAUDE.md di progetto, che resta il posto giusto per istruzioni di sistema durature (“usa questa convenzione”, “test con questo comando”). Non è nemmeno il task tracker della sessione corrente, che serve a tenere traccia dei passi in corso e si svuota a fine conversazione. La memoria sta in mezzo: ricordi che attraversano le sessioni, ma non sono regole architetturali del codice.

I quattro tipi di memoria

Claude distingue le voci per tipo, e il tipo guida sia il momento di scrittura sia il momento di richiamo.

• user: chi è l’utente, ruolo, competenze, obiettivi. Serve a tarare il tono delle risposte. Esempio: “data engineer con dieci anni di Python, prima volta su Rust”.
• feedback: correzioni e conferme sul modo di lavorare. Includono il perché. Esempio: “non aggiungere riassunti a fine risposta, perché l’utente legge già la diff”.
• project: stato di iniziative, deadline, decisioni che non si possono derivare dal codice o da git. Esempio: “freeze merge dal 30 maggio per release mobile”.
• reference: puntatori a sistemi esterni. Esempio: “i bug della pipeline sono in Linear progetto INGEST”.

Come Claude decide cosa salvare

La regola operativa è semplice: si salva quello che non si può ricostruire dal codice corrente o dalla cronologia git. Una convenzione di naming è derivabile leggendo i file, quindi non va in memoria. Una preferenza personale del tipo “preferisci PR singole, non spezzate” non si deduce, quindi va salvata come feedback.

Il momento di scrittura è quando Claude vede una correzione esplicita (“no, non così”) o una conferma non scontata (“sì, esatto, continua su questa linea”). I corretti sono ovvi; le conferme sono più sottili e vengono spesso perse, con il risultato che il modello diventa eccessivamente prudente nelle sessioni successive. Una memoria di tipo feedback ben scritta include il perché, perché serve a giudicare i casi limite e non solo a ripetere meccanicamente la regola.

File system in pratica

La directory di lavoro è una cartella memory all’interno del profilo Claude Code, dedicata al progetto specifico. Ogni voce è un file con un nome parlante: feedback_no_mocks_in_db_tests.md, project_release_mobile_freeze.md, reference_grafana_dashboard.md. Niente sottocartelle: l’organizzazione è semantica per nome, non gerarchica.

Il file MEMORY.md è l’indice: una riga per voce, sotto i 200 caratteri, con titolo e descrizione sintetica. Viene caricato a ogni conversazione: tenerlo asciutto evita che si saturi il contesto. Tutto il dettaglio sta nei file referenziati, che vengono aperti su richiesta.

Quando torna utile davvero

Tre esempi concreti dove la memoria fa la differenza.

Il primo caso è quando un team applica convenzioni locali non scritte. Ad esempio, in un repo i test di integrazione devono colpire un database reale e mai mock, perché in passato un mock divergente ha mascherato un bug in produzione. Senza memoria, Claude tende a riproporre i mock a ogni nuova sessione, perché è la prassi più comune. Con la memoria, la regola è presente e Claude tiene il punto.

Il secondo caso è il salto di contesto tra progetti diversi sulla stessa macchina. Ogni progetto ha la sua directory di memoria. Cambiando cartella di lavoro, Claude carica le voci giuste e non confonde le convenzioni di un repo con quelle di un altro.

Il terzo caso è la continuità di lavoro a settimane di distanza. Stati come “il refactor del modulo X è bloccato sulla decisione di prodotto Y, in attesa di conferma da Z entro fine mese” si perdono facilmente. Una voce di tipo project li conserva senza dover ricostruire il filo ogni volta.

Quando non usarla

La memoria non va caricata di pattern di codice già visibili nei file, di output di comando (“ho corso npm install, è andata”), di riassunti di attività della sessione in corso. Tutto questo è già derivabile o appartiene al log della conversazione. Se Claude viene istruito a salvare un riassunto delle ultime modifiche, in pratica sta scrivendo una versione peggiore del git log.

Una memoria scaduta è peggio di una memoria mancante. Voci che citano file e funzioni invecchiano: il file viene rinominato, la funzione cambia firma, il flag viene rimosso. Prima di affidarsi a una voce che fa nomi di codice, vale la pena verificare che il riferimento esista ancora. Claude lo fa di propria iniziativa quando deve agire, ma la regola è applicabile anche a chi rilegge la cartella memoria a mano.

Privacy e perimetro

I file restano locali al disco di chi usa Claude Code. Non vengono sincronizzati su un servizio remoto, non sono condivisi automaticamente tra account. Per i team che vogliono condividere conoscenza permanente sul progetto, il posto giusto resta il file CLAUDE.md versionato nel repository, che vale per tutti i collaboratori. La auto-memory è per la coppia “io e Claude”, non per il team.

Domande frequenti

Posso modificare i file di memoria a mano?

Sì. Sono file Markdown editabili con qualunque editor. Una modifica manuale è utile per correggere imprecisioni, eliminare voci obsolete o riorganizzare il MEMORY.md.

Come faccio a dire a Claude di dimenticare una cosa?

Basta chiederlo esplicitamente: “dimentica che X”. Claude individua la voce e la rimuove dall’indice e dalla cartella.

La memoria si carica tutta in ogni sessione?

No. Si carica sempre l’indice MEMORY.md, mentre i singoli file si aprono al bisogno quando il contesto della conversazione li rende rilevanti.

La auto-memory non cambia il modo in cui Claude scrive codice, ma cambia il modo in cui resta coerente nel tempo. Vale la pena spenderci dieci minuti la prima settimana, aprire la cartella, leggere cosa è stato salvato e aggiustare ciò che non serve più. Da quel momento in poi è un’infrastruttura che lavora da sola in sottofondo.

Fausto Pitzalis

Blogger dal 2001, Nativo Digitale, Developer.
Da 15 anni mi occupo di IT per una grande Azienda.
Lavoro per abbattere il Digital Divide.
Visita i miei altri progetti
sardiniamobility.com
www.cyberness.it