Come costruire una wiki personale con Obsidian e le istruzioni di Karpathy

Ho costruito la mia prima wiki personale con Obsidian tanti anni fa. Andò bene per qualche settimana: prendevo appunti, linkavo i documenti tra loro, la base di conoscenza cresceva. Poi, come succede quasi sempre, smisi di aggiornarla. Aggiornare i link, mantenere la coerenza tra file, eliminare informazioni obsolete: è un lavoro che richiede disciplina, e la disciplina finisce.

Il metodo di Karpathy risolve esattamente questo problema. L'idea è semplice: la parte noiosa della gestione di una wiki non è leggere o pensare, è la contabilità. Mantenere i riferimenti incrociati, verificare la coerenza, aggiornare 20 file quando cambia un concetto. Gli umani si stancano. Un LLM, no. Se vuoi capire perché questo approccio è diverso da RAG e Agentic File Search, ho scritto un post sull'evoluzione dei sistemi di memoria per l'AI che parte dall'inizio.

L'architettura in tre livelli

Prima di passare ai passi pratici, vale la pena capire la struttura concettuale. La LLM Wiki si organizza su tre livelli distinti.

Il primo è quello dei dati grezzi: la tua cartella raw/ dove vai a depositare tutto quello che vuoi ingerire nella wiki. Articoli, PDF, paper scientifici, pagine web salvate in markdown, dataset CSV, immagini. Questo livello non viene mai toccato dall'agente: è la fonte di verità.

Il secondo è la wiki vera e propria: una cartella wiki/ popolata di file markdown strutturati che l'LLM crea e mantiene. Dentro ci sono sottocartelle come concepts/, entities/, sources/, synthesis/, più due file di servizio: index.md (l'indice generale di tutto quello che contiene la wiki) e log.md (il diario di tutte le operazioni fatte nel tempo).

Il terzo livello è lo schema: le istruzioni date all'agente su come comportarsi, quali convenzioni seguire, come strutturare i documenti. Di solito vive in un file CLAUDE.md nella root del progetto.

La separazione tra questi tre livelli è importante. I dati grezzi restano sporchi. La wiki è pulita, strutturata, linkabile. Lo schema è il cervello che governa il processo.

Step 1: installa Obsidian

Obsidian è un'applicazione gratuita per macOS, Windows e Linux che permette di leggere e navigare file markdown locali. Non è un database, non è un servizio cloud: legge i file dal tuo computer e li visualizza in modo navigabile, con una vista grafo che mostra le connessioni tra documenti.

Vai sul sito ufficiale di Obsidian, scarica la versione per il tuo sistema operativo e installala.

Una volta aperto, clicca su "Crea nuovo vault", dai un nome al progetto (per esempio wiki-nutrizione o wiki-AI o qualsiasi topic vuoi esplorare), e scegli dove salvarlo sul tuo disco. Obsidian crea la cartella e apre un file di benvenuto.

Puoi visualizzare il grafo dei documenti usando la voce "Apri vista grafo" nella barra laterale. All'inizio sarà quasi vuoto: crescerà mano a mano che aggiungi contenuti.

Step 2: installa l'estensione Obsidian Web Clipper

Karpathy consiglia di installare l'estensione Obsidian Web Clipper per Chrome (o per il browser che usi). Questa estensione permette di convertire qualsiasi pagina web in un file markdown e salvarlo direttamente nella cartella del vault Obsidian.

Una volta installata, vai nelle impostazioni dell'estensione e imposta la cartella di destinazione predefinita come raw. In questo modo, ogni volta che clippi una pagina, finisce direttamente nella cartella dei dati grezzi senza dover specificare il percorso ogni volta.

Questo step rende il workflow molto più fluido: invece di scaricare PDF, copiare testi o prendere appunti manuali, clicchi sull'estensione e il documento è già nel posto giusto.

Step 3: apri il vault nel tuo coding agent

Questo è il passaggio che rende tutto possibile. Apri il terminale, spostati nella cartella dove hai creato il vault Obsidian, e avvia il tuo coding agent (Claude Code, OpenCode, o equivalente) da quella posizione.

