Repository: HKUDS/LightRAG

Stars: 33631

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

LightRAG is a Retrieval-Augmented Generation (RAG) framework that uses graph-based knowledge representation for enhanced information retrieval. The system extracts entities and relationships from documents, builds a knowledge graph, and uses multi-modal retrieval (local, global, hybrid, mix, naive) for queries.

Core Architecture

Key Components

- lightrag.py: Main orchestrator class (LightRAG) that coordinates document insertion, query processing, and storage management. Critical: Always call await rag.initialize_storages() after instantiation.

- operate.py: Core extraction and query operations including entity/relation extraction, chunking, and multi-mode retrieval logic.

- base.py: Abstract base classes for storage backends (BaseKVStorage, BaseVectorStorage, BaseGraphStorage, BaseDocStatusStorage).

- kg/: Storage implementations (JSON, NetworkX, Neo4j, PostgreSQL, MongoDB, Redis, Milvus, Qdrant, Faiss, Memgraph). Each storage type provides different trade-offs for production vs. development use.

- llm/: LLM provider bindings (OpenAI, Ollama, Azure, Gemini, Bedrock, Anthropic, etc.). All use async patterns with caching support.

- api/: FastAPI server (lightrag_server.py) with REST endpoints and Ollama-compatible API, plus React 19 + TypeScript WebUI.

Storage Layer

LightRAG uses 4 storage types with pluggable backends:
- KV_STORAGE: LLM response cache, text chunks, document info
- VECTOR_STORAGE: Entity/relation/chunk embeddings
- GRAPH_STORAGE: Entity-relation graph structure
- DOC_STATUS_STORAGE: Document processing status tracking

Workspace isolation is implemented differently per storage type (subdirectories for file-based, prefixes for collections, fields for relational DBs).

Query Modes

- local: Context-dependent retrieval focused on specific entities
- global: Community/summary-based broad knowledge retrieval
- hybrid: Combines local and global
- naive: Direct vector search without graph
- mix: Integrates KG and vector retrieval (recommended with reranker)

Development Commands

Setup

bash

Install core package (development mode)

uv sync
source .venv/bin/activate  # Or: .venv\Scripts\activate on Windows
Install with API support

uv sync --extra api
Install specific extras

uv sync --extra offline-storage  # Storage backends
uv sync --extra offline-llm      # LLM providers
uv sync --extra test             # Testing dependencies

API Server

bash

Copy and configure environment

cp env.example .env  # Edit with your LLM/embedding configs
Build WebUI

cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..
Run server

lightrag-server                                           # Production
uvicorn lightrag.api.lightrag_server:app --reload        # Development
lightrag-gunicorn                                         # Multi-worker (gunicorn)

Testing

bash

Run offline tests (default)

python -m pytest tests
Run integration tests (requires external services)

python -m pytest tests --run-integration
Or set: LIGHTRAG_RUN_INTEGRATION=true
Run specific test file

python test_graph_storage.py
Keep artifacts for debugging

python -m pytest tests --keep-artifacts
Run with custom workers

python -m pytest tests --test-workers 4

Linting

bash

ruff check .

Key Implementation Patterns

LightRAG Initialization (Critical)

The most common error is forgetting to initialize storages:

python

import asyncio
from lightrag import LightRAG
from lightrag.llm.openai import gpt_4o_mini_complete, openai_embed
async def main():
    rag = LightRAG(
        working_dir="./rag_storage",
        llm_model_func=gpt_4o_mini_complete,
        embedding_func=openai_embed
    )
    # REQUIRED: Initialize storage backends
    await rag.initialize_storages()
    # Now safe to use
    await rag.ainsert("Your text here")
    result = await rag.aquery("Your question", param=QueryParam(mode="hybrid"))
    # Cleanup
    await rag.finalize_storages()asyncio.run(main())

Custom Embedding Functions

Use @wrap_embedding_func_with_attrs decorator and call .func when wrapping:

python

