Se hai letto perché Claude Code dimentica il contesto tra una sessione e l'altra, qui trovi il lato pratico: come collegare una memoria persistente al tuo progetto, passo per passo. Non è una guida concettuale su cos'è un knowledge graph (quella è qui): è la sequenza di azioni per averne uno funzionante oggi.
Uso come riferimento il VibeCoded Orchestrator (VCO), lo strumento che conosco meglio perché è quello che uso ogni giorno: è gratuito, open source (AGPL-3.0) e gira interamente sulla tua macchina, nessun dato del progetto lascia il tuo computer. I passaggi restano validi nel principio anche se usi un altro sistema di memoria persistente: cambia il tool, non la logica.
Il modo più diretto è tramite il VCT Launcher, l'hub desktop gratuito (Tauri 2) che gestisce l'installazione e il collegamento di agenti, skill, hook e server MCP. Il wizard di onboarding rileva il tuo sistema, scarica i modelli AI locali necessari per generare gli embedding, e avvia i servizi del knowledge graph.
git clone https://github.com/hotak92/vibecoded-orchestrator cd vibecoded-orchestrator
Se preferisci la via manuale senza launcher, il repository su GitHub contiene lo script di installazione da riga di comando. Il launcher resta comunque il percorso più veloce se non vuoi gestire a mano container e modelli locali.
Una volta installato l'orchestratore, registra la cartella del progetto su cui vuoi lavorare. Questo passaggio crea la struttura .claude/ dentro il progetto: qui vivono gli agenti, le skill, gli hook di automazione e la cartella knowledge/ dove il knowledge graph tiene i suoi nodi in formato Markdown, non in un database binario chiuso.
Il vantaggio pratico di file .md leggibili: puoi aprirli, modificarli a mano, versionarli con git come qualsiasi altro file del progetto. Non c'è uno storage proprietario da cui dipendere.
Con l'estensione Claude Code in VS Code (il target principale) o con il CLI standalone, apri la cartella del progetto appena registrato. Agenti, skill e hook sono già attivi. Da questo momento, ogni volta che l'AI scrive una decisione architetturale rilevante in un nodo del knowledge graph, un hook PostToolUse intercetta il salvataggio, genera l'embedding e lo indicizza automaticamente in pochi secondi. Non devi chiamare a mano nessuna funzione tipo "memory.add()": succede da solo quando scrivi o modifichi un file dentro knowledge/.
Qui sta la differenza pratica rispetto a lasciare tutto scritto sparso nei commit o nei commenti del codice. Quando prendi una decisione che vuoi che sopravviva alle sessioni future (perché hai scelto JWT invece delle sessioni, perché un endpoint è strutturato in un certo modo, quale libreria hai scartato e perché), scrivila come un nodo di conoscenza:
Strategia di autenticazione
Scelto JWT a vita breve con refresh token invece delle sessioni server-side.
Perché: il servizio deve scalare orizzontalmente senza stato condiviso tra istanze. Le sessioni richiederebbero uno store centralizzato (Redis), complessità che non serve per il volume attuale.
Collegato a: [[uses::FastAPI]], [[extends::Base Auth Middleware]]
I doppi parentesi quadre ([[uses::FastAPI]]) sono wikilink tipizzati: collegano questo nodo ad altri concetti nel grafo, così una futura ricerca può risalire non solo al testo ma alle relazioni tra le decisioni.
Da qui in avanti, in una sessione futura (anche a settimane di distanza, anche in un progetto diverso se usi la collection condivisa cross-project), invece di rispiegare il contesto puoi semplicemente chiedere. L'agente interroga il knowledge graph con una domanda mirata e riceve indietro solo i nodi rilevanti, non l'intera cronologia del progetto:
Cosa abbiamo deciso sulla strategia di autenticazione e perché?
La ricerca (hybrid_search nel caso di VCO) combina similarità semantica e attraversamento dei link tipizzati: non trova solo testo che somiglia alla domanda, ma può seguire il nodo trovato fino ai concetti collegati, per esempio arrivando anche al middleware che dipende da quella scelta.
Con l'uso quotidiano, il grafo cresce insieme al progetto. Un agente dedicato alla cura della conoscenza (nel caso di VCO si chiama knowledge-curator) rivede periodicamente i nuovi nodi, propone collegamenti mancanti tra concetti simili, e segnala contenuti diventati obsoleti. Non è un passaggio da eseguire manualmente ogni settimana: è pensato per girare in background, così il costo di manutenzione della memoria resta basso anche quando il numero di nodi cresce.
Cosa aspettarti nella pratica
Il cambiamento non è "l'AI ricorda tutto per magia": è che il lavoro di mantenere il contesto passa da "rispiegare tutto a voce ogni volta" a "scrivere una volta in un posto strutturato, interrogabile in un secondo momento". La prima settimana richiede la disciplina di scrivere i nodi quando prendi una decisione, invece di lasciarla solo nella tua testa o in un commento di commit. Dopo, il ritorno si vede soprattutto sui progetti che vivono per mesi, o su cui torni dopo una pausa: la differenza tra riaprire un progetto e capire subito perché è fatto in un certo modo, o dover ricostruire tutto da zero leggendo il codice.
L'orchestratore di base, incluso il knowledge graph completo, il code graph e gli hook di automazione, è gratuito sotto licenza AGPL-3.0: VibeCoded Orchestrator.