14 KiB

Raw Blame History

summary

Querying the Graph & God Nodes

Querying is the highest-leverage skill in Graphify: a good query makes the graph do the reading for you so your assistant spends tokens on an answer, not on re-grepping the corpus. This page is the retrieval playbook — start at god nodes, scalpel down, and trust the graph as your memory.

Prerequisite: you've built a graph (graphify-out/graph.json, GRAPH_REPORT.md, graph.html). See 03-ingesting-code-ast.md and 04-ingesting-docs-knowledge.md. The cost story behind "ask the graph, not the corpus" lives in 07-token-economics-and-updates.md.

The core principle: prompt the graph, don't make the LLM read the corpus

The single most important habit, in the creator's words:

"When you are prompting the graph, don't ask the LLM to go through the graph — rather ask the LLM to extract from the graph. So the graph is the memory, the graph is the context." [interview]

The graph is the context/memory. You want the assistant to extract from it (pull the specific nodes/edges that answer the question), not traverse the whole thing (which just re-spends the tokens you built the graph to save) [interview].

This is backed by how the tool installs itself. The persistent install config tells your assistant to:

"consult the knowledge graph for codebase questions — preferring scoped queries like graphify query "<question>" over reading the full report or grepping raw files." [github]

On Claude Code and Gemini CLI a hook even fires before search-style tool calls (and before reading source files one-by-one) to nudge the assistant onto the graph path [github]. So the discipline is partly automated — but you still drive it with good queries.

Step 1 — Always ask for the god nodes first

God nodes are the most-connected concepts — the load-bearing spine of the project.

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

The retrieval playbook starts here every time:

"First of all you prompt to give you the god nodes from the whole corpus first of all ... from god nodes you can easily see where you have to prompt and write to minimize as much tokens as possible." [interview]

Get the high-level architecture in one shot, then "scalpel" down into the specific nodes you actually need [interview]. That ordering — map first, drill second — is where the token savings come from.

How to actually surface god nodes (important)

There is no dedicated graphify god-nodes command or --god-nodes flag. God nodes are surfaced in two honest ways:

Read the top of GRAPH_REPORT.md. God nodes are the first thing in the report [github]:

"What's in the report: God nodes — the most-connected concepts ... Everything flows through these." [github]
Ask your assistant for the high-level architecture; with the graph installed it reads the graph rather than the files [github].

Do not expect graphify query "what are the god nodes?" to return the structural ranking — query is semantic search over content, while the god-node ranking is a structural (degree-based) result that lives in the report [github]. You can ask a semantic question to get oriented, but the authoritative hub list is the report.

To tune that ranking, see --exclude-hubs under clusters below.

Step 2 — Scalpel down: query / path / explain

Three verified commands cover the drill-down. (Inside an IDE skill they take a / prefix, e.g. /graphify query; from a plain terminal drop the slash, e.g. graphify query. Same command, two entry points [github]. On Windows PowerShell, always use the no-slash form [github].)

Command	What it does	Use it to
`graphify query "<question>"`	Semantic search over the graph `[github]`	Find the nodes relevant to a question
`graphify path "Node1" "Node2"`	Find connections between two nodes `[github]`	Trace how two things relate
`graphify explain "Node"`	Single-node deep-dive `[github]`	Scalpel into one specific node

# semantic search — "extract from the graph"
graphify query "what connects auth to the database?"          # [github]
graphify query "show the auth flow"                           # [github]

# point at a specific graph file if not in the default location
graphify query "what connects DigestAuth to Response?" --graph graphify-out/graph.json   # [github]

# bound the search to keep the answer (and tokens) tight
graphify query "..." --dfs --budget 1500                      # [github]

# connection between two named nodes
graphify path "UserService" "DatabasePool"                    # [github]
graphify path "DigestAuth" "Response"                         # [github]

# deep-dive a single node — the literal "scalpel"
graphify explain "RateLimiter"                                # [github]