from lightrag.utils import wrap_embedding_func_with_attrs@wrap_embedding_func_with_attrs(embedding_dim=1536, max_token_size=8192)
async def custom_embed(texts: list[str]) -> np.ndarray:
    # Call underlying function, not wrapped version
    return await openai_embed.func(texts, model="text-embedding-3-large")

Storage Configuration

Configure via environment variables or constructor params:

python

Environment-based (recommended for production)

See env.example for full list
Constructor-based

rag = LightRAG(
    working_dir="./storage",
    workspace="project_name",  # For data isolation
    kv_storage="PGKVStorage",
    vector_storage="PGVectorStorage",
    graph_storage="Neo4JStorage",
    doc_status_storage="PGDocStatusStorage",
    vector_db_storage_cls_kwargs={
        "cosine_better_than_threshold": 0.2
    }
)

Document Insertion

python

Single document

await rag.ainsert("Text content")
Batch insertion

await rag.ainsert(["Text 1", "Text 2", ...])
With custom IDs

await rag.ainsert("Text", ids=["doc-123"])
With file paths (for citation)

await rag.ainsert(["Text 1", "Text 2"], file_paths=["doc1.pdf", "doc2.pdf"])
Configure batch size

rag = LightRAG(..., max_parallel_insert=4)  # Default: 2, max recommended: 10

Query Configuration

python

from lightrag import QueryParamresult = await rag.aquery(
    "Your question",
    param=QueryParam(
        mode="mix",                    # Recommended with reranker
        top_k=60,                      # KG entities/relations to retrieve
        chunk_top_k=20,                # Text chunks to retrieve
        max_entity_tokens=6000,
        max_relation_tokens=8000,
        max_total_tokens=30000,
        enable_rerank=True,
        user_prompt="Additional instructions for LLM",
        stream=False
    )
)

WebUI Development

Structure

- lightrag_webui/src/: React components (TypeScript)
- Uses Vite + Bun build system
- Tailwind CSS for styling
- React 19 with functional components and hooks

Commands

bash

cd lightrag_webui
bun install --frozen-lockfile  # Install dependencies
bun run dev                    # Development server (Node + Vite)
bun run dev:bun                # Development server (Bun native)
bun run build                  # Production build
bun run preview                # Preview production build locally
Linting (ESLint with TypeScript, React hooks, Stylistic rules)

bun run lint                   # Run ESLint on all *.ts/tsx/js/jsx files
Testing (Bun built-in test runner)

bun test                       # Run all tests
bun test --watch               # Watch mode
bun test --coverage            # With coverage report
bun test src/api/lightrag.test.ts  # Run a single test file

Lint Rules

ESLint is configured with TypeScript-ESLint, React Hooks plugin, Prettier integration, and @stylistic rules:
- 2-space indentation, single quotes enforced
- @typescript-eslint/no-explicit-any is disabled (allowed)

Common Issues

1. Storage Not Initialized

Error: AttributeError: __aenter__ or KeyError: 'history_messages'
Solution: Always call await rag.initialize_storages() after creating LightRAG instance

2. Embedding Model Changes

When switching embedding models, you MUST clear the data directory (except optionally kv_store_llm_response_cache.json for LLM cache).

3. Nested Embedding Functions

Cannot wrap already-decorated embedding functions. Use .func to access underlying function:

python

Wrong: EmbeddingFunc(func=openai_embed)

Right: EmbeddingFunc(func=openai_embed.func)

4. Context Length for Ollama

Ollama models default to 8k context; LightRAG requires 32k+. Configure via:

python

llm_model_kwargs={"options": {"num_ctx": 32768}}

Configuration Files

.env Configuration

Primary configuration file for API server. Key sections:
- Server settings (HOST, PORT, CORS)
- Storage backends (connection strings via environment variables)
- Query parameters (TOP_K, MAX_TOTAL_TOKENS, etc.)
- Reranking configuration (RERANK_BINDING, RERANK_MODEL)
- Authentication (AUTH_ACCOUNTS, LIGHTRAG_API_KEY)

