EdgeQuake

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

---

Why EdgeQuake?

Traditional RAG systems retrieve document chunks using vector similarity alone. This works for simple lookups but fails on multi-hop reasoning ("How does X relate to Y through Z?"), thematic questions ("What are the major themes?"), and relationship queries. The core problem: vectors capture semantic similarity but lose structural relationships between concepts.

EdgeQuake solves this by implementing the LightRAG algorithm in Rust: documents are not just chunked and embedded — they 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 vector search with the reasoning power of graph traversal.

What Sets EdgeQuake Apart

• Knowledge Graphs: LLM-powered entity extraction and relationship mapping create a structured understanding of your documents — not just keyword matching
• 6 Query Modes: From fast naive vector search to graph-traversing hybrid queries, each mode optimizes for different question types
• Rust Performance: Async-first Tokio architecture with zero-copy operations — handles thousands of concurrent requests
• Planned Advanced PDF Processing ⚠️ Available Soon: Table detection, multi-column layout, OCR with quality-based mode fallback
• Production Ready: OpenAPI 3.0 REST API, SSE streaming, health checks, multi-tenant workspace isolation
• Modern Frontend: React 19 with interactive Sigma.js graph visualizations

Performance Benchmarks

Metric	EdgeQuake	Traditional RAG	Improvement
Entity Extraction	~2-3x more	Baseline	3x
Query Latency (hybrid)	< 200ms	~1000ms	5x faster
Document Processing	25s (10k tokens)	~60s	2.4x faster
Concurrent Users	1000+	~100	10x
Memory Usage (per doc)	2MB	~8MB	4x better

⚠️ Experimental Feature — PDF Ingestion: PDF-to-Markdown extraction is currently in experimental/early prototype stage. For comprehensive testing and evaluation of EdgeQuake's core functionality (entity extraction, knowledge graphs, query modes, etc.), we recommend using Markdown documents in your initial setup. This ensures you can fully explore the stable features while we continue to refine the PDF processing pipeline.

---

Features

🚀 High Performance

• Async-First: Tokio-based runtime for maximum concurrency
• Zero-Copy: Efficient memory management with Rust ownership
• Parallel Processing: Multi-threaded entity extraction and embeddings
• Fast Storage: PostgreSQL AGE for graph + pgvector for embeddings

Knowledge Graph

• Entity Extraction: Automatic detection of people, organizations, locations, concepts, events, technologies, and products (7 configurable types)
• Relationship Mapping: LLM-powered relationship identification with keyword tagging
• Gleaning: Multi-pass extraction catches 15-25% more entities than single-pass
• Community Detection: Louvain modularity optimization clusters related entities for thematic queries
• Graph Visualization: Interactive Sigma.js-powered frontend with zoom/pan

📄 Advanced PDF Processing (⚠️ Available Soon)

• Text Mode: Fast extraction for text-based PDFs
• Vision Mode: OCR for scanned documents and images
• Hybrid Mode: Automatic quality assessment and fallback
• Table Detection: Enhanced detection for complex tables
• Multi-Column Layout: Accurate reading order detection

🔍 6 Query Modes

1. Naive: Simple vector similarity — fastest for keyword-like lookups (~100-300ms)
2. Local: Entity-centric with local graph neighborhood — best for specific relationships (~200-500ms)
3. Global: Community-based semantic search — best for thematic/high-level questions (~300-800ms)
4. Hybrid (default): Combines local + global for balanced, comprehensive results (~400-1000ms)
5. Mix: Weighted combination of naive + graph results with configurable ratios
6. Bypass: Direct LLM query without RAG retrieval — useful for general questions

🌐 REST API

