Ho già raccontato perché la memoria di un LLM non sta in un solo file, e perché il contesto è l'asset che il PM deve costruire. Erano articoli sul perché.

Questo parla del come. Apro il cofano del mio motore di contesto — il sistema che vive in una cartella 02-CONTEXT/ del mio vault — e seguo una missione reale dall'inizio alla fine. A ogni passaggio spiego il blocco che entra in gioco: la missione, il focus, le direttive, il file todo.md, la coda offline e i tre tipi di memoria.

L'obiettivo: che una persona che non ha mai visto questo sistema capisca come è organizzato e, soprattutto, perché è organizzato così. Perché ogni cartella, ogni file, risponde a un problema che ho incontrato lavorando con un'IA su temi che durano settimane.

Il principio di partenza: il disco è la memoria

Una cosa va messa in chiaro prima di tutto il resto. In questo sistema, il file system è la memoria principale dell'IA. Non la conversazione.

Una conversazione con un LLM è volatile. Chiudi la scheda e tutto è perso. La finestra di contesto è finita, e più la si riempie più l'attenzione si degrada — è il fenomeno del Lost in the Middle di cui ho parlato altrove. Quindi invece di tenere tutto nella conversazione, si scrive tutto su disco, in file suddivisi per natura dell'informazione. E a ogni sessione si ricarica solo lo stretto necessario.

Un contesto, dunque, è una cartella. Una cartella = una missione. Non esiste nessuna memoria trasversale implicita tra due contesti: ciò che l'IA sa del progetto A non filtra verso il progetto B. Ogni missione ha il suo cervello a sé.

Ecco, in forma semplificata, com'è fatto un contesto:

<contesto>/
├── 00_mission/     ← il quadro stabile: perché siamo qui, le regole
├── 01_active/      ← lo stato vivo: a che punto siamo, oggi
├── 02_checkpoints/ ← le fotografie di tappa
├── 03_sources/     ← la materia grezza
├── 04_notes/       ← le idee estratte, collegate tra loro
├── 05_memory/      ← la memoria consolidata
├── 06_index/       ← l'indice macchina, perché l'IA si orienti
└── 07_outputs/     ← i deliverable

La logica di archiviazione è semplice ma rigorosa: ciò che è stabile (la missione, le regole) è separato da ciò che cambia a ogni sessione (lo stato attuale), a sua volta separato dalla materia grezza (le fonti), da ciò che se ne estrae (le note) e da ciò che si produce (i deliverable). Niente è mescolato. Vedremo che questa separazione non è cosmetica: è lei a rendere il ragionamento tracciabile nel tempo.

Per rendere tutto questo concreto, seguo una missione che ho davvero portato avanti (un esempio semplice, per facilitare la lettura): PM016 — scrivere post LinkedIn a partire da tre articoli che ho pubblicato su una rivista di marketing. Una missione di produzione di contenuti, breve, ma che attiva la maggior parte dei blocchi.

Aprire un contesto: cosa l'IA carica e cosa lascia su disco

Avvio una sessione. La prima cosa che l'IA fa non è leggere tutto. È leggere un file di configurazione: il manifesto di caricamento (load_manifest.json). Questo file le dice cosa caricare e cosa invece lasciare su disco.

Contiene tre liste:

• always_load — il nucleo, caricato ogni volta. La missione, lo scope, le direttive, i rischi, lo stato attuale, il piano, il focus, la lista delle attività, le decisioni, le contraddizioni, la scheda di ripresa, la sintesi.
• load_on_demand — tutto ciò che resta su disco e viene caricato solo se il compito lo richiede: le decine di fonti, le note atomiche, i diari di sessione.
• Alcuni paletti di sicurezza: non più di 12 file attivi, circa 1200 righe al massimo nella finestra di contesto del LLM.

È un vassoio da chirurgo. Gli strumenti essenziali sono già pronti; gli altri sono a portata di mano, ma non ingombrano il vassoio. Un esperto umano non rilegge tutto il fascicolo prima di ogni riunione — ha interiorizzato l'essenziale e va a cercare un documento preciso quando gli serve. Un LLM non può interiorizzare: ha solo ciò che gli si dà. Da qui l'importanza di dargli il sottoinsieme giusto, non tutto.

