Ragex

Hybrid Retrieval-Augmented Generation for Multi-Language Codebases

Ragex is an MCP (Model Context Protocol) server that analyzes codebases using compiler output and language-native tools to build comprehensive knowledge graphs. It enables natural language querying of code structure, relationships, and semantics.

Features

Planned Features

• Streaming RAG responses
• MCP streaming notifications
• MetaAST-enhanced retrieval
• Code quality analysis
• Impact analysis and risk assessment
• CLI improvements (interactive wizards, dashboard, completions, man pages)
• CI tasks (diff-based analysis, GitHub Actions annotations, mix ragex.ci)
• Provider health checks and auto-failover
• Production optimizations
• Additional language support
• Cross-language refactoring via Metastatic
• Enhanced editor integrations (Zed, Claude Desktop, Cursor, LunarVim)

Architecture

graph TD
    MCP["MCP Server (stdio)<br/>~50 Tools + 6 Resources + 6 Prompts"]
    
    MCP --> Tools["Tools Handler"]
    MCP --> Resources["Resources Handler"]
    MCP --> Prompts["Prompts Handler"]
    MCP --> Analyzers["Analyzers<br/>(Elixir, Erlang, Metastatic)"]
    MCP --> Graph["Graph Store<br/>(ETS Knowledge Graph)"]
    MCP --> Vector["Vector Store<br/>(Cosine Similarity)"]
    MCP --> Bumblebee["Bumblebee Embedding<br/>(all-MiniLM-L6-v2)"]
    
    Tools <--> Analyzers
    Analyzers <--> Graph
    Resources --> Graph
    Resources --> Vector
    Resources --> Bumblebee
    Prompts --> Tools
    
    Tools --> Hybrid["Hybrid Retrieval (RRF)<br/>Semantic + Graph + Fusion"]
    Graph --> Hybrid
    Vector --> Hybrid
    
    Tools --> RAG["RAG Pipeline<br/>Cache → Context → Prompts → AI"]
    Hybrid --> RAG
    RAG --> Cache["AI Cache<br/>(TTL + LRU)"]
    RAG --> Usage["Usage Tracker<br/>(Costs + Limits)"]
    RAG --> AIProvider["AI Providers<br/>(OpenAI, Anthropic, DeepSeek, Ollama)"]
    
    style MCP fill:#e1f5ff,color:#01579b,stroke:#01579b,stroke-width:2px
    style Hybrid fill:#f3e5f5,color:#4a148c,stroke:#4a148c,stroke-width:2px
    style Graph fill:#e8f5e9,color:#1b5e20,stroke:#1b5e20,stroke-width:2px
    style Vector fill:#fff3e0,color:#e65100,stroke:#e65100,stroke-width:2px
    style Bumblebee fill:#fce4ec,color:#880e4f,stroke:#880e4f,stroke-width:2px
    style Resources fill:#e0f2f1,color:#004d40,stroke:#004d40,stroke-width:2px
    style Prompts fill:#fff9c4,color:#f57f17,stroke:#f57f17,stroke-width:2px
    style RAG fill:#ffebee,color:#b71c1c,stroke:#b71c1c,stroke-width:2px
    style AIProvider fill:#e8eaf6,color:#1a237e,stroke:#1a237e,stroke-width:2px
    style Cache fill:#e0f7fa,color:#006064,stroke:#006064,stroke-width:2px
    style Usage fill:#fff8e1,color:#f57c00,stroke:#f57c00,stroke-width:2px

Installation

Prerequisites

• Elixir 1.18 or later
• Erlang/OTP 27 or later
• Python 3.x (optional, for Python code analysis)
• Node.JS (optional, for Javascript code analysis)
• ~500MB RAM for embedding model (first run downloads ~90MB)
• dllb-server binary (optional, for per-project persistent database storage and hybrid full-text search)

Database Backend (dllb)

Ragex integrates with dllb—a high-performance multi-model NoSQL and vector database server written in Rust—to power persistent graph storage, full-text search (BM25 via Tantivy), HNSW vector index storage, and MetaAST symbol caching across application restarts.

When :dllb_mode is set to :per_project (or when per-project indexing is enabled), Ragex automatically manages dedicated dllb-server processes and connection pools for each workspace.

