Graphify Usage

Query the knowledge graph effectively, interpret results accurately, and stay within token budgets.

Overview

The graphify MCP server exposes the codebase as a pre-built knowledge graph stored in graphify-out/graph.json. The graph encodes structural relationships between concepts, modules, and files extracted by the graphify pipeline. This skill governs when, how, and with what discipline agents should query it.

Owner: Riko (Explorer Agent) — Riko is the primary graph query agent and owns interpretation of results. Consumers: Senku (Planner Agent), Lawliet (Reviewer Agent) — both may consult the graph during planning and review, but Riko is the preferred query agent for deep exploration. Out of scope: Loid (Executor) and Alphonse (Verifier) do NOT have graph access by design. Loid performs file writes and needs test output, not structural queries; Alphonse runs verification commands that cannot rely on graph freshness. This enforces the one-writer invariant: only agents that need structural context hold graph tool permissions.

All 7 tools are accessed via the MCP prefix mcp__plugin_agent-flow_graphify__*. See references/tool-reference.md for full signatures.

When to Query the Graph vs. Grep

Use the graph when you need structural relationships. Use grep when you need literal text matches.

Rule of thumb: If the answer requires traversal (who calls what, what clusters together, how far apart are two concepts), use the graph. If the answer is a literal substring or you need up-to-the-edit accuracy, use Grep or Read.

Tool Decision Table

Choose the right tool for the question type. See references/query-patterns.md for detailed decision sequences.

Token Hygiene

Hard rules for staying within context budget:

1. Always set top_k / top_n when available. Default god_nodes returns 10 nodes — only request more if explicitly needed.
2. Set token_budget on query_graph calls. The default is 2000 tokens; lower it (e.g., 500) for quick orientation queries.
3. Set depth conservatively. Default depth is 3; start at 1-2 for narrow questions, increase only if the result is insufficient.
4. Do NOT paste raw subgraph JSON downstream into task prompts or summaries. Extract only node IDs, labels, and source_location fields.
5. Summarize before handing off. Convert graph results to bullet lists of label → source_location pairs. Downstream agents (Senku, Lawliet) need names and file paths, not raw graph output.
6. Chain calls, don't parallelize blindly. Run graph_stats first, then decide if god_nodes is needed. Avoid firing all 7 tools simultaneously.

Result Interpretation

How to read and trust what the graph returns:

Cite source_location fields

Every node in the graph carries a source_location field (file path, sometimes line range). When reporting a finding, always cite this field:

Node: AgentOrchestrator
source_location: commands/orchestrate.md:1

Never report a concept without its source_location — downstream agents cannot verify unsourced claims.

Surface confidence tags

The graph annotates edges with confidence labels:

When an edge is INFERRED or AMBIGUOUS, note this explicitly in your summary. Do not present inferred relationships as certainties.

Trust-but-verify for freshly edited files

The graph is built once (at /graphify time) and is not updated during a session. If Loid has modified a file in the current session, graph data for that node is stale. For any file touched in this session:

• Use the graph for structural orientation only
• Use Read or Grep for current content

What NOT to Do

• Do not query the graph on freshly edited files expecting current content — it will be stale.
• Do not set depth > 4 without a specific reason — the output will overflow context.
• Do not pass raw graph JSON blobs in task descriptions or summaries to other agents.
• Do not fire query_graph for questions answerable by get_node or get_neighbors — cheaper specific tools first.
• Do not report INFERRED edges as facts — always surface the confidence tag.
• Do not skip source_location citations — every claimed relationship needs a file anchor.
• Do not use graph results as a substitute for reading changed files — the graph captures structure, not current content.

Cross-References

• docs/guides/using-graphify.md — installation, build steps, and how to run the graphify pipeline
• references/tool-reference.md — full MCP tool signatures, parameters, cost profiles
• references/query-patterns.md — decision table mapping question types to tool sequences
• examples/worked-queries.md — end-to-end query scenarios with expected result shapes