Il secondo cervello che legge anche il codice: come abbiamo costruito Synapse, 100% locale

Il problema

Nove progetti attivi. Circa 470 appunti tecnici in un vault Obsidian — decisioni architetturali, postmortem, pattern riusabili, accumulati progetto dopo progetto. E il codice, che cambia ogni giorno su otto repository.

La domanda che ci facevamo più spesso non era “come si fa X”. Era: “questo l’ho già risolto da qualche parte — dove?”

Un adapter multi-provider scritto per il gestionale ISP. Un rate limiter per-tenant costruito per la piattaforma marketing. Una regola sulla gestione dei calendari imparata a caro prezzo su un progetto medicale. La conoscenza c’era, scritta e versionata. Ma viveva in due mondi separati: gli appunti da una parte, il codice dall’altra. E il ponte tra i due era la memoria di chi aveva scritto entrambi.

A 470 appunti il ponte regge. A 600, su nove progetti, no.

La scorciatoia che non abbiamo preso

La risposta ovvia esisteva già: i tool di knowledge graph estraggono entità e relazioni dai tuoi documenti e dal tuo codice. Il più popolare della categoria ha quasi 50.000 stelle su GitHub.

C’era un problema: l’estrazione la fa un LLM in cloud. I tuoi appunti — con dentro nomi di clienti, pricing, decisioni di business — partono verso un’API esterna.

Per come lavoriamo noi, questo è un no per architettura, non per policy. Il vault contiene la storia operativa dello studio. Non esce dalla macchina, punto.

Quindi abbiamo fatto il contrario di quello che si fa di solito: invece di adattare il nostro vincolo al tool famoso, abbiamo misurato quanto tool serviva davvero.

Il grafo già annotato a mano batte l’estrazione automatica. E un estrattore leggero — 250 righe di libreria standard — basta per il valore core, se il vincolo è la privacy.

Gli appunti avevano già i collegamenti: li scriviamo noi, con i wikilink, da sempre. Serviva solo qualcuno che leggesse il significato — embedding multilingue calcolati in locale, modello da 470MB che gira su un portatile — e facesse emergere i collegamenti che NON avevamo scritto.

Per il codice, stessa logica: niente analisi semantica profonda in cloud. Un parser di libreria standard che decostruisce ogni repository in una nota per modulo — classi, funzioni esportate, dipendenze interne — e la scrive nel vault, accanto agli appunti. Una nota markdown come le altre, interrogabile come le altre.

Il risultato si chiama Synapse: il bibliotecario (ricerca semantica, collegamenti mancanti) e il cartografo (la mappa del codice). La biblioteca resta una: il vault.

La lezione che ha trasformato uno script in un sistema

La prima versione del cartografo funzionava a comando. La lanciavi, mappava il repository, scriveva le note. Perfetta in demo.

E sapevamo già come sarebbe finita, perché c’eravamo già passati: una mappa che va rigenerata a mano è stale entro una settimana. Nessuna disciplina personale regge il “ricordati di rilanciare lo script”. L’avevamo scritto in un appunto, mesi fa, su un altro progetto:

Architettura senza workflow è architettura morta.

Così la rigenerazione è diventata un hook post-commit: ogni commit, su ognuno degli otto repository, rigenera la mappa di quel repo in ~3 secondi. Non blocca mai il commit, non sovrascrive hook esistenti, si disinstalla con un comando. E un monitor giornaliero controlla che gli hook abbiano girato davvero — confronta l’ora dell’ultimo commit con l’ora delle note.

Il giorno del rollout, il monitor ha trovato il suo primo bug reale: il nostro. Avevamo installato gli hook su sette repository — e dimenticato l’ottavo. Venti minuti dopo, su quel repository, un’altra sessione di lavoro ha committato del codice nuovo. Il monitor l’ha segnalato al primo giro: commit più recente delle note, hook mancante.

Lo stesso pomeriggio, tre repository diversi hanno ricevuto commit veri — feature, fix, refactor del lavoro normale dello studio. Le mappe si sono rigenerate da sole, tre volte su tre, senza che nessuno facesse niente.

Il bonus inaspettato: misurare il drift della documentazione

