Memoria persistente, RAG, allegati: quando servono

Quattro modi di portare informazione al modello: prompt manuale, allegati nella sessione, memoria persistente del prodotto, RAG (retrieval augmented generation). Confonderli porta a sovraingegnerizzare per task piccoli (RAG dove bastava un allegato) o a sottostimare per task grandi (allegati a una knowledge base intera invece di RAG). Saperli distinguere è scelta di architettura, non opzione tecnica.

Perché questa lezione conta

L’industria parla molto di RAG come se fosse la soluzione universale. Per il 90% dei vibe-coder è overkill: un prompt ben strutturato + 2-3 file allegati copre la maggior parte dei casi. Per il restante 10% (knowledge base aziendale, doc tecniche di prodotto, manuali API) RAG è davvero utile. Sapere quale strumento usare quando evita ore di setup non necessario o sessioni che falliscono per mancanza di info.

Obiettivo operativo

Alla fine devi saper:

1. distinguere quattro meccanismi di contesto e cosa fa ognuno;
2. scegliere il meccanismo giusto per tre scenari tipici;
3. valutare rischi (allucinazione, leak dati, info stale) per ogni opzione.

Nucleo della lezione

1. Quattro meccanismi

Prompt manuale: scrivi nel prompt tutto ciò che serve. Niente file allegati, niente memoria.

Quando: task piccolo, autocontenuto, contesto < 5KB di testo. Esempio: “scrivi regex per validare codice fiscale italiano”.

Pro: zero setup, zero costi extra. Contro: non scala, ripeti tutto a ogni sessione.

Allegati nella sessione: fornisci file specifici al modello (drag&drop in chat, “@file” in IDE AI, lettura via tool dell’agente). Validi per la sessione corrente.

Quando: task richiede contesto specifico (codice di 1-3 file, doc puntuale, dataset piccolo). Sessione singola o riusabile entro la stessa conversazione.

Pro: contesto preciso, senza inventare. Contro: ripeti a ogni nuova sessione.

Memoria persistente del prodotto: feature offerte da Claude Projects, ChatGPT memory, Cursor rules, Continue rules. Salva info che vengono re-iniettate in ogni nuova sessione.

Quando: preferenze stabili (ruolo, vincoli, stack), informazioni su di te, regole di progetto leggere.

Pro: persistenti, automatiche. Contro: limiti di dimensione, asincrone (non sempre subito visibili al modello), gestione poco trasparente in alcuni prodotti.

RAG (retrieval augmented generation): sistema che, ad ogni query, cerca documenti rilevanti in una base esterna (vector DB, search engine), e inietta i top N risultati nel prompt.

Quando: knowledge base grande (centinaia o migliaia di documenti), info aggiornate (manuale prodotto, doc API, regolamenti), domande su contenuto specifico (“come si configura X nel nostro sistema?”).

Pro: scala, copre info che non stanno nella finestra di contesto. Contro: setup non banale, qualità dipende fortemente dal recupero, rischio di info irrilevanti che confondono.

2. Scelta in tre scenari

Scenario A: piccola repo personale, lavori da solo

• Default: prompt manuale + allegati specifici.
• File di regole + decisioni in AGENTS.md + decisions.md (versionati nella repo).
• Memoria persistente: utile per preferenze tue (es. “preferisco TypeScript strict, no any”).
• RAG: non serve.

Scenario B: knowledge base aziendale (manuale prodotto, doc procedure)

• File di regole AI con elementi base.
• RAG sui documenti aziendali. Setup: vector DB (Pinecone, Weaviate, Qdrant, pgvector), embedding ricalcolati a cambi documenti, integrazione con tool AI usato.
• Allegati: solo per task one-shot.
• Memoria: limitata utilità.

Considerazioni: aggiornamento (chi ricalcola embedding), governance (chi può vedere cosa), pertinenza (RAG cattivo è peggio di RAG assente: inietta rumore).

Scenario C: documentazione di un’API/SDK pubblica

• RAG su documentazione + esempi.
• Caching del prompt per parti stabili (riduce costo).
• Allegati per esempi specifici.

3. Rischi e qualità

Tre rischi principali:

Contesto sbagliato: RAG recupera doc non pertinenti, modello li usa come autorità. Mitigazione: misurare precision/recall del retrieval, filtrare per metadata (data, fonte, versione).

Materiale obsoleto: doc con info di 2 anni fa, modello le presenta come correnti. Mitigazione: filtra per data, etichetta esplicitamente quando un doc è “history vs current”, aggiornamento ricorrente della base.

Leakage di dati: memoria persistente o knowledge base contiene info sensibili (PII, credenziali, dati clienti). Diversi utenti vedono cose che non dovrebbero. Mitigazione: governance (chi indicizza cosa), separazione tenant, mai indicizzare segreti.

Qualità retrieval ≠ qualità generazione. Anche con buon retrieval, il modello può ignorare o stravolgere. Verifica empirica: quante volte la risposta cita correttamente vs inventa?

Procedura pratica

Per decidere il meccanismo:

