DOCSEARCHbyAlgolia
Submit Docs

Graphify: AI Coding Assistant Knowledge Graph Tool

repository·v8·Indexed 30 days ago

https://github.com/graphify-labs/graphify

An AI coding assistant skill that maps entire projects—including code, documentation, PDFs, images, and videos—into a queryable knowledge graph. It uses AST-based structural extraction for code and LLM-based semantic extraction for non-code assets. Supports integration with Claude Code, Cursor, Aider, GitHub Copilot, and more via CLI or MCP server. Enables natural language querying, path tracing, and concept explanation across diverse file types.

Tokens
479.1K
Snippets
948
Records
1.6K
Agent score
80%

What's inside graphifyy

  1. Understand Graphify privacy and data handling

    v8

    Graphify handles different file types with different privacy levels:

    • Code files: Processed entirely locally using tree-sitter AST. Code content is never sent to an external API.
    • Documents, papers, and images: Content is sent to the LLM API used by your AI coding assistant (e.g., Anthropic Claude, OpenAI) for semantic extraction.

    Graphify does not perform any telemetry, usage tracking, or analysis. All network requests are made using your own API keys to your existing model providers.

  2. Understand Graphify extraction limitations

    v8

    The current AST-based extraction pipeline is deterministic and fast but has specific architectural limitations:

    • Structural vs. Semantic: The AST extractor captures the 'skeleton' of the codebase (structure) but lacks 'architectural intent' (semantics). It primarily produces EXTRACTED edges.
    • Missing Call Graphs: The current pipeline may not capture method-to-method call flows (e.g., Method A calls Method B) without additional call-graph analysis or LLM-based extraction.
    • Inheritance Gaps: If a class inherits from an external base class (like Exception or ABC) not defined in the local corpus, the inheritance edge might be dropped if the target node is not registered. This can make hierarchies (like exception trees) invisible.
    • Corpus Size: For very small corpora (e.g., < 10 files), the graph may lack sufficient density to form meaningful community structures. The value of the graph increases significantly with larger, more complex codebases.

  3. Understand the Graphify extraction process

    v8

    Graphify uses a two-part parallel extraction process to build its knowledge graph:

    1. Structural Extraction (Part A): Uses AST (Abstract Syntax Tree) parsing for code files. This is deterministic, free, and requires no API keys. It extracts the structure of code (functions, classes, etc.) without LLM intervention.
    2. Semantic Extraction (Part B): Uses LLMs for non-code assets like documentation, papers, and images.

    LLM Configuration

    • No API Key Required: If no key is provided, semantic extraction falls back to the host agent (e.g., the LLM running your terminal session).
    • Gemini Support: To use Gemini for semantic extraction, set the GEMINI_API_KEY or GOOGLE_API_KEY environment variable.
    • Model Selection: The default Gemini model is gemini-3-flash-preview. You can override this by setting the GRAPHIFY_GEMINI_MODEL environment variable or using the --model flag in headless flows.
    • Note: Graphify does not use ANTHROPIC_API_KEY or OPENAI_API_KEY for its internal extraction processes.

  4. Understand Graphify output features

    v8

    When you generate a knowledge graph with Graphify, the output includes several specialized insights:

    • God Nodes: Concepts with the highest degree (central nodes that connect many other entities).
    • Surprising Connections: Relationships ranked by composite scores. Code-to-paper edges often receive high ranks.
    • Suggested Questions: 4-5 specific questions that the graph is uniquely well-equipped to answer.
    • "Why" (Rationale): Docstrings, inline comments, and design rationale are extracted as rationale_for nodes.
    • Confidence Scores: Every INFERRED edge includes a confidence_score ranging from 0.0 to 1.0.
    • Token Benchmarks: After each run, Graphify prints a token usage comparison. On mixed corpora, it typically uses 71.5x fewer tokens compared to raw file processing.

  5. Understand Graphify output files

    v8

    After running a scan, Graphify generates several files in the graphify-out/ directory:

    • graph.html: An interactive graph visualization that can be opened in a browser.
    • GRAPH_REPORT.md: An audit report containing insights like 'God Nodes', 'Surprising Connections', and 'Suggested Questions'.
    • graph.json: The raw graph data used for queries and analysis.
    • obsidian/: An Obsidian vault (only generated if the --obsidian flag was provided during execution).

  6. Understand the Graphify extraction process

    v8

    Graphify performs extraction in three distinct parts to build a comprehensive knowledge graph:

    1. Part A: AST Extraction (Structural): Deterministic extraction of code structure (nodes and edges) from code files. Results are saved to graphify-out/.graphify_ast.json.
    2. Part B: Semantic Extraction (LLM-based): Uses parallel subagents to extract semantic relationships from non-code assets (documents, papers, images) and high-level design patterns from code. This process uses a caching mechanism to avoid re-processing files and saves results to graphify-out/.graphify_semantic.json.
    3. Part C: Final Merge: Combines the structural AST data and the semantic LLM data into a single unified graph.

    Note: If your corpus contains only code files, the system will skip Part B (Semantic extraction) entirely to optimize performance.

  7. Understand the Graphify pipeline and feedback loop

    v8

    Graphify follows a multi-stage pipeline to transform raw assets into a queryable knowledge graph:

    1. detect: Identifies file types (e.g., code, paper, image) using heuristics like arXiv patterns for papers.
    2. extract (AST): Performs deterministic structural extraction for code files.
    3. build: Constructs the initial graph nodes and edges.
    4. cluster: Performs community detection to group semantically related nodes.
    5. analyze: Identifies patterns like 'god nodes' or 'surprising connections'.
    6. query: Uses BFS traversal to answer natural language questions.
    7. feedback loop: Query results (saved as markdown files) are picked up by the next detect() scan and can be extracted into the graph during the next --update run.

    This feedback loop allows the graph to grow based on the questions you ask it.

  8. Understand the Graphify extraction pipeline

    v8

    Graphify processes files through three distinct passes to build a knowledge graph:

    1. Pass 1 — Code structure (Local/Free): Uses Tree-sitter to extract classes, functions, imports, call graphs, and inline comments. Supports 25 languages. SQL files are parsed for tables, views, foreign keys, and JOIN relationships. This pass does not use LLMs.
    2. Pass 2 — Video and audio (Local/Free): Transcribes media using faster-whisper. The transcription is seeded with your existing top 'god nodes' (most-connected concepts) to improve domain accuracy. Transcripts are cached.
    3. Pass 3 — Docs, papers, images (LLM/Paid): Uses Claude subagents in parallel to process markdown, PDFs, images, and transcripts. Subagents output JSON fragments (nodes, edges, group relationships) which are merged into the final graph.

    Note: If your corpus contains only code files, Pass 3 is skipped entirely.

  10. Understand Graphify privacy and data handling

    v8

    Graphify follows these privacy principles:

    • Code Files: Processed locally using tree-sitter AST.
    • Media Files: Video and audio files are transcribed locally using faster-whisper.
    • Semantic Extraction: File content is sent to your AI assistant's model API (e.g., Claude or GPT-4) specifically for semantic extraction from documents, research papers, and images.
    • Data Usage: There is no telemetry and no usage tracking.

  11. Understand Graphify output files

    v8

    After a successful Graphify run, the results are stored in the graphify-out/ directory. The primary outputs include:

    • graph.html: An interactive visualization of the graph that can be opened in a web browser.
    • GRAPH_REPORT.md: An audit report containing insights like 'God Nodes', 'Surprising Connections', and 'Suggested Questions'.
    • graph.json: The raw graph data used for queries and analysis.
    • obsidian/: An Obsidian vault (this directory is only created if the --obsidian flag was used during the run).

  12. Understand the Graphify processing pipeline

    v8

    Graphify processes data through a linear pipeline where each stage is a single function in its own module. Modules communicate via plain Python dictionaries and NetworkX graphs, ensuring no shared state or side effects outside the graphify-out/ directory.

    Pipeline Stages:

    1. detect(): Collects files from a root directory.
    2. extract(): Performs structural or semantic extraction from files.
    3. build_graph(): Constructs a NetworkX graph from extraction results.
    4. cluster(): Performs community detection on the graph.
    5. analyze(): Identifies 'god nodes', surprises, and questions.
    6. report(): Renders a GRAPH_REPORT.md string.
    7. export(): Exports the graph to formats like Obsidian vaults, JSON, HTML, or SVG.