| name | graph-aware-navigation |
| version | 1.0 |
| description | Navigate the codebase via FlowAI's compiled knowledge graph instead of searching raw files. Mandatory context for all pipeline agents.
|
Graph-Aware Navigation
Overview
This project maintains a compiled knowledge graph of its codebase under
.flowai/wiki/. The graph engine always runs a structural pass (imports,
links, spec traceability, function nodes). An optional semantic pass (LLM-driven
concepts and inferred edges) runs only when graph.semantic_enabled is true in
.flowai/config.json — it adds cost and latency, so keep it off unless you need it.
Always navigate via the graph first. Raw file reads are for drilling into
specific locations the graph has already pointed you to.
Navigation Protocol
1. Start at GRAPH_REPORT.md
Before any task, read .flowai/wiki/GRAPH_REPORT.md. It contains:
- God nodes — the highest-degree hubs in the codebase (the files everything depends on)
- Community summaries — clusters of closely-related modules
- Suggested queries — pre-generated questions about the architecture
- Contradiction flags — relationships the system marked as ambiguous
This is your architectural map. Reading it before touching any file is mandatory.
2. Use index.md as a Catalog
.flowai/wiki/index.md lists every wiki page with a one-line summary and its
source count. Before asking "where is X implemented?", scan the index for a page
about X. If a page exists, read it. If it doesn't, check GRAPH_REPORT.md for
which god node or community is most likely to contain it.
3. Use graph.json for Multi-Hop Reasoning
For questions like "what does module A depend on transitively?" or "which files
import the Config struct?", query graph.json directly. Edges have three
provenance tags:
- EXTRACTED — relationship is directly present in source (imports, function calls). High confidence.
- INFERRED — relationship was inferred from context by the semantic pass. Treat as a strong hypothesis.
- AMBIGUOUS — relationship was flagged for review. Do not assume it is correct.
4. Read Raw Files Surgically
After the graph directs you to a specific location (a god node, a community,
a wiki page that cites a file and line range), then read that file. Do not
start by reading files — the graph is your GPS.
5. Contribute Back to the Graph
If you discover a relationship, pattern, or architectural decision that is not
represented in the wiki, include it clearly in your response. The human can
run flowai graph update to integrate it. This is how the knowledge base
compounds over time.
Token Efficiency
Reading the graph is dramatically more efficient than grepping raw files:
- GRAPH_REPORT.md gives you an architectural overview in ~2K tokens
- A typical wiki page gives you targeted knowledge in ~500 tokens
- graph.json lets you answer dependency questions without reading any source
Prefer this order:
GRAPH_REPORT.md → index.md → wiki/<topic>.md → graph.json → source files
Announcements
When starting work that involves navigating the codebase, announce:
"Reading .flowai/wiki/GRAPH_REPORT.md to orient via the knowledge graph."
This keeps the human informed and confirms you are following the graph-first protocol.