In pratica, l'apertura di un contesto avviene con un comando — digito /context_use pm016 — e l'IA esegue il manifesto: legge il nucleo, legge l'ultimo checkpoint, ed è operativa. Sa a che punto siamo senza che io abbia dovuto rispiegarle nulla.

La missione e il focus: lo scopo non è la stessa cosa dell'attenzione

Zoom sulle due cartelle principali — quella stabile e quella viva:

00_mission/          ← il quadro stabile
├── mission.md       lo scopo (non cambia)
├── scope.md         il perimetro
├── directives.md    come l'IA deve lavorare
├── risks.md         le minacce da sorvegliare
└── glossary.md      il vocabolario della missione

01_active/           ← lo stato vivo (cambia a ogni sessione)
├── focus.md         l'attenzione del momento
├── current_state.md a che punto siamo
├── current_plan.md  dove andiamo
├── todo.md          le azioni future
├── decisions.md     ciò che abbiamo deciso
├── contradictions.md ciò che ancora non torna
├── resume_work.md   la scheda di ripresa
└── offline.md       la casella di posta

Ecco la prima sottigliezza, e probabilmente la più importante da capire.

Ci sono due file che assomigliano a «ciò su cui stiamo lavorando», ma che non hanno nulla a che vedere l'uno con l'altro.

Il primo è la missione (00_mission/mission.md). È lo scopo. È stabile. Per PM016 la missione sta in una frase: «scrivere post LinkedIn basati sui tre articoli che ho pubblicato sul numero 16 della rivista». Questa frase non cambia per tutta la vita del contesto. È la rotta. Il file vive in 00_mission/, la cartella delle cose stabili.

Il secondo è il focus (01_active/focus.md). È l'attenzione del momento. Cambia a ogni sessione, a volte più volte nella stessa sessione. Il focus è «oggi lavoriamo su come spezzare le idee dell'articolo 2 in post distinti». Non è lo scopo — è il sottoproblema su cui puntiamo il riflettore adesso. Il file vive in 01_active/, la cartella delle cose vive.

Perché separare i due? Perché confondere lo scopo e l'attenzione è il modo migliore per andare alla deriva. Se l'IA scambia il focus del giorno per lo scopo della missione, rischia di ridefinire l'intera missione attorno a un dettaglio. Al contrario, se ha davanti solo lo scopo, resta troppo vaga: «scrivi post LinkedIn» non dice su cosa ci si concentra in questo istante. La missione dà la direzione, il focus dà la profondità di campo. Si può rifare il focus dieci volte senza mai toccare la missione. È esattamente come per una persona: il tuo ruolo (la tua missione) non cambia perché passi il pomeriggio su un compito preciso (il tuo focus).

Attorno alla missione, in 00_mission/, ci sono altri tre file che fanno da cornice.

Lo scope delimita ciò che è nel perimetro e ciò che non lo è — la barriera contro la deriva del tema.

I rischi (risks.md) sono la griglia delle minacce che pesano sulla missione. Su PM016 è poca cosa; ma su una vera opportunità di prodotto questo file segue i quattro grandi rischi di Marty Cagan — valore, usabilità, fattibilità, sostenibilità di business. L'idea: tenere costantemente sotto gli occhi le domande che possono far fallire il progetto, e spuntare ogni rischio man mano che un elemento lo chiarisce o lo aggrava. Una sezione vuota = un rischio ancora non documentato, quindi un punto cieco assunto consapevolmente.

Il glossario (glossary.md) fissa il vocabolario della missione, perché le stesse parole mantengano lo stesso senso dall'inizio alla fine. È lo stesso riflesso che ho avuto nel mio contesto sul condominio, dove avevo finito per esternalizzare tutti i termini tecnici e gli acronimi in un file dedicato: senza quello, ciascuno — l'essere umano come l'IA — finisce per usare le stesse parole con sensi diversi.