Il coding agent ha accesso completo al file system di quella cartella: può leggere, creare e modificare file, creare sottocartelle, seguire link tra documenti. È lui che farà il lavoro pesante.

Step 4: usa le istruzioni di Karpathy

Karpathy ha pubblicato un gist su GitHub con le istruzioni complete per costruire e gestire una LLM Wiki. Si tratta di un documento markdown che descrive l'architettura, le convenzioni, e le tre operazioni fondamentali: ingest, query e linting.

Copia il contenuto di quel file nel tuo vault. Poi dai al tuo coding agent questo prompt di avvio:

"Implementa questo file di istruzioni come il mio secondo cervello. Guidami passo passo: crea il file CLAUDE.md con le regole complete, imposta index.md e log.md, definisci le convenzioni per le cartelle, e mostrami il primo esempio di acquisizione (ingest). Da ora in poi ogni interazione seguirà questo schema."

L'agente risponderà creando la struttura di cartelle completa, il file di schema con le regole operative, e i due file di servizio. A quel punto sei pronto per iniziare.

Le tre operazioni quotidiane

Una volta impostato tutto, il flusso di lavoro si riduce a tre operazioni.

Ingest. Hai trovato un articolo interessante? Lo clippa nella cartella raw/ con l'estensione, poi dici all'agente "ingesta i nuovi documenti in raw/". L'agente legge i file grezzi, estrae concetti e entità, crea o aggiorna i file markdown nella wiki, aggiunge i backlink tra i documenti correlati, e aggiorna l'indice. Il file grezzo rimane intatto; la wiki si arricchisce.

Query. Vuoi esplorare un tema o trovare connessioni tra concetti? Fai la domanda all'agente. Lui consulta prima index.md per capire quali documenti sono rilevanti, li legge, segue i backlink verso altri documenti correlati, e ti risponde in modo sintetico. Non fa una ricerca vettoriale: naviga la wiki come farebbe un ricercatore umano, ma senza dimenticare nulla.

Linting. Periodicamente, puoi chiedere all'agente di fare un controllo di salute della wiki: trovare documenti orfani senza link di entrata, identificare concetti menzionati in più posti ma non ancora collegati, segnalare informazioni che potrebbero essere obsolete rispetto a fonti più recenti. È la manutenzione che gli umani abbandonano e che un LLM fa senza lamentarsi.

Dove ha senso applicarlo

Il metodo funziona bene per quasi qualsiasi tipo di ricerca o approfondimento personale. Karpathy lo usa principalmente per paper scientifici: li accumula, li ingesta, e interroga la wiki per trovare connessioni tra ricerche diverse.

Io lo trovo utile per costruire una base di conoscenza sui temi che seguo: agenti AI, strumenti di produttività, framework di marketing. Ogni settimana aggiungo qualcosa di nuovo e la wiki si aggiorna da sola.

Funziona benissimo anche per la ricerca accademica (tesi, paper con molti rimandi incrociati), per la documentazione tecnica con molte interdipendenze, per l'analisi competitiva su mercati complessi, e per qualsiasi topic dove si accumula materiale nel tempo e si vuole poterlo interrogare in modo intelligente.

Una nota pratica sulla scala

Karpathy ha costruito wiki da 100 articoli e 400.000 parole prima di considerarle "abbastanza grandi" per fare query complesse. Non è necessario arrivare a quei numeri per iniziare a vedere i vantaggi, ma è utile sapere che il metodo scala bene: più materiale aggiungi, più connessioni emergono, più la wiki diventa utile.

Obsidian mostra visivamente questa evoluzione nella graph view: all'inizio hai pochi nodi isolati, dopo qualche settimana di uso regolare vedi emergere cluster di documenti interconnessi intorno ai concetti centrali del tuo dominio. È una delle cose visivamente più soddisfacenti che ho visto in ambito knowledge management.

Il file di istruzioni di Karpathy è volutamente lasciato un po' astratto in alcune parti, proprio per permettere a ciascuno di personalizzarlo. Prendi le convenzioni che propone come punto di partenza, non come regole rigide: dopo qualche settimana di uso capirai cosa cambiare in base al tuo flusso di lavoro specifico.