Second brain con Obsidian e LLM wiki: guida pratica

“Second brain”: di cosa stiamo parlando?

Se non sai di cosa stiamo parlando, ti rimando al mio articolo su cos’è un second brain, spiegato semplice. Se sei diventato allergico all’AI (capisco) il punto di partenza è Second-brain e LLM-wiki: cosa cambia. Quindi in questa guida do per scontato che tu sappia di cosa stiamo parlando.

La guida è scritta per macOS. Una versione per Windows arriverà: su quel sistema alcuni passaggi sono un po’ una rogna, soprattutto dove servono gli strumenti di sviluppo.

0. Setup: La base è fatta da un vault, agente e manifesto.

Prima ti aiuto a costruirlo, poi spiego tutti i passaggi. In meno di un’ora hai un vault che funziona e nella sezione 1 capisci cosa è successo.

0.1 Creiamo il contenitore del second brain: il vault, in iCloud.

Si parte dallo smartphone:

1. Installi Obsidian sul telefono dall’app store.
2. Crei un vault nuovo e scegli iCloud come posizione: così la stessa cartella è disponibile sul telefono e sul Mac, senza altro lavoro. Un vault è un bel nome, ma è solo una cartella. Puoi chiamarla con il tuo nome semplice “Marco”, “Gianni” o “Second brain”.
3. Sul Mac installi Obsidian e apri lo stesso vault, che trovi tra quelli in iCloud. A questo punto è completamente vuoto (se non per un file di benvenuto che puoi cancellare).

0.2 È tempo di metterci l’intelligenza: l’agente.

1. Potresti usare qualsiasi framework agentico. Io in questa guida la faccio semplice e ti suggerisco di scaricare Claude Desktop da claude.com/download.
2. Serve un piano a pagamento: Claude Code non è incluso nel piano gratuito, ma lo è in tutti quelli a pagamento. Il più economico è Pro (la pagina dei piani è claude.com/pricing). Prezzi e piani cambiano, quindi si controlla la pagina prima di abbonarsi.
3. Configuri la privacy subito, prima di aprire il vault. Nelle impostazioni di privacy dell’account decidi se chat e sessioni di codice possono essere usate per migliorare i modelli. I file restano sul disco, ma ogni volta che l’agente ne legge uno il contenuto parte verso i server del fornitore per ottenere la risposta. Sui piani consumer l’uso per addestrare i modelli dipende da un’impostazione che scegli tu (pagina privacy.claude.com del 16 marzo 2026). Farlo adesso conta: dopo, i dati veri sono già passati. La posizione esatta dell’impostazione cambia con le versioni dell’app.
4. Poi in Claude bisogna spostarsi nella scheda Code, è uno strumento ormai simile al classico ambiente di chat di Claude ma ha maggior libertà di usare gli strumenti che troverà nel tuo computer. Importante: scegli come cartella di lavoro quella del vault, altrimenti
5. Lasci il modello predefinito: Sonnet.

Altre tre abitudini sulla privacy, che costano poco:

• tenere separati i vault: uno di lavoro, pulito e senza dati dei clienti, più uno personale;
• non mettere nel vault password, chiavi e credenziali: il manifesto (che vedremo tra poco) raccomanda di filtrarle all’ingresso, prima che finiscano in una pagina;
• se il contenuto riguarda altre persone (clienti, famigliari, figli), decidere a monte cosa può entrarci.

0.3 Le regole del tuo second brain: il manifesto.

Il gist di Karpathy è un file di idee pensato per essere copiato e incollato al proprio agente. Descrive il pattern senza costruirlo: il compito di arrivare alla versione adatta a te passa all’agente, insieme a te. È quello che facciamo adesso, con un testo che riunisce in un solo documento il pattern di Karpathy e altre funzionalità aggiuntive come il strato sul ciclo di vita della conoscenza. Si chiama calibra-second-brain.

Il file si scarica qui: calibra-second-brain.md. Lo apri, copi il testo intero (non un riassunto) e lo incolli in Claude Code.

Mi raccomando: è davvero semplice. Lo copi e incolli dentro una finestra di claude code in una sessione impostata sulla cartella della tua vault.
Questo è quello che dovresti grossomodo vedere prima di premere invio.

Dentro ci sono i tre livelli (fonti, wiki, schema), le quattro operazioni (ingest, query, lint, crystallize), il ciclo di vita (confidence, decadimento, supersessione, tier di memoria), otto regole di comportamento per l’agente e la privacy. I livelli da 2 a 5 restano fuori di proposito. Nelle sezioni 1 e 2 spiego tutto, pezzo per pezzo.

