Graphify trasforma una cartella in un grafo. Il 71.5x va spiegato

Graphify ha raccolto circa 7,300 stelle questa settimana, il che lo porta in cima alle tendenze settimanali di GitHub e spinge il totale oltre quota 137,000. Il messaggio sta in una riga: punta l'agente di coding su una cartella, digita /graphify . e ottieni un grafo della conoscenza di tutto ciò che contiene.

La cosa interessante non è il grafo. È il numero appiccicato accanto: 71.5x in meno di token per query, misurato rispetto alla lettura dei file grezzi. Se regge in generale, non è uno strumento di comodo, è un cambiamento nella quantità di contesto che un agente deve portarsi dietro.

Da dove viene

L'autore, safishamsi, presenta il progetto come risposta a un'abitudine molto precisa di Andrej Karpathy: tenere una cartella /raw in cui finiscono paper, tweet, screenshot e note, senza riuscire mai più a ritrovare nulla. Il problema è riconoscibile, e l'origine è più onesta della media, perché descrive una modalità di fallimento e non un mercato.

L'obiettivo dichiarato è più stretto di «cerca nei tuoi documenti». Si tratta di produrre qualcosa di persistente che sopravviva tra una sessione e l'altra, ed essere espliciti su cosa è stato inferito e cosa estratto. Ogni arco del grafo porta un'etichetta: EXTRACTED, INFERRED o AMBIGUOUS. È una scelta di progetto insolita e, a mio parere, la parte più preziosa dell'intera faccenda.

Cosa fa davvero

L'installazione sono due comandi, e sì, il nome del pacchetto su PyPI per ora è sbagliato:

pip install graphifyy && graphify install

La Y doppia nasce da una disputa sul nome, non da un refuso. La CLI e il comando dello skill restano entrambi graphify. Su Windows, se dopo l'installazione il comando non viene riconosciuto, bisogna aggiungere la cartella Scripts di Python al PATH, oppure usare pipx install graphifyy e aggirare il problema.

Poi, dentro Claude Code, in una directory qualsiasi:

/graphify .
/graphify ./raw --mode deep
/graphify query "what connects attention to the optimizer?"
/graphify path "DigestAuth" "Response"
/graphify explain "SwinTransformer"

L'output finisce in graphify-out/. Ci sono un graph.html interattivo da esplorare cliccando, una cartella obsidian/ che si apre come vault, un graph.json persistente per interrogare settimane dopo senza rileggere nulla, una cache/ con chiave SHA256 perché le riesecuzioni trattino solo i file cambiati e un GRAPH_REPORT.md che elenca i cosiddetti god nodes — i concetti con il grado più alto — più le «connessioni sorprendenti», ordinate da un punteggio composito in cui gli archi da codice a paper pesano più di quelli da codice a codice.

La parte multimodale non è marketing. I file di codice passano per tree-sitter per l'analisi AST più una passata sul call graph. Markdown, PDF e immagini passano per Claude: concetti e relazioni dalla prosa, estrazione di citazioni dai paper e visione per screenshot, diagrammi, foto di lavagna e immagini in altre lingue.

Ci sono anche export che contano per chi non vuole vivere dentro questo strumento: --svg, --graphml per Gephi o yEd, e --neo4j, che genera un cypher.txt invece di pretendere un database in esecuzione. Lo stack è NetworkX, clustering Leiden via graspologic, tree-sitter e vis.js. Nessun server. Nulla esce dalla macchina, tranne le chiamate a Claude.

Il 71.5x, esaminato

Il corpus di riferimento sono 52 file: i repository di Karpathy, cinque paper, quattro immagini. Risultato: 71.5x in meno di token per query rispetto alla lettura dei file grezzi.

Il repository è insolitamente onesto su come questo si comporta al crescere della scala, cosa abbastanza rara da meritare una citazione nella sostanza: il risparmio di token cresce con la dimensione del corpus, e su sei file il valore del grafo è la chiarezza strutturale più che la compressione, perché sei file stanno comunque in una finestra di contesto. Il loro stesso esempio, sul codice di graphify più il paper Transformer, dà 5.4x. Su sei file di libreria sintetici, circa 1x.

