# LightRAG Comparison & Adopted Patterns

## Overview

This document records our analysis of [LightRAG](https://github.com/hkuds/lightrag) (EMNLP 2025) and what we adopted from it. LightRAG is a graph-enhanced RAG system that constructs knowledge graphs from documents and uses dual-level retrieval (entity-first vs relation-first) to improve context quality.

We evaluated LightRAG and [RAG-Anything](https://github.com/HKUDS/RAG-Anything) (its multi-modal extension) against our schema discovery search service to identify transferable techniques.

**Last updated**: 2026-05-10 (LightRAG v1.4.16, 34,977 stars (up from 34,965), 4,957 forks, MIT license, 232 open issues. @coda/search post-PR-198 with engine decomposition, graph exploration RPCs, 9 sub-path exports, lintGlossary. Key additions since v1.4.3: Bedrock/Vertex AI/Voyage AI providers, workspace isolation, RAGAS+Langfuse evaluation, citation system, reranker providers (Cohere/Jina/Dashscope), setup wizard, OpenSearch as unified backend, cosign-signed Docker images. Latest v1.4.16 (May 7): Voyage AI task-aware embeddings, OpenSearch version-aware sort tiebreaker. New since last update: Podman Compose support, Yandex Cloud embeddings, Atlas Local Docker for MongoDB, AG2 multi-agent demo, batch graph operations for large KG imports, cooperative yielding, PostgreSQL timing instrumentation, HALFVEC support for large embeddings. Active RAGAS offline audit improvements merged May 9. Still no BM25/lexical search.)

---

## How LightRAG works

LightRAG's core innovation is knowledge graph-enhanced retrieval:

1. **Entity extraction**: LLM extracts entities and relationships from each text chunk.
2. **Knowledge graph construction**: Entities become nodes, relationships become edges. Descriptions merged via LLM.
3. **Dual-level retrieval**: Low-level (entity VDB -> 1-hop neighbors) and high-level (relation VDB -> endpoint entities).
4. **Fusion**: Round-robin positional interleaving of local and global results.

### LightRAG's current state (v1.4.16, May 2026)

- **34,977 GitHub stars**, 4,957 forks, active community, rapid release cadence (~30 releases since v1.4.3)
- **13 storage backends**: NetworkX, Neo4J, PostgreSQL (AGE), MongoDB, Redis, Milvus, Qdrant, FAISS, OpenSearch, Memgraph, NanoVectorDB, JSON, TiDB
- **16+ LLM providers**: OpenAI, Anthropic, Azure, Bedrock, Gemini, Vertex AI, Ollama, HuggingFace, Jina, Voyage AI, and more
- **Reranker support** (v1.4.5+): Mixed-mode query as default; reranker providers: Cohere, Jina, Dashscope
- **RAGAS evaluation + Langfuse tracing** (v1.4.8+): Including offline sample retrieval audit (merged May 9)
- **Web UI + API server**: Full-stack with KG visualization, Ollama-compatible chat, i18n
- **Interactive setup wizard** (v1.4.11+): Docker-based local deployment with backend selection
- **Security hardening**: JWT algorithm confusion fix, Cypher injection prevention, cosign-signed Docker images
- **Task-aware embeddings** (v1.4.16): Voyage AI explicit support with document vs query prefixes

---

## How our system differs

| Aspect               | LightRAG (v1.4.16)                  | @coda/search (v0.1.0)                                                  |
| -------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
| **Purpose**          | Document QA via graph-enhanced RAG  | Schema discovery for AI agent tool selection                           |
| **Corpus**           | Unstructured text documents         | Structured schema metadata (GraphQL types, Snowflake tables)           |
| **Graph source**     | LLM-extracted entities/relations    | Structurally derived (type->field, FK inference from `_ID` columns)    |
| **Score fusion**     | Round-robin positional interleaving | Reciprocal Rank Fusion (RRF) -- score-based, mathematically principled |
| **Indexing cost**    | High (LLM calls per chunk)          | Low (tokenize + embed, no LLM)                                         |
| **Query latency**    | ~200-500ms (LLM keyword extraction) | ~10-15ms (in-memory BM25 + HNSW)                                       |
| **Lexical matching** | None (no BM25)                      | BM25 with Porter stemming and prefix fallback                          |
| **Reranking**        | Cohere/Jina/Dashscope providers     | `RerankProvider` interface with deployed cross-encoder                 |
| **Evaluation**       | RAGAS + Langfuse (v1.4.8+)          | NDCG/MRR/Recall golden queries + MRR regression guard                  |
| **State machine**    | Pipeline status tracking            | CREATED->READY->DEGRADED->DESTROYED with two-phase embed               |
| **Observability**    | Langfuse tracing integration        | OTel-compatible EventBus with 28 structured event types                |
| **Storage backends** | 13 backends                         | In-memory only + S3 snapshot persistence                               |
| **Deployment**       | Docker Compose + server + WebUI     | Fargate container, ConnectRPC service                                  |

### Why we didn't adopt LightRAG wholesale

1. **Our corpus is already structured** -- LLM entity extraction is redundant when schemas have explicit relationships.
2. **Latency budget incompatible** -- LLM keyword extraction at query time adds ~200-500ms.
3. **RRF > round-robin fusion** -- mathematically principled for heterogeneous signals.
4. **Indexing cost prohibitive** -- LLM per chunk during indexing at our poll frequency.
5. **Python-only** -- no embeddable TypeScript library.

---

## What we adopted

Four techniques that transfer well to our architecture:

### 1. Graph degree boost (from degree-based edge ranking)

`DegreeSignal` implementing `StaticSignal<T>` -- computed once, cached until graph rebuild. Highly-connected types/tables get a ranking boost.

**Implementation**: `packages/search/src/signals/degree-signal.ts`

### 2. Dual-level keyword weighting (from local/global retrieval)

Raw query tokens = "low-level" (specific); glossary-expanded tokens = "high-level" (conceptual). HybridSearch runs KeywordStage twice, producing two RRF signals: `"keyword"` (local) and `"keyword_expanded"` (global).

**Implementation**: `KeywordRankingStage` in `packages/search/src/hybrid-search.ts`

### 3. Weighted context allocation (from `pick_by_weighted_polling`)

`allocateBudget()` distributes a fixed budget across ranked results using a linear gradient -- top results get more context, lower results get less.

**Implementation**: `packages/search/src/token-budget.ts`

### 4. Token budget management (from `max_entity_tokens`)

Same `allocateBudget()` with optional `totalBudget` cap. Prevents unbounded response sizes.

---

## What we could adopt from LightRAG

### 1. Query-time reranking as default mode

Since v1.4.5, reranker-based "mix mode" is the default. LightRAG now supports Cohere, Jina, and Dashscope reranker providers. We have the `RerankProvider` interface and pipeline stage, but no production model deployed yet. **Gap**: Deploy a cross-encoder reranker.

### 2. Evaluation framework with golden context

Integrated RAGAS evaluation (v1.4.8+) returns retrieved contexts for context precision metrics. Latest improvement (May 9): offline sample retrieval audit that excludes zero-score docs. Our benchmarks evaluate document-level relevance but not context sufficiency. **Gap**: Add "does the result contain the fields the agent actually needs?" metric.

### 3. Citation / provenance tracking

Added citation support (v1.4.8+). Low priority for us since schema provenance is deterministic.

### 4. Task-aware embeddings

Voyage AI integration (v1.4.16) uses different embedding prefixes for documents vs queries. Our `EmbeddingProvider` interface already supports separate `embed()` and `embedQuery()` methods, so task-aware models are pluggable. **No gap** -- architecturally supported.

---

## Enterprise readiness comparison

| Dimension                | LightRAG (v1.4.16)                                         | @coda/search                                                              |
| ------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------- |
| **Language / runtime**   | Python 3.10+, async                                        | TypeScript, Node 24+, ESM                                                 |
| **LLM dependency**       | Required for indexing AND querying                         | Required only for embedding (optional); zero LLM at query time            |
| **Storage backends**     | 13 backends (added OpenSearch, TiDB)                       | In-memory only + S3 snapshot persistence                                  |
| **Observability**        | Langfuse tracing integration (v1.4.8+)                     | OTel-compatible EventBus (28 event types), TraceSubscriber                |
| **State management**     | Pipeline status history                                    | Explicit state machine (EngineState: CREATED->READY->DEGRADED->DESTROYED) |
| **Graceful degradation** | Falls back when LLM unavailable (unclear behavior)         | Explicit: keyword-only when vectors unavailable, per-stage fallback       |
| **Test coverage**        | ~54 test files, primarily integration                      | ~1,386 unit tests, zero LLM dependency, NDCG regression guard             |
| **Multi-tenancy**        | Workspace isolation (v1.4.9.9+)                            | Per-tenant engine instances + SearchFilter                                |
| **Security**             | JWT hardening, Cypher injection prevention, cosign signing | Filter allowlist/blocklist + SearchFilter access control                  |
| **Reranking**            | Cohere, Jina, Dashscope providers (deployed)               | `RerankProvider` interface with deployed cross-encoder                    |
| **Deployment tooling**   | Docker Compose, setup wizard, cosign-signed images         | Fargate + Jenkins CI pipeline                                             |

**LightRAG is an application; @coda/search is a library.** LightRAG ships a complete server with REST API, WebUI, Docker Compose, auth, and setup wizard. @coda/search is a composable library with clean interfaces that gets embedded into a larger service.

---

## Developer experience comparison

| Dimension            | LightRAG                                                | @coda/search                                                                           |
| -------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Getting started**  | `pip install lightrag-hku`, env file, `lightrag-server` | `pnpm add @coda/search`, implement interfaces, call `init()`                           |
| **Sub-path exports** | N/A (monolithic Python package)                         | 9 entry points: primitives, engine, pipeline, events, graph, signals, stages, snapshot |
| **Type safety**      | Python type hints                                       | Full TypeScript generics (`SearchEngine<TRaw, TDoc, TContext>`)                        |
| **Extensibility**    | Storage backends via abstract classes                   | Interface-based DI: `SearchStage`, `StaticSignal`, `QuerySignal`, `ScoreFusion`        |
| **Setup wizard**     | Interactive Docker-based setup (v1.4.11+)               | Manual env config + Docker Compose                                                     |
| **WebUI**            | Full-stack with KG visualization, chat, i18n            | Admin UI with terminal, graph, waterfall, dashboard pages                              |

---

## Abstraction quality comparison

| Dimension              | LightRAG                                              | @coda/search                                                           |
| ---------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------- |
| **Core abstraction**   | `LightRAG` class: monolithic orchestrator (~2K lines) | `SearchEngine<TRaw, TDoc, TContext>`: generic, ~620 lines              |
| **Signal composition** | Hardcoded local+global retrieval paths                | N-signal `ScoreFusion` interface with pluggable `NamedSignal[]`        |
| **Stage composition**  | Fixed pipeline: extract->retrieve->fuse->generate     | Composable: `SearchStage[]` + `QueryExpander[]` + signals              |
| **Graph abstraction**  | Direct storage-specific implementations               | Generic `LabeledGraph<T>` with `ReadonlyLabeledGraph<T>` for consumers |
| **Lifecycle**          | Implicit (init on first use)                          | Explicit state machine: `isReady()`, `isDegraded()`, `destroy()`       |

---

## Documentation & examples comparison

| Dimension            | LightRAG                                            | @coda/search                                                     |
| -------------------- | --------------------------------------------------- | ---------------------------------------------------------------- |
| **README**           | Comprehensive, heavily visual, installation-focused | Package-level TSDoc, links to architecture docs                  |
| **API docs**         | 15+ markdown files                                  | 6 doc pages + TSDoc on every export + architecture overview      |
| **Code examples**    | 10+ example scripts                                 | 4 progressive examples + 8 cookbook recipes + golden query suite |
| **Deployment guide** | Docker, offline, multi-site, interactive setup      | Docker guide for consuming service                               |
| **i18n**             | Web UI with i18n support                            | English only                                                     |

---

## Scope & limitations

### What LightRAG does that we don't need

1. LLM-based entity extraction (our schemas are already structured)
2. Document management UI with file upload
3. Chat interface (Ollama-compatible)
4. Multi-modal document parsing (via RAG-Anything)
5. 13 storage backends (in-memory + S3 is sufficient)
6. Setup wizard with interactive backend selection

### What we do that LightRAG doesn't

1. Sub-millisecond BM25 lexical search (LightRAG has no BM25/lexical path -- this remains the key gap across all graph-RAG systems)
2. In-memory operation (zero network calls at query time)
3. Glossary-based domain expansion without LLM calls
4. Graph proximity signal (multi-source BFS from vector candidates)
5. Two-phase initialization (keyword immediately, vectors async)
6. Quantized HNSW (4x memory reduction)
7. Formal evaluation metrics (NDCG, MRR, Precision@K, Recall@K) with MRR regression guard
8. `lintGlossary()` -- automated glossary health checks (5 check types)
9. Production operations guide with deployment, monitoring, capacity planning, and failure recovery

### Where LightRAG is ahead

1. **Breadth of integrations**: 13 storage backends, 16+ LLM providers, 3 reranker providers, RAGAS, Langfuse
2. **Community**: ~35K stars, 4,958 forks, active Discord, rapid release cadence (30 releases)
3. **Production tooling**: Setup wizard, Docker Compose, cosign-signed Docker images, bcrypt auth, JWT enforcement
4. **Research grounding**: Published at EMNLP 2025
5. **Security hardening**: Cypher injection prevention, JWT algorithm confusion fix, bcrypt password hashing
6. **Deployment maturity**: Offline deployment guide, Docker Compose, multi-site support

### Competitive landscape -- graph-RAG systems

| Project                  | Stars  | Status            | Notes                                                                              |
| ------------------------ | ------ | ----------------- | ---------------------------------------------------------------------------------- |
| **LightRAG** (HKUDS)     | 34,977 | Active (daily)    | Market leader in OSS graph-RAG. No BM25. v1.4.16. Voyage AI task-aware embeddings. |
| **Microsoft GraphRAG**   | 32,871 | Active (moderate) | Maturing -- mostly maintenance/incremental (pushed May 9).                         |
| **Graphiti** (Zep)       | 25,863 | Active (daily)    | Saga abstraction, combined extraction (pushed May 8).                              |
| **RAG-Anything** (HKUDS) | 20,001 | Active (weekly)   | v1.3.0. Multi-modal RAG. DoclingParser Python API migration.                       |
| **KAG** (OpenSPG)        | ~8,725 | Stalled           | v0.8.0 (10+ months old). Last push Jan 28, 2026.                                   |
| **HippoRAG** (OSU)       | ~3,494 | Stalled           | Research project (NeurIPS 2024). Last push Sep 2025.                               |

**Key gap across all graph-RAG systems**: None have added BM25/lexical search. This remains our primary differentiator.

---

## How our architecture enabled adoption

The stage-based decomposition made adoption straightforward:

| Pattern             | Integration point                             | Lines changed |
| ------------------- | --------------------------------------------- | ------------- |
| Graph degree boost  | `DegreeSignal` implementing `StaticSignal<T>` | ~60 lines     |
| Dual-level keywords | `KeywordRankingStage` + `GlossaryExpander`    | ~50 lines     |
| Weighted allocation | `allocateBudget()` utility                    | ~60 lines     |
| Token budget        | Same `allocateBudget()` utility               | 0 additional  |
| Proximity signal    | `ProximitySignal` implementing `QuerySignal`  | ~100 lines    |

**Current signal inventory (6 signals fused via RRF)**:

1. `keyword` -- BM25 scoring on raw query tokens
2. `keyword_expanded` -- BM25 scoring on glossary-expanded tokens
3. `vector` -- HNSW embedding similarity
4. `glossary_match` -- direct glossary term matching
5. `degree` -- graph node degree centrality (static)
6. `proximity` -- graph distance from vector anchors (per-query)

---

## Verdict & recommendations

### If we started fresh, what would we adopt from LightRAG?

The four patterns we already adopted (degree signal, dual-level keywords, weighted allocation, token budget) plus the proximity signal. These transferred cleanly because they address universal ranking concerns. We would NOT adopt LightRAG's core architecture (LLM-dependent indexing and querying, round-robin fusion, no BM25) for our use case.

### What are we doing better?

- **Lexical search**: BM25 with stemming and prefix fallback. No graph-RAG system has this.
- **Query latency**: ~10-15ms vs ~200-500ms. 20-50x faster.
- **Cost**: $0 per query and $0 per index build vs LLM costs for both.
- **Determinism**: Fully deterministic pipeline vs LLM-dependent extraction and querying.
- **Signal architecture**: N-signal RRF with pluggable `SearchStage[]` + `StaticSignal[]` + `QuerySignal[]` vs hardcoded local+global paths.
- **Type safety**: Full TypeScript generics with compile-time contracts vs Python type hints.
- **Two-phase initialization**: Keyword search available immediately while vectors embed async.
- **Glossary system**: Domain-aware query expansion and term boosting without LLM calls, with `lintGlossary()` health checks.

### What are we missing for enterprise-level production readiness?

- **Deployed reranker**: `RerankProvider` interface exists but no production model. LightRAG has 3 reranker providers deployed.
- **Storage backend breadth**: In-memory only. LightRAG supports 13 backends. Not needed at our scale but limits large-corpus deployments.
- **Community and ecosystem**: 35K stars, 4,958 forks, Discord, weekly releases vs private internal project.
- **Context precision evaluation**: RAGAS-style "is the retrieved context sufficient?" metrics.
- **Deployment tooling**: Setup wizard, cosign-signed Docker images, offline deployment guide.

### Overall assessment

LightRAG and @coda/search solve fundamentally different problems with overlapping techniques. The four patterns we adopted transfer cleanly because they address universal ranking concerns. The absence of BM25/lexical search across the entire graph-RAG ecosystem (LightRAG, GraphRAG, Graphiti, RAG-Anything, KAG, HippoRAG) remains our most significant technical differentiator.

---

## References

- Guo, Z. et al.: [LightRAG: Simple and Fast Retrieval-Augmented Generation](https://arxiv.org/abs/2410.05779) (EMNLP 2025)
- [LightRAG GitHub](https://github.com/hkuds/lightrag) -- v1.4.16, 34,977 stars, MIT license
- RAG-Anything comparison: [raganything-comparison.md](raganything-comparison.md)
- ChromaFs comparison: [chromafs-comparison.md](chromafs-comparison.md)