dllb Binary Resolution Precedence

Ragex automatically locates the dllb-server executable in the following order:

1. Custom Configuration / Environment Variable:
   • Config setting: config :ragex, dllb_server_bin: "/path/to/dllb-server"
   • Environment variable: DLLB_SERVER_BIN=/path/to/dllb-server
2. System $PATH Executables:
   • Standard binary directories in $PATH (e.g. /usr/local/bin/dllb-server, ~/.cargo/bin/dllb-server).
3. Sibling Repository Target Paths (Relative to working directory):
   • Release build: ../dllb/target/release/dllb-server
   • Debug build: ../dllb/target/debug/dllb-server

💡 Tip: Pre-compiled dllb-server release binaries can be grabbed directly from the dllb GitHub Releases page, or compiled locally from source via cargo build --release -p dllb-server.

Build

cd ragex
mix deps.get
mix compile

Note: First compilation will take longer due to ML dependencies. The embedding model (~90MB) will download on first run and be cached at ~/.cache/huggingface/.

Demo

A comprehensive demo showcasing all Ragex features is available in examples/product_cart/.

The demo uses an intentionally mediocre e-commerce cart application to demonstrate:

• Security vulnerability scanning (8+ issues detected)
• Code complexity analysis (cyclomatic, cognitive, Halstead metrics)
• Code smell detection (long functions, deep nesting, magic numbers)
• Code duplication detection (Type I-IV clones)
• Dead code analysis (4 unused functions)
• Dependency and coupling analysis
• Impact analysis and refactoring suggestions
• AI-enhanced features (ValidationAI, AIPreview, AIRefiner, AIAnalyzer, AIInsights)

Quick Start:

cd examples/product_cart
./run_demo.sh

The demo generates 11 detailed reports showing:

• 8 security vulnerabilities (2 critical, 3 high)
• 18 code smells across 5 types
• 52 lines of duplicated code (10% of codebase)
• 28 lines of dead code (7% of codebase)
• 8 prioritized refactoring suggestions
• Expected improvement: 65% better maintainability

See Produce Cart’s README for full details and Product Cart’s DEMO for step-by-step walkthrough.

Usage

As an MCP Server

The recommended entry point is bin/ragex-mcp, a self-contained launcher that handles compilation, detects a running instance and bridges to it instead of starting a second VM, and sets the correct environment for stdio MCP communication:

bin/ragex-mcp

# Auto-analyze a project on startup
bin/ragex-mcp --project /path/to/your/project

# Override log verbosity
bin/ragex-mcp --log-level debug

Alternatively, a bare server start (without the bridge logic) is available:

./start_mcp.sh

For detailed installation instructions and client-specific configuration (Claude Desktop, Cursor, Zed, LunarVim, generic stdio), see Using Ragex as MCP Server.

Auto-Analyze Directories on Startup

You can configure Ragex to automatically analyze specific directories when it starts. Add to config/config.exs:

config :ragex, :auto_analyze_dirs, [
  "/opt/Proyectos/MyProject",
  "~/workspace/important-lib"
]

This pre-loads your frequently used codebases into the knowledge graph, making them immediately available for querying. See CONFIGURATION for details.

Suppressing Ragex Findings

Findings from mix ragex.analyze and mix ragex.ci (which also runs MetaCredo) can be suppressed using inline comments, configuration files, or CLI flags.

1. Inline Comments

Suppress findings directly at the code site using standard Credo-style directives:

# Suppress a specific check on the next line
# credo:disable-for-next-line MetaCredo.Check.Security.HardcodedValue
api_endpoint = "https://internal-service.local/api"

# Suppress all findings on the next line
# credo:disable-for-next-line
refactored_result = risky_operation()

# Suppress a check for the entire file
# credo:disable-for-this-file MetaCredo.Check.Readability.LongFunction

# Suppress a check for a range of lines
# credo:disable-for-lines:20 Credo.Check.Refactor.CyclomaticComplexity

# Suppress via module attribute
@credo:disable-for-next-line Credo.Check.Refactor.CyclomaticComplexity
def complex_function do
  # ...
end

2. Configuration Files