Chi preferisce partire dagli originali trova i due gist pubblici:

• Karpathy
• il llm-wiki2

Claude Code chiede conferma prima di scrivere file. Conviene leggere cosa sta per creare prima di approvare. Da poco è stata inserita una modalità di lavoro “automatica” che impara a capire quali sono le decisioni critiche e quali invece si possono lasciar correre. Se lavoriamo solo nella vault che abbiamo creato non ci sono problemi, ma se inizi a dare accesso all’agente ad altre parti del tuo computer le cose possono andare male, molto male se non sai cosa stai facendo.

0.4 Arrediamo il tuo nuovo second brain: l’intervista.

Appena incolli, l’agente non parte a costruire: ti interroga. Senza sapere chi sei e a cosa serve l’archivio, qualsiasi struttura sarebbe generica.

Il manifesto gli chiede di farti le domande una alla volta e di non creare niente prima di aver finito. Le prime tre vengono dalla mia pratica, le altre due le ha aggiunte il manifesto:

• chi sei e cosa fai;
• che uso avrà l’archivio: lavoro, vita personale, studio, un progetto in particolare;
• su quali temi vuoi cominciare;
• come vuoi che ti parli;
• cosa non deve mai finire nell’archivio: dati di clienti, di famigliari, credenziali.

Si risponde come a un collega nuovo il primo giorno: più le risposte sono reali, più lo schema che esce somiglia a te. Le risposte finiscono nel file CLAUDE.md, che viene caricato a ogni sessione. È il motivo per cui in seguito non devi ripresentarti.

Se l’agente non le fa, basta scrivere: «Intervistami una domanda alla volta per costruire il mio profilo, poi scrivilo nello schema.»

Alla fine l’agente riassume quello che ha capito e chiede conferma. Solo dopo crea le cartelle, lo schema, l’index e il log e registra il manifesto stesso come prima fonte.

È come entrare in una casa appena acquistata. Vuota, piena di buoni propositi e con un sacco di roba tua da dover organizzare. Se lo facciamo passo passo e con un po’ di cognizione diventa un bel posto dove vivere, altrimenti può diventare officina, magazzino, cantina o soffitta.

0.5 La verifica

Chiedi all’agente:

Elenca le cartelle e i file che hai creato e dimmi a cosa serve ciascuno.

Poi apri Obsidian: devi vedere gli stessi file nella barra laterale e un CLAUDE.md che nomina confidence, supersessione e decadimento. Se la risposta coincide con quello che vedi, il setup è completo.

Alla fine della sezione hai un vault sincronizzato tra Mac e telefono, un agente che lo vede e uno schema scritto su misura dopo qualche domanda.

Nota, tutte le strutture io le tengo in inglese per diversi motivi (gli llm lavorano meglio con l’inglese e ancora meglio con ASD-STE100, una versione di inglese tecnica e semplificata).

1. Cosa hai appena costruito

Hai incollato un documento e risposto a poche domande ma ora ti spiego cosa è successo dietro le quinte.

Il modo più diffuso di usare un LLM con i propri documenti funziona così: carichi dei file, fai una domanda, il modello pesca dei frammenti e ne ricava una risposta. Domani rifà tutto da capo. Nessun frammento è diventato conoscenza e nessuna risposta ha lasciato una traccia.

Se non hai chiaro questo concetto, leggi questo articolo su https://calibra.co/stories/second-brain-llm-wiki-cosa-cambia/

Il pattern che hai appena installato, descritto da Andrej Karpathy in un gist pubblico, ribalta il meccanismo. L’LLM costruisce e aggiorna un wiki persistente: file markdown collegati fra loro, che stanno tra te e le fonti grezze. Quando aggiungi una fonte, non si limita a indicizzarla. La legge, ne estrae l’essenziale, la integra nelle pagine che esistono già e segnala dove contraddice quello che c’era scritto.

In altre parole: la conoscenza si compila una volta e resta aggiornata, invece di essere ricostruita a ogni domanda.

Tu scegli le fonti, fai le domande e decidi cosa significa quello che leggi. L’LLM riassume, incrocia, archivia e tiene i conti. La parte noiosa di una base di conoscenza non è leggere e nemmeno pensare: è la contabilità. È il motivo per cui la maggior parte degli archivi personali muore, perché la manutenzione cresce più in fretta del valore che restituisce. Con un wiki mantenuto così non succede: lo uso da aprile 2026 e dopo cinque mesi il rapporto tra valore e manutenzione è ancora positivo.

I livelli

Il pattern base è volutamente minimo. Chi l’ha usato a lungo ha aggiunto pezzi. Il gist LLM Wiki v2 li ordina in uno spettro di sei livelli, ognuno opzionale: userò quello come mappa.

