119 lines
8.7 KiB
Markdown
119 lines
8.7 KiB
Markdown
# 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](02-installation-setup.md) to get it running and [08-workflows-and-use-cases.md](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](https://www.augmentcode.com/learn/graphify-knowledge-graphs-ai-coding))
|
|
|
|
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](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](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](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](https://www.augmentcode.com/learn/graphify-knowledge-graphs-ai-coding))
|
|
|
|
The mental-model takeaway: `EXTRACTED` edges come from deterministic parsing (the AST — see [03-ingesting-code-ast.md](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](07-token-economics-and-updates.md). Local-vs-cloud extraction backends are in [05-local-models-and-backends.md](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](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](04-ingesting-docs-knowledge.md) and [05-local-models-and-backends.md](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](09-best-practices-checklist.md). Index: [00-README.md](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.
|