Un punto importante su tutti questi file, ed è forse il più controintuitivo del sistema: non si riempiono tutti in una volta all'avvio. Si riempiono progressivamente, nel corso degli scambi. E «scambio» non vuol dire soltanto «offrire un documento». Il più delle volte vuol dire parlare. Discuto con l'IA, penso ad alta voce, le do un contesto che ho in testa — ed è lei a sistemare questo flusso al posto giusto: questo punto è un rischio di sostenibilità, questo termine merita una voce di glossario, questa frase delimita lo scope. Un rischio non scritto diventa una riga in risks.md perché l'ho menzionato parlando, non perché ho aperto il file per riempirlo. È lì che il contesto smette di essere una pratica da archiviare e diventa un segretario personale che annota ciò che penso ad alta voce.

Le direttive: codificare una conoscenza che l'IA non ha

Altro file del nucleo stabile: le direttive (00_mission/directives.md).

Una direttiva non parla del tema della missione. Parla del modo di lavorare. È la differenza tra gli ingredienti e la ricetta.

Un esempio tratto da un altro dei miei contesti, dove faccio trattare centinaia di email di condominio: «quando due persone hanno lo stesso cognome, usa il senso dell'email per indicare il loro nome e la loro azienda» (due fornitori avevano lo stesso cognome). Non è un'informazione sul condominio. È una regola di trattamento. Codifica una conoscenza che possiedo solo io, e che l'IA applica poi in modo sistematico — senza dimenticare, senza stancarsi.

Per PM016, una direttiva tipica sarebbe: «ogni post deve difendere una sola idea atomica, mai un riassunto dell'articolo intero». È un vincolo di produzione che pongo una volta e che vale per tutti e ventisette i post.

Le direttive stanno nel nucleo always_load: vengono quindi ricaricate a ogni sessione. Una regola stabilita nella settimana 1 vale ancora nella settimana 6, senza che io debba ripeterla. È cumulativo. Più una missione avanza, più le sue direttive si affinano, e più l'IA lavora come me.

Dettaglio d'uso: per aggiungere una direttiva durante la conversazione, mi basta far precedere il mio messaggio da alpha directive : ... e l'IA la consolida nel file. Esiste una manciata di parole chiave come questa (decision :, contradiction :, todo :, checkpoint, fine sessione) — scorciatoie per sistemare un'informazione nel file giusto senza doverlo dire esplicitamente. Sono solo comodità; il cuore del sistema sono i concetti, non le parole chiave.

Il file todo.md: le azioni future non inquinano il ragionamento presente

Il file todo.md (01_active/todo.md) è un file semplice, ma che risolve un problema vero.

Quando si lavora su un tema, le idee di azioni future emergono di continuo. «Bisognerà verificare questa cifra.» «Dovremmo declinare questo post in un carosello.» «Ricordarsi di rileggere la versione inglese.» Se si lasciano fluttuare queste azioni nella conversazione, succedono due cose: o le si dimentica, o inquinano il ragionamento in corso tirando l'attenzione in tutte le direzioni.

La lista delle attività è il posto in cui si depositano queste azioni per non doverle più tenere a mente. È un backlog. Ogni attività ha un identificativo (T-NNN) e uno stato. La si alimenta scrivendo todo : .... E poiché fa parte del nucleo caricato a ogni sessione, nessuna azione si perde tra una sessione e l'altra.

È la stessa logica di tutto il resto: togliere un'informazione dalla memoria volatile della conversazione per depositarla in un posto stabile e con un nome.

La coda offline: parlare al contesto mentre dorme

Ecco un blocco a cui all'inizio non si pensa, e che diventa presto indispensabile: il file offline (01_active/offline.md).

Il problema: le idee non arrivano solo quando si è seduti davanti all'IA, con il contesto aperto. Un'idea su PM016 mi attraversa la mente una domenica sera, quando non ho nessuna voglia di aprire una sessione completa. Dove metterla?

Nel file offline. È una casella di posta. Ci deposito un messaggio — un'idea, una correzione, un promemoria — senza aprire una sessione. Il file dorme insieme al contesto.

Poi, all'avvio della sessione successiva, il workflow prevede un passaggio preciso: se offline.md non è vuoto, trattare il suo contenuto come un messaggio in arrivo, poi svuotare il file. L'IA legge il mio messaggio della domenica sera come se l'avessi appena digitato, ne tiene conto, agisce di conseguenza e azzera la casella. Niente va perso, e non ho dovuto aprire una sessione solo per annotare un'idea.

