Graphify: Overview & Mental Model

Graphify turns any folder — code, documents, and media — into a single queryable knowledge graph that your AI assistant reads instead of blindly re-reading raw files. This page is the mental model you need before deciding whether to adopt it; the how-to lives in the rest of this set.

The one-line concept

"Graphify transforms project folders into queryable knowledge graphs ... it maps your entire codebase — code, documentation, PDFs, images, and videos — into a structured representation you can search and explore." [github]

The pitch is a knowledge-graph-of-everything: source code, docs, PDFs, images, and transcribed audio/video all land in one graph you can query, rather than living in separate silos that your assistant has to grep through one at a time. The creator (Safi Shamsi) frames it as a "digital brain" / "digital twin" of a codebase or enterprise that you can recall at any time [interview].

See 02-installation-setup.md to get it running and 08-workflows-and-use-cases.md for concrete scenarios.

Why a graph beats plain file search

Plain AI coding assistants work on flat files:

"AI coding assistants operate on flat-file context. They read files, sometimes many at once, but they have no map of how concepts relate across your codebase." [community](augmentcode)

A graph pre-computes the relationships — which function calls which, which doc explains which module, which concepts recur across files. The verified payoff over grep/file-search is cross-file structure:

"Unlike grep or file search, Graphify understands relationships across your codebase ... links between things that live in different files or modules. Ranked by how unexpected they are." [github]

So instead of "find the file named auth," you can ask "what connects auth to the database?" and get a path through the graph. Query mechanics are covered in 06-querying-and-god-nodes.md.

Why a graph beats Obsidian

People reasonably ask: isn't this just an Obsidian vault graph? The creator's argument is that Obsidian only visualizes links, while Graphify does real graph analysis on top [interview]:

Obsidian "can't do clustering for you" — it won't group related notes into communities. [interview]
Obsidian "can't do cross-community interaction" — it won't surface links between clusters. [interview]
Obsidian's graph "looks pretty much well but there is nothing credible you can take from there." [interview]

Treat those three claims as the creator's framing (unconfirmed), not measured fact. The verified version of the same point is milder: Graphify computes ranked "surprising connections" across files/modules [github], which a visualization-only tool doesn't do. In practice Obsidian remains a fine visual pairing — the interview itself calls it "a decent recommended pairing because it's visual" [interview].

God nodes

God nodes are the most important hubs in your graph:

"the most-connected concepts in your project. Everything flows through these." [github]

Mental model: god nodes are the load-bearing entities — the architecture's spine. The recommended habit is to ask for god nodes first, get the high-level map in one shot, then "scalpel" down into specific nodes only where needed (this is the core token-saving move) [interview]. The creator also offers a rough diagnostic: an unexpectedly large number of god nodes can signal poor cohesion in a codebase [interview] (unverified heuristic). Details and example queries: 06-querying-and-god-nodes.md.

Community / cluster detection

Graphify runs clustering to group related entities into communities, with adjustable granularity:

"The tool runs clustering to group related entities. You can rerun clustering on existing graph and adjust granularity with resolution parameters." [github]

This is what powers the two things Obsidian reportedly can't do: grouping nodes into communities, and detecting cross-community links (relationships that bridge otherwise-separate clusters). Conceptually this is standard graph theory (community detection via clustering algorithms) [interview]. The relevant flags (e.g. cluster-only runs and a resolution setting) are documented in 06-querying-and-god-nodes.md — don't guess at them from here.

Confidence tags: EXTRACTED / INFERRED / AMBIGUOUS

Every relationship in the graph carries a confidence label, so you know how much to trust it:

EXTRACTED — "directly found in source" [github]
INFERRED — "logically deduced" [github]
AMBIGUOUS — "uncertain connections" [github]

Corroborated by community write-ups: "Every relationship gets tagged as EXTRACTED, INFERRED, or AMBIGUOUS, so developers know which connections came from code versus model inference." [community](augmentcode)

The mental-model takeaway: EXTRACTED edges come from deterministic parsing (the AST — see 03-ingesting-code-ast.md); INFERRED/AMBIGUOUS edges come from a language model reading prose. Weight them accordingly when you act on a query result.

The "neuro-symbolic" framing

The creator positions Graphify as more than a RAG store — as a step toward neuro-symbolic AI, where the graph acts as a layer of symbols that ground the neural network:

Graphify "isn't just supporting neural networks, it's giving rise to neuro-symbolic AI systems where you have a map or symbols to support the neural networks to come up with a response." [interview]

The stated motivation: neural networks (LLMs) hallucinate and lose context, especially as you cram more into the context window; a symbolic graph constrains and grounds retrieval, reducing that drift [interview]. Neuro-symbolic AI is a genuine research area, but the specific claim that Graphify meaningfully reduces hallucination is the creator's pitch — not independently verified here. Treat it as a useful intuition, not a measured result.

The three outputs

Every run produces three artifacts [github]:

File	What it is
`graph.html`	Interactive visualization — "open in any browser — click nodes, filter, search" `[github]`
`GRAPH_REPORT.md`	Markdown report — "the highlights: key concepts, surprising connections, suggested questions" `[github]`
`graph.json`	The full graph — "query it anytime without re-reading your files" `[github]`

The graph.json is the durable, reusable asset: it's what lets later queries stay cheap. That cost story (and the incremental-update mechanism) is in 07-token-economics-and-updates.md. Local-vs-cloud extraction backends are in 05-local-models-and-backends.md.

How the pieces fit (decision summary)

Code is parsed locally via tree-sitter ASTs — no API calls, no tokens spent [github] [interview]. See 03-ingesting-code-ast.md.
Docs / media need a language model to extract meaning, so they cost tokens (or run on a local model) [interview]. See 04-ingesting-docs-knowledge.md and 05-local-models-and-backends.md.
The graph is the memory/context; the discipline is "ask the graph, don't make the LLM re-read the corpus" [interview].
Start from god nodes, then drill down — that's where the savings come from [interview].

For an end-to-end adoption checklist, jump to 09-best-practices-checklist.md. Index: 00-README.md.

Open questions / unverified

Headline numbers are marketing. Token savings of "70x"/"90x", "500K downloads," "43K stars" are sales claims and they conflict across sources (e.g. one community post cites 58.3K stars). [unverified claim] Do not treat any of these as fact.
Neuro-symbolic = less hallucination for Graphify specifically is the creator's framing [interview], not independently measured.
The Obsidian critique (can't cluster, no cross-community links, "nothing credible") is [interview] only; the verified contrast is the narrower "ranked cross-file connections" claim [github].
"Large god-node count signals poor cohesion" is an unverified diagnostic heuristic from the interview.
graphifylabs.ai could not be fetched (HTTP 403 bot protection), so its exact tagline/claims are not directly verified here.

9.0 KiB Raw Blame History