See env.example for comprehensive template.

Workspace Isolation

Each LightRAG instance can use a workspace parameter for data isolation. Implementation varies by storage type:
- File-based: subdirectories
- Collection-based: collection name prefixes
- Relational DB: workspace column filtering
- Qdrant: payload-based partitioning

Testing Guidelines

Test Structure

- tests/: Main test suite (mirrors feature folders)
- test_*.py in root: Specific integration tests
- Markers: offline, integration, requires_db, requires_api

Running Tests

bash

Default: runs only offline tests

pytest tests
Include integration tests

pytest tests --run-integration
Keep test artifacts for debugging

pytest tests --keep-artifacts
Configure test workers

pytest tests --test-workers 4

Environment Variables for Tests

Set LIGHTRAG_* variables for integration tests:
- LIGHTRAG_RUN_INTEGRATION=true
- LIGHTRAG_KEEP_ARTIFACTS=true
- LIGHTRAG_TEST_WORKERS=4
- Plus storage-specific connection strings

Code Style

Language

- Comment Language - Use English for comments and documentation
- Backend Language - Use English for backend code and messages
- Frontend Internationalization: i18next for multi-language support

Python

- Follow PEP 8 with 4-space indentation
- Use type annotations
- Prefer dataclasses for state management
- Use lightrag.utils.logger instead of print
- Async/await patterns throughout
- Keep storage implementations in kg/ with consistent base class inheritance

TypeScript/React

- Functional components with hooks
- 2-space indentation
- PascalCase for components
- Tailwind utility-first styling

Important Architectural Notes

LLM Requirements

- Minimum 32B parameters recommended
- 32KB context minimum (64KB recommended)
- Avoid reasoning models during indexing
- Stronger models for query stage than indexing stage

Embedding Models

- Must be consistent across indexing and querying
- Recommended: BAAI/bge-m3, text-embedding-3-large
- Changing models requires clearing vector storage and recreating with new dimensions

Reranker Configuration

- Significantly improves retrieval quality
- Recommended models: BAAI/bge-reranker-v2-m3, Jina rerankers
- Use "mix" mode when reranker is enabled

README.md

🚀 LightRAG: Simple and Fast Retrieval-Augmented Generation

</div>

---

---

🎉 News

- [2026.03]🎯[New Feature]: Integrated OpenSearch as a unified storage backend, providing comprehensive support for all four LightRAG storage.
- [2026.03]🎯[New Feature]: Introduced a setup wizard. Support for local deployment of embedding, reranking, and storage backends via Docker.
- [2025.11]🎯[New Feature]: Integrated RAGAS for Evaluation and Langfuse for Tracing. Updated the API to return retrieved contexts alongside query results to support context precision metrics.
- [2025.10]🎯[Scalability Enhancement]: Eliminated processing bottlenecks to support Large-Scale Datasets Efficiently.
- [2025.09]🎯[New Feature] Enhances knowledge graph extraction accuracy for Open-Sourced LLMs such as Qwen3-30B-A3B.
- [2025.08]🎯[New Feature] Reranker is now supported, significantly boosting performance for mixed queries (set as default query mode).
- [2025.08]🎯[New Feature] Added Document Deletion with automatic KG regeneration to ensure optimal query performance.
- [2025.06]🎯[New Release] Our team has released RAG-Anything — an All-in-One Multimodal RAG system for seamless processing of text, images, tables, and equations.
- [2025.06]🎯[New Feature] LightRAG now supports comprehensive multimodal data handling through RAG-Anything integration, enabling seamless document parsing and RAG capabilities across diverse formats including PDFs, images, Office documents, tables, and formulas. Please refer to the new multimodal section for details.
- [2025.03]🎯[New Feature] LightRAG now supports citation functionality, enabling proper source attribution and enhanced document traceability.
- [2025.02]🎯[New Feature] You can now use MongoDB as an all-in-one storage solution for unified data management.
- [2025.02]🎯[New Release] Our team has released VideoRAG-a RAG system for understanding extremely long-context videos
- [2025.01]🎯[New Release] Our team has released MiniRAG making RAG simpler with small models.
- [2025.01]🎯You can now use PostgreSQL as an all-in-one storage solution for data management.
- [2024.11]🎯[New Resource] A comprehensive guide to LightRAG is now available on LearnOpenCV. — explore in-depth tutorials and best practices. Many thanks to the blog author for this excellent contribution!
- [2024.11]🎯[New Feature] Introducing the LightRAG WebUI — an interface that allows you to insert, query, and visualize LightRAG knowledge through an intuitive web-based dashboard.
- [2024.11]🎯[New Feature] You can now use Neo4J for Storage-enabling graph database support.
- [2024.10]🎯[New Feature] We've added a link to a LightRAG Introduction Video. — a walkthrough of LightRAG's capabilities. Thanks to the author for this excellent contribution!
- [2024.10]🎯[New Channel] We have created a Discord channel!💬 Welcome to join our community for sharing, discussions, and collaboration! 🎉🎉