Livello	Cosa aggiunge	Quando serve	In questa guida
0. Minimo	Fonti, wiki, schema, index, log	Sempre. Si parte da qui	Sezioni 0, 2 e 4
1. Ciclo di vita	Confidence, supersessione, decadimento nel tempo	Quando il wiki comincia a contenere cose non più vere	Sezione 5
2. Struttura	Entità e relazioni tipate	Quando le domande diventano «cosa dipende da cosa»	Cenno, qui sotto
3. Automazione	Hook e attività programmate	Quando la manutenzione a mano ti pesa	Sezione 7
4. Scala	Ricerca ibrida, tier di consolidamento	Oltre le 100-200 pagine	Cenno
5. Collaborazione	Più agenti o più persone sullo stesso wiki	Lavoro di squadra	Fuori perimetro

Il manifesto incollato al passo 0.3 ti porta già ai livelli 0 e 1. Gli altri li aggiungi uno alla volta, quando servono.

Il livello 2 merita un avvertimento: è il più seducente e il più facile da sbagliare. Aggiunge struttura, ma ogni struttura ha un costo di manutenzione che il wiki paga al posto tuo. E quella sbagliata si vede tardi, quando l’hai già riempita. Cerco di spiegarmi meglio con l’esempio della casa vuota: se inizi a portarci spazzatura dentro, quella che avresti dovuto buttare in questi anni, casa nuova pian piano diventa come la vecchia. Se ti dici “Massì, lo riorganizzo poi…” ogni giorno quell’ambiente disfunzionale o non ideale influisce sulle tue decisioni e le tue scelte nel presente. Le domande di onboarding servono per non andare troppo fuori strada, ma presto scriverò una guida per organizzare al meglio il tuo nuovo second brain.

Il livello 2 nel mio wiki

Ci sono passato. Il mio schema prevedeva una tassonomia di tipi di relazione: ogni collegamento fra pagine portava un’etichetta, related_to, depends_on e simili. A luglio ho fatto un audit del wiki: ho fatto rileggere a un modello esterno le 122 voci del registro delle operazioni, per capire dove il sistema accumulava senza servire a niente. Il 3 del mese ho tolto quella tassonomia, insieme ad altre cose, portando il file dello schema da 365 a 265 righe. Il motivo, per come lo ricostruisco, è che quelle etichette le scrivevo e nessuno le leggeva.

Otto giorni dopo ne ho riammessa una sola, contradicts, ispirata al gist v2. Stavolta aveva un consumatore: il controllo di salute del wiki la legge ogni volta che lo eseguo. La regola che ne ricavo è una: un tipo di relazione entra nel wiki solo se c’è qualcosa che lo legge.

Cosa serve per proseguire

• Un agente che legga e scriva file locali. Qui uso Claude Code, ma il pattern non dipende dall’agente: il gist dice esplicitamente di condividerlo con il proprio LLM e di costruire insieme la versione adatta. Può essere gemini in Antigravity o Codex in OpenAI o Hermes con un modello locale su ollama.
• Obsidian. Karpathy lo usa come finestra per guardare il risultato: «Obsidian is the IDE; the LLM is the programmer». Non è indispensabile al funzionamento, ma è il modo più comodo di navigare i collegamenti e vedere il grafo.
• Poche fonti su un solo tema. Meglio dieci che ti interessano davvero che mille alla rinfusa. Se non hai niente, il tuo curriculum è un buon punto di partenza.

Cosa non è

Non è un prodotto da comprare. Sono file di testo sul tuo disco: l’agente li legge e li scrive, Obsidian li mostra. Se domani cambi agente, i file restano dove sono.

Questo è anche il suo più grande punto di forza: rimarrà per sempre tuo. Non è soggetto ad abbonamenti o rincari. E per la privacy puoi configurarlo in modo che nessun byte esca dal tuo computer.

2. Architettura: come funziona il suo second brain

I tre livelli

Livello	Di chi è	Regola
Fonti grezze (raw)	Tue	Immutabili. L’LLM le legge e non le modifica mai. Per quanto strano qui tu metterai tutto quello che vuoi “portare dentro” al tuo second brain. Rimarrà come sorgente dell’informazione e nessuno ci metterà mano.
Wiki	Dell’LLM	Tu leggi, lui scrive. Pagine di riassunto, entità, concetti, confronti. Sono il frutto del tuo second brain: una sorta di wikipedia costruita con le tue informazioni.
Schema	Di tutti e due	Un documento (CLAUDE.md per Claude Code, AGENTS.md per Codex) che dice all’LLM come è fatto il wiki e quali procedure seguire