The --dfs --budget flags are the direct, runnable expression of "minimize tokens": you cap the traversal/budget so the assistant extracts a bounded slice instead of wandering the whole graph [github].

Architecture / call-flow diagram

For a visual map of how the system fits together:

graphify export callflow-html                       # Mermaid architecture/call-flow HTML  [github]
graphify export callflow-html --max-sections 8      # cap the number of generated sections  [github]
graphify export callflow-html --output docs/arch.html
graphify export callflow-html ./some-repo/graphify-out

If you installed the git hook, this auto-regenerates on every commit [github]. This pairs well with the god-node read: the report tells you which nodes matter, the call-flow HTML shows you how they connect.

Step 3 — Read the confidence tags

Every inferred relationship is labeled so you know how much to trust it:

"Confidence tags — every inferred relationship is marked EXTRACTED, INFERRED, or AMBIGUOUS. You always know what was found vs guessed." [github]

Tag	Meaning `[github]` (overview doc)	How much to trust
`EXTRACTED`	"directly found in source"	High — deterministic; for code this is the AST `[github]`
`INFERRED`	"logically deduced"	Medium — a model reasoned it out
`AMBIGUOUS`	"uncertain connections"	Low — verify before acting

Rule of thumb: code edges are EXTRACTED from the tree-sitter AST with no model involved [github], so they're solid; INFERRED/AMBIGUOUS edges came from a language model reading prose [github] — weight them down and confirm before you act. (Confidence-tag concept also covered in 01-overview-concepts.md.)

Step 4 — Community / cluster detection

Graphify groups related entities into communities, and you can rerun clustering at adjustable granularity without re-extracting (so it's free — no API calls):

graphify cluster-only ./my-project                          # rerun clustering on existing graph  [github]
graphify cluster-only ./my-project --resolution 1.5         # more, smaller communities  [github]
graphify cluster-only ./my-project --exclude-hubs 99        # exclude p99-degree nodes from partitioning  [github]

The same controls exist as flags on a build run:

/graphify . --cluster-only                                  # rerun clustering, no re-extract  [github]
/graphify . --cluster-only --resolution 1.5                 # more granular communities  [github]
/graphify . --cluster-only --exclude-hubs 99                # suppress utility super-hubs from god-node rankings  [github]

--resolution raises granularity: a higher value (e.g. 1.5) yields more, smaller communities; lower values yield fewer, larger ones [github]. Sweep it to find the topic-cluster scale that matches how you think about the project.
--exclude-hubs 99 drops the very highest-degree utility nodes (e.g. a logger imported everywhere) from the partitioning / god-node ranking so they don't swamp the real structure [github].

Cross-community links — relationships that bridge otherwise-separate clusters — are the thing the creator says plain visualizers (e.g. Obsidian) can't surface [interview]. There is no dedicated flag for them; they appear in the report as "surprising connections":

"Surprising connections — links between things that live in different files or modules. Ranked by how unexpected they are." [github]

So: clusters come from cluster-only/--resolution; the bridges between them are the ranked "surprising connections" in GRAPH_REPORT.md.

Step 5 — The god-node diagnostic heuristic

A rough health signal from the creator:

"If you have large amount of god nodes that means that something has gone wrong with the cohesion or maybe with your codebase ... if you have a decent number of god nodes ... things have worked fine." [interview]

Treat this as an [interview] heuristic, not a measured threshold — there's no defined "too many." [unverified claim] But it's testable: run --exclude-hubs 99 to strip out the utility super-hubs and see whether a sane architecture remains underneath [github]. If a huge, sprawling god-node set survives even after excluding the obvious utility hubs, that's a soft signal of poor cohesion worth a closer look. (--exclude-hubs adjusts the ranking; it does not fix cohesion.)

Putting it together: inspecting a fresh graph

A concrete sequence for a graph you've never seen (e.g. a new hire on an unfamiliar codebase — the interview's headline scenario [interview]):