<details>
<summary style="font-size: 1.4em; font-weight: bold; cursor: pointer; display: list-item;">
Algorithm Flowchart
</summary>

!LightRAG Indexing Flowchart
Figure 1: LightRAG Indexing Flowchart - Img Caption : Source
!LightRAG Retrieval and Querying Flowchart
Figure 2: LightRAG Retrieval and Querying Flowchart - Img Caption : Source

</details>

Installation

💡 Using uv for Package Management: This project uses uv for fast and reliable Python package management. Install uv first: curl -LsSf https://astral.sh/uv/install.sh | sh (Unix/macOS) or powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows)

Note: You can also use pip if you prefer, but uv is recommended for better performance and more reliable dependency management.

> 📦 Offline Deployment: For offline or air-gapped environments, see the Offline Deployment Guide for instructions on pre-installing all dependencies and cache files.

Install LightRAG Server

The LightRAG Server is designed to provide Web UI and API support. The Web UI facilitates document indexing, knowledge graph exploration, and a simple RAG query interface. LightRAG Server also provide an Ollama compatible interfaces, aiming to emulate LightRAG as an Ollama chat model. This allows AI chat bot, such as Open WebUI, to access LightRAG easily.

* Install from PyPI

bash

Install LightRAG Server as tool using uv (recommended) 

uv tool install "lightrag-hku[api]"
Or using pip 

python -m venv .venv

source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install "lightrag-hku[api]"
Build front-end artifacts 

cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..
Setup env file

Obtain the env.example file by downloading it from the GitHub repository root

or by copying it from a local source checkout.

cp env.example .env  # Update the .env with your LLM and embedding configurations
Launch the server

lightrag-server

* Installation from Source

bash

git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
Bootstrap the development environment (recommended)

make dev
source .venv/bin/activate  # Activate the virtual environment (Linux/macOS)
Or on Windows: .venv\Scripts\activate
make dev installs the test toolchain plus the full offline stack

(API, storage backends, and provider integrations), then builds the frontend.

Run make env-base or copy env.example to .env before starting the server.
Equivalent manual steps with uv

Note: uv sync automatically creates a virtual environment in .venv/

uv sync --extra test --extra offline
source .venv/bin/activate  # Activate the virtual environment (Linux/macOS)
Or on Windows: .venv\Scripts\activate
Or using pip with virtual environment 

python -m venv .venv

source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install -e ".[test,offline]"
Build front-end artifacts

cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..
setup env file

make env-base  # Or: cp env.example .env and update it manually
Launch API-WebUI server

lightrag-server

* Launching the LightRAG Server with Docker Compose

bash

git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env  # Update the .env with your LLM and embedding configurations
modify LLM and Embedding settings in .env

docker compose up

Historical versions of LightRAG docker images can be found here: LightRAG Docker Images

