LightRAG Storage Backends: Complete Guide to KV, Vector, Graph, and Doc Status

LightRAG supports 24 production-ready storage backends across four persistence layers—key-value, vector, graph, and document-status data—utilizing a plug-in architecture that enables mixing JSON files, Redis, PostgreSQL, MongoDB, Neo4j, OpenSearch, and other databases.

The HKUDS/LightRAG repository decouples data persistence from retrieval logic through abstract base classes defined in lightrag/base.py. This modular design allows developers to configure independent storage backends for each layer, swapping file-based solutions for enterprise databases as deployment requirements evolve.

KV Storage Backends

LightRAG provides five concrete implementations for key-value storage, handling raw text chunks, LLM cache, and entity data:

• JsonKVStorage – File-based JSON persistence located in lightrag/kg/json_kv_impl.py (line 27)
• RedisKVStorage – Redis hash store implemented in lightrag/kg/redis_impl.py (line 127)
• PGKVStorage – PostgreSQL table storage in lightrag/kg/postgres_impl.py (line 1939)
• OpenSearchKVStorage – OpenSearch document store in lightrag/kg/opensearch_impl.py (line 179)
• MongoKVStorage – MongoDB collection storage in lightrag/kg/mongo_impl.py (line 81)

All KV backends inherit from BaseKVStorage and implement standardized methods including get_by_id, upsert, and delete.

Vector Storage Backends

Eight backends support embedding vector persistence for similarity search, ranging from local file indices to distributed vector databases:

• FaissVectorDBStorage – Faiss index on disk in lightrag/kg/faiss_impl.py (line 24)
• QdrantVectorDBStorage – Qdrant service integration in lightrag/kg/qdrant_impl.py (line 119)
• PGVectorStorage – PostgreSQL vector type extension in lightrag/kg/postgres_impl.py (line 2469)
• OpenSearchVectorDBStorage – OpenSearch k-NN plugin in lightrag/kg/opensearch_impl.py (line 2322)
• NanoVectorDBStorage – NanoVectorDB implementation in lightrag/kg/nano_vector_db_impl.py (line 26)
• MongoVectorDBStorage – MongoDB Atlas Vector Search in lightrag/kg/mongo_impl.py (line 2040)
• MilvusVectorDBStorage – Milvus service integration in lightrag/kg/milvus_impl.py (line 332)
• ChromaVectorDBStorage – Deprecated Chroma DB in lightrag/kg/deprecated/chroma_impl.py (line 20)

These classes extend BaseVectorStorage and provide query methods for approximate nearest neighbor search.

Graph Storage Backends

Six graph storage implementations manage knowledge-graph nodes and edges using undirected graph structures:

• NetworkXStorage – In-process NetworkX graphs in lightrag/kg/networkx_impl.py (line 26)
• PGGraphStorage – PostgreSQL table-based graphs in lightrag/kg/postgres_impl.py (line 4004)
• OpenSearchGraphStorage – OpenSearch k-NN plus document graphs in lightrag/kg/opensearch_impl.py (line 947)
• Neo4JStorage – Neo4j database integration in lightrag/kg/neo4j_impl.py (line 66)
• MongoGraphStorage – MongoDB collection storage in lightrag/kg/mongo_impl.py (line 728)
• MemgraphStorage – Memgraph database connector in lightrag/kg/memgraph_impl.py (line 35)

Graph backends inherit from BaseGraphStorage and expose methods for node insertion, edge creation, and graph traversal.

Document Status Storage Backends

Five backends track per-document processing state, including chunk lists, metadata, and pipeline status:

• JsonDocStatusStorage – JSON file persistence in lightrag/kg/json_doc_status_impl.py (line 30)
• RedisDocStatusStorage – Redis storage in lightrag/kg/redis_impl.py (line 518)
• PGDocStatusStorage – PostgreSQL tables in lightrag/kg/postgres_impl.py (line 3354)
• OpenSearchDocStatusStorage – OpenSearch documents in lightrag/kg/opensearch_impl.py (line 470)
• MongoDocStatusStorage – MongoDB collections in lightrag/kg/mongo_impl.py (line 285)

