EdgeQuake

High-Performance Graph-RAG Framework in Rust
Transform documents into intelligent knowledge graphs for superior retrieval and generation

Quick Start

No Rust, no Node.js, no build. Just Docker.

curl -fsSL https://raw.githubusercontent.com/raphaelmansuy/edgequake/edgequake-main/quickstart.sh | sh

The wizard guides you through provider selection (OpenAI / Ollama), model choice, and starts the full stack.
Open http://localhost:3000 and you're in — no login required (quickstart runs with open API via EDGEQUAKE_DEV_MODE=true).

Ports: Docker quickstart maps the Web UI to http://localhost:3000. Local make dev defaults to http://localhost:3010 (avoids collisions with other stacks).

curl -fsSL https://raw.githubusercontent.com/raphaelmansuy/edgequake/edgequake-main/docker-compose.quickstart.yml \
  -o docker-compose.quickstart.yml
docker compose -f docker-compose.quickstart.yml up -d

# OpenAI
EDGEQUAKE_LLM_PROVIDER=openai \
  OPENAI_API_KEY=sk-... \
  docker compose -f docker-compose.quickstart.yml up -d

# Ollama (on host)
EDGEQUAKE_LLM_PROVIDER=ollama \
  EDGEQUAKE_LLM_MODEL=gemma4:e4b \
  EDGEQUAKE_EMBEDDING_PROVIDER=ollama \
  OLLAMA_EMBEDDING_MODEL=embeddinggemma \
  docker compose -f docker-compose.quickstart.yml up -d

*Local make dev picks free ports starting at 8090 (API) / 3010 (UI); see make status for the bound ports. Verify:

curl -s http://localhost:8080/health | python3 -m json.tool

Pin a version: EDGEQUAKE_VERSION=0.24.4 sh quickstart.sh

What's new in 0.24.4