Una volta che hai un monitor che confronta “quando è cambiato il codice” con “quando è stato aggiornato il resto”, la domanda successiva arriva da sola: e le istruzioni di progetto, quanto sono indietro?

Ogni nostro repository ha un file di istruzioni operative — architettura, regole, vincoli — che guida sia gli umani sia gli agenti AI che ci lavorano. L’abbiamo misurato la sera stessa: un progetto aveva 342 commit dopo l’ultimo aggiornamento delle sue istruzioni. Praticamente l’intera vita del progetto era avvenuta dopo l’ultima volta che la sua “costituzione” era stata letta da qualcuno con l’intenzione di aggiornarla.

Ora il monitor segnala anche questo, ogni mattina. Con una distinzione che per noi è diventata una regola di design:

La detection si automatizza. Il giudizio no. Lo script ti dice che la documentazione è indietro di 342 commit. Decidere cosa di quei 342 commit merita di entrare nelle istruzioni resta un lavoro di comprensione — assistito dall’AI, mai delegato alla cieca.

Un sistema che riscrivesse da solo le proprie istruzioni operative, senza review, è il loop sbagliato da chiudere: un errore lì non resta un errore — si auto-propaga a ogni sessione successiva.

I numeri, a fine giornata

• 8 repository mappati in 226 note-modulo, stack diversi (Python/FastAPI, TypeScript/React, Cloudflare Workers, Astro)
• ~3 secondi di rigenerazione a ogni commit, zero manutenzione prevista
• 3 auto-rigenerazioni organiche il giorno stesso del rollout, su commit di lavoro reale
• 1 gap di deploy trovato dal monitor al primo run (il nostro)
• 342 commit di drift documentale scoperti su un singolo progetto
• 28 test, zero dipendenze runtime oltre Python

E una query che prima non esisteva: “adapter multi-provider con credenziali cifrate” adesso restituisce, nella stessa risposta, il modulo che lo implementa e l’appunto che spiega perché è fatto così — attraverso tutti i progetti.

Due livelli: free per la community, completo per chi vuole padroneggiarlo

Il cartografo è open source da oggi: synapse-codemap, licenza MIT, un file Python senza dipendenze. Config di esempio, hook auto-regen, monitor incluso. Se hai un vault markdown e più di un repository, fa il suo lavoro così com’è — sul tuo PC, senza mandare un byte a nessuno.

Perché regalarlo? Tre ragioni, oneste:

1. Il problema è di tutti i builder. Chiunque abbia più di un repository e una base di appunti vive la stessa frattura tra codice e conoscenza. Una soluzione che funziona, tenuta in un cassetto, non serve a niente e a nessuno.
2. Uno studio che vende sistemi si giudica dai sistemi. Il codice pubblico — leggibile, testato, con le sue scelte spiegate — dice di noi più di qualsiasi pagina di marketing. È il biglietto da visita che preferiamo.
3. La community lo porterà dove non immaginiamo. Stack che non conosciamo, casi d’uso che non abbiamo previsto, fork che ci insegnano qualcosa. Il free non è una demo zoppa del paid: è un tool completo che migliora se viene usato davvero.

Il sistema completo è un’altra storia — e ha un altro percorso. Il bibliotecario (ricerca semantica locale, collegamenti mancanti, integrazione con gli agenti AI via MCP) e soprattutto il metodo che lo rende utile — come strutturare il vault, come scrivere appunti che si ritrovano a distanza di mesi, come tenere vivo tutto il sistema senza manutenzione — saranno il cuore di una community a pagamento che stiamo costruendo: il posto dove non scarichi un tool, ma impari a far funzionare il sistema sulla tua operazione, con noi dentro.

Non è ancora aperta. E in pieno stile proof-before-promise, niente date e niente programmi annunciati: apriremo quando il materiale avrà le stesse cicatrici di produzione del tool. Se vuoi esserci dal primo giorno, scrivici citando “community” — entri in lista, ti avvisiamo noi.

È la stessa regola di sempre, quella del manifesto: prima per noi, con cicatrici vere, poi per il mercato. Questo articolo è il diario della prima cicatrice: il giorno in cui il nostro secondo cervello ha imparato a leggere il nostro codice — senza che un solo byte lasciasse il PC.