These extend DocStatusStorage and maintain processing state across document ingestion pipelines.

How to Initialize Storage Backends

Instantiate any storage class by importing from its implementation module and passing the standard constructor arguments defined in the base classes:

from lightrag.kg.json_kv_impl import JsonKVStorage
from lightrag.kg.faiss_impl import FaissVectorDBStorage
from lightrag.kg.networkx_impl import NetworkXStorage
from lightrag.kg.json_doc_status_impl import JsonDocStatusStorage

# Initialize JSON-backed KV storage

kv = JsonKVStorage(
    namespace="text_chunks",
    embedding_func=my_embed,
    global_config={"working_dir": "./data"},
    workspace="my_project",
)

# Initialize Faiss vector storage

vector = FaissVectorDBStorage(
    namespace="text_chunks",
    embedding_func=my_embed,
    global_config={"working_dir": "./data"},
    workspace="my_project",
)

# Initialize NetworkX graph storage

graph = NetworkXStorage(
    namespace="knowledge_graph",
    embedding_func=my_embed,
    global_config={"working_dir": "./data"},
    workspace="my_project",
)

# Initialize JSON document status storage

doc_status = JsonDocStatusStorage(
    namespace="doc_status",
    embedding_func=my_embed,
    global_config={"working_dir": "./data"},
    workspace="my_project",
)

To switch backends, change only the imported class while maintaining identical initialization parameters. For example, replacing JsonKVStorage with RedisKVStorage requires updating the import statement and class name:

from lightrag.kg.redis_impl import RedisKVStorage

kv = RedisKVStorage(
    namespace="text_chunks",
    embedding_func=my_embed,
    global_config={"working_dir": "./data"},
    workspace="my_project",
)

All storage classes share common interface methods including is_empty, upsert, and get_by_id, enabling seamless backend substitution without modifying pipeline logic.

Summary

• LightRAG provides 24 production-ready storage backends across four persistence layers: KV (5), Vector (8), Graph (6), and Document Status (5)
• Each backend implements standardized interfaces (BaseKVStorage, BaseVectorStorage, BaseGraphStorage, DocStatusStorage) defined in lightrag/base.py
• Database-specific implementations reside in lightrag/kg/ with dedicated modules for PostgreSQL, MongoDB, Redis, Neo4j, OpenSearch, Memgraph, Milvus, Qdrant, and others
• Constructor signatures are uniform across all backends, allowing drop-in replacement by changing only the import statement and class name
• ChromaVectorDBStorage is deprecated and located in lightrag/kg/deprecated/chroma_impl.py (line 20); new implementations should use FaissVectorDBStorage or database-backed alternatives

Frequently Asked Questions

Can I use different database backends for different storage layers in LightRAG?

Yes. LightRAG's modular architecture allows mixing storage technologies according to your operational needs. For example, you can configure RedisKVStorage for key-value data, MilvusVectorDBStorage for vectors, Neo4JStorage for graphs, and JsonDocStatusStorage for document status within the same pipeline instance.

Which storage backend offers the best performance for large-scale deployments?

PostgreSQL (via PGKVStorage, PGVectorStorage, PGGraphStorage, and PGDocStatusStorage) and Neo4j (via Neo4JStorage) provide the strongest consistency and query performance for high-volume transactional workloads. For specialized vector search throughput, Milvus or Qdrant typically outperform file-based alternatives in distributed environments.

How do I migrate from file-based storage to PostgreSQL?

Migration requires changing import statements from file-based implementations (e.g., JsonKVStorage) to PostgreSQL equivalents (e.g., PGKVStorage) while maintaining the same constructor arguments. You must ensure your global_config includes PostgreSQL connection parameters. The data itself requires manual migration or re-ingestion, as storage implementations do not provide automatic data transfer between backend types.

Is the Chroma vector storage still supported?

ChromaVectorDBStorage is deprecated and remains available only in lightrag/kg/deprecated/chroma_impl.py at line 20 for backward compatibility. It is not recommended for new projects. Migrate to FaissVectorDBStorage for local file-based vector storage, or to PGVectorStorage or QdrantVectorDBStorage for production database solutions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}