Come creare agenti AI che non dimenticano (usando i file di memoria)

La maggior parte degli agenti AI non fallisce perché il modello è scadente.

Falliscono perché si risvegliano con l'amnesia a ogni sessione.

Dici a Claude: "usiamo pnpm, non npm."

Sessione successiva: prova di nuovo npm.

Gli dici: "niente default export qui."

Sessione successiva: scrive un default export.

Ogni correzione che fai svanisce nel momento in cui la sessione finisce.

C'è una soluzione in un unico file.

Ci sono voluti tre mesi di ripetizioni per trovarla.

Ecco tutto ciò che ho imparato.

Perché la maggior parte degli agenti AI fallisce

Non è il modello.

È il livello mancante sotto il modello.

→ Scrivi un prompt

→ L'agente esegue il compito

→ La sessione finisce

→ La memoria svanisce

→ Sessione successiva: stessi errori

→ Ripeti le stesse istruzioni

→ Per sempre

Questo loop è la singola più grande fonte di tempo sprecato nella programmazione con l'AI.

Non codice scadente. Non allucinazioni.

Ripetizione.

Il livello mancante: la memoria

Tutti si fissano su quale modello sia il più intelligente.

Livello sbagliato.

Il vero miglioramento non è un modello più intelligente.

È dare al modello un posto dove memorizzare ciò che impara.

→ Prompt → dicono all'agente cosa fare adesso

→ Agenti → eseguono il compito

→ Memoria → mantiene il contesto tra le sessioni

→ Contesto persistente → niente più correzioni ripetute

→ Sistema di apprendimento → l'agente migliora davvero col tempo

Questa è la differenza tra uno strumento e un compagno di squadra.

Uno strumento fa quello che dici, ogni volta, partendo da zero.

Un compagno di squadra ricorda ciò che è successo ieri.

I 5 file di memoria di cui ogni agente AI ha bisogno

Una volta accettato che la memoria è il livello mancante, la prossima domanda è: dove risiede?

Cinque file. Ognuno con un ruolo diverso.

→ CLAUDE.md — il documento di briefing personale di Claude

→ AGENTS.md — lo standard universale, letto da tutti i principali strumenti

→ CLAUDE.local.md — le tue preferenze personali, mai in git

→ MEMORY.md — appunti che l'AI scrive su sé stessa, automaticamente

→ README.md — per umani, non per agenti

Vediamoli uno per uno.

CLAUDE.md — quello che ha dato il via a tutto

Mettilo nella root del tuo progetto.

Claude lo legge all'inizio di ogni sessione.

Pensalo come un documento di briefing per un nuovo membro del team con amnesia.

Un buon CLAUDE.md ha quattro sezioni:

→ Contesto del progetto — una riga. "App e-commerce Next.js con Stripe e Postgres."

→ Stile del codice — non "formatta il codice correttamente" ma "usa ES modules, named export, indentazione a 2 spazi."

→ Comandi — stringhe esatte. pnpm test:integration, non "esegui i test."

→ Architettura — "Le route API vanno in /src/api/[risorsa]/route.ts. Pattern repository per l'accesso al DB."

1# CLAUDE.md
2
3## Contesto del Progetto
4App e-commerce Next.js 14. Integrazione Postgres + Stripe.
5
6## Stile del Codice
7- Solo ES modules
8- Named export, mai default export
9- Indentazione a 2 spazi
10- TypeScript modalità strict
11
12## Comandi
13- Installazione: pnpm install
14- Sviluppo: pnpm dev
15- Test: pnpm test:integration
16- Lint: pnpm lint:fix
17
18## Architettura
19- Route API: /src/api/[risorsa]/route.ts
20- Accesso DB: solo pattern repository
21- Componenti: /src/components, un file per componente

Obiettivo: meno di 300 righe.

Ogni riga compete per l'attenzione con il lavoro vero.

Esegui /init e Claude genera automaticamente un file iniziale.

Poi cancella la maggior parte.

Il file predefinito include cose che Claude sa già dal tuo package.json. Tieni solo ciò che Claude sbaglierebbe senza il file.

Il sistema @imports — mantienilo snello

CLAUDE.md non deve contenere tutto.

Può importare altri file:

Vedi

@README .md per la panoramica del progetto Vedi

@docs/api-patterns .md per le convenzioni API Vedi

@package .json per gli script npm disponibili

Gli import possono essere ricorsivi — fino a 5 livelli di profondità.

Questo risolve il problema del "file unico gigante".

Per i team: il team frontend possiede docs/frontend-rules.md.

La sicurezza possiede docs/security.md.

CLAUDE.md li importa semplicemente tutti.

Un file radice. Molte fonti specializzate.

AGENTS.md — lo standard universale

CLAUDE.md funziona solo per Claude.

Se il tuo team usa anche Cursor, Copilot o Gemini CLI — loro non lo leggono mai.

AGENTS.md risolve questo problema.

Un file. Ogni agente principale lo legge.

Supportato da Claude Code, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Aider, Zed, Warp e altri.

È markdown standard. Nessuno schema speciale. Nessun YAML richiesto.