Lo schema è il pezzo che fa la differenza: trasforma un chatbot generico in un manutentore disciplinato del wiki. Lo costruisci insieme all’LLM man mano che capisci cosa funziona nel tuo dominio. Gli dedico la sezione 3.

Le fonti sono immutabili per un motivo semplice: sono la tua fonte di verità. Se potessero cambiare, non avresti più niente contro cui controllare cosa ha scritto il wiki.

I due file di servizio

Due file aiutano te e l’LLM a orientarvi quando il wiki cresce:

• index.md è il catalogo di contenuto: ogni pagina con un link, una riga di sintesi e, volendo, la data o il numero di fonti. L’LLM lo aggiorna a ogni ingest e lo legge per primo quando deve rispondere a una domanda.
• log.md è il registro cronologico: si scrive solo in aggiunta, mai a ritroso. Un trucco del gist: se ogni voce comincia con lo stesso prefisso, per esempio ## [2026-10-03] ingest | Titolo, il log si interroga da terminale. Con grep "^## \[" log.md | tail -5 ottieni le ultime cinque operazioni.

Come si presenta il vault

Il gist non prescrive nomi di cartelle. Questa è la convenzione che usiamo noi:

vault/
├── CLAUDE.md        ← lo schema
├── index.md         ← il catalogo
├── log.md           ← il registro
├── raw/             ← le fonti, mai modificate dall'LLM
│   └── assets/      ← immagini e allegati scaricati in locale
└── wiki/            ← le pagine che scrive l'LLM

Altre guide in circolazione propongono tre cartelle con una outputs/, sei cartelle piatte o strutture a nove cartelle ispirate a PARA. Sono scelte legittime, ma sono decisioni di chi le ha scritte e non parte del pattern. Se parti con un vault piccolo e lasci che la struttura emerga dall’uso, difficilmente sbagli. Progettarla prima di aver scritto la prima pagina è come arredare un appartamento vuoto senza sapere ancora come ci vivrai.

Le tre operazioni

Le vedremo una per una nelle sezioni 4 e 5. Per ora basta sapere che esistono:

• Ingest. Aggiungi una fonte e chiedi all’LLM di elaborarla: la legge, discute con te i punti chiave, scrive la pagina di riassunto e aggiorna le pagine collegate, l’index e il log. Una sola fonte può toccare dieci o quindici pagine. Karpathy preferisce procedere una fonte alla volta restando coinvolto: legge i riassunti, controlla gli aggiornamenti e guida l’LLM su cosa enfatizzare. Una modalità a lotto con meno supervisione è possibile, ma è una scelta e non il default.
• Query. Fai una domanda al wiki. L’LLM legge l’index, apre le pagine pertinenti e risponde con le citazioni. Le risposte che valgono tornano nel wiki come pagine nuove, invece di sparire nella cronologia della chat.
• Lint. Ogni tanto chiedi un controllo di salute: contraddizioni tra pagine, affermazioni superate da fonti più recenti, pagine orfane, concetti citati senza una pagina propria, riferimenti incrociati mancanti.

Quanto regge l’index

L’index sembra funzionare senza ricerca vera fino a circa cento fonti e qualche centinaio di pagine. Il v2 è più prudente: fino a 100-200 pagine, poi l’index diventa troppo lungo per essere letto in un colpo solo e serve una ricerca ibrida. Il gist suggerisce qmd, un motore di ricerca locale per markdown. È un livello 4: finché non ti serve, lo ignori.

Obsidian su iCloud è una soluzione con qualche compromesso.

Sul tuo Mac molto probabilmente la cartella sta qui:

~/Library/Mobile Documents/iCloud~md~obsidian/Documents/<nome del vault>

Nota che puoi saltare se non sei un tecnico. Con iCloud di mezzo possono andare storte due cose:

• File già esistenti che l’agente non riesce a scrivere. È un limite noto di Obsidian su iCloud e succede ancora. macOS blocca i file che Obsidian o iCloud hanno in gestione e l’agente riceve EPERM: operation not permitted anche se i permessi sembrano normali. Non è un problema dell’agente: è il sistema operativo che nega l’accesso. Le vie d’uscita sono tre: far scrivere il contenuto in un file nuovo (i file nuovi funzionano), chiudere Obsidian e riprovare, oppure dare al terminale l’Accesso completo al disco in Impostazioni, Privacy e sicurezza. Insistere con tentativi ripetuti non serve.
• File non scaricati sul Mac. Se il vault è in iCloud e il Mac è a corto di spazio, alcuni file possono esistere solo online. Conviene verificare che la cartella sia scaricata per intero prima di partire.