La forma è quella giusta. Se il corpus sta già dentro una finestra di contesto, non stai risparmiando token, stai comprando una mappa. Se sono cinquanta file di tipi misti, il risparmio è reale e grande, perché l'alternativa non è leggere i file una volta, ma rileggerli più e più volte lungo diversi turni, ogni volta che un agente perde il segno.

Il confronto peraltro lusinga graphify in una direzione e lo sottovaluta nell'altra. Leggere i file grezzi è il baseline peggiore possibile; un indice di retrieval ben tarato farebbe più bella figura rispetto ai file grezzi. Ma un indice di retrieval restituisce passaggi, e ciò che restituisce graphify sono relazioni: la risposta a «cosa collega l'attention all'optimizer» non è un passaggio, è un percorso. Sono query diverse, e un vector store ne serve una sola.

«Niente vector store» è una vera posizione architetturale

La maggior parte dei sistemi di retrieval spezzetta il testo, lo embedda e fa ricerca dei vicini più prossimi. Graphify salta tutto: parsing AST locale e deterministico per il codice, estrazione via LLM per prosa e immagini, poi un grafo. Nessuno step di embedding, nessuna ricerca per similarità.

Quello che si ottiene in cambio è spiegabilità. Chiedi perché due cose sono collegate e ottieni gli archi, ciascuno etichettato a seconda che sia stato estratto dalla fonte o inferito dal modello. Un indice vettoriale non sa dirtelo. Può solo dirti che la distanza coseno era piccola.

Il prezzo è la copertura. Un grafo conosce solo ciò che l'estrattore ha trovato. Se la passata di estrazione ha mancato una relazione, nessuna query la farà emergere, e non c'è alcun fallback sfumato. L'etichetta AMBIGUOUS è l'ammissione onesta di questo limite, e il flag --mode deep esiste perché la passata predefinita è prudente nell'inferire archi.

Dove si guadagna il suo posto

Due flussi di lavoro, per la mia esperienza con strumenti di questo tipo.

Il primo è l'inserimento in un codebase sconosciuto. Non «dov'è la funzione X» — per quello basta grep — ma «quali sono i concetti portanti qui, e quali toccano il codice di fatturazione». È una domanda da grafo, e il report dei god nodes la risponde in una forma che si legge in due minuti.

Il secondo è il caso multi-agente. Quando più agenti scrivono codice in parallelo, il modello che ciascuno ha del repository diventa obsoleto nel giro di minuti. Un grafo ricostruito a ogni commit (graphify hook install imposta un hook post-commit) o al salvataggio di un file (--watch) dà a tutti gli agenti la stessa mappa aggiornata invece di cinque congetture divergenti.

Il limite evidente: è costruito prima di tutto come skill per Claude Code. Il percorso di installazione manuale mette uno SKILL.md in ~/.claude/skills/graphify/ e aggiunge una riga a CLAUDE.md. Esiste una modalità server MCP (--mcp) usabile da altri client, ma l'ergonomia è chiaramente ottimizzata per un solo ecosistema, e la dipendenza da Claude significa che la passata di estrazione costa denaro vero su un corpus grande.

Il verdetto onesto

Graphify non è un motore di ricerca e non va valutato come tale. È un modello persistente e ispezionabile di ciò che contiene una cartella, con la proprietà insolita di dirti quali parti ha indovinato. Per un progetto da 137,000 stelle che fa tendenza da una settimana, la domanda interessante non è se il grafo sia impressionante, ma se l'abitudine di etichettare l'inferenza sopravviva al contatto con utenti che vogliono solo risposte.

La mia previsione è che quasi tutti useranno query, ignoreranno le etichette degli archi e non apriranno mai graph.json. Quelli che resteranno sono quelli che avevano bisogno della mappa, non delle soluzioni.