代码图谱

📋 Prerequisites

• Python 3.12+
• Docker & Docker Compose (for Memgraph)
• cmake (required for building pymgclient dependency)
• ripgrep (rg) (required for shell command text searching)
• For cloud models: Google Gemini API key
• For local models: Ollama installed and running
• uv package manager

Pull required models

ollama pull llama3.2

Key Dependencies

• loguru: Python logging made (stupidly) simple
• mcp: Model Context Protocol SDK
• pydantic-ai: Agent Framework / shim to use Pydantic with LLMs
• pydantic-settings: Settings management using Pydantic
• pymgclient: Memgraph database adapter for Python language
• python-dotenv: Read key-value pairs from a .env file and set them as environment variables
• tiktoken: tiktoken is a fast BPE tokeniser for use with OpenAI's models
• toml: Python Library for Tom's Obvious, Minimal Language
• tree-sitter-python: Python grammar for tree-sitter
• tree-sitter: Python bindings to the Tree-sitter parsing library
• watchdog: Filesystem events monitoring
• typer: Typer, build great CLIs. Easy to code. Based on Python type hints.
• rich: Render rich text, tables, progress bars, syntax highlighting, markdown and more to the terminal
• prompt-toolkit: Library for building powerful interactive command lines in Python
• diff-match-patch: Repackaging of Google's Diff Match and Patch libraries.
• click: Composable command line interface toolkit
• protobuf
• defusedxml: XML bomb protection for Python stdlib modules
• huggingface-hub: Client library to download and publish models, datasets and other repos on the huggingface.co hub
• griffe: Signatures for entire Python programs. Extract the structure, the frame, the skeleton of your project, to generate API documentation or find breaking changes in your API.

Installing cmake and ripgrep

On macOS:

brew install cmake ripgrep

On Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install cmake ripgrep

On Linux (CentOS/RHEL): ```bash sudo yum install cmake sudo dnf install ripgrep

Note: ripgrep may need to be installed from EPEL or via cargo

```

🛠️ Installation

System-wide install (recommended for end users)

cgr is published to PyPI and can be installed system-wide so it works from any target repo without activating a project virtualenv. Install with the treesitter-full (all languages) and semantic (vector search) extras:

```bash

Local development install

git clone https://github.com/vitali87/code-graph-rag.git
cd code-graph-rag

1. Install dependencies:

For basic Python support:

uv sync

For full multi-language support:

uv sync --extra treesitter-full

For development (including tests and pre-commit hooks):

make dev

This installs all dependencies and sets up pre-commit hooks automatically.

This installs Tree-sitter grammars for all supported languages (see Multi-Language Support section).

3. Set up environment variables: ```bash cp .env.example .env

Install Ollama (macOS/Linux)

curl -fsSL https://ollama.ai/install.sh | sh

If installed from PyPI:

cgr --help

Quick Setup

claude mcp add --transport stdio code-graph-rag \
  --env TARGET_REPO_PATH=/absolute/path/to/your/project \
  --env CYPHER_PROVIDER=openai \
  --env CYPHER_MODEL=gpt-4 \
  --env CYPHER_API_KEY=your-api-key \
  -- uv run --directory /path/to/code-graph-rag code-graph-rag mcp-server

📦 Building a binary

You can build a binary of the application using the build_binary.py script. This script uses PyInstaller to package the application and its dependencies into a single executable.

python build_binary.py

🎯 Usage

The Code-Graph-RAG system offers four main modes of operation: 1. Parse & Ingest: Build knowledge graph from your codebase 2. Interactive Query: Ask questions about your code in natural language 3. Export & Analyze: Export graph data for programmatic analysis 4. AI Optimization: Get AI-powered optimization suggestions for your code. 5. Editing: Perform surgical code replacements and modifications with precise targeting.

Use architectural guidelines

cgr optimize java \ --reference-document ./ARCHITECTURE.md

Example Usage

> Index this repository
> What functions call UserService.create_user?
> Update the login function to add rate limiting

For detailed setup, see Claude Code Setup Guide.

Examples:

cgr language add-grammar c-sharp cgr language add-grammar php cgr language add-grammar ruby cgr language add-grammar kotlin

#### Custom Grammar Repositories

For languages hosted outside the standard tree-sitter organization:

Edit .env with your configuration (see options below)

```

Configuration Options

The new provider-explicit configuration supports mixing different providers for orchestrator and cypher models.

Option 1: All Ollama (Local Models)

```bash

.env file

ORCHESTRATOR_PROVIDER=ollama ORCHESTRATOR_MODEL=llama3.2 ORCHESTRATOR_ENDPOINT=http://localhost:11434/v1

CYPHER_PROVIDER=ollama CYPHER_MODEL=codellama CYPHER_ENDPOINT=http://localhost:11434/v1

#### Option 2: All OpenAI Models

.env file

ORCHESTRATOR_PROVIDER=openai ORCHESTRATOR_MODEL=gpt-4o ORCHESTRATOR_API_KEY=sk-your-openai-key

CYPHER_PROVIDER=openai CYPHER_MODEL=gpt-4o-mini CYPHER_API_KEY=sk-your-openai-key

#### Option 3: All Google Models

.env file

ORCHESTRATOR_PROVIDER=google ORCHESTRATOR_MODEL=gemini-2.5-pro ORCHESTRATOR_API_KEY=your-google-api-key

CYPHER_PROVIDER=google CYPHER_MODEL=gemini-2.5-flash CYPHER_API_KEY=your-google-api-key

#### Option 4: Mixed Providers

.env file - Google orchestrator + Ollama cypher

