Memoria per agenti AI: 5 regole per non ripetere errori

Ogni sessione AI riparte da zero: l'agente rifà l'errore di ieri e ti rifà la stessa domanda. Con una cartella di file di testo e due abitudini, leggere all'inizio e scrivere alla fine, gli dai una memoria. La prepari in mezz'ora e funziona con qualsiasi agente che legge file.

Cos'è

Un secondo cervello per l'agente: una cartella di note in markdown (testo semplice con titoli e liste) che l'agente legge quando inizia e aggiorna quando finisce. Dentro ci sono le trappole già incontrate, le soluzioni che funzionano, le decisioni prese e un diario di cosa è successo ogni giorno.

Perché serve

Senza una memoria che resta, ogni sessione è il primo giorno di lavoro. L'agente non sa che quel bug l'avete già risolto, né perché avete scelto quella libreria. Così lo rifà, e tu rispieghi.

Da quando lavoriamo così, su sei progetti di clienti in produzione abbiamo visto il 63% in meno di bug già noti che tornano, e il 40% in meno di tempo perché un nuovo agente si ambienti nel progetto (febbraio 2026). Per noi è la soglia tra un prototipo e un progetto che regge.

1. Parti semplice: una cartella di file markdown

Cos'è: la memoria più semplice possibile, fatta di file di testo.

Perché serve: la nostra prima versione era una cartella di Obsidian (un'app gratuita per prendere note in markdown) che Claude Code leggeva e scriveva in ogni sessione. Markdown, link tra le note, una cartella per progetto. Niente di più. Ha funzionato, e da lì è nato tutto il nostro modo di dare memoria agli agenti. Gli strumenti semplici battono quelli sofisticati quando seguono un lavoro vero.

Come si fa: crea nel progetto una cartella, per esempio "memoria", con quattro sottocartelle:

• trappole: errori già fatti e come evitarli, una nota per trappola;
• schemi: soluzioni che funzionano e vanno riusate;
• decisioni: cosa avete scelto e perché;
• diario: un file per giorno, con una riga per ogni lavoro finito.

Obsidian non è obbligatorio: è comodo per leggere le note e vedere i collegamenti, ma l'agente lavora sui file e basta.

2. Apri ogni sessione leggendo trappole e regole

Cos'è: un'istruzione fissa che fa leggere la memoria all'agente prima di lavorare.

Perché serve: una memoria che nessuno legge non serve. La lettura deve essere automatica, non affidata al fatto che tu te ne ricordi.

Come si fa: metti l'istruzione nel file che il tuo agente legge da solo all'avvio. In Claude Code è CLAUDE.md, nella cartella del progetto. Altri strumenti hanno un file simile, per esempio AGENTS.md.

Pronto da copiare, da incollare in quel file:

3. Chiudi ogni sessione scrivendo nel diario

Cos'è: una riga di diario a fine lavoro, scritta dall'agente.

Perché serve: il diario è la storia del progetto. Domani un altro agente, o tu, legge cosa è stato fatto e cosa si è scoperto senza scavare tra le conversazioni.

Come si fa: aggiungi questa istruzione sotto la precedente, nello stesso file.

4. Scrivi poco, e di proposito

Cos'è: un filtro su cosa merita di entrare in memoria.

Perché serve: la memoria di un agente non è un database che salva tutto in automatico e poi cerca per somiglianza. È scrittura voluta: regole, trappole, decisioni. Un agente che sa cosa non ricordare è più utile di uno che ricorda tutto, perché non affoga nel rumore.

Come si fa: prima di salvare una nota, fai passare la scoperta da quattro domande. Se anche una sola risposta è no, non si salva.

5. Collega la memoria al codice e le note tra loro

Cos'è: due tipi di collegamento. Un breve commento nel codice che rimanda alla nota giusta (lo chiamiamo breadcrumb, briciola di pane), e link tra le note che parlano della stessa cosa.

Perché serve: l'agente apre un file e trova subito la trappola che lo riguarda, senza cercarla. E le note collegate formano una mappa: da una trappola arrivi alla decisione che l'ha causata. Nel nostro editor Quack questa memoria è diventata un grafo: dopo tre mesi contava 1.847 note collegate, con il 58% in meno di errori ricorrenti e il 41% in meno di domande ripetute all'utente.

Come si fa:

1. Quando risolvi un bug che ha una nota in memoria, metti sopra il codice un commento con il nome della nota, per esempio "Memoria: trappole/doppio-addebito".
2. In ogni nota aggiungi in fondo i link alle note collegate. In Obsidian si scrivono tra doppie parentesi quadre.
3. Una volta al mese chiedi all'agente di trovare note doppie o superate e di proporti cosa unire o cancellare.

Prova piccola

Dieci minuti. Pensa a un errore che il tuo agente ha fatto questa settimana. Scrivi una nota in memoria/trappole con titolo, causa e soluzione, e aggiungi l'istruzione della regola 2 al file di avvio. Poi apri una sessione nuova e dagli un compito vicino a quell'errore.

È riuscita se l'agente cita la nota prima di iniziare e non rifà l'errore. Se non la cita, il titolo della nota non è abbastanza chiaro: riscrivilo con le parole che useresti tu per chiedere il compito.

Attenzione a

• Mai segreti nelle note. Password, chiavi e token vanno in un gestore di password, non in file che l'agente legge e che magari finiscono su git.
• Le note invecchiano. Una trappola risolta da una nuova versione diventa un consiglio sbagliato. Scrivi la data in ogni nota e fai pulizia.
• Più memoria non vuol dire più qualità. Ogni nota letta occupa spazio nel contesto dell'agente e costa. Per questo si leggono prima solo i titoli.
• Rivedi quello che l'agente salva. Per questo le istruzioni chiedono il tuo OK: una regola sbagliata in memoria si ripete in ogni sessione.
• I numeri sono nostri, misurati sui nostri progetti. Contano più le due abitudini che le percentuali.

Passo successivo: se più agenti leggono la stessa memoria, organizzali con 5 regole per gli agenti in parallelo. Se una trappola si ripete sempre nello stesso processo, trasformalo in una skill che l'agente esegue.

In breve: Un agente smette di ripetere gli errori quando legge le trappole note a inizio sessione, scrive le scoperte alla fine e salva solo quello che servirà davvero.