1# AGENTS.md
2
3## Panoramica del Progetto
4Piattaforma e-commerce costruita con Next.js 14, Postgres e Stripe.
5
6## Build e Test
7- Installazione: pnpm install
8- Sviluppo: pnpm dev
9- Test: pnpm test
10- Lint: pnpm lint:fix
11
12## Standard di Codice
13- TypeScript modalità strict
14- Named export anziché default export
15- Route API seguono convenzioni REST in /src/api/
16
17## Requisiti di Test
18- Tutte le PR devono includere test
19- vitest per unit test, playwright per e2e

Pensalo come un README per agenti AI.

README.md è per umani. AGENTS.md è per ogni agente, indipendentemente dal fornitore. CLAUDE.md aggiunge extra specifici di Claude sopra.

Sono complementari. Non in competizione.

Auto-memoria — l’AI che si prende appunti da sola

Questo è il livello più nuovo e interessante.

Claude Code ora scrive i propri file di memoria durante le tue sessioni.

memory/ ├── MEMORY.md ← indice, caricato ogni sessione ├── debugging.md ← appunti sui pattern di debug ├── api-conventions.md ← decisioni di progettazione API └── ...

Il cambiamento chiave:

Tu scrivi CLAUDE.md. Tu fornisci le istruzioni.

Claude scrive MEMORY.md. Cattura ciò che ha imparato.

→ L'umano scrive le regole

→ L'agente scopre pattern mentre lavora

→ L'agente scrive la propria memoria

→ Le sessioni future iniziano più intelligenti

Puoi attivarlo direttamente. Alla fine di una sessione produttiva, dì semplicemente:

"Aggiorna i tuoi file di memoria con ciò che hai imparato oggi sul nostro codebase."

Le conoscenze persistono. Niente più dover rispiegare il tuo wrapper ORM personalizzato per la quinta volta.

Esegui /memory in qualsiasi momento per rivedere o modificare ciò che Claude ha salvato.

Il flusso di lavoro /init poi cancella

Il modo più veloce per avviare un file di memoria su un nuovo progetto:

1. Esegui /init nella directory del tuo progetto
2. Claude genera un CLAUDE.md iniziale basato sul tuo codebase
3. Cancella ciò che non ti serve

Il passaggio 3 è dove la maggior parte delle persone sbaglia.

Il file generato è una bozza, non un prodotto finito.

Spesso include riempitivi. "Questo progetto usa JavaScript." Grazie — è visibile da package.json.

Modificare una bozza ragionevole è meglio che scrivere da un file vuoto.

Dopo la configurazione, costruisci organicamente.

Quando Claude fa un'ipotesi sbagliata — ad esempio continua a importare un pacchetto deprecato — non correggerlo solo una volta.

Digli: "aggiungi al mio CLAUDE.md: importa sempre da @company/utils-v2, non da @company/utils."

L'istruzione persiste per ogni sessione futura.

Ogni poche settimane, chiedi a Claude di rivedere e pulire CLAUDE.md.

Le istruzioni si accumulano. Alcune diventano ridondanti. Altre iniziano a entrare in conflitto. Una revisione rapida lo mantiene efficace.

La mia configurazione attuale

Dopo aver testato tutto questo su vari progetti in produzione, ecco cosa è rimasto:

→ AGENTS.md nella root del progetto — istruzioni condivise che qualsiasi strumento AI legge. Comandi di build, standard di codice, requisiti di test.

→ CLAUDE.md con @imports per comportamenti specifici di Claude. Sotto le 100 righe, per lo più rimanda a file in docs/.

→ CLAUDE.local.md per le mie stranezze personali — i miei dati di test, URL sandbox, comandi abbreviati. Mai in git.

→ Auto-memoria attivata. Claude si prende appunti. Io li revisiono mensilmente.

→ Tutto il resto sostituito con symlink che puntano ad AGENTS.md. Un'unica fonte di verità.

1# Configurazione symlink per coerenza tra più strumenti
2ln -sfn AGENTS.md .github/copilot-instructions.md
3mkdir -p .cursor/rules && ln -sfn ../../AGENTS.md .cursor/rules/main.mdc

Non elegante.

Ma elimina la deriva delle istruzioni tra tutti gli strumenti del team.

Il cambiamento più grande

La maggior parte degli sviluppatori pensa:

Modello migliore = agente migliore.

Sbagliato.

La vera formula:

Modello + Memoria + Recupero + Feedback = Agente Utile

Un modello più intelligente senza memoria dimenticherà comunque il tuo comando di test domani.

Un modello modesto con una grande memoria diventa più affilato ogni settimana.

La memoria è la variabile che si accumula.

L'intelligenza del modello no.

Il miglioramento più grande che ho fatto al mio flusso di lavoro con l'AI non è stato cambiare modello.

È stato dare una memoria al modello.

La differenza tra:

"Claude, usiamo pnpm" — ogni singola sessione

e:

"Claude lo sa già" — ogni singola sessione

È la differenza tra uno strumento e un compagno di squadra.

Se è stato utile:

→ Ripubblica per condividerlo con ogni sviluppatore che ancora si ripete con Claude

→ Segui @sairahul1 per altri sistemi che crescono mentre dormi

→ Aggiungi ai segnalibri — impostalo stasera, smetti di correggere domani

Scrivo di AI, creazione di prodotti e sistemi che funzionano senza di te.