Struttura e debug del vault
Organizza un vault markdown come seconda memoria ricercabile. Triage le quattro modalità di fallimento quando Claude fa qualcosa di inaspettato.
STATE.md e MEMORY.md contengono ciò di cui ogni sessione ha bisogno. Un vault markdown (Obsidian o qualsiasi cartella) contiene tutto il resto: note di strategia, trascrizioni di riunioni, diari di progetto, ricerca, analisi della concorrenza.
Il vault si trasforma in memoria istituzionale: decisioni prese sei mesi fa e perché, materiali di riferimento che informano il lavoro attuale, schemi che attraversano i progetti. Collegalo tramite un MCP di Obsidian o del filesystem e Claude può cercare l'intero contenuto su richiesta. Senza il vault, questa conoscenza esiste solo nella tua testa o sepolta in vecchi documenti.
Perché markdown batte un database: i file semplici sono ricercabili, versionabili con git, apribili in qualsiasi editor e sopravvivono a ogni cambio di strumento. Una struttura funzionante:
~/notes/
├── STATE.md # Sempre caricato
├── MEMORY.md # Indice, sempre caricato
├── STRATEGY-DIGEST.md # Riepiloghi di documenti di strategia
├── strategy/ # Documenti completi, letti su richiesta
├── projects/ # Note di progetto datate
├── resources/
└── reference/La chiave di scalabilità è il modello digest: quando scrivi un documento di strategia di 1.000 parole, scrivi un digest di 3 frasi accanto ad esso e indicizza il digest in MEMORY.md. Claude legge circa 50 token all'inizio della sessione invece delle circa 1.500 del documento completo. Con 25 documenti di strategia, si tratta di 1.250 token contro 37.500, e le sessioni rimangono veloci.
Quando Claude fa qualcosa di inaspettato, controlla quattro modalità di fallimento in ordine, dalla più alla meno comune:
Memoria obsoleta: STATE.md dice una cosa, la realtà ne dice un'altra. Claude ha seguito perfettamente le tue istruzioni; le istruzioni erano sbagliate. Chiedi "Mostrami il tuo STATE.md" per primo, ogni volta.
Contesto mancante: il file rilevante non è mai stato caricato, quindi Claude ha fatto una supposizione ragionevole. Carica il file esplicitamente e ri-chiedi.
Strumento non disponibile: un MCP è inattivo o un hook ha bloccato un comando, e Claude ha aggirato il problema male. Controlla la disponibilità dello strumento prima di incolpare il ragionamento.
Allucinazione: la causa più rara. Verifica prima: cerca la funzione, controlla che l'endpoint esista. La maggior parte delle "allucinazioni" si rivelano essere una delle prime tre.
Una domanda diagnostica per ogni modalità di fallimento:
Memoria obsoleta: "Cosa dice il tuo STATE.md su [argomento]?" Contenuti di tre sessioni fa significano stato obsoleto.
Contesto mancante: "Quali file hai caricato su [argomento]?" Nessun file rilevante significa caricare quello giusto.
Strumento non disponibile: "Quali strumenti hai a disposizione in questo momento?"
Allucinazione: "Cerca [funzione/endpoint] e mostrami cosa trovi."
La sequenza richiede due minuti e trova la causa quasi ogni volta. Saltare direttamente a "Claude ha allucinato" di solito ritarda la vera soluzione riscrivendo codice che non aveva bisogno di essere riscritto.
La prevenzione batte il debugging. Le abitudini:
Aggiornamento di STATE.md a fine sessione. Elimina l'80% dei problemi di memoria obsoleta.
Archivia i progetti spediti in file project_* datati.
Audit mensile di MEMORY.md: conferma che ogni puntatore punti ancora a un file esistente.
Digest di ogni documento di oltre 500 parole.
Scrivi le decisioni al momento della decisione, non alla fine della settimana. La cattura retroattiva perde il ragionamento.
Prima di archiviare le note di progetto, estrai le lezioni durature in voci feedback_*. Il progetto diventa storia; le lezioni rimangono attive.
Un vault con 10 documenti ben mantenuti batte uno con 200 obsoleti. Qualità e attualità battono il volume.
Con un MCP di Obsidian o del filesystem, il vault diventa una base di conoscenza viva:
Archeologia delle decisioni: "Cerca nel vault il motivo per cui abbiamo scelto Postgres invece di MySQL." Una ricerca manuale di 10 minuti diventa 15 secondi.
Rilevamento di schemi: "Trova tutte le menzioni di problemi di limitazione della velocità o errori 429 tra i progetti." Claude individua una causa radice comune diffusa in cinque file di progetto.
Ricerca di riferimento: "Trova le informazioni di contatto nelle note del fornitore." Recupero istantaneo da file non indicizzati.
La qualità della ricerca dipende dalla coerenza dei nomi: project_[nome]_[data].md e feedback_[regola].md battono qualsiasi cosa sembrasse naturale al momento. Le convenzioni di denominazione sono l'indice che costruisci prima di averne bisogno.
Tutte e quattro le modalità risultano pulite e l'output è ancora sbagliato? Due cause sembrano allucinazioni ma non lo sono.
Ordinamento del contesto: quando i file caricati sono in conflitto, il contenuto caricato successivamente tende a prevalere. Se le vecchie note di progetto contraddicono STATE.md, assegna esplicitamente l'autorità: "STATE.md è la verità fondamentale attuale. Sostituisce qualsiasi cosa nelle note di progetto."
Collisioni di vincoli: CLAUDE.md dice "parametrizza tutto il SQL", quindi Claude riscrive il SQL durante quello che intendevi come un refactoring solo di stile. Non è un bug; specificalo esplicitamente: "Solo stile, non modificare i pattern SQL."
La diagnostica per entrambi: "Quali istruzioni stai seguendo che governano [questa decisione]? Elenca le regole in ordine di priorità." Troverai una fonte obsoleta, una regola in conflitto o una lacuna in CLAUDE.md. Tutto risolvibile.
Un vault markdown con file digest scala la tua seconda memoria; i digest mantengono le sessioni veloci, i documenti completi si caricano su richiesta. Quando Claude si comporta male, fai il triage in ordine: memoria obsoleta, contesto mancante, strumento non disponibile, allucinazione, e inizia sempre con "mostrami il tuo STATE.md". Alimenta il vault al momento della decisione e il suo valore si moltiplica ogni settimana.