Graphify con Ollama: il grafo delle note Markdown in locale

Quando le note in Markdown diventano centinaia, è difficile ricordare quali idee si collegano tra loro. Graphify legge una cartella e ne ricava un grafo di conoscenza: i concetti diventano nodi e le relazioni diventano archi. Il grafo si esplora in una pagina HTML e si interroga dal terminale. Questa guida è per chi vuole costruirlo con un modello che gira su Ollama, senza mandare le note a un servizio cloud. Alla fine avrete il grafo delle vostre note, saprete interrogarlo per trovare collegamenti e riferimenti e saprete tenerlo aggiornato. I comandi sono quelli della documentazione ufficiale, elencata in fondo.

Cosa fa Graphify e cosa no

Il progetto ufficiale è Graphify-Labs/graphify. Su PyPI il pacchetto si chiama graphifyy, con due y. Il README ufficiale avverte che gli altri pacchetti graphify* non sono collegati al progetto. Il comando da terminale invece si chiama graphify.

Graphify tratta in due modi diversi quello che trova nella cartella:

• Il codice viene analizzato in locale con tree-sitter, che ne costruisce l’albero sintattico (AST). L’analisi è deterministica, non usa modelli linguistici e niente esce dal computer.
• I documenti (Markdown, MDX, testo, HTML e reStructuredText) hanno bisogno di un backend semantico che ne estragga i concetti, come spiega la pagina sugli input supportati. In questa guida quel backend è Ollama.

Ogni arco del grafo ha un’etichetta: EXTRACTED vuol dire che la relazione è scritta in modo esplicito nel sorgente, INFERRED che l’ha ricostruita Graphify. I link Markdown tra file e i [[wikilink]] diventano archi references tra documenti. Graphify però non si limita a disegnare i link come fa il grafo di Obsidian, perché ci aggiunge i concetti estratti dal modello.

Graphify non è un indice vettoriale: non usa embedding né database vettoriali, ma costruisce un grafo da percorrere. Funziona in modo diverso da un sistema RAG e non va preso come un suo sostituto.

Cosa serve

• Python 3.10 o successivo.
• uv, il gestore consigliato dal README, disponibile per Linux, macOS e Windows. Per installarlo il README indica Homebrew su macOS, winget su Windows e lo script ufficiale di uv su Ubuntu e Debian.
• Ollama installato e avviato, con almeno un modello già scaricato e adatto ai vostri testi.
• Una cartella di lavoro con le note nella sottocartella docs.
• Un browser per aprire la vista interattiva del grafo.

Installare graphifyy con il supporto a Ollama

Per usare Ollama nell’estrazione semantica serve il componente aggiuntivo (extra) ollama del pacchetto. Questo comando, preso dalla guida allo sviluppo locale, installa il programma insieme al componente in un ambiente isolato gestito da uv:

uv tool install "graphifyy[ollama]"

Se tutto è andato a buon fine, in un nuovo terminale il comando graphify viene trovato. Se la shell risponde «command not found», guardate la sezione sui problemi.

Verificare l’installazione su un piccolo progetto di prova

Prima di coinvolgere il modello conviene fare una prova che non ne ha bisogno e non richiede chiavi API. Non fatela nella cartella delle note. Con --code-only Graphify analizza solo il codice, quindi su una cartella di sole note il grafo resta vuoto e il comando può terminare con «graph is empty» e codice di uscita 1. È il comportamento previsto, non un guasto.

Usate invece il progetto della guida al primo grafo. Create una cartella vuota, separata da quella delle note, e scriveteci un file app.py con tre funzioni Python:

• normalize_email, che riceve un indirizzo email e lo restituisce senza spazi ai lati e tutto in minuscolo;
• find_user, che chiama normalize_email;
• login, che chiama find_user.

Lavorate in un terminale in cui GRAPHIFY_OUT non è impostata: questa variabile compare nella prossima sezione e, se fosse già attiva, i risultati della prova finirebbero nella cartella del grafo delle note. Dalla cartella di prova lanciate l’estrazione:

graphify extract . --code-only

Poi raggruppate i nodi e generate la vista HTML:

graphify cluster-only . --no-label

graphify export html

Aprite graphify-out/graph.html nel browser oppure leggete graphify-out/GRAPH_REPORT.md. Ci devono essere le tre funzioni e le chiamate tra loro. Per provare le interrogazioni, chiedete a Graphify di spiegare un nodo:

graphify explain "normalize_email"

E di trovare il percorso tra due nodi:

graphify path "login" "normalize_email"

Il percorso giusto va da login a find_user e poi a normalize_email. Gli identificativi esatti e il formato del report possono cambiare da una versione all’altra. Finita la prova, la cartella di prova non serve più.

Scegliere il modello di Ollama e la cartella dei risultati

Graphify si configura con variabili d’ambiente, da impostare nella shell in cui lavorerete sulle note, come spiega il riferimento della configurazione. Per Ollama non serve nessuna chiave API.

In OLLAMA_MODEL mettete il nome di un modello che avete davvero installato: la documentazione raccomanda di non dare per scontato un nome particolare. OLLAMA_BASE_URL si può lasciare non impostata. Se la fate puntare a un computer remoto, le note vengono inviate a quel computer.

GRAPHIFY_OUT in questa guida va impostata, e con un percorso assoluto, per esempio il percorso completo di una cartella graphify-out dentro la cartella di lavoro. Il motivo è pratico: l’estrazione delle note si lancia su ./docs, mentre raggruppamento, esportazione e interrogazioni si lanciano sulla cartella di lavoro. Senza un percorso assoluto in comune, l’estrazione scriverebbe in docs/graphify-out e gli altri comandi cercherebbero graphify-out nella cartella di lavoro: lavorereste su due grafi diversi. Tenete la stessa GRAPHIFY_OUT per tutti i comandi che seguono, aggiornamenti compresi.

Estrarre i concetti dalle note con Ollama

Questo è il passaggio in cui le note diventano nodi e relazioni. Dalla cartella di lavoro, Graphify invia il contenuto di docs al modello indicato in OLLAMA_MODEL. Scrivete sempre il backend in modo esplicito: se nella shell c’è la chiave di un altro servizio, come Gemini, Claude o OpenAI, il rilevamento automatico la preferisce a Ollama.

graphify extract ./docs --backend ollama

Se il comando termina senza errori, l’estrazione è riuscita e i risultati sono nella cartella indicata da GRAPHIFY_OUT. Se invece si ferma dicendo che l’estrazione è incompleta, guardate la sezione sui problemi.

Se il modello non ci sta in memoria

Con documenti lunghi o poca memoria video conviene usare blocchi di testo più piccoli e meno richieste in parallelo, come suggerisce la pagina sull’estrazione headless:

graphify extract ./docs --backend ollama --token-budget 4000 --max-concurrency 2

--token-budget rimpicciolisce i blocchi e --max-concurrency limita le richieste contemporanee al modello. --max-workers regola invece il parallelismo dell’estrazione strutturale, mentre --api-timeout cambia il tempo di attesa massimo delle richieste. Anche qui i risultati vanno nella cartella di GRAPHIFY_OUT.

Raggruppare il grafo e creare la vista HTML

Dopo l’estrazione, Graphify raggruppa i nodi in comunità di concetti vicini e prepara i file da consultare. Lanciate questi due comandi dalla cartella di lavoro:

graphify cluster-only . --no-label

graphify export html

Nella cartella di GRAPHIFY_OUT trovate tre file:

• graph.html, il grafo interattivo da aprire nel browser, in cui si possono cliccare, filtrare e cercare i nodi;
• GRAPH_REPORT.md, il riepilogo con i concetti più collegati, le connessioni inattese e alcune domande suggerite;
• graph.json, il grafo completo, che le interrogazioni leggono senza riaprire le note.

Interrogare relazioni e riferimenti

query fa una domanda libera e restituisce la parte di grafo che la riguarda. L’esempio della documentazione è questo:

graphify query "entry points"

Tra le virgolette, al posto di «entry points», scrivete un concetto o una domanda che riguardano le vostre note. explain e path si usano come nella prova: tra le virgolette mettete il titolo di una nota o un concetto che compare nel grafo. explain mostra da dove viene un nodo e quali collegamenti ha, ciascuno con l’etichetta EXTRACTED o INFERRED. path cerca come sono collegati due nodi.

Nelle risposte guardate i riferimenti alle fonti, che dicono da quale nota viene ogni relazione. Se un nome corrisponde a più nodi, usate l’identificativo restituito da query per una ricerca più precisa.

Tenere il grafo aggiornato

