Graphify - Knowledge Graphs for Monorepo Navigation
Query the graph before you grep
Agents and humans burn sessions grep-reading through monorepos and still miss cross-file seams. Wrong-file edits are expensive; onboarding without a map takes weeks. Brute-force exploration is the default because dependencies are implicit - until you index structure.
Here's what this piece covers: the leadership problem of search exhaustion, what commit 261c071 (2026-07-14) shipped as a portable kit, how I use query / path / explain, the named pattern, and three habits before you scale agent exploration across repos.
Part of the Field Notes: agentic delivery series - structural navigation before token burn.
1. The leadership problem
The anti-pattern is search exhaustion - read every file because the graph of the system only exists in someone's head.
Wrong: "Use AI to search the repo."
Right: "261c071: graphify query / path / explain - AST knowledge graph first; grep only when the graph is insufficient."
Agent sessions that skip structure pay twice: token cost and wrong edits. Leads pay a third time in review.
2. What the git history shows
On 2026-07-14, commit 261c071 - Add Graphify setup documentation and portable install kit - made adoption copyable:
| Artifact | Role |
|---|---|
docs/graphify/ |
README, guide, new-computer setup, agent prompt |
tooling/graphify-setup-kit/ |
install.sh / .ps1, rules, .graphifyignore |
| Cursor rule | Query graph before Read/Grep/Glob |
Later adoption spread into github-analysis, Planning, and consumer monorepos. Combined footprint across four indexed monorepos: ~42,400 nodes / 6,350 files (derived sum of local GRAPH_REPORT snapshots - light verify today: websites 12,652 + global-services 24,417 + global-user-services 3,549 + Planning ~2,088 ≈ **42.7k**). Exploration cost reduction of 50×+ vs brute-force file reads is team-estimated - confirm methodology before treating it as a measured KPI.
Daily habit encoded as a rule, not a suggestion:
# AST-only refresh - no LLM, no API cost
graphify update .
# Structural questions first
graphify query "How does HTML export reach the data cache?"
graphify path "export_html_report" "load_snapshot"
graphify explain "spec-driven"3. What I built
Portable setup kit - install Graphify on a new machine or consumer repo without inventing process. Artifacts stay local and gitignored; only pointers and tooling live in Git.
Query surface - graphify update . builds/refreshes the AST graph; query returns a scoped subgraph (including INFERRED cross-file edges); path connects two symbols; explain shows a node and neighbors. Optional graphify-out/wiki/ and GRAPH_REPORT.md for orientation.
Adoption pattern - Cursor beforeSubmitPrompt hook refreshes the graph; .graphifyignore excludes data/cache dumps; skills (graphify, graphify-search) keep agents honest about search order.
What broke: a stale graph is worse than none - it points at deleted symbols. Rebuild after refactors (graphify update ., --force when the graph legitimately shrinks). Kit doc duplication later forced token compression (Index Protocol - later in the series).
4. Named pattern: query graph before grep
Query graph before grep - AST knowledge graph for navigation;query/path/explainbefore search exhaustion.
| Command | When | Decision it supports |
|---|---|---|
graphify update . |
After edits / pull | Is the map current? |
graphify query |
Any architecture question | Which subgraph matters? |
graphify path A B |
Seam / dependency risk | How does A reach B? |
graphify explain X |
Onboarding / naming | What surrounds this concept? |
What broke: treating Graphify as evangelism. The mechanism is cheaper context for the same question you were going to ask with grep - measure time-to-first-correct-file, not tool enthusiasm.
5. What I'd do as a lead
Three habits - steal one this month:
- Index one monorepo per quarter - start with highest-churn. Portable kit first; custom process never.
- Require
graphify queryin agent exploration rules (AGENTS.md/ Cursor rules). Make grep the fallback, not the default. - Measure time-to-first-correct-file on agent tasks. If the graph does not move that number, fix adoption or freshness - do not celebrate node counts alone.
Further reading
- Field notes: agentic delivery - series intro
- Previous: Invisible Unicode - markdown as an attack surface
- agentic-framework anchor: commit
261c071· 2026-07-14 ·docs/graphify/README.md