> Official GHCR images published by GitHub Actions are signed with Sigstore Cosign using GitHub OIDC. See docs/DockerDeployment.md for verification commands.

Create .env File With Setup Tool

Instead of editing env.example by hand, use the interactive setup wizard to generate a configured .env and, when needed, docker-compose.final.yml:

bash

make env-base           # Required first step: LLM, embedding, reranker
make env-storage        # Optional: storage backends and database services
make env-server         # Optional: server port, auth, and SSL
make env-base-rewrite   # Optional: force-regenerate wizard-managed compose services
make env-storage-rewrite # Optional: force-regenerate wizard-managed compose services
make env-security-check # Optional: audit the current .env for security risks

For full description of every target see docs/InteractiveSetup.md.
The setup wizards update configuration only; run make env-security-check separately to audit the
current .env for security risks before deployment.
By default, rerunning the setup preserves unchanged wizard-managed compose service blocks; use a
*-rewrite target only when you need to rebuild those managed blocks from the bundled templates.

Install LightRAG Core

* Install from source (Recommended)

bash

cd LightRAG
Note: uv sync automatically creates a virtual environment in .venv/

uv sync
source .venv/bin/activate  # Activate the virtual environment (Linux/macOS)
Or on Windows: .venv\Scripts\activate
Or: pip install -e .

* Install from PyPI

bash

uv pip install lightrag-hku
Or: pip install lightrag-hku

Quick Start

LLM and Technology Stack Requirements for LightRAG

LightRAG's demands on the capabilities of Large Language Models (LLMs) are significantly higher than those of traditional RAG, as it requires the LLM to perform entity-relationship extraction tasks from documents. Configuring appropriate Embedding and Reranker models is also crucial for improving query performance.

- LLM Selection:
- It is recommended to use an LLM with at least 32 billion parameters.
- The context length should be at least 32KB, with 64KB being recommended.
- It is not recommended to choose reasoning models during the document indexing stage.
- During the query stage, it is recommended to choose models with stronger capabilities than those used in the indexing stage to achieve better query results.
- Embedding Model:
- A high-performance Embedding model is essential for RAG.
- We recommend using mainstream multilingual Embedding models, such as: BAAI/bge-m3 and text-embedding-3-large.
- Important Note: The Embedding model must be determined before document indexing, and the same model must be used during the document query phase. For certain storage solutions (e.g., PostgreSQL), the vector dimension must be defined upon initial table creation. Therefore, when changing embedding models, it is necessary to delete the existing vector-related tables and allow LightRAG to recreate them with the new dimensions.
- Reranker Model Configuration:
- Configuring a Reranker model can significantly enhance LightRAG's retrieval performance.
- When a Reranker model is enabled, it is recommended to set the "mix mode" as the default query mode.
- We recommend using mainstream Reranker models, such as: BAAI/bge-reranker-v2-m3 or models provided by services like Jina.

Quick Start for LightRAG Server

The LightRAG Server is designed to provide Web UI and API support. The LightRAG Server offers a comprehensive knowledge graph visualization feature. It supports various gravity layouts, node queries, subgraph filtering, and more. For more information about LightRAG Server, please refer to LightRAG Server.

!iShot_2025-03-23_12.40.08

Quick Start for LightRAG core

To get started with LightRAG core, refer to the sample codes available in the examples folder. Additionally, a video demo demonstration is provided to guide you through the local setup process. If you already possess an OpenAI API key, you can run the demo right away:

bash

you should run the demo code with project folder 

cd LightRAG
provide your API-KEY for OpenAI 

export OPENAI_API_KEY="sk-...your_opeai_key..."
download the demo document of "A Christmas Carol" by Charles Dickens 

curl https://raw.githubusercontent.com/gusye1234/nano-graphrag/main/tests/mock_data.txt > ./book.txt
run the demo code 

python examples/lightrag_openai_demo.py

For a streaming response implementation example, please see examples/lightrag_openai_compatible_demo.py. Prior to execution, ensure you modify the sample code's LLM and embedding configurations accordingly.

