# skill-shamsi-graphify-2026-08-06

## Veille

**Voce di tipo Skill** (non un articolo): **graphify** di **Safi Shamsi** (Graphify Labs, **Y Combinator S26**) trasforma un intero progetto — codice, documenti, PDF, immagini, video — in un **grafo di conoscenza interrogabile**, invocato tramite `/graphify` da Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot e una quindicina di altri client. Osservato il **6 agosto 2026**: **103.187 stelle**, **10.024 fork**, repository creato il **3 aprile 2026** — una traiettoria straordinaria in quattro mesi. **Apache-2.0**, Python 3.10+, branch predefinito **v8**. **I tre impegni di progettazione stanno in tre righe del README**: *« Mappe del codice gratuite, completamente locali »* (il codice viene analizzato in **AST tree-sitter**, deterministico, senza LLM, **nulla lascia la macchina**); *« Ogni arco è spiegato »* (ogni arco è etichettato **`EXTRACTED`** — esplicito nella fonte — o **`INFERRED`** — risolto da graphify —, con un terzo valore `AMBIGUOUS` che compare nel report); e *« Non è un indice vettoriale »* — *« nessun embedding, nessun vector store: un vero grafo che si attraversa »*. **Tre output**: `graph.html` (grafo interattivo), `GRAPH_REPORT.md` (nodi god, connessioni sorprendenti, domande suggerite) e `graph.json` (grafo persistente, interrogabile settimane dopo senza rileggere i file). **Tre modalità di interrogazione** sostituiscono grep: `query` (sottografo per una domanda in linguaggio naturale), `path A B` (percorso più breve tra due entità) ed `explain` (vicinato di un concetto). **Copertura**: 36 grammatiche tree-sitter (~40 linguaggi), oltre a Terraform, Apex, **configurazioni MCP**, manifest di pacchetti, Office, Google Workspace, PDF, immagini e trascrizioni video/audio **in locale** tramite faster-whisper. Comunità rilevate tramite **Leiden**, etichettate **senza LLM**. ⭐ **Il risultato di benchmark più interessante non è una vittoria ma una vittoria gratuita**: su LOCOMO, graphify ottiene un **recall@10 di 0,497** contro 0,149 di supermemory e 0,048 di mem0, ma **perde sull'accuratezza QA** (45,3% contro 49,7%); su LongMemEval-S ottiene **76%, a pari merito con un RAG denso**; e la riga che conta è *« Costruzione del grafo — crediti LLM: **0** »*, laddove il settore fattura tipicamente per token. ⚠️ **Punti da annotare**: il branch `main` porta un README dell'epoca v1 che descrive un prodotto diverso (skill Claude Code soltanto, l'affermazione dei « 71,5× meno token »); il pacchetto PyPI si chiama **`graphifyy`** con due *y*, in attesa che il nome `graphify` venga recuperato; e un **log delle query** viene scritto per impostazione predefinita in `~/.cache/graphify-queries.log`, disattivabile tramite una variabile d'ambiente.

## Titre Article

graphify — « Turn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store. »

## Date

2026-08-06

## URL

https://github.com/Graphify-Labs/graphify

## Keywords

skill, grafo di conoscenza, grafo di conoscenza, AST, tree-sitter, analisi statica deterministica, estrazione locale, nessun LLM, NetworkX, Leiden, rilevamento di comunità, nodo god, connessioni sorprendenti, EXTRACTED, INFERRED, AMBIGUOUS, provenienza degli archi, affidabilità, nessun vettore, nessun embedding, nessun vector store, attraversamento del grafo, query, path, explain, graph.json, graph.html, GRAPH_REPORT, cache SHA256, aggiornamento incrementale, watch, hook post-commit, wiki navigabile dagli agenti, MCP stdio, Neo4j, GraphML, Obsidian, multimodale, PDF, visione, faster-whisper, trascrizione locale, Terraform, Apex, configurazioni MCP, manifest di pacchetti, Google Workspace, LOCOMO, LongMemEval, recall, mem0, supermemory, RAG denso, zero crediti LLM, residenza dei dati, Ollama, Bedrock, log delle query, telemetria, Y Combinator, Graphify Labs, Safi Shamsi

## Authors

**Safi Shamsi** — créateur et mainteneur de graphify, et de **Graphify Labs**, société passée par **Y Combinator (promotion S26)** selon le badge du dépôt. Il maintient aussi le site d'annuaire `graphify.net` (cf. [[graphify-net-annuaire-ia-coding-2026-08-06]]) et publie un livre, *The Memory Layer*, sur les idées et l'architecture derrière le projet.

**Trace d'historique à connaître** : le dépôt s'appelait `safishamsi/graphify` avant son transfert vers l'organisation `Graphify-Labs`. Le README de la branche `main` porte encore l'ancien chemin dans son badge d'intégration continue et dans sa procédure d'installation manuelle.

**Signaux d'adoption au 6 août 2026** : 103 187 étoiles, 10 024 forks, 823 issues ouvertes, dernier push la veille. Le dépôt affiche un badge Trendshift et propose son README en **33 langues**. Communauté sur Discord, page LinkedIn d'entreprise.

## Ton

**Profilo**: documentazione densa di un progetto open source, scritta per essere letta da uno sviluppatore di fretta **e** da un agente. Registro tecnico, pochissime promesse, molte tabelle — tipi di file, grammatiche, variabili d'ambiente, un riferimento completo ai comandi.

**Stile**: **la dimostrazione precede l'argomentazione**. Il README mostra un output reale prima di spiegare qualsiasi cosa — un comando `graphify explain "APIRouter"` con il suo vicinato annotato riga per riga, poi un `graphify path "FastAPI" "ModelField"` che mostra il percorso a tre salti. Il prodotto viene mostrato all'opera su un repository che il lettore già conosce (FastAPI) prima di qualsiasi argomento commerciale.

**Tre tratti degni di nota**:

1. **La posizione è definita da una negazione deliberata.** *« Non è un indice vettoriale. Nessun embedding, nessun vector store: un vero grafo che si attraversa. »* Il progetto si posiziona **contro** il RAG vettoriale, ormai lo standard, e questa opposizione struttura tutto il resto — determinismo, costo zero, tracciabilità degli archi.
2. **Onestà riguardo ai propri benchmark.** La tabella pubblica una **sconfitta**: 45,3% di accuratezza QA su LOCOMO contro 49,7% per supermemory. Pochi progetti pubblicano la colonna in cui perdono.
3. **Il confine della privacy è tracciato per tipo di file, non per principio.** Il codice resta locale, così come il video (trascritto tramite faster-whisper), documenti e immagini vengono inviati al modello. La sezione *Privacy* enumera i casi invece di promettere la località.

**Registro operativo imposto all'agente** (il "tono" nel senso usato per le voci di tipo skill): lo strumento non impone nulla all'agente, **fornisce un substrato**. Il README dedica un'intera sezione a *« Fai in modo che il tuo assistente usi sempre il grafo »* — l'obiettivo è che l'agente consulti il grafo **prima** di leggere i file.

**Frasi marcatrici**: *« interrogare invece di fare grep »*, *« mappe del codice gratuite, completamente locali »*, *« ogni arco è spiegato »*, *« sai sempre cosa è stato trovato e cosa è stato ipotizzato »*, *« un vero grafo che si attraversa »*, *« costruzione del grafo — crediti LLM: 0 »*.

## Pense-betes

- **Natura**: skill `/graphify` + CLI Python, Apache-2.0, distribuita su PyPI con il nome **`graphifyy`** (due *y*, in attesa che `graphify` venga recuperato). Installazione tramite `uv tool install graphifyy && graphify install`. Funziona in Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot e una quindicina di altri client.
- **⭐⭐ I tre impegni di progettazione, e reggono insieme**: 1. **Il codice viene analizzato in locale, senza LLM.** AST tree-sitter, deterministico, *« nulla lascia la tua macchina »*. Un corpus puramente di codice **non richiede alcuna chiave API** e funziona offline. Documenti, PDF e immagini, invece, passano attraverso un modello. 2. **Ogni arco porta la propria provenienza.** `EXTRACTED` = esplicito nella fonte; `INFERRED` = risolto da graphify; `AMBIGUOUS` nel report. *« Sai sempre cosa è stato trovato e cosa è stato ipotizzato. »* 3. **Nessun indice vettoriale.** Nessun embedding, nessun vector store: un grafo che si attraversa. → **I tre si rafforzano a vicenda**: il determinismo azzera il costo, il costo zero rende possibile una ricostruzione frequente, e l'etichettatura degli archi rende il risultato verificabile. Stessa famiglia di ragionamento dell'eseguibile che supera il brief in [[lassiege-usine-logicielle-heure-ia-2026-07-28]].
- **⭐ Il grafo sostituisce grep, ed è questo l'argomento d'uso**: `query "<domanda>"` restituisce un sottografo per una domanda in linguaggio naturale, `path A B` traccia il percorso tra due entità, `explain X` sviluppa il vicinato di un concetto. L'esempio del README lo dimostra: `path "FastAPI" "ModelField"` restituisce un percorso a tre salti con il tipo di ciascun arco. **Si chiede una relazione, non una corrispondenza di stringa.** È esattamente il vantaggio che Hugo Lassiège attribuisce a GitNexus in [[lassiege-usine-logicielle-heure-ia-2026-07-28]] — *« cercare un flusso di esecuzione piuttosto che fare grep sul nome di una funzione »*, e *« il punto reale non è la velocità, è individuare tutti gli effetti collaterali »*.
- **⭐⭐ La tabella dei benchmark, letta correttamente — la riga che conta non è una vittoria**: | Benchmark | Metrica | graphify | Settore | |---|---|---|---| | LOCOMO (n=300) | recall@10 | **0,497** | supermemory 0,149 · mem0 0,048 | | LOCOMO (n=300) | accuratezza QA | 45,3% | **supermemory 49,7%** · mem0 27,3% | | LongMemEval-S (n=50) | accuratezza QA | 76% | **a pari merito** con un RAG denso | | Costruzione del grafo | crediti LLM | **0** | fatturati per token altrove | → **graphify domina largamente sul recall, perde sull'accuratezza QA, pareggia con il RAG denso sul secondo benchmark e costruisce il proprio grafo gratuitamente.** Il differenziatore difendibile è quindi **il costo e la tracciabilità, non la qualità delle risposte**. Presentare graphify come « migliore del RAG » sarebbe una sovrainterpretazione contraddetta dai suoi stessi numeri. Protocollo accreditato: stesso harness, stesso modello, stessi budget, giudice validato alla cieca rispetto a un secondo giudice (**90,6% di accordo, kappa di Cohen 0,81**).
- **⭐ Da confrontare con l'unica cifra comparabile del corpus**: Compare the Market ha misurato un grafo AST al **~70%** contro **~58%** per un RAG vettoriale su 79 merge request, con il RAG che ottiene risultati **peggiori dell'assenza di contesto** (cfr. [[comparethemarket-context-retrieval-ai-code-review-gkg-rag-2026-03-06]], ripreso in [[sfeir-code-review-anneau-contraintes-2026-07-30]]). **Due misurazioni indipendenti convergono sulla superiorità del grafo strutturato per il codice** — e graphify aggiunge che la costruzione non costa nulla.
- **Copertura delle fonti — più ampia di "solo codice"**: 36 grammatiche tree-sitter che coprono ~40 linguaggi (fino a CUDA, Metal, Zig, Elixir, Julia, Dart, SystemVerilog, Delphi, Fortran), oltre a **SQL**, **Terraform/HCL**, **Apex Salesforce**, **configurazioni MCP** (`.mcp.json`, `claude_desktop_config.json` — estrae server, pacchetti e variabili d'ambiente richieste), **manifest di pacchetti** (`pyproject.toml`, `go.mod`, `pom.xml` — un nodo canonico per pacchetto, quindi un unico hub), Office, Google Workspace, PDF, immagini, video e audio. ⭐ **Applicare graphify alle proprie configurazioni MCP** è un modo inatteso e immediatamente utile per mappare la propria superficie di strumenti.
- **Il "perché" estratto come oggetto di primo livello**: i commenti `# NOTE:`, `# WHY:`, `# HACK:`, i docstring e il ragionamento di progettazione presenti nella documentazione diventano **nodi separati collegati al codice che spiegano**. → **L'intento è trattato come un'entità del grafo**, il che affronta direttamente il debito di comprensione: si può chiedere *perché*, non solo *cosa*.
- **Aggiornamento del grafo, tre meccanismi**: cache SHA256 (vengono rielaborati solo i file modificati), `--watch` (ricostruzione istantanea al salvataggio di un file di codice, **solo AST, nessun LLM**; documenti e immagini segnalano che è necessario un `--update`) e `graphify hook install` (**hook post-commit**, nessun processo in background). La modalità `--watch` è esplicitamente giustificata per i flussi di lavoro multi-agente: *« il grafo resta aggiornato automaticamente tra un'ondata e l'altra »*.
- **Output per gli agenti**: `--wiki` produce articoli in stile enciclopedico per ciascuna comunità con un `index.md`, *« punta qualsiasi agente su index.md e potrà navigare la base di conoscenza leggendo file invece di analizzare JSON »*. E `--mcp` avvia un server MCP stdio. Esportazioni verso Obsidian, GraphML (Gephi, yEd), Neo4j (cypher), SVG. → **Il grafo è costruito per essere letto da una macchina, con più punti d'ingresso a seconda dello strumento.** Stessa intenzione del markdown servito agli agenti in [[martinho-allen-cloudflare-markdown-for-agents-2026-02-12]].
- **⚠️ Privacy — il confine è sottile, vale la pena conoscerlo**:
- **In locale**: codice (tree-sitter), video e audio (faster-whisper). Un corpus solo di codice funziona **offline**, e `--code-only` forza questa modalità su un repository misto.
- **Inviato al modello**: documenti, PDF, immagini. In modalità headless è richiesta una chiave API, con una **catena di priorità automatica** (Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama). ⚠️ **Kimi instrada verso i server di Moonshot AI in Cina** — il README lo segnala, e `--backend ollama` offre una modalità interamente locale.
- **Nessuna telemetria**, nessun tracciamento dell'utilizzo.
- ⚠️ **Ma un log delle query viene scritto per impostazione predefinita** in `~/.cache/graphify-queries.log` (timestamp, domanda, corpus, nodi restituiti, durata). I sottografi non vengono memorizzati. Disattivabile tramite `GRAPHIFY_QUERY_LOG_DISABLE=1`. **Locale, ma attivo senza opt-in**: da tenere presente prima di un utilizzo in un contesto sensibile.
- **⚠️ Due trappole documentali nel repository stesso**: 1. **Il branch `main` è obsoleto.** Porta un README dell'epoca **v1** (7 KB) che descrive *« una skill Claude Code »* per un singolo client, mette in evidenza l'affermazione dei **« 71,5× meno token »** su un corpus Karpathy di 52 file, e punta ancora a `safishamsi/graphify`. Il branch predefinito è **v8** (57 KB), che descrive un prodotto multi-client e mette in evidenza i benchmark LOCOMO/LongMemEval. **Leggere v8, mai `main`.** 2. **Il nome del pacchetto**: `pip install graphifyy` (due *y*). Il comando CLI e della skill restano `graphify`.
- **Modello di business, da monitorare**: la skill open source è il punto d'ingresso verso una **piattaforma commerciale** su `graphify.com` — *« il livello sempre attivo… applica lo stesso approccio a grafo all'intero contesto di lavoro: riunioni, file, documenti e codice, aggiornandosi continuamente in background »*, attualmente in lista d'attesa, con una prova gratuita annunciata. **Open source locale da un lato, servizio ospitato continuo dall'altro**: uno schema classico, da considerare in qualsiasi decisione di adozione.
- **⚠️ La trazione richiede una lettura prudente**: **103.187 stelle in quattro mesi** è un ritmo eccezionale, anche per uno strumento virale. La cifra è quella restituita dall'API GitHub il 6 agosto 2026; non dice nulla sull'utilizzo effettivo, e il sito ufficiale del progetto mostra ancora **3.700** (cfr. [[graphify-net-annuaire-ia-coding-2026-08-06]]), segno che la comunicazione non ha tenuto il passo. **Citare il numero di stelle come segnale di attenzione, mai come misura di adozione.**
- **Meta / riferimenti incrociati**: stessa famiglia di [[skill-gibbs-hyperresearch-2026-08-03]] (archiviazione persistente, provenienza, output leggibile dagli agenti), ma per il codice piuttosto che per la ricerca documentale; realizza in forma di prodotto ciò che Hugo Lassiège ottiene da GitNexus in [[lassiege-usine-logicielle-heure-ia-2026-07-28]]; convergenza numerica con [[comparethemarket-context-retrieval-ai-code-review-gkg-rag-2026-03-06]] e [[sfeir-code-review-anneau-contraintes-2026-07-30]] su grafo AST contro RAG vettoriale; si inserisce nel contesto codificato di [[vasilopoulos-codified-context-infrastructure-ai-agents-2026-02-24]] e nelle piattaforme di contesto di [[memodb-acontext-context-data-platform-agents-2025-12-11]]; parentela formale con altre voci di tipo skill, [[skill-pocock-grill-with-docs-2026-06]]; meccanica delle skill in [[agent-skills-anthropic-2025-10-16]], [[shihipar-claude-code-lessons-building-skills-2026-06-03]] e [[vincent-superpowers-agentic-skills-framework-github-2026-04-02]]. ⚠️ **Disambiguazione**: il sito `graphify.net` è una proprietà distinta da `graphify.com` (la piattaforma commerciale) — vedi la voce dedicata.

## RésuméDe400mots

**graphify** (Safi Shamsi, Graphify Labs, Y Combinator S26) trasforma un intero progetto in un **grafo di conoscenza interrogabile**, invocato tramite `/graphify` da Claude Code, Cursor, Codex, Gemini CLI e una quindicina di altri client. Osservato il 6 agosto 2026: **103.187 stelle** per un repository creato il 3 aprile, Apache-2.0, Python.

**Tre impegni sostengono il progetto.** **Il codice viene analizzato in locale** in AST tree-sitter, senza LLM: deterministico, nulla lascia la macchina, nessuna chiave API richiesta per un corpus puramente di codice. **Ogni arco porta la propria provenienza** — `EXTRACTED` se esplicito nella fonte, `INFERRED` se risolto da graphify —, *« così puoi distinguere ciò che è stato letto direttamente da ciò che è stato inferito »*. E il progetto si definisce **in opposizione al RAG vettoriale**: *« Non è un indice vettoriale. Nessun embedding, nessun vector store: un vero grafo che si attraversa. »*

**L'uso sostituisce grep.** `query` restituisce un sottografo per una domanda in linguaggio naturale, `path A B` traccia il percorso tra due entità, `explain` sviluppa un concetto. Tre output: un grafo interattivo, un report leggibile (nodi god, connessioni sorprendenti, domande suggerite) e un `graph.json` persistente, interrogabile settimane dopo.

**La copertura va oltre il codice**: 36 grammatiche tree-sitter, ma anche SQL, Terraform, Apex, **configurazioni MCP**, manifest di pacchetti, Office, PDF, immagini e video trascritti in locale. I commenti `# WHY:` e il ragionamento di progettazione diventano **nodi a pieno titolo collegati al codice che spiegano**.

**I benchmark meritano una lettura attenta.** Su LOCOMO, graphify domina in recall (0,497 contro 0,149 e 0,048) ma **perde sull'accuratezza QA** (45,3% contro 49,7%); su LongMemEval-S **pareggia con un RAG denso** al 76%. La riga che conta si trova altrove: *« Costruzione del grafo — crediti LLM: 0 »*. Il differenziatore difendibile è **il costo e la tracciabilità, non la qualità delle risposte**.

⚠️ **Tre avvertenze.** Il branch `main` porta un README obsoleto dell'epoca v1 che descrive un prodotto diverso: leggere `v8`. Il pacchetto PyPI si chiama `graphifyy`, in attesa che il nome venga recuperato. E un **log delle query locale** è attivo per impostazione predefinita, disattivabile tramite una variabile d'ambiente.

La skill funge anche da punto d'ingresso verso una piattaforma commerciale con lista d'attesa su graphify.com, che applica lo stesso approccio in modo continuo all'intero contesto di lavoro.

## Anti-patterns

- **Lire la branche `main`.** Elle décrit un produit de l'ère v1, mono-client, avec un argument marketing (« 71,5× moins de tokens ») que la version courante n'utilise plus. La branche par défaut est `v8`.
- **Citer « graphify bat le RAG ».** Ses propres benchmarks le contredisent : il perd en exactitude QA sur LOCOMO et **égale** un RAG dense sur LongMemEval-S. L'argument défendable est le coût nul et la traçabilité.
- **Annoncer « fully local » sans nuance.** Seul le code et la transcription vidéo le sont. Documents, PDF et images partent vers un modèle, sauf backend Ollama explicite.
- **Déployer en contexte sensible sans couper le journal de requêtes.** `~/.cache/graphify-queries.log` enregistre chaque question par défaut ; poser `GRAPHIFY_QUERY_LOG_DISABLE=1`.
- **Laisser la chaîne de priorité choisir le backend** dans un contexte à contrainte de résidence des données : la détection automatique peut router vers Kimi, donc vers des serveurs en Chine. Passer un `--backend` explicite.
- **Graphifier un corpus minuscule** en attendant un gain de tokens : en dessous de la taille d'une fenêtre de contexte, l'apport est structurel, pas économique.
- **Traiter 103 000 étoiles comme une mesure d'adoption.** C'est un signal d'attention sur quatre mois, rien de plus.

## Artefacts

**Sorties principales**, dans `graphify-out/` :
- `graph.html` — graphe interactif, nœuds cliquables, filtres par communauté, recherche
- `GRAPH_REPORT.md` — god nodes, connexions surprenantes avec leur justification en clair, 4-5 questions suggérées, étiquettes de confiance
- `graph.json` — le graphe complet, persistant et interrogeable

**Sorties optionnelles** : `wiki/` (articles par communauté avec `index.md`, pour navigation par un agent), `obsidian/` (coffre Obsidian), `graph.svg`, `graph.graphml` (Gephi, yEd), `cypher.txt` (Neo4j), serveur MCP stdio, `converted/` (passerelles markdown pour Google Workspace).

**Sous-produits** : `cache/` (empreintes SHA256 par fichier) et `~/.cache/graphify-queries.log` (journal des requêtes, actif par défaut).

## Commentaire

**En une phrase** : graphify parie que, pour du code, **un graphe déterministe construit gratuitement bat un index vectoriel payant** — et publie les chiffres qui le nuancent.

**L'idée centrale** tient dans une asymétrie que le projet exploite bien. Le code a une structure formelle : un analyseur syntaxique sait dire, sans deviner, que telle fonction en appelle telle autre. Le RAG vectoriel jette cette information pour la remplacer par une proximité statistique, et paie des tokens pour le faire. graphify garde la structure là où elle existe (le code, en AST local) et ne convoque un modèle que là où elle manque (la prose, les images). D'où les trois propriétés qui découlent l'une de l'autre : le déterminisme rend l'extraction gratuite, la gratuité rend la reconstruction fréquente possible, et la reconstruction fréquente rend le graphe fiable au lieu de périmé.

**Le second principe est la traçabilité.** Étiqueter chaque arête `EXTRACTED` ou `INFERRED` paraît mineur et change tout : on peut faire confiance différemment à deux relations selon leur origine, et un agent qui traverse le graphe sait quand il marche sur du solide. C'est la même discipline épistémique que les types de source dans une fiche de veille, ou que la distinction entre lecture et substitution dans [[skill-gibbs-hyperresearch-2026-08-03]].

**En résumé** : l'outil est utile, ses chiffres sont honnêtes, et son argument le plus fort est économique avant d'être qualitatif. Sa faiblesse tient à sa documentation — un dépôt dont la branche `main` décrit un produit périmé et dont le site officiel affiche 3 700 étoiles quand GitHub en compte 103 000 n'inspire pas confiance sur sa capacité à tenir sa propre cartographie à jour.

## Déclencheur

**Quand la skill s'active** : sur `/graphify <chemin>` dans un assistant de codage, après `uv tool install graphifyy && graphify install`. En dehors d'un assistant, la CLI `graphify extract` fait le même travail en mode headless, avec une clé d'API pour la partie sémantique.

**Entrées attendues** : un **répertoire quelconque** — dépôt de code, dossier de notes, corpus de PDF, mélange des trois. Aucune structure préalable n'est requise.

**Options qui changent le comportement** : `--code-only` (n'indexe que le code, donc aucun appel réseau), `--update` (ne retraite que les fichiers modifiés), `--watch` (reconstruction continue), `--wiki` (sortie navigable par un agent), `--mcp` (serveur MCP stdio), `--backend ollama` (tout en local, y compris la partie sémantique).

**Quand ne pas la déclencher** : sur un corpus de quelques fichiers qui tient déjà dans une fenêtre de contexte — le README le dit lui-même à propos de son exemple à 6 fichiers, *« graph value there is structural clarity, not compression »*. Et sur un corpus dont les documents sont confidentiels sans backend local configuré, puisque la passe sémantique les enverrait à un modèle distant.

## Fonctionnement

**Le pipeline se lit en quatre temps.**

1. **Extraction, par type de fichier.** Le code passe par tree-sitter : AST, graphe d'appels, docstrings, le tout déterministe et local. La prose, les PDF et les images passent par un modèle. La vidéo et l'audio sont transcrits localement par faster-whisper, puis traités comme de la prose. Les commentaires d'intention (`# WHY:`, `# HACK:`) sont extraits comme nœuds distincts.
2. **Résolution et fusion.** Les nœuds et arêtes sont fusionnés dans un graphe NetworkX. Les liens inter-fichiers (`calls`, `imports`, `inherits`, `mixes_in`) sont résolus à travers ~40 langages. Un paquet référencé depuis plusieurs manifestes devient **un seul nœud canonique**, donc un hub.
3. **Structuration.** L'algorithme **Leiden** découpe le graphe en communautés, **labellisées sans LLM**. Les nœuds de plus fort degré sont désignés *god nodes*. Les connexions inattendues sont classées par un score composite, une arête code-article pesant plus qu'une arête code-code.
4. **Restitution.** Trois artefacts, plus les exports optionnels. Chaque arête conserve son étiquette de provenance jusqu'à la sortie.

**La boucle de fraîcheur** est traitée à trois niveaux de coût croissant : le cache SHA256 évite tout retraitement inutile ; `--watch` reconstruit instantanément sur sauvegarde d'un fichier de code, **sans appel LLM** ; le hook post-commit reconstruit à chaque commit sans processus résident.

**L'interrogation** se fait ensuite contre `graph.json`, sans relire les fichiers sources : `query` pour une question ouverte, `path` pour une relation entre deux entités, `explain` pour un voisinage.

## Lecture commentée du SKILL.md

Le fichier commenté est le README de la branche `v8` (57 Ko), qui fait office de spécification publique de la skill, et le `skills/graphify/skill.md` qu'installe la commande `graphify install`.

**L'énoncé de mission, en une phrase, place le verbe au bon endroit** :

> *« Type `/graphify` in your AI coding assistant and it maps your entire project (code, docs, PDFs, images, videos) into a **knowledge graph** you can **query instead of grepping** through files. »*

*Glose* : la promesse n'est pas « comprendre votre code » mais **remplacer une opération précise** — le grep. Une skill qui se définit par le geste qu'elle supprime est plus facile à évaluer qu'une skill qui promet de la compréhension.

**Les trois puces qui suivent sont la spécification réelle** :

> *« **Code maps for free, fully local.** Code is parsed with tree-sitter AST: deterministic, no LLM, nothing leaves your machine. (Docs, PDFs, images and video use your assistant's model, or a configured API key, for a semantic pass.) »*

*Glose* : la parenthèse fait le travail honnête. Elle dit exactement où finit le local. Beaucoup d'outils annoncent « fully local » et laissent le lecteur découvrir l'exception.

> *« **Every edge is explained.** Each connection is tagged `EXTRACTED` (explicit in the source) or `INFERRED` (resolved by graphify), so you can tell what was read directly from what was inferred. »*

*Glose* : la définition des deux étiquettes est donnée **dans la même phrase** que leur nom. Un agent qui lit cette ligne sait comment pondérer une arête sans consulter d'autre documentation.

> *« **Not a vector index.** No embeddings, no vector store: a real graph you traverse. »*

*Glose* : positionnement par la négation, assumé. Le projet se situe dans un paysage où le RAG vectoriel est le défaut, et refuse d'y entrer.

**La sortie montrée avant d'être décrite** — choix de rédaction remarquable :

```text
$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField
```

*Glose* : trois sauts, le sens de chaque arête, son type. Le lecteur comprend en une ligne ce que « traverser un graphe » veut dire, sur un dépôt qu'il connaît. C'est plus efficace que n'importe quel paragraphe d'explication.

**La section qui trahit l'intention profonde** s'intitule *« Make your assistant always use the graph »*.

*Glose* : l'objectif n'est pas qu'un humain lance une commande, c'est que **l'agent consulte le graphe avant de lire les fichiers**. La skill vise à s'insérer dans la boucle par défaut de l'assistant, pas à rester un outil invoqué à la demande. C'est le même mouvement que la rule de routage vers les skills chez Hugo Lassiège : rendre le bon réflexe automatique.

**Choix de design à retenir** : l'**extraction hybride par type de fichier** (déterministe où la structure existe, sémantique ailleurs) est la décision qui produit toutes les autres propriétés ; le **cache SHA256** et le **hook post-commit** traitent la fraîcheur comme un problème d'ingénierie et non de discipline ; et la **sortie en wiki markdown** reconnaît qu'un agent lit mieux des fichiers qu'il ne parse du JSON.

## GrapheDeConnaissance

- Safi Shamsi —a_créé→ graphify (METHODOLOGIE, 0.97)
- Graphify Labs —publie→ graphify (METHODOLOGIE, 0.95)
- graphify —permet→ d'interroger un projet par traversée de graphe au lieu de grepper des fichiers (CITATION, 0.96)
- graphify —utilise→ tree-sitter (TECHNOLOGIE, 0.97)
- graphify —utilise→ NetworkX (TECHNOLOGIE, 0.93)
- graphify —utilise→ algorithme de Leiden (CONCEPT, 0.93)
- analyse AST locale —permet→ une extraction de code déterministe, sans appel de modèle et sans sortie de données (AFFIRMATION, 0.96)
- graphify —s_oppose_à→ l'index vectoriel, refusant embeddings et magasin de vecteurs (CITATION, 0.96)
- étiquetage EXTRACTED et INFERRED —permet→ de distinguer une relation lue dans la source d'une relation déduite (AFFIRMATION, 0.96)
- graphify —mesure→ un recall@10 de 0,497 sur LOCOMO contre 0,149 pour supermemory et 0,048 pour mem0 (MESURE, 0.93)
- graphify —mesure→ une exactitude QA de 45,3 % sur LOCOMO, inférieure aux 49,7 % de supermemory (MESURE, 0.93)
- graphify —mesure→ 76 % d'exactitude sur LongMemEval-S, à égalité avec un RAG dense (MESURE, 0.92)
- construction du graphe par AST —réduit→ le coût de construction à zéro crédit de modèle (MESURE, 0.95)
- graphe de code structuré —surpasse→ la récupération vectorielle pour la compréhension de code (AFFIRMATION, 0.85)
- graphify —s_applique_à→ code, documents, PDF, images, vidéo, configurations MCP et manifestes de paquets (AFFIRMATION, 0.94)
- commentaires d'intention —fait_partie_de→ le graphe, comme nœuds distincts reliés au code qu'ils expliquent (AFFIRMATION, 0.92)
- cache par empreinte et hook post-commit —résout→ la péremption du graphe face à un code qui change (AFFIRMATION, 0.92)
- sortie en wiki markdown —permet→ à un agent de naviguer la base de connaissance en lisant des fichiers plutôt qu'en analysant du JSON (CITATION, 0.92)
- graphify —utilise→ faster-whisper pour transcrire vidéo et audio localement (TECHNOLOGIE, 0.9)
- journal de requêtes local —s_oppose_à→ l'absence totale de trace, étant actif par défaut et désactivable par variable d'environnement (AFFIRMATION, 0.9)
- détection automatique de backend —s_oppose_à→ une contrainte de résidence des données, pouvant router vers des serveurs situés en Chine (AFFIRMATION, 0.88)
- graphify —converge_avec→ GitNexus (TECHNOLOGIE, 0.85)
- Graphify Labs —publie→ une plateforme commerciale appliquant la même approche en continu à tout le contexte de travail (AFFIRMATION, 0.9)
- branche main du dépôt —s_oppose_à→ la branche v8, en décrivant un produit de génération antérieure (AFFIRMATION, 0.92)

---
Canonical: https://www.thekb.eu/it/fiches/skill-shamsi-graphify-2026-08-06/