• OpenAPI 3.0: Full Swagger documentation at /swagger-ui
• Streaming: Server-Sent Events (SSE) for real-time responses
• Versioned: /api/v1/* with backward compatibility
• Health Checks: Kubernetes-ready /health, /ready, /live

🎯 React 19 Frontend

• Real-Time Streaming: Token-by-token generation display
• Graph Visualization: Interactive network graph with zoom/pan
• Document Upload: Drag-and-drop with progress tracking
• Configuration UI: Visual PDF processing config builder

---

Quick Start

Prerequisites

• Rust: 1.78 or later (Install Rust)
• Node.js: 18+ or Bun 1.0+ (Install Node)
• Docker: For PostgreSQL (Install Docker)
• Ollama: For local LLM (optional, Install Ollama)

Installation (5 minutes)

# 1. Clone the repository
git clone https://github.com/raphaelmansuy/edgequake.git
cd edgequake

# 2. Install dependencies
make install

# 3. Start the full stack (PostgreSQL + Backend + Frontend)
make dev

That's it! 🎉

• Backend: http://localhost:8080
• Frontend: http://localhost:3000
• Swagger UI: http://localhost:8080/swagger-ui
• Provider: Ollama (local, free)

First Document Upload

# Upload a file (PDF, TXT, MD, etc.)
curl -X POST http://localhost:8080/api/v1/documents/upload \
  -F "file=@your-document.pdf"

Response:

{
  "id": "doc-123",
  "status": "completed",
  "chunk_count": 15,
  "entity_count": 12,
  "relationship_count": 8,
  "processing_time_ms": 2500
}

First Query

# 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"
  }'

Response:

{
  "answer": "The main concepts are: knowledge graphs, entity extraction, and hybrid retrieval...",
  "sources": [
    { "chunk_id": "chunk-1", "similarity": 0.92 },
    { "chunk_id": "chunk-5", "similarity": 0.87 }
  ],
  "entities": ["KNOWLEDGE_GRAPH", "ENTITY_EXTRACTION"],
  "relationships": [
    {
      "source": "KNOWLEDGE_GRAPH",
      "target": "ENTITY_EXTRACTION",
      "type": "ENABLES"
    }
  ]
}

---

Architecture

┌────────────────────────────────────────────────────────────────────────────┐
│                              EdgeQuake System                              │
└────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│  Frontend (React 19 + TypeScript)                                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │  Document    │  │    Query     │  │    Graph     │  │   Settings   │     │
│  │   Upload     │  │  Interface   │  │ Visualization│  │   Config     │     │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘     │
│         │                 │                 │                 │             │
│         └─────────────────┴─────────────────┴─────────────────┘             │
│                                    │                                        │
│                                    ▼                                        │
│  ┌────────────────────────────────────────────────────────────────────┐     │
│  │                         REST API (Axum)                            │     │
│  │  /api/v1/documents  •  /api/v1/query  •  /api/v1/graph             │     │
│  │  OpenAPI 3.0 Spec  •  SSE Streaming  •  Health Checks              │     │
│  └────────────────────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Backend (Rust - 11 Crates)                                                 │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │  edgequake-core          │  Orchestration & Pipeline                 │   │
│  │  edgequake-llm           │  OpenAI, Ollama, LM Studio, Mock          │   │
│  │  edgequake-storage       │  PostgreSQL AGE, Memory adapters          │   │
│  │  edgequake-api           │  REST API server                          │   │
│  │  edgequake-pipeline      │  Document ingestion pipeline              │   │
│  │  edgequake-query         │  Query engine (6 modes)                   │   │
│  │  edgequake-pdf           │  PDF extraction (text/vision/hybrid)      │   │
│  │  edgequake-auth          │  Authentication & authorization           │   │
│  │  edgequake-audit         │  Compliance & audit logging               │   │
│  │  edgequake-tasks         │  Background job processing                │   │
│  │  edgequake-rate-limiter  │  Rate limiting middleware                 │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                    ┌───────────────┴───────────────┐                        │
│                    ▼                               ▼                        │
│  ┌─────────────────────────────┐   ┌──────────────────────────────────┐     │
│  │   LLM Providers             │   │   Storage Backends               │     │
│  │  • OpenAI (gpt-4.1-nano)    │   │  • PostgreSQL 15+ (AGE + vector) │     │
│  │  • Ollama (gemma3:12b)      │   │  • In-Memory (dev/testing)       │     │
│  │  • LM Studio (local models) │   │  • Graph: Property graph model   │     │
│  │  • Mock (testing, free)     │   │  • Vector: pgvector embeddings   │     │
│  │  Auto-detection via env     │   │                                  │     │
│  └─────────────────────────────┘   └──────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────────────────┘

                    Data Flow: Document → Chunks → Entities → Graph
                    Query Flow: Question → Graph Traversal → LLM → Answer

How the Algorithm Works

EdgeQuake implements the LightRAG algorithm in Rust. The core insight: extract a knowledge graph during indexing, then traverse it during querying.

Indexing Pipeline (per document):

1. Chunk — Split document into ~1200-token segments with 100-token overlap
2. Extract — LLM parses each chunk into (entity, type, description) and (source, target, keywords, description) tuples
3. Glean — Optional second pass catches missed entities (improves recall by ~18%)
4. Normalize — Deduplicate entities via case normalization and description merging (reduces duplicates by ~36-40%)
5. Embed — Generate vector embeddings for chunks and entities
6. Store — Write to PostgreSQL: chunks to pgvector, entities/relationships to Apache AGE graph

Query Flow (6 modes):

• Naive — Vector similarity on chunks only (fast, no graph)
• Local — Find relevant entities via vector search, then traverse their local graph neighborhood
• Global — Use Louvain community detection to find thematic clusters, retrieve community summaries
• Hybrid (default) — Combine local entity context + global community context
• Mix — Weighted blend of naive vector results and graph-enhanced results
• Bypass — Skip retrieval entirely, pass question directly to LLM

See LightRAG Algorithm Deep Dive for the complete technical explanation.

---

Documentation

📚 Complete Documentation Index

Explore the full documentation at docs/README.md

📦 SDKs

EdgeQuake provides official SDKs for multiple languages:

• Python SDK (Changelog)
• TypeScript SDK (Changelog)
• Rust SDK
• Other SDKs for C#, Go, Java, Kotlin, PHP, Ruby, Swift

See the CHANGELOG.md for SDK and core updates.

🚀 Getting Started (15 minutes)

Guide	Description	Time
Installation	Prerequisites and setup	5 min
Quick Start	First ingestion and query	10 min
First Ingestion	Understanding the pipeline	15 min

📖 Tutorials (Hands-On)

Tutorial	Description
Building Your First RAG App	End-to-end tutorial
PDF Ingestion	PDF upload and configuration
Multi-Tenant Setup	Workspace isolation
Document Ingestion	Upload and processing workflows
Migration from LightRAG	Python to Rust migration guide

🏗️ Architecture (How It Works)

Document	Description
Overview	System design and components
Data Flow	How documents flow through the system
Crate Reference	11 Rust crates explained

💡 Core Concepts (Theory)

Concept	Description
Graph-RAG	Why knowledge graphs enhance RAG
Entity Extraction	LLM-based entity recognition
Knowledge Graph	Nodes, edges, and communities
Hybrid Retrieval	Combining vector and graph search

Deep Dives (Advanced)

Article	Description
LightRAG Algorithm	Core algorithm: extraction, graph, retrieval
Query Modes	6 modes explained with trade-offs
Entity Normalization	Deduplication and description merging
Gleaning	Multi-pass extraction for completeness
Community Detection	Louvain clustering for global queries
Chunking Strategies	Token-based segmentation with overlap
Embedding Models	Model selection and dimension trade-offs
Graph Storage	Apache AGE property graph backend
Vector Storage	pgvector HNSW indexing and search
PDF Processing	Text/Vision/Hybrid extraction pipeline
Cost Tracking	LLM cost monitoring per operation
Pipeline Progress	Real-time progress tracking

📊 Comparisons

Comparison	Key Insights
vs LightRAG (Python)	Performance and design differences
vs GraphRAG	Microsoft's approach comparison
vs Traditional RAG	Why graphs matter

API Reference

API	Description
REST API	HTTP endpoints
Extended API	Advanced API features

Operations (Production)

Guide	Description
Deployment	Production deployment
Configuration	All config options
Monitoring	Observability setup
Performance Tuning	Optimization guide

🐛 Troubleshooting

Guide	Description
Common Issues	Debugging guide
PDF Extraction	PDF-specific troubleshooting

🔗 Integrations

Integration	Description
OpenWebUI	Chat interface with Ollama emulation
LangChain	Retriever and agent integration
Custom Clients	Python, TypeScript, Rust, Go clients

📓 More Resources

• FAQ - Frequently asked questions
• Cookbook - Practical recipes
• Security - Security best practices

---

Development

Building and Testing

# Build backend
cd edgequake && cargo build --release

# Run tests
cargo test

# Lint and format
cargo clippy
cargo fmt

# Build frontend
cd edgequake_webui
bun run build

Make Commands

EdgeQuake uses a unified Makefile for all development tasks:

# Full development stack
make dev              # Start all services (PostgreSQL + Backend + Frontend)
make dev-bg           # Start in background (for agents/automation)
make dev-memory       # Start with in-memory storage (testing only)
make stop             # Stop all services
make status           # Check service status

# Backend only
make backend-dev      # Run backend with PostgreSQL
make backend-memory   # Run backend with in-memory storage
make backend-bg       # Run backend in background
make backend-test     # Run backend tests

# Frontend only
make frontend-dev     # Start frontend dev server
make frontend-build   # Build frontend for production

# Database
make db-start         # Start PostgreSQL container
make db-stop          # Stop PostgreSQL container
make db-wait          # Wait for database to be ready

# Quality checks
make test             # Run all tests
make lint             # Lint all code
make format           # Format all code
make clean            # Clean build artifacts

Agent Workflow

EdgeQuake development follows a Specification-Driven Development approach using the edgecode SOTA coding agent.

• AGENTS.md: Comprehensive agent guidelines and workflow
• specs/: All development specifications
• OODA Loop: Iterative development cycles (Observe, Orient, Decide, Act)

See AGENTS.md for detailed agent workflow documentation.

---

Contributing

EdgeQuake is developed using the edgecode SOTA coding agent created by Raphaël MANSUY. The project follows a Specification-Driven Development approach where all changes are specified in the specs/ directory before implementation.

Current Status: edgecode is not yet public but will be released soon.

For now, contributions should go through Raphaël MANSUY directly:

• GitHub Issues: Report bugs and request features
• GitHub Discussions: Ask questions and share ideas
• Direct Contact: For major contributions, contact @raphaelmansuy

See CONTRIBUTING.md for detailed contribution guidelines.

---

Community & Support

Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please read our Code of Conduct.

Support Channels

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: Questions and community help
• LinkedIn: @raphaelmansuy
• Twitter/X: @raphaelmansuy

Founder

Raphaël MANSUY 🇫🇷 - 🇭🇰🇨🇳 — Permanent Resident of Hong Kong, building the future of intelligent document retrieval systems and context graph systems.

---

License

Licensed under the Apache License, Version 2.0 (the "License").
You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the LICENSE file for the specific language governing permissions and limitations.

Copyright © 2024-2026 Raphaël MANSUY

---

Acknowledgments

EdgeQuake is inspired by and builds upon the excellent work of:

• LightRAG Research Paper (arxiv.org/abs/2410.05779): We are grateful to the authors of the foundational LightRAG algorithm which powers the core knowledge graph extraction and retrieval capabilities in EdgeQuake. Their innovative approach to entity extraction, relationship mapping, and hybrid retrieval has been instrumental in our framework's design.

  Special thanks to the LightRAG authors:

  • Zirui Guo
  • Lianghao Xia
  • Yanhua Yu
  • Tu Ao
  • Chao Huang

• GraphRAG (arxiv.org/abs/2404.16130): Microsoft's "From Local to Global" knowledge graph approach to query-focused summarization.

  • Shuai Wang
  • Yingqiang Ge
  • Ying Shen
  • Jianfeng Gao
  • Xiaodong Liu
  • Yelong Shen
  • Jianfeng Wang
  • Ming Zhou

• Rust Community: For the amazing async ecosystem (Tokio, Axum, SQLx) that enables EdgeQuake's high performance

• React Community: For React 19 and the modern frontend stack that powers our interactive UI

---

Quick Links

Resource	URL
📚 Full Documentation	docs/README.md
🚀 Quick Start Guide	docs/getting-started/quick-start.md
📦 SDKs Overview	sdks/
🐍 Python SDK	sdks/python/README.md
🦀 Rust SDK	sdks/rust/README.md
🟦 TypeScript SDK	sdks/typescript/README.md
📜 CHANGELOG	CHANGELOG.md
🔧 Agent Workflow	AGENTS.md
🤝 Contributing	CONTRIBUTING.md
📜 Code of Conduct	CODE_OF_CONDUCT.md
📄 License	LICENSE
🐛 Report Issues	GitHub Issues
💬 Discussions	GitHub Discussions
🌐 Repository	github.com/raphaelmansuy/edgequake

---

Ready to build intelligent document retrieval? Get started now!

Star History