Note 1: When running the demo program, please be aware that different test scripts may use different embedding models. If you switch to a different embedding model, you must clear the data directory (./dickens); otherwise, the program may encounter errors. If you wish to retain the LLM cache, you can preserve the kv_store_llm_response_cache.json file while clearing the data directory.

Note 2: Only lightrag_openai_demo.py and lightrag_openai_compatible_demo.py are officially supported sample codes. Other sample files are community contributions that haven't undergone full testing and optimization.

Programming with LightRAG Core

For the complete Core API reference — including init parameters, QueryParam, LLM/embedding provider examples (OpenAI, Ollama, Azure, Gemini, HuggingFace, LlamaIndex), reranker injection, insert operations, entity/relation management, and delete/merge — see docs/ProgramingWithCore.md.

⚠️ If you would like to integrate LightRAG into your project, we recommend utilizing the REST API provided by the LightRAG Server. LightRAG Core is typically intended for embedded applications or for researchers who wish to conduct studies and evaluations.

Advanced Features

LightRAG provides additional capabilities including token usage tracking, knowledge graph data export, LLM cache management, Langfuse observability integration, and RAGAS-based evaluation. See docs/AdvancedFeatures.md.

Multimodal Document Processing (RAG-Anything Integration)

LightRAG integrates with RAG-Anything for end-to-end multimodal RAG across PDFs, Office documents, images, tables, and formulas. For setup and usage examples, see docs/AdvancedFeatures.md.

LightRAG Server will soon integrate RAG-Anything’s multimodal processing capabilities into its file processing pipeline. Stay tuned.

Replicating Findings in the Papper

LightRAG consistently outperforms NaiveRAG, RQ-RAG, HyDE, and GraphRAG across agriculture, computer science, legal, and mixed domains. For the full evaluation methodology, prompts, and reproduce steps, see docs/Reproduce.md.

Overall Performance Table

||Agriculture||CS||Legal||Mix||
|----------------------|---------------|------------|------|------------|---------|------------|-------|------------|
||NaiveRAG|LightRAG|NaiveRAG|LightRAG|NaiveRAG|LightRAG|NaiveRAG|LightRAG|
|Comprehensiveness|32.4%|67.6%|38.4%|61.6%|16.4%|83.6%|38.8%|61.2%|
|Diversity|23.6%|76.4%|38.0%|62.0%|13.6%|86.4%|32.4%|67.6%|
|Empowerment|32.4%|67.6%|38.8%|61.2%|16.4%|83.6%|42.8%|57.2%|
|Overall|32.4%|67.6%|38.8%|61.2%|15.2%|84.8%|40.0%|60.0%|
||RQ-RAG|LightRAG|RQ-RAG|LightRAG|RQ-RAG|LightRAG|RQ-RAG|LightRAG|
|Comprehensiveness|31.6%|68.4%|38.8%|61.2%|15.2%|84.8%|39.2%|60.8%|
|Diversity|29.2%|70.8%|39.2%|60.8%|11.6%|88.4%|30.8%|69.2%|
|Empowerment|31.6%|68.4%|36.4%|63.6%|15.2%|84.8%|42.4%|57.6%|
|Overall|32.4%|67.6%|38.0%|62.0%|14.4%|85.6%|40.0%|60.0%|
||HyDE|LightRAG|HyDE|LightRAG|HyDE|LightRAG|HyDE|LightRAG|
|Comprehensiveness|26.0%|74.0%|41.6%|58.4%|26.8%|73.2%|40.4%|59.6%|
|Diversity|24.0%|76.0%|38.8%|61.2%|20.0%|80.0%|32.4%|67.6%|
|Empowerment|25.2%|74.8%|40.8%|59.2%|26.0%|74.0%|46.0%|54.0%|
|Overall|24.8%|75.2%|41.6%|58.4%|26.4%|73.6%|42.4%|57.6%|
||GraphRAG|LightRAG|GraphRAG|LightRAG|GraphRAG|LightRAG|GraphRAG|LightRAG|
|Comprehensiveness|45.6%|54.4%|48.4%|51.6%|48.4%|51.6%|50.4%|49.6%|
|Diversity|22.8%|77.2%|40.8%|59.2%|26.4%|73.6%|36.0%|64.0%|
|Empowerment|41.2%|58.8%|45.2%|54.8%|43.6%|56.4%|50.8%|49.2%|
|Overall|45.2%|54.8%|48.0%|52.0%|47.2%|52.8%|50.4%|49.6%|