Le interrogazioni leggono il grafo salvato, non i file: se modificate una nota senza aggiornarlo, potete ricevere una risposta superata. Il README spiega che codice e documenti si aggiornano separatamente. Dopo le modifiche, con la stessa GRAPHIFY_OUT di prima, procedete in quest’ordine.

1. Rilanciate l’estrazione semantica, così le note nuove o modificate ripassano dal modello.
2. Se nella cartella di lavoro c’è anche codice, aggiornate la sua parte del grafo.
3. Ricalcolate i raggruppamenti.
4. Rigenerate la vista HTML e solo dopo tornate a interrogare il grafo.

L’estrazione è la stessa dell’inizio:

graphify extract ./docs --backend ollama

Il comando per la parte di codice è questo. Riguarda il codice, non le note: se la cartella contiene solo note, saltatelo.

graphify update .

Poi ricalcolate le comunità:

graphify cluster-only . --no-label

Infine rigenerate graph.html:

graphify export html

Rifate le interrogazioni e confrontate i collegamenti con quelli di prima.

Privacy, assistenti e come tornare indietro

Il README propone anche un altro modo di usare Graphify: lo si registra in un assistente di programmazione e poi si scrive /graphify . nella chat (in PowerShell si scrive graphify ., senza la barra). Con un assistente cloud, però, la parte semantica usa il modello dell’assistente e le note escono dal vostro computer. In questa guida le note restano sulla vostra macchina perché usate Ollama con un modello e un endpoint locali.

Il README dichiara che Graphify non raccoglie telemetria. Sul registro delle interrogazioni il README si contraddice: in un punto dice che ogni domanda viene registrata in ~/.cache/graphify-queries.log, in un altro che il registro è spento di default. La pagina Configuration conferma che nell’implementazione attuale è spento finché non lo attivate. Se volete esserne certi, la variabile GRAPHIFY_QUERY_LOG_DISABLE=1 lo tiene spento. Il grafo può contenere brani delle note, titoli e percorsi, quindi va conservato con la stessa cura delle note.

Per tornare indietro cancellate la cartella indicata da GRAPHIFY_OUT, che contiene graph.html, GRAPH_REPORT.md e graph.json, e la cartella del progetto di prova. Le note in docs restano come sono. Per riavere il grafo dovrete ripetere l’estrazione semantica di tutte le note. Le pagine consultate non riportano un comando per disinstallare il pacchetto installato con uv. Graphify è distribuito con licenza Apache-2.0, e il file NOTICE conserva alcune parti precedenti con licenza MIT.

Se qualcosa va storto

• «graphify: command not found» dopo l’installazione: la cartella dei programmi di uv (~/.local/bin) non è nel PATH. Succede spesso su un macOS appena configurato con zsh. Eseguite uv tool update-shell e aprite un nuovo terminale.
• L’estrazione con --code-only finisce con «graph is empty»: la cartella non contiene codice. Per la verifica usate il progetto di prova descritto sopra.
• Ollama esaurisce la memoria video o supera la finestra di contesto: abbassate --token-budget e --max-concurrency come visto sopra. Potete anche ridurre la finestra di contesto con la variabile GRAPHIFY_OLLAMA_NUM_CTX.
• «extraction was incomplete … refusing to overwrite»: Graphify non sostituisce un grafo più grande con un risultato parziale. Risolvete la causa e rilanciate. L’opzione --allow-partial forza la sovrascrittura, ma il graph.json esistente viene sostituito da uno più piccolo: copiatelo prima.
• Il grafo conserva i nodi di file cancellati: --force, oppure GRAPHIFY_FORCE=1, sovrascrive il grafo anche quando quello nuovo ha meno nodi. Anche in questo caso fate prima una copia di graph.json.
• Una risposta non tiene conto di una modifica recente: ripetete i passaggi dell’aggiornamento e rifate la domanda.

Documentazione di riferimento

Pagine ufficiali consultate il 7 ottobre 2026:

• Graphify Docs: Local development
• Graphify Docs: Headless extraction
• Graphify Docs: First graph
• Graphify Docs: Supported inputs
• Graphify Docs: Configuration reference
• README ufficiale di Graphify-Labs/graphify (branch v8)

Leggi anche

• Obsidian second brain: guida per Windows, macOS e Linux
• Ollama su Linux: come installarlo e usare un modello in locale
• AnythingLLM: come chattare con i documenti usando Ollama o LM Studio