Knowledge Graph

Graphify builds a structural index of your project's codebase using AST analysis. Agents use it as a fast pre-search before broad file scans, surfacing the 2–4 most relevant files for any question and saving significant context-window cost on large repos.

How it works

Graphify parses your source files with tree-sitter (no LLM, no API key required) and builds a graph of files, symbols, and cross-file edges stored at .agenties/graphify/<slug>/graph.json. Agents check the graph status at session start and query it before spawning a scout or running a wide codebase scan.

Step	What happens
1 — Status check	Agent calls `graph_status`. If `installed: false` or the graph is absent, the graph is skipped and normal scouting proceeds.
2 — Query	Agent calls `graph_query` with a natural-language question. Returns a list of relevant file paths from the structural index.
3 — Read	Agent reads the 2–4 top files directly. No scout spawn needed.
4 — Fallback	If results are empty, off-topic, or the graph is very stale, normal scouting proceeds.

Tip:The Knowledge Graph is a heuristic, not a guarantee. For deeply cross-cutting questions, agents still fall back to manual scouting. Skip the graph entirely when the target file path is already known.

AST analysis vs semantic embeddings

By default, Graphify uses AST-only (structural) analysis — it parses source files with tree-sitter to extract symbols, imports, and call edges. No LLM, no embeddings, no API key required. This is fast, deterministic, and works fully offline.

An optional clustering step (--cluster) groups related nodes using the Leiden algorithm for community detection, which can improve query relevance on very large codebases. This step is disabled by default in Agenties (the graph_update tool uses --no-cluster) to keep builds fast and cost-free.

Mode	API key?	Build time	When to use
AST / structural (default)	No	Fast	Most projects — all languages, no cost
With clustering (--cluster)	No	Slower	Very large repos where query precision matters

MCP tools

Tool	Parameters	Description
`graph_status`	projectCwd?	Check whether Graphify is installed, the graph path, node/edge counts, and when it was last built. Returns installed, graphPath, nodeCount, edgeCount, lastUpdated.
`graph_query`	question, projectCwd?	Query the graph with a natural-language question. Returns file paths relevant to the question. Requires an existing graph.json — run graph_update first if the graph is missing.
`graph_update`	projectCwd?	Rebuild the knowledge graph index from source files. Run after significant codebase changes. Returns nodeCount, edgeCount, and durationMs.

Installation

Graphify requires Python 3.10 or higher. Agenties manages a project-local virtual environment automatically — you do not need to configure a system Python or install packages globally.

bash

# Install the graphify package into the project-local venv
# Agenties creates the venv at .agenties/tools/graphify-venv/ automatically
pip install graphifyy

Note:The package is published as graphifyy(two y's) on PyPI. This is the correct package name — a single-y search will not find it.

After installation, the binary is resolved in this order:

Resolution order

1. $AGENTIES_GRAPHIFY_BIN  (env override)
2. .agenties/tools/graphify-venv/Scripts/graphify.exe  (Windows, project-local)
   .agenties/tools/graphify-venv/bin/graphify           (macOS/Linux, project-local)
3. ~/.agenties/tools/graphify-venv/...                  (global fallback)
→  null → graph tools return { installed: false } gracefully

Verify the installation:

Verification

# From the orchestrator or a scout
graph_status()
# → { installed: true, graphPath: ".agenties/graphify/my-project/graph.json",
#     nodeCount: 1240, edgeCount: 3870, lastUpdated: "2026-06-02T..." }

Keeping the graph fresh

Agenties triggers a graph rebuild automatically on project switch and after journal writes (using a 30-minute staleness window). For most active projects the graph stays current without manual intervention.

After a major refactor, adding many new files, or a dependency upgrade that changes your module structure, call graph_update manually to ensure the index reflects the new state.

Note:The graph index is a local file — it is not synced to the cloud and not committed to git. Each developer maintains their own local graph under .agenties/graphify/.

Orchestrator usage pattern

The orchestrator guide bakes in this pattern for any question that spans the codebase:

Pattern

1. graph_status()              → confirm installed: true + graph exists
2. graph_query("auth flow")    → get 2–4 file pointers
3. Read those files directly   → answer the question
4. If empty / stale / missing  → fall back to normal scouting

Skip the graph when the file path is already known, the task targets a single file, or graph_status returns installed: false.

Troubleshooting

Symptom	Cause	Fix
graph_status → installed: false	Binary not found at expected paths	Install with `pip install graphifyy` into `.agenties/tools/graphify-venv/`, or set `AGENTIES_GRAPHIFY_BIN`.
graph_query → "graph.json not found"	Graph has never been built	Run `graph_update()` first to build the initial index.
graph_update times out	Very large repo or slow disk	The update command has a 120-second timeout. For very large monorepos, try running graphify directly from the CLI.
Query results feel irrelevant	Graph is stale after a large refactor	Run `graph_update()` to rebuild. Verify the output: `graph_status()` shows a recent `lastUpdated`.
Python version error on build	System Python < 3.10	Graphify requires Python 3.10+. Install a newer Python and recreate the venv at .agenties/tools/graphify-venv/.

← PreviousWordPress Next →Google Workspace