• .ragex.exs (Dedicated Ragex Exclusions Configuration):
  Create a .ragex.exs file in your project root to exclude specific findings by line number or rule:

  [
    {"lib/ragex/analyzers/directory.ex:248", "long_parameter_list"},
    {"lib/ragex/analyzers/directory.ex", 150, "cyclomatic_complexity"},
    {"lib/my_app/legacy.ex", "magic_number"}
  ]
  

  (Can also be passed explicitly via --ragex-config path/to/config.exs or RAGEX_CONFIG env variable)

• .metacredo.exs (Project-wide check configuration):
  Disable specific checks globally or exclude directories:

  %{
    configs: [
      %{
        name: "default",
        files: %{
          included: ["lib/", "src/"],
          excluded: [~r"/_build/", ~r"/deps/", ~r"lib/legacy/"]
        },
        checks: %{
          enabled: :all,
          disabled: [
            {MetaCredo.Check.Security.HardcodedValue, []},
            {MetaCredo.Check.Readability.LongFunction, []}
          ]
        }
      }
    ]
  }
  

• config/config.exs (Ragex engine configuration):
  Tune or disable Ragex static analysis passes (e.g. dead code detection):

  import Config
  
  config :ragex, :analysis,
    enable_dead_code_detection: true,
    dead_code_min_confidence: 0.8  # Only report high-confidence dead code (0.0 to 1.0)
  

3. Command Line Flags

Filter findings dynamically on invocation:

# Exclude DB-related or user-input security checks
mix ragex.ci --no-db --no-user
mix ragex.analyze --no-db --no-user

# Filter by minimum severity (low, medium, high, critical)
mix ragex.analyze --severity high

# Custom thresholds for complexity and god modules
mix ragex.analyze --min-complexity 15 --god-threshold 20 --threshold 0.90

MCP Protocol Example

Initialize the server:

{"jsonrpc":"2.0","method":"initialize","params":{"clientInfo":{"name":"test-client","version":"1.0"}},"id":1}

List available tools:

{"jsonrpc":"2.0","method":"tools/list","id":2}

Analyze a file (with auto-detection):

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "analyze_file",
    "arguments": {
      "path": "lib/ragex.ex"
    }
  },
  "id": 3
}

Or specify the language explicitly:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "analyze_file",
    "arguments": {
      "path": "script.py",
      "language": "python"
    }
  },
  "id": 3
}

Query the graph:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "query_graph",
    "arguments": {
      "query_type": "find_module",
      "params": {"name": "Ragex"}
    }
  },
  "id": 4
}

Development

Running Tests

mix test

Interactive Development

RAGEX_NO_SERVER=1 iex -S mix

# Analyze a file
{:ok, content} = File.read("lib/ragex.ex")
{:ok, analysis} = Ragex.Analyzers.Elixir.analyze(content, "lib/ragex.ex")

# Check graph stats, it’s expected to be empty for this single file
Ragex.stats()

MCP Tools Reference

Core Analysis Tools

analyze_file

Analyzes a source file and extracts code structure into the knowledge graph.

Parameters:

• path (string, required): Path to the file
• language (string, optional): Programming language - elixir, erlang, python, javascript, typescript, or auto (default: auto-detect from extension)
• generate_embeddings (boolean, optional): Generate embeddings for semantic search (default: true)

analyze_directory

Batch analyzes all source files in a directory.

Parameters:

• path (string, required): Directory path
• language (string, optional): Language to filter files (default: auto-detect)
• recursive (boolean, optional): Recursively analyze subdirectories (default: true)
• generate_embeddings (boolean, optional): Generate embeddings (default: true)

query_graph

Queries the knowledge graph for code entities and relationships (symbolic search).

Parameters:

• query_type (string, required): Type of query
  • find_module: Find a module by name
  • find_function: Find a function by module and name
  • get_calls: Get function call relationships
  • get_dependencies: Get module dependencies
• params (object, required): Query-specific parameters

list_nodes

Lists all nodes in the knowledge graph with optional filtering.

Parameters:

• node_type (string, optional): Filter by type (module, function, etc.)
• limit (integer, optional): Maximum results (default: 100)

File Watching Tools

watch_directory

Automatically re-index files when they change.

Parameters:

• path (string, required): Directory to watch

unwatch_directory

Stop watching a directory.

Parameters:

• path (string, required): Directory to stop watching

list_watched

List all watched directories.

Parameters: None

Semantic Search Tools

semantic_search

Performs natural language code search using vector embeddings.

Parameters:

• query (string, required): Natural language query (e.g., "function to parse JSON")
• limit (integer, optional): Maximum results (default: 10)
• threshold (number, optional): Minimum similarity score 0.0-1.0 (default: 0.7)
• node_type (string, optional): Filter by type (module, function)
• include_context (boolean, optional): Include caller/callee context (default: false)

Example:

{
  "query": "HTTP request handler",
  "limit": 5,
  "threshold": 0.75,
  "node_type": "function"
}

hybrid_search

Combines symbolic graph queries with semantic search for best results.

Parameters:

• query (string, required): Search query
• strategy (string, optional): Search strategy:
  • fusion (default): RRF fusion of both approaches
  • semantic_first: Semantic search then graph filtering
  • graph_first: Graph query then semantic ranking
• limit (integer, optional): Maximum results (default: 10)
• threshold (number, optional): Minimum similarity (default: 0.7)
• graph_filter (object, optional): Optional symbolic constraints
• include_context (boolean, optional): Include context (default: false)

Example:

{
  "query": "database connection",
  "strategy": "fusion",
  "limit": 10,
  "graph_filter": {"module": "DB"}
}

get_embeddings_stats

Returns ML model and vector store statistics.

Parameters: None

Returns:

• Model information (name, dimensions, status)
• Vector store metrics (total embeddings, by type)
• Graph statistics (nodes, edges)

Code Editing Tools

edit_file

Safely edit a single file with automatic backup, validation, and atomic operations.

Parameters:

• path (string, required): Path to the file to edit
• changes (array, required): List of changes to apply
  • type (string): replace, insert, or delete
  • line_start (integer): Starting line number (1-indexed)
  • line_end (integer): Ending line number (for replace/delete)
  • content (string): New content (for replace/insert)
• validate (boolean, optional): Validate syntax before applying (default: true)
• create_backup (boolean, optional): Create backup before editing (default: true)
• format (boolean, optional): Format code after editing (default: false)
• language (string, optional): Explicit language for validation (auto-detected from extension)

Example:

{
  "path": "lib/my_module.ex",
  "changes": [
    {
      "type": "replace",
      "line_start": 10,
      "line_end": 15,
      "content": "def new_function do\n  :ok\nend"
    }
  ],
  "validate": true,
  "format": true
}

edit_files

Atomically edit multiple files with coordinated rollback on failure.

Parameters:

• files (array, required): List of files to edit
  • path (string): Path to the file
  • changes (array): List of changes (same format as edit_file)
  • validate (boolean, optional): Override transaction-level validation
  • format (boolean, optional): Override transaction-level formatting
  • language (string, optional): Explicit language for this file
• validate (boolean, optional): Validate all files before applying (default: true)
• create_backup (boolean, optional): Create backups for all files (default: true)
• format (boolean, optional): Format all files after editing (default: false)

Example:

{
  "files": [
    {
      "path": "lib/module_a.ex",
      "changes": [{"type": "replace", "line_start": 5, "line_end": 5, "content": "@version \"2.0.0\""}]
    },
    {
      "path": "lib/module_b.ex",
      "changes": [{"type": "replace", "line_start": 10, "line_end": 12, "content": "# Updated"}]
    }
  ],
  "validate": true,
  "format": true
}

validate_edit

Preview validation of changes without applying them.

Parameters:

• path (string, required): Path to the file
• changes (array, required): List of changes to validate
• language (string, optional): Explicit language for validation

rollback_edit

Undo a recent edit by restoring from backup.

Parameters:

• path (string, required): Path to the file to rollback
• backup_id (string, optional): Specific backup to restore (default: most recent)

edit_history

Query backup history for a file.

Parameters:

• path (string, required): Path to the file
• limit (integer, optional): Maximum number of backups to return (default: 10)

refactor_code

Semantic refactoring operations using AST analysis and knowledge graph.

Parameters:

• operation (string, required): Type of refactoring - rename_function or rename_module
• params (object, required): Operation-specific parameters
  • For rename_function:
    • module (string): Module containing the function
    • old_name (string): Current function name
    • new_name (string): New function name
    • arity (integer): Function arity
  • For rename_module:
    • old_name (string): Current module name
    • new_name (string): New module name