È un modo asincrono di parlare a un contesto. Il contesto diventa qualcosa a cui posso lasciare un biglietto, anche quando non è «acceso».

Le fonti e le note: dalla materia grezza alla conoscenza riutilizzabile

Finora abbiamo parlato di pilotaggio. Ora, il contenuto.

Zoom sulla catena che va dal grezzo alla conoscenza:

03_sources/          ← la materia grezza
├── SRC-001.md       la scheda (trascrizione utilizzabile)
└── raw/             l'originale così com'è (il PDF, illeggibile per l'IA)

04_notes/            ← la conoscenza estratta
├── atomic/          un'idea = una nota (NOTE-0001, 0002…)
└── thematic/        le sintesi che collegano più note

Quando porto della materia — per PM016, il PDF dei tre articoli — questa non si riversa nella conversazione. Va in 03_sources/, la materia grezza. Ogni fonte riceve una scheda e un identificativo (SRC-001, SRC-002…). Il PDF originale, non leggibile direttamente dall'IA, viene conservato così com'è in una sottocartella raw/, e una scheda .md ne offre una trascrizione utilizzabile. Si sa sempre da dove viene ogni informazione.

Poi arriva il lavoro di estrazione. A partire dalle fonti, l'IA produce note atomiche in 04_notes/atomic/. Una nota atomica cattura una sola unità di pensiero: un fatto, una definizione, un'ipotesi, un pattern, una contraddizione. Per PM016, l'analisi dei tre articoli ha prodotto ventidue note. Eccone una, reale:

NOTE-0022 — Decidere tra opzioni senza diventare ciechi: il cursore tra quadro e autonomia Pattern: dare a una responsabilità abbastanza autorità per decidere tra opzioni crea un rischio nuovo — la centralizzazione cieca. […] La coerenza non è l'omogeneità. Esempio Nike: universi molto diversi (running, calcio, basket…) coesistono senza uniformare tutto.

Questa nota è autonoma: la si capisce senza riaprire l'articolo. Ne è indicata la fonte (punta a SRC-001, pagina 67). Ed è collegata: in fondo, una sezione ## Backlinks la connette alla nota tematica the-brand-man. È Zettelkasten — unità di pensiero collegate tra loro, dove l'intelligenza emerge dai legami, non dall'accumulo.

C'è una regola che mi impongo qui, ed è più sottile di quanto sembri: una nota atomica non è mai materia pre-formattata per il deliverable. Anche se lo scopo della missione è produrre post LinkedIn, una nota non deve essere un «gancio» o una «battuta a effetto». La nota cattura una conoscenza neutra e vera. La messa in forma al servizio dell'obiettivo avviene soltanto nei deliverable. La catena è rigorosa: fonti (grezzo) → note (conoscenza neutra) → output (deliverable orientato). Finché siamo nelle note, lo scopo della missione non ha ancora voce in capitolo. Altrimenti si avvelena la propria materia prima.

Questa regola sembra rigida. In realtà è lei a rendere le note potenti — perché una conoscenza neutra è agnostica rispetto al deliverable, quindi riutilizzabile per qualunque di essi.

Prendiamo una missione di prodotto invece di PM016. A partire da uno stesso insieme di note atomiche — una posta in gioco per il cliente, un vincolo di adozione, un pattern di mercato — posso generare materiali molto diversi: un pitch per un comitato direttivo, una documentazione di supporto, un articolo di blog, una sales narrative, un onboarding. Ogni deliverable pesca e combina i blocchi di cui ha bisogno in questo corpus comune. Se avessi formattato quelle note per il pitch, servirebbero solo al pitch. Tenendole neutre, servono per tutti e cinque. La messa in forma, l'angolo, il tono: tutto questo arriva all'ultimo momento, in 07_outputs/, una volta che si sa quale deliverable si sta producendo.

E la riutilizzabilità non si ferma alla missione. I contesti non sono silos a tenuta stagna. Una nota prodotta per un contesto può illuminarne un altro — perché si possono collegare tra loro contesti affini. Posso persino aprire un contesto per andare a fare l'audit di un altro: scorrere le sue note e individuare le buone idee da riprendere. Un blocco di conoscenza scritto una volta può così alimentare un deliverable oggi, un altro deliverable domani, e una decisione in un terzo contesto tra sei mesi. È esattamente la promessa di partenza: il deliverable è usa e getta, la nota è un asset.

Quando più note convergono, si scrive una nota tematica in 04_notes/thematic/ — una sintesi di un angolo o di una tensione. Per PM016, una per articolo.

Le tre memorie: episodica, semantica e le fotografie di tappa

Zoom sui tre luoghi della memoria — tre scale temporali:

05_memory/
├── journal/         ciò che è successo, giorno per giorno (la storia)
└── synthesis.md     ciò che se ne trattiene (la lezione)

02_checkpoints/      lo stato completo a un istante T (la fotografia per riprendere)

È qui che si gioca la seconda grande sottigliezza del sistema. Un cervello umano non ha una memoria, ne ha diverse, che funzionano su scale temporali differenti: quella che trattiene ciò che sta succedendo adesso, quella che immagazzina gli eventi vissuti e quella che consolida i saperi duraturi. Il sistema riproduce questa architettura con tre oggetti distinti, che non vanno assolutamente confusi.

Il diario (memoria episodica). In 05_memory/journal/, un file per ogni giorno di lavoro. Racconta ciò che è successo: cosa si è fatto quel giorno, in quale ordine, quali decisioni sono state prese, cosa si è inceppato. È il racconto cronologico. Ci si va quando ci si chiede «ma cosa avevamo deciso martedì, e perché?». È datato, sequenziale, mai riscritto.

La sintesi (memoria semantica). In 05_memory/synthesis.md, un unico file. Non racconta ciò che è successo — condensa ciò che se ne trattiene. Le conclusioni stabili, le convinzioni validate, i pattern estratti da decine di sessioni. È la memoria a lungo termine, liberata dalla cronologia. Un product manager senior non riscopre a ogni progetto che gli utenti mentono in intervista: è diventato un sapere semantico. La sintesi è questo. Fa parte del nucleo caricato a ogni sessione, perché è il condensato più utile per riprendere il filo.

I checkpoint (le fotografie di tappa). In 02_checkpoints/, al massimo un file al giorno. Un checkpoint è un'istantanea completa dello stato del contesto in un dato momento. L'angolo di scrittura è molto preciso, ed è ciò che ne fa il valore: «se un LLM arrivasse adesso senza aver letto nulla, cosa deve sapere per riprendere senza errori e senza ricominciare da capo?» Il checkpoint è la rete di sicurezza della ripresa.

La distinzione diario / sintesi è quella che sfugge più spesso. Il diario è la storia; la sintesi è la lezione. Servono entrambi, esattamente per la ragione che mi aveva spinto, nei miei primissimi tentativi, a separare l'aggregazione da un log cronologico: volevo al tempo stesso sapere a che punto siamo (la sintesi) e poter risalire il filo (il diario). Schiacciare l'uno sull'altro significa perdere o la memoria o la tracciabilità.

Ed è precisamente questo che rende il sistema verificabile. Un cervello dimentica — è la sua forza. Un file system, invece, non dimentica nulla. Dalla sintesi si risale al checkpoint. Dal checkpoint ai diari. Dai diari alle note. Dalle note alle fonti grezze. Quando qualcuno chiede «perché questa decisione?», la risposta non è mai «perché l'ha detto l'IA». È una catena di prove: fonte → nota → decisione.

Il ciclo di una sessione, dall'inizio alla fine

Ora che abbiamo i blocchi, ecco il film completo di una sessione su PM016.

All'avvio. L'IA legge il manifesto, carica il nucleo, legge l'ultimo checkpoint. Verifica il file offline: se contiene un biglietto che ho lasciato tra due sessioni, lo tratta e poi lo svuota. In pochi secondi sa a che punto siamo. La scheda di ripresa (resume_work.md) le indica perfino la prima azione da fare.

Durante la sessione. Si discute — spesso ad alta voce, davanti allo schermo. E nel corso della conversazione l'IA sistema di continuo. Arriva una nuova fonte → 03_sources/. Emerge un'idea duratura → una nota atomica in 04_notes/. Viene presa una decisione → decisions.md. Compare una contraddizione → contradictions.md (non la si appiana artificialmente, la si tiene visibile). Un'azione futura → la lista delle attività. Ogni volta che viene creato un file, il README.md della sua cartella e l'indice macchina vengono aggiornati. Il contesto resta costantemente aggiornato, senza alcuno sforzo da parte mia.

A fine sessione. Digito /context_close. L'IA avvia il rituale di chiusura: scrive il diario del giorno, aggiorna lo stato attuale e la scheda di ripresa, promuove verso la sintesi ciò che merita di diventare duraturo e crea un checkpoint se viene raggiunta una soglia. Poi fa il commit di tutto. La sessione successiva potrà riprendere esattamente dove questa si è fermata.

Esiste anche una compattazione in corso d'opera (/context_push): quando lo stato attuale si gonfia, quando la lista delle attività diventa illeggibile, o quando si gira a vuoto, si condensa, si deduplica, si stabiliscono le priorità, si archivia ciò che non serve più — senza mai perdere la tracciabilità.

Ma il /context_push ha un ruolo ancora più vitale, ed è una trappola in cui si finisce inevitabilmente quando si scopre il sistema. Quando una sessione dura a lungo, la conversazione finisce per superare la finestra del LLM. A quel punto il LLM fa la propria compattazione: riassume silenziosamente gli scambi più vecchi per fare spazio. E tutto ciò che in quell'istante non era ancora stato scritto su disco — una decisione accennata a voce, un'idea lanciata di sfuggita, una sfumatura importante — viene limato, deformato o semplicemente perso. Il LLM non ti avvisa; crede di aver conservato l'essenziale, ma è lui ad aver scelto cosa fosse essenziale.

Il /context_push è la contromisura: forza la persistenza su disco prima che il LLM compatti la propria memoria di lavoro. Spingendo regolarmente, si garantisce che tutto ciò che conta sia già scritto nei file — al posto giusto, con la fonte indicata — e quindi che la compattazione del LLM non faccia più perdere nulla di importante. È il principio fondativo dell'articolo, applicato nel corso della sessione: ciò che vive soltanto nella conversazione ha i giorni contati; solo ciò che è su disco è davvero memorizzato.

L'oblio senza la perdita

Un ultimo punto, perché dice molto della filosofia del sistema. Non esiste nessuna cancellazione brutale.

Quando un'informazione non è più utile, non la si cancella. La si toglie dal caricamento di default, la si compatta, oppure la si archivia. Quando un'idea ne sostituisce un'altra, non la si schiaccia: la si marca come superseded, si tiene il vecchio identificativo e si fa puntare il vecchio verso il nuovo. Si cancella davvero solo in caso di errore evidente o di duplicato non ambiguo.

Perché tante precauzioni? Perché la verificabilità è tutto il valore del sistema. Il giorno in cui una convinzione di prodotto va difesa, devo poter risalire fino alla sua fonte, anche se risale a due mesi fa e nel frattempo è stata «superseded». Un ragionamento di cui si è cancellata la storia non è più un ragionamento — è un'opinione senza prove.

Cos'è davvero il contesto

In fondo, questo motore di contesto non è un sistema di archiviazione. È un'architettura di memoria per un'intelligenza che nativamente non ne ha.

Ogni blocco risponde a un limite del LLM: il manifesto risponde alla finestra finita; le tre memorie rispondono all'oblio tra una sessione e l'altra; le note atomiche rispondono al Lost in the Middle; la separazione fonti/note/deliverable risponde al bisogno di tracciabilità; il file offline risponde al fatto che il pensiero non si ferma quando la sessione si chiude.

E il risultato è ciò che descrivevo nei miei articoli precedenti: il deliverable non è più il punto di partenza del lavoro, è un sottoprodotto. Ciò che ha valore è il contesto stesso — questa memoria strutturata, tracciabile, riutilizzabile, che si arricchisce sessione dopo sessione e che finisce per produrre molto più di quanto le si chieda.

Per PM016 lo scopo erano ventisette post LinkedIn. Ma ciò che resta, una volta pubblicati i post, è un contesto: ventidue idee atomiche collegate, tre sintesi tematiche, fonti tracciate. Una materia che potrò riaprire tra sei mesi per un deliverable completamente diverso. Il post era l'obiettivo. Il contesto è l'asset.