raphaelmansuy/edgequake

EdgeQuake – Graph‑RAG in a single Rust binary

What it is – EdgeQuake is an open‑source Retrieval‑Augmented Generation (RAG) system that stores documents as a knowledge graph instead of only as flat text vectors. It is written in Rust, ships as one executable, and uses a single PostgreSQL instance (with the pgvector and Apache AGE extensions) for both vector embeddings and graph data. Any LLM that speaks the OpenAI/Anthropic API can be used – from cloud services (OpenAI, Anthropic, Gemini, Mistral) to local servers (Ollama, LM Studio, oMLX, llama.cpp, vLLM‑MLX, etc.).

---

How it works (high‑level flow)

Document → chunking → LLM extracts entities & relations → stored as:
   • embeddings in pgvector
   • graph nodes/edges in Apache AGE

Query → keyword extraction → vector search + graph walk → LLM generates answer

The system supports several retrieval modes (naive, local, global, hybrid (default), mix, bypass) that blend pure vector similarity with graph traversal to surface answers that depend on relationships between concepts.

---

Quick start (Docker‑only, no Rust/Node needed)

# One‑liner pulls the helper script, runs the Docker compose and starts the UI
curl -fsSL https://raw.githubusercontent.com/raphaelmansuy/edgequake/edgequake-main/quickstart.sh | sh

• UI: http://localhost:3000
• REST API (Swagger): http://localhost:8080/swagger-ui
• Health endpoint: http://localhost:8080/health

You can also run head‑less in CI:

quickstart.sh --yes --provider ollama
quickstart.sh --yes --provider omlx --base-url http://host.docker.internal:9050

Upload a PDF via the UI or the API and ask a question:

curl -X POST http://localhost:8080/api/v1/documents/upload -F "file=@my.pdf"
curl -X POST http://localhost:8080/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"query":"What are the main concepts?","mode":"hybrid"}'

---

Choosing a language model

Goal	Provider	How to configure
Best quality, no hardware	OpenAI, Anthropic, Gemini, Mistral	Settings → Connections or env vars (e.g. OPENAI_API_KEY)
Private, runs locally	Ollama, LM Studio, oMLX, MLX‑LM, llama.cpp, vLLM‑MLX	Same UI or env vars (EDGEQUAKE_PROVIDER=ollama)
Mix cloud LLM + local embeddings	Any cloud LLM + local embedding server	Set EDGEQUAKE_EMBEDDING_PROVIDER
Custom gateway	Any OpenAI‑compatible endpoint	Use the generic provider docs

Each workspace can assign a different model to each role (extraction, query, summarisation, embedding, vision, etc.). The edgequake doctor command and POST /api/v1/providers/test let you verify connectivity.

---

Production‑ready features

• Single datastore – PostgreSQL 16‑18 with pgvector (embeddings) and Apache AGE (graph). No separate vector DB or graph DB to manage.
• Safe migrations – Explicit edgequake migrate command; migrations are replay‑tested for every release.
• Security – Loopback‑only default, AES‑256‑GCM encrypted provider keys, optional SSO (Keycloak/OIDC), audit logging, multi‑tenant workspace isolation.
• PDF vision pipeline – Text extraction via embedded pdfium; optional vision mode for scanned tables and complex layouts.
• Health checks – /health probes real LLM providers; edgequake doctor checks DB, schema, and security posture.
• Multi‑arch Docker images – linux/amd64 and linux/arm64 published on GHCR.

---

Benchmarks (honest numbers)

Metric	EdgeQuake	LightRAG (Python)	Verdict
Answer accuracy	0.792	0.786	Statistical tie
Cold‑query p50 latency	4447 ms	4359 ms	≈ tied
Warm‑query p50 (cached)	82 ms	993 ms	EdgeQuake much faster
Evidence recall	0.932	0.949	LightRAG slightly ahead

The authors stress that EdgeQuake matches LightRAG’s retrieval quality while offering a production‑grade Rust implementation, faster cached responses, and a richer feature set.

---

Ecosystem & integrations

• SDKs – Python, TypeScript, Rust, plus community SDKs for Go, Java, Kotlin, C#, PHP, Ruby, Swift.
• AI agents – MCP server for agent orchestration.
• Apps – Ready‑to‑use integrations with OpenWebUI and LangChain.
• API – OpenAPI 3.0 spec, SSE streaming, batch ingestion, Swagger UI.

---

Documentation & learning resources

• Visual tour of the web UI (tutorial/README.md).
• Full Getting started guide, first‑RAG‑app tutorial, and provider configuration docs.
• Deep‑dive into the LightRAG algorithm and EdgeQuake architecture.
• Operations docs: deployment, Docker options, monitoring, runtime auth hardening, upgrade procedures, troubleshooting.

---

Who might use it?

• Enterprises that need a self‑hosted RAG stack with strict data isolation and auditability.
• Developers building AI agents or chat‑bots that require relationship‑aware retrieval (e.g., “who reports to whom”).
• Researchers wanting to experiment with Graph‑RAG without managing multiple services.
• Teams that already run PostgreSQL and prefer a single binary for easier ops.

---

License

Apache License 2.0 (2024‑2026 © Raphaël Mansuy).

---

TL;DR

EdgeQuake gives you a Rust‑native, single‑binary RAG platform that stores documents as a knowledge graph in PostgreSQL, lets you plug in any LLM (cloud or local), and provides a ready‑made UI, REST API, SDKs, and production‑grade security and upgrade mechanisms. It’s a practical way to try Graph‑RAG without the operational overhead of separate vector and graph databases.