Ecosystem & Extensions

<div align="center">
<table>
<tr>
<td align="center">
<a href="https://github.com/HKUDS/RAG-Anything">
<div style="width: 100px; height: 100px; background: linear-gradient(135deg, rgba(0, 217, 255, 0.1) 0%, rgba(0, 217, 255, 0.05) 100%); border-radius: 15px; border: 1px solid rgba(0, 217, 255, 0.2); display: flex; align-items: center; justify-content: center; margin-bottom: 10px;">
<span style="font-size: 32px;">📸</span>
</div>
<b>RAG-Anything</b><br>
<sub>Multimodal RAG</sub>
</a>
</td>
<td align="center">
<a href="https://github.com/HKUDS/VideoRAG">
<div style="width: 100px; height: 100px; background: linear-gradient(135deg, rgba(0, 217, 255, 0.1) 0%, rgba(0, 217, 255, 0.05) 100%); border-radius: 15px; border: 1px solid rgba(0, 217, 255, 0.2); display: flex; align-items: center; justify-content: center; margin-bottom: 10px;">
<span style="font-size: 32px;">🎥</span>
</div>
<b>VideoRAG</b><br>
<sub>Extreme Long-Context Video RAG</sub>
</a>
</td>
<td align="center">
<a href="https://github.com/HKUDS/MiniRAG">
<div style="width: 100px; height: 100px; background: linear-gradient(135deg, rgba(0, 217, 255, 0.1) 0%, rgba(0, 217, 255, 0.05) 100%); border-radius: 15px; border: 1px solid rgba(0, 217, 255, 0.2); display: flex; align-items: center; justify-content: center; margin-bottom: 10px;">
<span style="font-size: 32px;">✨</span>
</div>
<b>MiniRAG</b><br>
<sub>Extremely Simple RAG</sub>
</a>
</td>
</tr>
</table>
</div>

---

⭐ Star History

