GraphRAG LlamaIndex

Full-stack GraphRAG engine optimized for local indexing and lightweight cloud querying. Built on DuckDB, LlamaIndex, and the Model Context Protocol (MCP).

1. Context

This project implements a Decoupled Architecture:

• Indexer (Image A): Heavy-duty ML environment (PyTorch, GLiNER) for local graph construction.

• Query (Image B): Lightweight API environment (Node.js, DuckDB) for fast cloud deployment (~1GB footprint).

2. Building the Images

# Build specialized images via Docker Compose
docker compose build

3. Running Indexer & Query

Load the shell aliases for the fastest workflow:

• macOS (Zsh): source .graphrag-alias.zsh

• WSL/Bash: source .graphrag-alias.sh

• PowerShell: . .\.graphrag-alias.ps1

Indexing Documents

# 1. Initialize a database entry
graphrag start my_project --source /app/documents/source_files

# 2. Run the ingestion pipeline (Indexer Image)
graphrag index my_project [--reset] [--prune]

Querying

# CLI Search (Query Image)
graphrag search my_project "What are the common themes?"

# Start MCP Server for Agents
docker compose up query

4. Deployment Folder

• deployment/fly/: Scripts for zero-latency hosting on Fly.io (optimized for free-tier fly-machines).

• deployment/aws/: Infrastructure scripts for ECR, S3 backups, and App Runner deployments.

5. Setup & Configuration

Environment (.env)

Copy .env.example and set:

• OPENAI_API_KEY: For LLM reasoning and extraction.

• DOCUMENTS_HOME: Absolute path to your local data folder (mapped to /app/documents in Docker).

Engine Configuration (core/graphrag_config.py)

Tweak these parameters to refine performance:

• SearchType: Switch between entity_connections (graph-heavy) or thematic_overview (summary-heavy).

• ExtractionMode: Choose llm (creative) or gliner (fast/cost-effective).

6. Local Integration & Testing

Integrate this project as an MCP Server in Desktop Agents (Claude Desktop, Cursor, etc.) to give them memory of your documents.

Add to your MCP Config:

{
  "mcpServers": {
    "graphrag": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "C:/Users/<USER>/.graphrag:/root/.graphrag",
        "graphrag-query"
      ]
    }
  }
}

7. Database Cheatsheet

Core Commands

• graphrag list: Show all registered databases.

• graphrag status <db>: Check entity/relationship counts and health.

• graphrag delete <db> [--files]: Unregister database entry and optionally remove physical files.

• graphrag index <db> [--reset]: Index documents into database (use --reset to skip duplicate checks).

Managed Storage Workflow

To keep your project portable, move database files into a Managed/ folder inside your data directory.

Manual Move:

1. Move your_db.duckdb to [DOCUMENTS_HOME]/Managed/.

2. Re-register the path:

graphrag register my_db --db-path /app/documents/Managed/your_db.duckdb

For S3 management see S3_CHEATSHEET.md.