Graphify: Building Codebase Knowledge Graphs to Replace Vector Retrieval

Token Tax in Large Codebases

Context windows keep growing—Claude Sonnet 4.6 supports 200 K tokens, GPT‑5.4 reaches 1 M—but the primary issue is cost and latency. Feeding hundreds of files into each query is both expensive and slow, and most of the information in those files is irrelevant to a specific question, similar to moving an entire library to find a single paragraph.

Why Graphify Differs from RAG

The industry standard RAG approach chunks files, embeds them, and retrieves the top‑K chunks. This works well for prose where semantic similarity is a reliable signal, but code relationships are structural. Calls such as process_payment invoking validate_card exist in the call graph, not in embedding space. Graphify avoids embedding and similarity search; it builds an explicit graph of entities (functions, classes, concepts, document sections) and relationships (calls, imports, references, inferred dependencies). Queries traverse this graph, mirroring how an experienced engineer mentally maps a codebase before searching.

Artifacts Produced

Running /graphify in a directory creates several artifacts in graphify-out/:

An interactive HTML graph rendered with vis.js.

A persistent JSON graph for programmatic queries.

A Markdown report highlighting high‑degree nodes and community clusters.

Optional outputs: an Obsidian vault, a Neo4j database, SVG, GraphML, or an MCP server exposing the graph as an LLM‑callable tool.

Community detection uses the Leiden algorithm, automatically separating distinct modules (e.g., auth, billing, infra) and exposing bridge nodes.

Three Data‑Processing Passes

Pass 1: Deterministic AST Extraction (code stays on‑machine)

Source files are parsed with tree‑sitter (https://tree-sitter.github.io/), a rule‑based deterministic parser that acts like a compiler front‑end. It reads files, applies language grammars, and emits abstract syntax trees without any network calls, ensuring code never leaves the host machine. tree‑sitter supports 23 languages (Python, TypeScript, Go, Rust, Java, C/C++, Ruby, C#, Kotlin, Scala, PHP, etc.). The output is a dictionary of nodes and edges encoding every explicit function, class, import, and call relationship. Each edge receives an EXTRACTED confidence label, guaranteeing factual correctness.

Pass 2: Local Audio/Video Transcription (optional)

If the target directory contains audio or video, Graphify invokes faster‑whisper (a CTranslate2‑accelerated Whisper implementation) to transcribe locally; no media are uploaded. Install the optional dependency with pip install "graphifyy[video]". The generated transcript becomes a document node in the graph, treated like any other text source.

Pass 3: Semantic Extraction (documents & images sent to AI provider)

Non‑code assets (Markdown, PDF, RST, PNG, JPG, GIF) lack a syntactic parser, so Graphify calls a user‑configured AI provider (Anthropic, OpenAI, etc.) to extract entities and relationships. The tool uses the credentials already set up for Claude Code or other assistants, sending data directly from the machine to the provider without an intermediate relay. Graphify does not store credentials, emit telemetry, or perform network calls during graph analysis itself.

Confidence System

EXTRACTED : Directly observed in the source code (e.g., validate_card called by process_payment).

INFERRED : Deduced by the LLM from contextual co‑occurrence (e.g., a dependency inferred between PaymentService and FraudDetector).

AMBIGUOUS : The model is uncertain; such edges are retained but should not be used for decisive reasoning without human verification.

Installation and Usage

Requirements: Python 3.10+, Claude Code installed.

# Install the core package
pip install graphifyy

# Register the skill with your AI platform
graphify install

Optional extras can be installed as needed:

# Audio/video transcription
pip install "graphifyy[video]"

# Office document support (.docx, .xlsx)
pip install "graphifyy[office]"

# MCP server (expose graph as LLM tool)
pip install "graphifyy[mcp]"

# Install all extras
pip install "graphifyy[all]"

Typical commands:

/graphify                     # Standard analysis of current directory
/graphify --deep              # Aggressive relationship inference
/graphify ./src/auth          # Analyze a specific subdirectory
/graphify --watch             # Re‑build graph on file changes
/graphify query "..."        # Natural‑language query against the graph
/graphify path "UserService" "DatabasePool"
/graphify explain "PaymentProcessor"

Graphify tracks SHA‑256 hashes; only changed files are re‑processed, making subsequent queries cheap. A Git hook can be installed with /graphify --install-hooks so that every git commit or git checkout triggers an incremental update, keeping the graph in sync with the current branch.

71.5× Token Reduction Claim

The README reports a 71.5‑fold token reduction on a mixed‑corpus benchmark (the project's worked/ dataset). Querying the graph for “what calls process_payment?” returns a handful of node IDs, whereas answering the same question by scanning raw files would require loading many potentially relevant files. The exact multiplier depends on corpus size, file types, and query specificity; no public benchmark comparing Graphify, raw file scans, and traditional RAG has been released.

Suitable and Unsuitable Scenarios

Suitable: mixed‑media repositories that contain code, architecture docs, design PDFs, and recorded meetings; stable codebases where queries are repeated over time; teams using Claude Code as a coding assistant who want to lower per‑call API costs; projects with complex call graphs where flat RAG performs poorly.

Unsuitable: very small projects (<20 files) where the graph overhead outweighs benefits; repositories dominated by prose where semantic search is more effective; environments where the AI provider’s data policy forbids sending documents (Pass 3 would be blocked); use‑cases requiring fully verifiable analysis, because INFERRED and AMBIGUOUS edges may introduce uncertainty.

Limitations

Graphify is a personal open‑source project (v0.4.10) without corporate backing; long‑term maintenance is uncertain. The PyPI package name is graphifyy (double y) while the tool is called “graphify,” so users should verify the correct package name before installing.

Future Directions

The upcoming MCP server integration is noteworthy. As MCP becomes common in AI coding assistants, exposing a codebase graph as an LLM‑callable tool could become foundational infrastructure for autonomous agents that need structured code understanding rather than simple file search.