ORCHESTRATOR_PROVIDER=google ORCHESTRATOR_MODEL=gemini-2.5-pro ORCHESTRATOR_API_KEY=your-google-api-key

CYPHER_PROVIDER=ollama CYPHER_MODEL=codellama CYPHER_ENDPOINT=http://localhost:11434/v1

Get your Google API key from [Google AI Studio](https://aistudio.google.com/app/apikey).

**Install and run Ollama**:

Flush every 5,000 records instead of the default from settings

cgr start --repo-path /path/to/repo --update-graph \ --batch-size 5000 ```

The system automatically detects and processes files for all supported languages (see Multi-Language Support section).

Step 2.5: Real-Time Graph Updates (Optional)

For active development, you can keep your knowledge graph automatically synchronized with code changes using the realtime updater. This is particularly useful when you're actively modifying code and want the AI assistant to always work with the latest codebase structure.

What it does: - Watches your repository for file changes (create, modify, delete) - Automatically updates the knowledge graph in real-time - Maintains consistency by recalculating all function call relationships - Filters out irrelevant files (.git, node_modules, etc.)

How to use:

Run the realtime updater in a separate terminal:

```bash

Optional: override Memgraph batch flushing during optimization

cgr optimize javascript --repo-path /path/to/frontend \ --batch-size 5000

**Supported Languages for Optimization:**
All supported languages: `python`, `javascript`, `typescript`, `rust`, `go`, `java`, `scala`, `c`, `cpp`

**How It Works:**
1. **Analysis Phase**: The agent analyzes your codebase structure using the knowledge graph
2. **Pattern Recognition**: Identifies common anti-patterns, performance issues, and improvement opportunities
3. **Best Practices Application**: Applies language-specific best practices and patterns
4. **Interactive Approval**: Presents each optimization suggestion for your approval before implementation
5. **Guided Implementation**: Implements approved changes with detailed explanations

**Example Optimization Session:**

🔍 Analyzing codebase structure... 📊 Found 23 Python modules with potential optimizations

💡 Optimization Suggestion #1: File: src/data_processor.py Issue: Using list comprehension in a loop can be optimized Suggestion: Replace with generator expression for memory efficiency

[y/n] Do you approve this optimization?

**Reference Document Support:**
You can provide reference documentation (like coding standards, architectural guidelines, or best practices documents) to guide the optimization process:

🔧 Configuration

Configuration is managed through environment variables in .env file:

Provider-Specific Settings

#### Orchestrator Model Configuration - ORCHESTRATOR_PROVIDER: Provider name (google, openai, ollama) - ORCHESTRATOR_MODEL: Model ID (e.g., gemini-2.5-pro, gpt-4o, llama3.2) - ORCHESTRATOR_API_KEY: API key for the provider (if required) - ORCHESTRATOR_ENDPOINT: Custom endpoint URL (if required) - ORCHESTRATOR_PROJECT_ID: Google Cloud project ID (for Vertex AI) - ORCHESTRATOR_REGION: Google Cloud region (default: us-central1) - ORCHESTRATOR_PROVIDER_TYPE: Google provider type (gla or vertex) - ORCHESTRATOR_THINKING_BUDGET: Thinking budget for reasoning models - ORCHESTRATOR_SERVICE_ACCOUNT_FILE: Path to service account file (for Vertex AI)

#### Cypher Model Configuration - CYPHER_PROVIDER: Provider name (google, openai, ollama) - CYPHER_MODEL: Model ID (e.g., gemini-2.5-flash, gpt-4o-mini, codellama) - CYPHER_API_KEY: API key for the provider (if required) - CYPHER_ENDPOINT: Custom endpoint URL (if required) - CYPHER_PROJECT_ID: Google Cloud project ID (for Vertex AI) - CYPHER_REGION: Google Cloud region (default: us-central1) - CYPHER_PROVIDER_TYPE: Google provider type (gla or vertex) - CYPHER_THINKING_BUDGET: Thinking budget for reasoning models - CYPHER_SERVICE_ACCOUNT_FILE: Path to service account file (for Vertex AI)

System Settings

• MEMGRAPH_HOST: Memgraph hostname (default: localhost)
• MEMGRAPH_PORT: Memgraph port (default: 7687)
• MEMGRAPH_HTTP_PORT: Memgraph HTTP port (default: 7444)
• LAB_PORT: Memgraph Lab port (default: 3000)
• MEMGRAPH_BATCH_SIZE: Batch size for Memgraph operations (default: 1000)
• TARGET_REPO_PATH: Default repository path (default: .)
• LOCAL_MODEL_ENDPOINT: Fallback endpoint for Ollama (default: http://localhost:11434/v1)

List all configured languages

cgr language list-languages

🔌 MCP Server (Claude Code Integration)

Code-Graph-RAG can run as an MCP (Model Context Protocol) server, enabling seamless integration with Claude Code and other MCP clients.

🤖 Agentic Workflow & Tools

The agent is designed with a deliberate workflow to ensure it acts with context and precision, especially when modifying the file system.

Remove a language (this also removes the git submodule unless --keep-submodule is specified)

cgr language remove-language <language-name>

#### Language Configuration

The system uses a configuration-driven approach for language support. Each language is defined in `codebase_rag/language_config.py` with the following structure:

#### Troubleshooting

**Grammar not found**: If the automatic URL doesn't work, use a custom URL:

**Version incompatibility**: If you get "Incompatible Language version" errors, update your tree-sitter package:

Missing node types: The tool automatically detects common node patterns, but you can manually adjust the configuration in language_config.py if needed.