edgequake

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

Headless / CI (no interactive terminal):

# 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.26.5 sh quickstart.sh

What's new in 0.26.4

Patch: SPEC-144 Next.js 16.3.3 Active LTS (August Critical RCEs) + proxy SSOT; SPEC-140/141 list completeness; SPEC-122 bulk-ingest honesty; health poll off by default; distroless API. No new migration (schema stays 149). Pull GHCR 0.26.4 for the patched frontend image.

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

What's new in 0.26.3

Patch: SPEC-139 mid-cutover engine (iw2 21000, W3 coverage-sum, KV remainder after 119-before-122); Langfuse 3.22/3.225 isolated OTLP stacks. No new migration (schema stays 149). Pull GHCR 0.26.3 — do not stay on 0.26.1 for leftover DROP OLD copy.

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

What's new in 0.26.2

Patch: Langfuse 3.1.x ingestion fallback (SPEC-124), Kubernetes Helm/kind (SPEC-138), SSE/conversation restore, workspace include_stats. No new migration (schema stays 149). Pull GHCR 0.26.2.

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

What's new in 0.26.1

Patch: SPEC-137 migrate honesty (--drop-confirm alias, unknown apply flags fail-closed, classified DROP abort hints). No new migration (schema stays 149). Pull GHCR 0.26.1 — the 0.26.0 image still has the old CLI.

Upgrade: upgrade-to-0.26.1.md · leftover 091: upgrade-to-0.26.0.md · changelog: CHANGELOG.md.

What's new in 0.26.0

Minor: PDF pack-to-budget (SPEC-135), manuscript page-as-unit convert (SPEC-134), Langfuse dev sibling (SPEC-124), wizard persist honesty (SPEC-101), and reliability (#377, #383–#386 + mig 149). Crates.io: edgequake-llm 0.10.8, edgequake-pdf2md 0.9.11, edgequake-sdk 0.4.0.

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

What's new in 0.25.0

Minor: Langfuse OTLP/HTTP (SPEC-124), structure-aware markdown pack (SPEC-125), provider KV / prompt cache (SPEC-126), PDF layout overlay (SPEC-128 + mig 148), omit-temperature / Responses API (SPEC-131 / #379), multi-PDF admit honesty (#378), document status CHECK SSOT (#381), fleet-mirror UUID + target--> parse (#380 / SPEC-133). Crates.io deps: edgequake-llm 0.10.8, edgequake-pdf2md 0.9.11.

Upgrade: upgrade-to-0.25.0.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-20260815T110218Z): Acc EQ 0.792 vs LR 0.786 (Δ Acc 95% CI [-0.022, +0.034] — statistical tie; L2 promote gates unmet — 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 [email protected]   # 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 "[email protected]"

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 (