| name | knowledge-graph |
| description | Build + keep-fresh + query a deterministic code knowledge graph to cut agent orientation-token cost. Triggers: knowledge graph, graphify, code graph, god nodes, orientation cost, token bill, map the codebase, what connects X to Y, callers of, blast radius. |
| allowed-tools | Read, Bash, Grep, Glob |
| kernel | {"kind":"methodology","version":1,"side_effects":"filesystem","confirmation":"none"} |
An agent's token bill splits into ORIENTATION (finding where the answer lives — reading
files, following imports, grepping) and REASONING (actually solving). On a large, tangled
repo the orientation half dominates, and it is pure overhead: the model is not thinking yet,
it is still navigating. A pre-built code knowledge graph replaces that file-crawl with one
query, so you pay orientation tokens once (at build) instead of every session.
The saving is CONDITIONAL on repo size × tangle, not a fixed multiplier. Measured on real
repos: ~5.7x fewer tokens/query on a mid-size service, ~73x on a large interconnected one,
~13% on a tiny library. The graph query cost is ~constant; naive full-corpus cost scales with
size — so reduction = corpus ÷ constant. Do the arithmetic on YOUR repo, don't quote a headline.
Hard boundary: the graph helps NAVIGATION, not REASONING. "Design a cache", "why is this slow"
get zero lift. It gathers context efficiently; it does not think for the model.
Uses `graphify` (open-source, tree-sitter + NetworkX, MIT). Code extraction is local +
deterministic + free (no API key). Install once: `uv tool install graphifyy` (or `pipx`/`pip`).
If graphify is absent, this skill degrades to a no-op — never a hard failure.
Code-layer graph (free, offline, seconds):
```bash
graphify extract --code-only # local AST only; skips docs; no LLM, no cost
```
Outputs `graphify-out/graph.json` (+ report; +interactive graph.html under ~5000 nodes).
NEVER commit `graphify-out/` — it is DERIVED. Gitignore it and rebuild on demand
(the sqlite-mirror discipline: commit the source, rebuild the artifact).
```bash
graphify query "what connects auth to the database?" # BFS over the graph, token-budgeted
graphify path "UserService" "DatabasePool" # shortest path between two symbols
graphify god-nodes --top 12 # architectural hubs (most-connected)
graphify affected "RateLimiter" # reverse traversal = change blast radius
graphify benchmark # measure YOUR token reduction, per question
```
`god-nodes` doubles as a comprehension + pruning lens: hubs are the real spine; low-degree,
never-linked nodes are dead-code / consolidation candidates. Also available as an MCP server
(`query_graph`, `shortest_path`, `get_neighbors`) for repeated structured access.
The graph pays off only if it is CONSULTED. A skill telling the agent to reach for it is opt-in
and unreliable, so the orientation layer is AMBIENT: when the working repo has a graph, the
session-start hook injects its architectural spine (top god-nodes + the query commands) directly
into context — the agent boots already oriented, no tool call, no human ask. Deep on-demand
queries ("what calls this exact function") still go through `graphify query`/`path`/`affected`
or the MCP tools; those are available + steered, but the baseline map arrives for free.
A stale graph is worse than none. Keep it fresh, cheaply:
- **Code layer (free):** `graphify extract --code-only` is incremental via its AST cache
("N cached/unchanged, 0 re-extracted"). Wire it into `post-commit` so the graph is never more
than one commit stale, at ~zero cost. Opt-in installer: `hooks/scripts/knowledge-graph.sh install`
(gated on `KERNEL_GRAPH_ON=1`, mirroring autopush — never stamps hooks by surprise).
- **NEVER `graphify update`** for the code graph: it re-scans ALL files and adds docs as bare
nodes (measured 1506 → 13156 on one tree). Always `extract --code-only`.
- **Doc/semantic layer** (summaries, tags, prose edges) needs a model and is OPTIONAL polish.
Run it incrementally (changed files only), never full-corpus, never on every commit. Local
models are "good enough for orientation, not a top-tier artefact"; a frontier model is sharper.
- Free + deterministic is the CODE layer only. The doc/paper/image "why" layer sends semantic
descriptions (never raw source) to a configured backend — that costs a model.
- Small or reasoning-heavy repos: the graph is a solved problem you did not have. Skip it.
- The graph is a comprehension artefact that also saves tokens — value it as a map first.