![Star History Chart](https://star-history.com/#HKUDS/LightRAG&Date)

🤝 Contribution

<div align="center">
We welcome contributions of all kinds — bug fixes, new features, documentation improvements, and more.<br>
Please read our <a href=".github/CONTRIBUTING.md"><strong>Contributing Guide</strong></a> before submitting a pull request.
</div>

<br>

<div align="center">
We thank all our contributors for their valuable contributions.
</div>

📖 Citation

python

@article{guo2024lightrag,
title={LightRAG: Simple and Fast Retrieval-Augmented Generation},
author={Zirui Guo and Lianghao Xia and Yanhua Yu and Tu Ao and Chao Huang},
year={2024},
eprint={2410.05779},
archivePrefix={arXiv},
primaryClass={cs.IR}
}

---

<div align="center">
<div style="width: 100%; max-width: 600px; margin: 20px auto; padding: 20px; background: linear-gradient(135deg, rgba(0, 217, 255, 0.1) 0%, rgba(0, 217, 255, 0.05) 100%); border-radius: 15px; border: 1px solid rgba(0, 217, 255, 0.2);">
<div style="display: flex; justify-content: center; align-items: center; gap: 15px;">
<span style="font-size: 24px;">⭐</span>
<span style="color: #00d9ff; font-size: 18px;">Thank you for visiting LightRAG!</span>
<span style="font-size: 24px;">⭐</span>
</div>
</div>
</div>

Repository: HKUDS/LightRAG

Stars: 33631

CLAUDE.md Copy Chapter

CLAUDE.md

Project Overview Copy Chapter

Core Architecture Copy Chapter

Key Components Copy Section

Storage Layer Copy Section

Query Modes Copy Section

Development Commands Copy Chapter

Setup Copy Section

Install core package (development mode)

Install with API support

Install specific extras

API Server Copy Section

Copy and configure environment

Build WebUI

Run server

Testing Copy Section

Run offline tests (default)

Run integration tests (requires external services)

Or set: LIGHTRAG_RUN_INTEGRATION=true

Run specific test file

Keep artifacts for debugging

Run with custom workers

Linting Copy Section

Key Implementation Patterns Copy Chapter

LightRAG Initialization (Critical) Copy Section

Custom Embedding Functions Copy Section

Storage Configuration Copy Section

Environment-based (recommended for production)

See env.example for full list

Constructor-based

Document Insertion Copy Section

Single document

Batch insertion

With custom IDs

With file paths (for citation)

Configure batch size

Query Configuration Copy Section

WebUI Development Copy Chapter

Structure Copy Section

Commands Copy Section

Linting (ESLint with TypeScript, React hooks, Stylistic rules)

Testing (Bun built-in test runner)

Lint Rules Copy Section

Common Issues Copy Chapter

1. Storage Not Initialized Copy Section

2. Embedding Model Changes Copy Section

3. Nested Embedding Functions Copy Section

Wrong: EmbeddingFunc(func=openai_embed)

Right: EmbeddingFunc(func=openai_embed.func)

4. Context Length for Ollama Copy Section

Configuration Files Copy Chapter

.env Configuration Copy Section

Workspace Isolation Copy Section

Testing Guidelines Copy Chapter

Test Structure Copy Section

Running Tests Copy Section

Default: runs only offline tests

Include integration tests

Keep test artifacts for debugging

Configure test workers

Environment Variables for Tests Copy Section

Code Style Copy Chapter

Language Copy Section

Python Copy Section

TypeScript/React Copy Section

Important Architectural Notes Copy Chapter

LLM Requirements Copy Section

Embedding Models Copy Section

Reranker Configuration Copy Section

README.md Copy Chapter

🚀 LightRAG: Simple and Fast Retrieval-Augmented Generation

🎉 News Copy Chapter

Installation Copy Chapter

Install LightRAG Server Copy Section

Install LightRAG Server as tool using uv (recommended) Copy Section

Or using pip Copy Section

python -m venv .venv

CLAUDE.md

Project Overview

Core Architecture

Key Components

Storage Layer

Query Modes

Development Commands

Setup

API Server

Testing

Linting

Key Implementation Patterns

LightRAG Initialization (Critical)

Custom Embedding Functions

Storage Configuration

Document Insertion

Query Configuration

WebUI Development

Structure

Commands

Lint Rules

Common Issues

1. Storage Not Initialized

2. Embedding Model Changes

3. Nested Embedding Functions

4. Context Length for Ollama

Configuration Files

.env Configuration

Workspace Isolation

Testing Guidelines

Test Structure

Running Tests

Environment Variables for Tests

Code Style

Language

Python

TypeScript/React

Important Architectural Notes

LLM Requirements

Embedding Models

Reranker Configuration

README.md

🎉 News

Installation

Install LightRAG Server

Install LightRAG Server as tool using uv (recommended)

Or using pip

Build front-end artifacts

Or using pip with virtual environment

Create .env File With Setup Tool

Install LightRAG Core

Quick Start

LLM and Technology Stack Requirements for LightRAG

Quick Start for LightRAG Server

Quick Start for LightRAG core

you should run the demo code with project folder

provide your API-KEY for OpenAI

download the demo document of "A Christmas Carol" by Charles Dickens

run the demo code

Programming with LightRAG Core

Advanced Features

Multimodal Document Processing (RAG-Anything Integration)

Replicating Findings in the Papper

🔗 Related Projects

⭐ Star History

🤝 Contribution

📖 Citation