• scope (string, optional): module (same file only) or project (all files, default: project)
• validate (boolean, optional): Validate before/after (default: true)
• format (boolean, optional): Format code after (default: true)

Example - Rename Function:

{
  "operation": "rename_function",
  "params": {
    "module": "MyModule",
    "old_name": "old_function",
    "new_name": "new_function",
    "arity": 2
  },
  "scope": "project",
  "validate": true,
  "format": true
}

Example - Rename Module:

{
  "operation": "rename_module",
  "params": {
    "old_name": "OldModule",
    "new_name": "NewModule"
  },
  "validate": true
}

RAG (AI-Powered) Tools

rag_query

Query the codebase using Retrieval-Augmented Generation with AI assistance.

Parameters:

• query (string, required): Natural language query about the codebase
• limit (integer, optional): Maximum number of code snippets to retrieve (default: 10)
• include_code (boolean, optional): Include full code snippets in context (default: true)
• provider (string, optional): AI provider override (deepseek_r1)

Example:

{
  "query": "How does authentication work in this codebase?",
  "limit": 15,
  "include_code": true
}

Returns:

• AI-generated response based on retrieved code context
• Sources count and model information

rag_explain

Explain code using RAG with AI assistance and aspect-focused analysis.

Parameters:

• target (string, required): File path or function identifier (e.g., MyModule.function/2)
• aspect (string, optional): What to explain - purpose, complexity, dependencies, or all (default: all)

Example:

{
  "target": "Ragex.Graph.Store.add_node/3",
  "aspect": "complexity"
}

Returns:

• AI-generated explanation based on code analysis
• Related code context and dependencies

rag_suggest

Suggest code improvements using RAG with AI analysis.

Parameters:

• target (string, required): File path or function identifier
• focus (string, optional): Improvement focus - performance, readability, testing, security, or all (default: all)

Example:

{
  "target": "lib/ragex/editor/core.ex",
  "focus": "performance"
}

Returns:

• AI-generated improvement suggestions
• Code context and rationale

Configuration:

RAG tools require the DEEPSEEK_API_KEY environment variable:

export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxx"

Documentation

• CI / Diff-Based Analysis - PR analysis, GitHub Actions, mix ragex.ci
• Using Ragex as MCP Server - Installation, client setup, RAG queries, configuration
• Usage Guide - Editor-specific integration (VIM, LunarVim)
• Zed Editor Integration - First-class Zed support with tasks and keybindings
• Configuration - Embedding model configuration and migration
• MCP Tools Reference - Complete tool parameter reference
• Algorithms - Graph algorithms and complexity
• Analysis - Code analysis features and tools
• Refactoring Suggestions - Automated refactoring suggestion engine
• Persistence - Embedding cache management and performance
• MCP Prompts - Pre-built high-level workflows
• MCP Resources - Read-only state access
• Streaming Notifications - Real-time progress events
• Troubleshooting - Common issues and error messages

Cache Management

Ragex automatically caches embeddings for faster startup:

# View cache statistics
mix ragex.cache.stats

# Clear current project cache
mix ragex.cache.clear --current

# Clear all caches
mix ragex.cache.clear --all --force

TODO: Streaming Enhancements

The following streaming improvements are planned but not yet implemented:

• Tool-call delta parsing in providers: Currently, streaming parsers for all four providers (DeepSeek, OpenAI, Anthropic, Ollama) silently skip tool_calls deltas in the SSE stream. Adding index-based function.arguments accumulation would allow real-time thinking tokens even during intermediate tool-call steps in the agent loop. This requires per-provider work (OpenAI/DeepSeek: delta.tool_calls[i]; Anthropic: content_block_start + input_json_delta; Ollama: not supported by API).

• Full MCP streaming protocol: Emit individual JSON-RPC streaming responses (not just notifications) per chunk, allowing MCP clients to render responses incrementally. Includes cancellation support via MCP protocol.

• Stream caching and replay: Cache reconstructed responses from consumed streams so that repeated queries can be served from cache without re-calling the AI provider.

Supported Languages

Everything that’s supported by metastatic