1. Stima dimensione conoscenza: KB di testo? MB? GB?
2. Stima frequenza accesso: una volta? a ogni task? a ogni messaggio?
3. Stima volatilità info: stabile per anni? cambia mensilmente? quotidianamente?
4. Privacy/sensibilità: pubblico? interno? confidenziale?

Mappa:

• < 50KB stabile, accesso frequente → prompt + allegato fisso o memoria persistente.
• < 5KB volatile, una sessione → allegato.

• 100KB ma < 1MB stabile, accesso frequente → prompt caching + sezione fissa nel prompt.

• 1MB o volatile o cresce → RAG.

• Materiale sensibile → mai memoria persistente di prodotti SaaS senza accordi specifici.

Laboratorio guidato

Tre casi reali, scegli meccanismo:

Caso 1: piccola repo personale (4000 righe), lavori da solo, vuoi che il modello rispetti convenzioni stack.

→ Prompt manuale + AGENTS.md versionato + memoria persistente per preferenze tue (es. lingua di output).

Caso 2: knowledge base aziendale (200 documenti, sigle, processi interni). Vuoi che il modello risponda a domande dei dipendenti su procedure HR, IT, security.

→ RAG con vector DB. Embedding di documenti, indicizzati per categoria. Filtri per gruppo utente (sicurezza). Aggiornamento mensile.

Caso 3: SDK pubblico che produci, vuoi assistente che risponda a domande sviluppatori.

→ RAG su documentazione + esempi codice. Allegato per “ultima versione SDK”. Prompt caching per parti stabili.

Per ognuno: stima costo setup, costo a regime, qualità attesa.

Output atteso

Una guida personale a una pagina che mappa “tipo di conoscenza → meccanismo”: stack/regole, decisioni, doc tecniche, knowledge base. Riferimento per future scelte.

Studio passo passo

Studia questa lezione in tre passaggi, senza correre subito al prompt o al codice.

1. Prima lettura: chiarisci l’obiettivo: capire quando basta fornire file mirati e quando servono meccanismi più avanzati di recupero conoscenza. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Allegati e file selezionati per task locali, memoria persistente per preferenze durature, RAG per basi documentali grandi.
• Qualità del recupero: non basta caricare documenti, bisogna verificare pertinenza, fonte e aggiornamento.
• Rischi: contesto sbagliato, materiale obsoleto, leakage di dati, falsa autorevolezza di documenti interni.

3. Applicazione: svolgi il laboratorio: decidere quale forma di contesto usare per tre casi: piccola repo, knowledge base aziendale, manuale API. L’output da ottenere è: una guida di scelta tra prompt manuale, file allegati, memoria e recupero documentale.

Prima di passare alla lezione successiva, controlla di avere un artefatto concreto: una tabella, un prompt, una checklist, un mini report, un diff commentato o una decisione scritta. Nel vibe coding la comprensione resta astratta finché non produce una traccia verificabile.

Checklist di verifica

• so distinguere prompt manuale, allegati, memoria persistente, RAG;
• ho default chiaro per progetto solo (prompt + allegati + AGENTS.md);
• so quando RAG diventa necessario;
• ho politica esplicita per dati sensibili (cosa non indicizzare).

Errori comuni

RAG come default. Setup di vector DB per progetto da 1000 righe = procrastinazione travestita.

Niente RAG quando serve. Knowledge base con migliaia di documenti, lavori a copia-incolla. Iterazioni infinite.

Memoria persistente come archivio. Riempi memory di tutto, modello dimentica priorità, output peggiora.

RAG con embedding stale. Aggiorni doc, embedding restano vecchi. Risposte sbagliate.

Indicizzare dati sensibili. Email clienti, segreti, PII finiscono in vector DB → recuperati in query random → leak.

Confondere quantità e qualità retrieval. “Top 20 risultati” non è meglio di “Top 3 mirati”. Più rumore = output peggiore.

Prompt di lavoro

Aiutami a scegliere il meccanismo di contesto giusto per questo caso:

Conoscenza da portare al modello:
- Tipo: [codice / doc / dati / procedure / regolamenti / ...]
- Dimensione: [KB / MB / GB]
- Frequenza accesso: [una sessione / a ogni task / a ogni messaggio]
- Volatilità: [stabile per anni / mensile / quotidiana]
- Privacy: [pubblico / interno / confidenziale]
- Numero utenti: [solo io / piccolo team / molti]

Per ognuno dei 4 meccanismi (prompt manuale, allegati, memoria persistente, RAG):

1. Fit con il caso (alto/medio/basso) + motivazione.
2. Costo setup stimato.
3. Costo a regime stimato.
4. Rischi specifici al mio caso.

Concludi con raccomandazione esplicita e indicazione di soglia per migrare al meccanismo successivo (es. "fino a 50 documenti allegati va, oltre RAG").

Esercizio finale

Apri tre conversazioni AI recenti su progetti diversi. Per ognuna, identifica: hai usato il meccanismo giusto? hai ripetuto info che potevi mettere in memoria persistente? hai sopravalutato bisogno di RAG o lo hai sottovalutato? Quasi sempre c’è almeno un caso di mismatch. Quel mismatch è la lezione: scegli il livello giusto, niente di più, niente di meno.