Patch: partner reliability (#370 PDF matrix honesty, #374 legacy_vector_id race, #375 delete citation indexes, #376 injection IDs), SPEC-123 env/config cascade, SPEC-122 admit honesty, SPEC-114/015V/116/117 KG + vision + extract budget. Migrations 145–147.

Upgrade: upgrade-to-0.24.4.md · changelog: CHANGELOG.md.

What's new in 0.24.0

Database migration (read this first)

The API never migrates the database. Schema changes are an explicit operator step.

Irreversible drops (125 KV, 126/131 vectors) need --confirm-drop and a backup; rollback after that is restore-only. Migration 142 asserts empty leftovers (aborts if rows remain; deferred while residue exists).

Full plain-language guide: Migrate to v0.23.0+ · production soak: SPEC-091 upgrade runbook.

Highlights

• SPEC-104 production data-layer monitors — StorageInspector uses workspace_id + PostgresConfig AGE graph SSOT; no 42703 / 42P01 probes; INV-03 dual-read; tenant create 201/200/409.
• SPEC-105 legacy cutover assert — census SSOT; unknown VECTOR_BACKEND → typed; migration 142; mid-upgrade deferral so expandables soft-exit while residue remains.
• Schema — migrations through 142 (0.23.0 stopped at 141).

Also in 0.23.0: SPEC-091 relational cutover (106–141), LD-15 boot gate, SPEC-094 parse API, SPEC-103 LLM cache, wizard/UX. 0.22.0: SPEC-090 multi-pool + migrate CLI.

Performance testing

Publish Acc is medical-mid n=200 (make bench) — not smoke n=40. Latest publish pack (medical-mid-20260812T004216Z): Acc EQ 0.783 vs LR 0.774 (Δ Acc 95% CI [-0.052, +0.118] — statistical tie; L2 incomplete — do not claim EQ beats LightRAG / Acc Beat). Fair cold latency ratio 1.02× (C1COLD_v1). Smoke peers remain CI/ablation references only. Required local pre-tag gate: see Release & CD § SPEC-001.

• EQ vs LightRAG Acc Bench — measured scorecard
• BUSINESS_REPORT.md — regenerated by make bench (n=200)
• EXEC_SUMMARY.txt
• peers.json
• Protocol: 000-index · 001-first-principles
• Context: 055 · 063

Authentication (v0.15+)

From v0.15, the API enables authentication secure by default (SPEC-027). Identity lives in PostgreSQL; login requires at least one user with a real password hash.

Enable login on Docker / production:

export EDGEQUAKE_DEV_MODE=false
export EDGEQUAKE_AUTH_ENABLED=true
export EDGEQUAKE_BOOTSTRAP_ADMIN_USERNAME=admin
export EDGEQUAKE_BOOTSTRAP_ADMIN_PASSWORD='ChangeMe123!'   # min 8 chars, mixed complexity
export EDGEQUAKE_BOOTSTRAP_ADMIN_EMAIL=admin@example.com   # optional
export NEXT_PUBLIC_AUTH_ENABLED=true
export NEXT_PUBLIC_DISABLE_DEMO_LOGIN=true
docker compose -f docker-compose.quickstart.yml up -d

The API creates the bootstrap admin on startup. Sign in at http://localhost:3000/login (Docker quickstart) or http://localhost:3010/login (make dev).

Upgrades from pre-v0.15: legacy KV auth:user:* records are imported into PostgreSQL automatically when present.

See Runtime Auth Hardening for master API keys, OIDC, and troubleshooting (GitHub #288).

Ingestion cancel & restart (v0.19+)

From v0.19, cancel and restart are durable (SPEC-057): UI shows Stopping… until terminal Cancelled (not Failed); Pending tasks survive process restart via Postgres claim/lease (FOR UPDATE SKIP LOCKED). See Ingestion cancel and fairness.

First Steps

Upload a document (PDF, TXT, MD):

curl -X POST http://localhost:8080/api/v1/documents/upload \
  -F "file=@your-document.pdf"

Or drag-and-drop in the Web UI at http://localhost:3000 (Docker) or http://localhost:3010 (make dev).

Query the knowledge graph:

curl -X POST http://localhost:8080/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the main concepts?", "mode": "hybrid"}'

Why EdgeQuake?

Traditional RAG retrieves document chunks by vector similarity alone. This works for keyword lookups but fails on multi-hop reasoning, thematic questions, and relationship queries. Vectors capture similarity but lose structural relationships.

EdgeQuake implements the LightRAG algorithm in Rust: documents are decomposed into a knowledge graph of entities and relationships. At query time, the system traverses both the vector space and the graph structure — combining the speed of embeddings with the reasoning power of graph traversal.

Features

Knowledge Graph

• Entity Extraction — LLM-powered detection of people, organizations, locations, concepts, technologies, and products
• Relationship Mapping — Automatic identification of connections with keyword tagging
• Multi-Pass Gleaning — Second-pass extraction catches 15-25% more entities
• Community Detection — Louvain clustering groups related entities for thematic queries
• Custom Entity Types — 5 domain presets (General, Manufacturing, Healthcare, Legal, Research), up to 50 types per workspace
• Knowledge Injection — Domain glossaries, acronym definitions, and synonym mappings

Query Engine — 6 Modes

Hybrid RAG (v0.16 / SPEC-046)

Production Hybrid RAG with fail-closed ops and science-grade retrieval defaults:

• PPR-default graph walk — Personalized PageRank expands entity neighborhoods (EDGEQUAKE_GRAPH_WALK=bfs escape hatch)
• Bipartite dual-node pick — entity∪chunk adjacency for Local / Global / Mix chunk selection
• HNSW fail-closed + /ready — missing ANN index blocks traffic instead of silent degradation
• Intent-gated Mix/Hybrid arms — skip irrelevant retrieval arms; GenAI rag.retrieval spans
• Failed-chunk retry → merge — persist / list / retry extraction failures into the knowledge graph
• Faithfulness sampling — heuristic + optional LLM judge (EDGEQUAKE_FAITHFULNESS_JUDGE)
• ACC CI gate — make spec046-acc writes a deterministic AccReport JSON (no API key)

Ops runbooks: specs/046-graphrag-study/13-OPS-RUNBOOKS.md.

PDF Vision Pipeline

• Text Mode — Fast pdfium-based extraction (default, zero-config, embedded in binary)
• Vision Mode — GPT-4o, Claude, Gemini read each page as an image
• Table Reconstruction — Recovers complex tables that text parsers mangle
• Multi-Column Layout — LLM understands reading order across columns
• Automatic Fallback — Vision failures gracefully fall back to text extraction

Production Ready

• REST API — OpenAPI 3.0, SSE streaming, batch ingestion, health checks
• Multi-Tenant — Fail-closed workspace isolation for query, delete, and recovery
• Auth & Audit — Built-in authentication, authorization, and compliance logging
• PostgreSQL 16/17/18 — Triple-track support with pgvector + Apache AGE
• Multi-Arch Docker — linux/amd64 + linux/arm64, published to GHCR on every release
• MCP Integration — Expose capabilities to AI agents via Model Context Protocol
• React 19 Frontend — Real-time streaming, interactive Sigma.js graph visualization, drag-and-drop upload

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│  Frontend (React 19 + TypeScript)                                   │
│  Document Upload · Query Interface · Graph Visualization · Config   │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│  REST API (Axum)                                                    │
│  /api/v1/documents · /api/v1/query · /api/v1/graph                  │
│  OpenAPI 3.0 · SSE Streaming · Health Checks                        │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
              ┌────────────────┴────────────────┐
              ▼                                 ▼
┌──────────────────────────┐   ┌────────────────────────────────────┐
│  LLM Providers           │   │  Storage                           │
│  OpenAI · Anthropic      │   │  PostgreSQL 16 / 17 / 18           │ 
│  Gemini · Mistral        │   │  ├─ pgvector (embeddings)          │
│  Ollama · LM Studio      │   │  └─ Apache AGE (knowledge graph)   │
│  xAI · Azure · VertexAI  │   │                                    │
└──────────────────────────┘   └────────────────────────────────────┘

Data flow: Document → Chunks → Entity Extraction → Knowledge Graph → Vector + Graph Storage
Query flow: Question → Graph Traversal + Vector Search → LLM → Answer with Sources

EdgeQuake is built from 11 Rust crates: edgequake-core, edgequake-storage, edgequake-api, edgequake-pipeline, edgequake-query, edgequake-pdf, edgequake-auth, edgequake-audit, edgequake-tasks, edgequake-rate-limiter, edgequake-observability. LLM providers are handled by the external edgequake-llm crate.

See Architecture Overview and LightRAG Algorithm Deep Dive.

Docker Deployment

Three options depending on your setup:

docker run -d --name edgequake -p 8080:8080 \
  -e DATABASE_URL="postgres://user:pass@your-db:5432/edgequake" \
  -e EDGEQUAKE_LLM_PROVIDER=openai \
  -e OPENAI_API_KEY="sk-..." \
  ghcr.io/raphaelmansuy/edgequake:latest

cd edgequake/docker
cp .env.example .env
docker compose -f docker-compose.prebuilt.yml up -d

# Pin full stack to this release
EDGEQUAKE_VERSION=0.24.4 docker compose -f docker-compose.quickstart.yml up -d

# Pin PostgreSQL major (optional; default tag follows EDGEQUAKE_VERSION → PG18)
EDGEQUAKE_VERSION=0.24.4 EDGEQUAKE_POSTGRES_TAG=0.21.0-pg16 \
  docker compose -f docker-compose.quickstart.yml up -d

cd edgequake/docker && docker compose up -d

gcloud auth application-default login   # not: gcloud auth login application-default
export GOOGLE_CLOUD_PROJECT=your-gcp-project
export GOOGLE_CLOUD_REGION=europe-west1   # optional; default us-central1

SDKs

Development

For contributors building from source. Most users should use the Quick Start above.

git clone https://github.com/raphaelmansuy/edgequake.git && cd edgequake
make install
cp edgequake_webui/.env.local.example edgequake_webui/.env.local
make dev                        # Start full stack (PostgreSQL + Backend + Frontend)
# Web UI defaults to http://localhost:3010 — confirm with: make status

cd edgequake && cargo test --workspace --lib --locked   # Unit / lib suite
cargo clippy --workspace --lib --locked -- -D warnings
cargo fmt --all -- --check
cd .. && make status && make stop

Pre-delivery checklist (v0.19+)

Run these before tagging a release. Prefer Makefile targets — they set required env vars.

# Fast local gates (mirrors CI first principles: fail cheap → compile once → proofs)
make ops17-smoke                # PG extension pin SSOT (pg16/17/18)
make spec046-acc                # SPEC-046 ACC + AccReport JSON
make release-gates              # fmt + workspace clippy + SPEC-006/018 + WebUI + version parity
make test-e2e-lint              # Playwright flake anti-patterns
# SPEC-001 LightRAG Acc (local mandatory before tag — not in CI / release_gates.sh):
make bench001-doctor
make bench                      # EQ vs LightRAG Acc n=200 + publish/latest
# Optional UI-only (no backend): make test-e2e-ui

CI speed principles (see .github/workflows/ci.yml): shared cargo cache across jobs, CARGO_INCREMENTAL=0 + sparse index, --locked, cancel-in-progress, no duplicate workspace lib suite in sibling workflows, release gates skip per-crate clippy / lib re-run when CI already owns them.

See AGENTS.md for the full developer workflow and Release & CD for the release process.

Documentation

Full index: docs/README.md

Contributing

EdgeQuake uses a Specification-Driven Development approach. See CONTRIBUTING.md.

• GitHub Issues — Bug reports and feature requests
• GitHub Discussions — Questions and community help

Acknowledgments

EdgeQuake implements the LightRAG algorithm by Zirui Guo, Lianghao Xia, Yanhua Yu, Tu Ao, and Chao Huang. Also inspired by Microsoft's GraphRAG.

License

Apache License, Version 2.0 — see LICENSE.
Copyright 2024-2026 Raphaël MANSUY

Star History