Core Components of code-graph-rag: A Complete Architecture Guide

code-graph-rag consists of six interconnected layers: codebase_rag (graph engine), services (LLM orchestration and Memgraph integration), providers (multi-vendor LLM abstraction), tools (sandboxed LLM capabilities), evals (cross-language benchmarks), and support modules for configuration and logging.

What Is code-graph-rag?

code-graph-rag is an open-source Python package that combines Retrieval-Augmented Generation (RAG) with language-agnostic code graph analysis. Built by vitali87, it enables LLMs to answer natural-language questions about codebases by parsing multiple programming languages into a unified call-graph, persisting it to Memgraph, and exposing safe tools for file operations and semantic search.

The Six Core Components

codebase_rag: The Graph Engine

The codebase_rag package forms the heart of the system. It handles source-code parsing, graph construction, and the interactive RAG loop.

File	Responsibility
codebase_rag/main.py	Entry point, session management, and UI rendering
codebase_rag/graph_loader.py	Loads persisted graphs from JSON
codebase_rag/graph_updater.py	Incremental updates while watching the repository
codebase_rag/parser_fingerprint.py	Cache-friendly AST parsing with content hashing

In codebase_rag/main.py, the run_chat_loop() function drives the interactive session, managing conversation history and delegating to the LLM orchestrator. The parser fingerprinting system in parser_fingerprint.py ensures that only changed files trigger re-parsing, making large codebase updates efficient.

services: LLM and Database Glue

The services layer bridges the graph engine with external systems—LLMs, vector stores, and cost trackers.

• services/llm.py – Creates a pydantic_ai-based agent, handles streaming responses, and formats tool calls for the RAG pipeline
• services/graph_service.py – Wraps Memgraph ingestion operations and graph export functionality
• services/usage_cost.py – Estimates token-based pricing across OpenAI, Anthropic, and other supported providers

The create_rag_orchestrator() function in services/llm.py instantiates the agent that mediates between natural-language queries and Cypher graph queries.

providers: Multi-Vendor LLM Abstraction

The providers package implements a strategy pattern for LLM backends, ensuring the same RAG pipeline works regardless of which model provider you choose.

• providers/base.py – Defines the common interface all providers must implement
• providers/openai.py – OpenAI GPT-4, GPT-4o, and GPT-3.5 support
• providers/anthropic.py – Claude 3 Opus, Sonnet, and Haiku support
• Additional providers (Ollama, etc.) follow the same pattern

This abstraction allows code-graph-rag users to switch models via configuration without modifying the core RAG logic.

tools: Sandboxed LLM Capabilities

The tools package exposes discrete, safe operations that the LLM can invoke. Each tool is a function with a well-defined schema, preventing arbitrary code execution.

Tool Module	Function
tools/file_reader.py	Read files as binary or text content
tools/file_writer.py	Write files with atomic replacement
tools/directory_lister.py	Enumerate repository contents with filtering
tools/semantic_search.py	Vector-store lookup for code similarity
tools/structural_editor.py	AST-based code modifications (add/remove/replace nodes)
tools/web_search.py	Safe web-search integration for external context

These tools are instantiated via factory functions like create_query_tool() and create_file_editor_tool(), then passed to the LLM orchestrator in services/llm.py.

evals: Cross-Language Benchmarking

The evals directory contains language-specific evaluation scripts that verify retrieval accuracy and graph completeness. This ensures the parser works correctly across the supported language set.

• evals/ts_retrieval.py – TypeScript/TypeScript+React retrieval benchmarks
• evals/python_l1.py – Python L1 (function-level) evaluation
• evals/structure_report.py – Generates completeness metrics for the entire graph

Running these evaluations validates that the call-graph correctly captures imports, function calls, and inheritance relationships before deploying the RAG system.

Support Modules: Configuration and Utilities

Supporting infrastructure includes:

• config.py – Loads .cgrignore patterns, CLI flags, and model settings from environment or config files
• constants.py – UI strings, color codes, and token threshold defaults
• exceptions.py – Domain-specific error types for parser failures, LLM errors, and graph inconsistencies
• logs.py – Structured logging helpers for the interactive session
• utils/ – Cross-cutting utilities for path handling, text processing, and validation

How the Components Work Together

The code-graph-rag architecture follows this data flow:

1. Parse – codebase_rag walks the repository, using tree-sitter grammars to parse Python, Java, TypeScript, Rust, Go, C/C++, Lua, PHP, and others into a unified AST representation
2. Graphify – The AST transforms into a call-graph with nodes for functions, classes, and modules; edges capture calls, imports, and inheritance
3. Persist – graph_service serializes to JSON or streams directly into Memgraph for Cypher querying
4. Query – The LLM agent in services/llm receives natural language, optionally invokes tools for additional context, and generates Cypher or direct answers
5. Iterate – graph_updater watches for filesystem changes and incrementally updates the graph without full re-parsing

Code Example: Running the RAG Loop

from pathlib import Path
from codebase_rag.main import run_chat_loop, ConfirmationToolNames
from codebase_rag.services.llm import create_rag_orchestrator
from codebase_rag.tools import create_query_tool, create_file_editor_tool

repo_root = Path("/path/to/your/repo")

# Instantiate the LLM orchestrator with configured provider

rag_agent = create_rag_orchestrator()

# Build tool set available to the LLM

tools = [
    create_query_tool(),
    create_file_editor_tool(),
]

# Start interactive session

await run_chat_loop(rag_agent, tools, repo_root, ConfirmationToolNames())

Code Example: Exporting the Graph

from codebase_rag.graph_updater import MemgraphIngestor
from codebase_rag.main import export_graph_to_file

# Connect to local Memgraph instance

ingestor = MemgraphIngestor(host="localhost", port=7687, batch_size=500)

# Export serialized graph to JSON

export_graph_to_file(ingestor, "graph_export.json")

Summary

• codebase_rag provides the parsing engine, graph construction, and interactive loop
• services connects LLMs, Memgraph, and cost estimation in a unified interface
• providers abstracts OpenAI, Anthropic, and other backends behind a common base class
• tools exposes safe, schema-validated operations for file I/O, search, and AST editing
• evals validates graph quality across multiple programming languages
• Support modules handle configuration, logging, and cross-cutting concerns

Frequently Asked Questions

What graph database does code-graph-rag use?

code-graph-rag uses Memgraph as its primary graph database. The services/graph_service.py module handles all ingestion and export operations via the Bolt protocol (default port 7687). Graphs can also be serialized to JSON for offline analysis or transfer.

Which programming languages does the parser support?

The parser supports Python, Java, TypeScript/JavaScript, Rust, Go, C/C++, Lua, and PHP. The evals/ directory contains benchmarking scripts for most of these languages. Language support is extensible through tree-sitter grammar integration.

How does code-graph-rag handle API costs?

The services/usage_cost.py module tracks token consumption and estimates pricing based on the active provider's rate card. Costs are logged per session and can be capped via configuration in config.py.

Can I use local LLMs instead of cloud APIs?

Yes. The providers package is designed for pluggable backends. While providers/openai.py and providers/anthropic.py ship by default, the providers/base.py interface supports any OpenAI-compatible endpoint—including Ollama, vLLM, or llama.cpp servers running locally.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}