TUTORIAL • DEVOPS • AI

Local GraphRAG with HelixDB & Docker

Bypass LLM context limits with a fully local, on-premise GraphRAG architecture. Index your entire codebase into HelixDB and let AI agents query it surgically via MCP tools.

Key Benefits

Why GraphRAG Changes Everything

Large Language Models (LLMs) are revolutionizing software development. However, regardless of whether you use powerful open-source models like Qwen or Llama, or commercial APIs, they all hit a physical hard stop: the context window limit.

Attempting to cram an entire enterprise codebase into a single prompt degrades response quality, exhausts memory limits, and inevitably leads to AI hallucinations.

The enterprise-grade solution to this bottleneck is GraphRAG (Graph Retrieval-Augmented Generation). Instead of passively dumping your repository into a prompt, a hybrid graph and vector database like HelixDB stores your code intelligently as a structural network. Your AI coding agent (such as VS Code Cline) can then surgically query exactly the relevant code snippets it needs via Model Context Protocol (MCP) tools.

This guide walks you through setting up this powerful architecture from scratch. It is completely local, fully on-premise, and guarantees absolute data privacy for your source code.

Prerequisites

Before diving into the setup, ensure your development environment has Docker and Docker Compose running on a Linux server, macOS, or Windows via WSL2, plus Python 3.10 or newer installed on your primary development machine.

Step 1: Deploying HelixDB via Docker Compose

In modern production architectures, HelixDB relies on a high-performance storage engine backed by object storage. To persist your graph data reliably on your local machine, we will deploy a local, S3-compatible MinIO container as the storage layer right alongside the HelixDB core engine.

1.1 Prepare Directory Structure and Permissions

Before spinning up the containers, we must create the local directories and assign the correct write permissions. This prevents frustrating access denied errors down the line.

Open your terminal and execute:

mkdir helixdb-docker && cd helixdb-docker
mkdir data
chmod 777 data

1.2 The Docker Compose Configuration

Create a docker-compose.yml file inside your helixdb-docker folder.

Note: We expose MinIO on ports 9090 and 9091 externally to prevent conflicts with other common local developer tools, while internal container routing remains on port 9000.

version: '3.8'
services:
  minio:
    image: minio/minio
    container_name: helix-minio
    command: server /data --console-address ':9001'
    restart: unless-stopped
    environment:
      MINIO_ROOT_USER: admin_user
      MINIO_ROOT_PASSWORD: secure_password_123
    volumes:
      - ./data:/data
    ports:
      - '9090:9000'
      - '9091:9001'
  minio-setup:
    image: minio/mc
    container_name: helix-minio-setup
    depends_on:
      - minio
    entrypoint: >
      /bin/sh -c "
      sleep 5;
      mc alias set myminio http://minio:9000 admin_user secure_password_123;
      mc mb --ignore-existing myminio/helix-storage-bucket;
      exit 0;
      "
  helix:
    image: ghcr.io/helixdb/enterprise-dev:latest
    container_name: helix-db
    restart: unless-stopped
    ports:
      - '6969:8080'
    depends_on:
      - minio-setup
    environment:
      - S3_BUCKET=helix-storage-bucket
      - S3_REGION=us-east-1
      - DB_PATH=/
      - AWS_ACCESS_KEY_ID=admin_user
      - AWS_SECRET_ACCESS_KEY=secure_password_123
      - AWS_ENDPOINT=http://minio:9000
      - AWS_ALLOW_HTTP=true
      - AWS_S3_FORCE_PATH_STYLE=true

Launch the database network:

docker compose up -d

Step 2: The Bulletproof Python Virtual Environment

We need to create an isolated Python virtual environment (venv) inside your actual codebase workspace. To prevent the notorious environment ghosting where pip accidentally installs packages globally instead of inside your virtual environment, we strictly use the absolute path to the local Python executable.

Navigate to your source code directory in your terminal and run the commands for your OS:

For Windows Users (PowerShell):

python -m venv venv
.venvScriptsActivate.ps1
.venvScriptspython.exe -m pip install --upgrade pip
.venvScriptspython.exe -m pip install mcp
.venvScriptspython.exe -m pip install git+https://github.com/HelixDB/helix-db.git#subdirectory=sdks/python

For Linux / macOS Users (Bash/Zsh):

python3 -m venv venv
source venv/bin/activate
./venv/bin/python3 -m pip install --upgrade pip
./venv/bin/python3 -m pip install mcp
./venv/bin/python3 -m pip install git+https://github.com/HelixDB/helix-db.git#subdirectory=sdks/python

Step 3: Building the Universal Workspace Indexer

Large enterprise projects contain compiled binaries (.dll), images, and heavy dependency folders (node_modules). Feeding these to an AI ruins the vector embeddings. We solve this by writing a Python script featuring a Blacklist and a Delta-Sync mechanism (calculating MD5 hashes so only modified files are synced).

Create index_repo.py in your workspace root. The script walks your workspace, filters out binaries and ignored directories, and syncs only changed files to HelixDB using MD5 hashes for delta detection.

Key Tip: Run this script using the direct python path (.venv/Scripts/python.exe index_repo.py or ./venv/bin/python3 index_repo.py) to avoid environment ghosting.

Step 4: Connecting the AI via Model Context Protocol (MCP)

To allow AI agents to navigate the database, we build an MCP Bridge. This provides the agent with two explicit capabilities: a search engine to locate files by keyword, and a reader to extract the exact code.

Create helix_mcp.py in your workspace. The bridge exposes two MCP tools:

• search_codebase_by_keyword(keyword) - Searches the codebase for specific concepts, variables, or class names. Returns matching file paths.
• get_file_content_by_name(filename) - Reads the exact, full source code of a specific file from the database.

Register this server in your AI assistant's configuration (e.g., cline_mcp_settings.json), ensuring you point the command directly to the python executable inside your venv folder.

Step 5: Taming the AI Agent (System Prompts)

AI coding agents are inherently lazy. They will try to guess code implementations or rely on their default, inefficient local file-search tools. We must explicitly forbid this behavior.

Create a .clinerules file in your workspace root to force the agent into the GraphRAG workflow with three strict rules:

1. No local file system searches - The agent is strictly forbidden from using default tools like read_file, list_dir, or search_files.
2. Zero hallucination policy - The agent must query the database to retrieve ground truth, never guess implementations.
3. Iterative discovery - If a retrieved file references an unknown class, the agent must use its tools iteratively to map out the architecture before answering.

Step 6: The End-to-End Test Scenario

Let's prove the architecture works. Create a dummy file named vulnerable_logic.py in your workspace with a deliberate security bug, then run your indexer script to push it into HelixDB.

Challenge the Agent

Open your AI assistant and prompt:

Find out where transactions are processed in the app. Analyze the authorization logic, identify the security vulnerability, and provide a patch.

The Result

Instead of blindly searching your hard drive or hallucinating a generic Python script, the agent will:

1. Call search_codebase_by_keyword('transaction').
2. Identify vulnerable_logic.py from the database payload.
3. Call get_file_content_by_name('vulnerable_logic.py').
4. Instantly spot the inverted comparison operator and provide the correct fix.

You have successfully bypassed context limits. Your codebase remains 100% private, and your AI assistant now has the precise, surgical memory required for enterprise-scale engineering.

Ready to Supercharge Your AI Workflow?

Deploy HelixDB today and give your AI agents surgical precision over your entire codebase — without ever sending a single line of code to the cloud.