# 1. Build the graph (AST for code = free, no API calls)            [github][interview]
/graphify .

# 2. Read the high-level map FIRST: god nodes + surprising
#    connections are at the top of the report                        [github][interview]
#    -> open graphify-out/GRAPH_REPORT.md

# 3. See how the spine connects, visually
graphify export callflow-html                                       # [github]

# 4. Sanity-check cohesion: strip utility super-hubs, re-look
graphify cluster-only . --exclude-hubs 99                           # [github]
#    too many god nodes left? possible cohesion problem  [interview / unverified]

# 5. Scalpel into specifics — extract from the graph, bounded
graphify query "what connects auth to the database?" --dfs --budget 1500   # [github]
graphify path "UserService" "DatabasePool"                          # [github]
graphify explain "RateLimiter"                                      # [github]

# 6. Tune cluster granularity if topics feel too coarse/fine
graphify cluster-only . --resolution 1.5                            # [github]

Throughout: read the confidence tag on any edge before you act on it — EXTRACTED is trustworthy, INFERRED/AMBIGUOUS needs a second look [github].

Example queries to copy

graphify query "what connects attention to the optimizer?"          # [github]
graphify query "show the auth flow"                                 # [github]
graphify path "DigestAuth" "Response"                               # [github]
graphify explain "SwinTransformer"                                  # [github]

Repeated / programmatic access (MCP)

For an assistant that hits the graph many times in a session, expose it as an MCP server instead of one-off CLI calls:

python -m graphify.serve graphify-out/graph.json                    # [github]

This gives structured tools: query_graph, get_node, get_neighbors, shortest_path, list_prs, get_pr_impact, triage_prs [github]. Note get_neighbors / shortest_path are the programmatic equivalents of explain / path. (PR-impact tooling — graphify prs — is covered in 08-workflows-and-use-cases.md.)

Quick reference

Goal	Do this
See the architecture spine	Read god nodes at top of `GRAPH_REPORT.md` `[github]`
Visual call-flow	`graphify export callflow-html` `[github]`
Find relevant nodes (semantic)	`graphify query "..."` (add `--dfs --budget N`) `[github]`
Connect two named nodes	`graphify path "A" "B"` `[github]`
Deep-dive one node	`graphify explain "Node"` `[github]`
Re-cluster (free)	`graphify cluster-only . --resolution 1.5` `[github]`
De-noise god-node ranking	`--exclude-hubs 99` `[github]`
Bridges between clusters	"surprising connections" in the report `[github]`
Judge trust of an edge	Read its `EXTRACTED` / `INFERRED` / `AMBIGUOUS` tag `[github]`

Index: 00-README.md · Next: 07-token-economics-and-updates.md · Workflows: 08-workflows-and-use-cases.md

Open questions / unverified

No god-nodes command exists. God nodes are surfaced via GRAPH_REPORT.md and the assistant, not a dedicated CLI verb. graphify query is semantic search, not the structural hub ranking — don't conflate them. [github]
"Too many god nodes = poor cohesion" is an [interview] heuristic with no defined threshold. [unverified claim] --exclude-hubs lets you test it but does not fix cohesion.
Cross-community links have no flag. They map to the report's ranked "surprising connections" [github]; the interview's framing that Obsidian "can't do cross-community interaction" [interview] is the creator's claim, not independently verified.
--resolution direction (higher = more, smaller communities) is from the README's inline comments [github]; exact algorithm/parameter semantics aren't documented in the README.
--dfs --budget appears in the README command reference [github] but the exact budget units (tokens? nodes? hops?) and the --budget default are not spelled out there. [unverified claim]
graphifylabs.ai returns HTTP 403 to plain fetch, so any query syntax documented only on the official site is not directly verified here.
Token-savings figures ("70x"/"90x"/"20x") are sales claims handled in 07-token-economics-and-updates.md, not retrieval facts. [unverified claim]

14 KiB Raw Blame History