Installation#

Requirements#

Python 3.11, 3.12, or 3.13. On Python 3.10, pip installs 0.2.0 instead, and on 3.14 it installs 0.1.0, both without an error; these pages describe neither.
A running AgensGraph 2.17 or later. The agensgraph-python 2.0 driver refuses an older server at connect.
The pgvector extension available on the server (for the vector storage)
The LightRAG core, lightrag-hku 1.5.6 or a later 1.5 release (>=1.5.6,<1.6)

lightrag-agensgraph also depends on the agensgraph-python driver (2.0 or later) and psycopg[binary] (3.3.4 or later). Every statement goes through the driver.

Install#

pip install lightrag-agensgraph

This also installs lightrag-hku in the supported range. The same package is available through the umbrella distribution, which produces the same environment:

pip install "agensgraph-ai[lightrag]"

There is no agensgraph_ai module; you import the package under its own name. Importing it once registers all four storage backends with LightRAG:

import lightrag_agensgraph   # registers AgensgraphStorage, AgensgraphVectorStorage,
                             #            AgensgraphKVStorage, AgensgraphDocStatusStorage

Set up the pgvector extension#

The vector storage uses pgvector. AgensGraph does not bundle it, so build it once against your AgensGraph install:

git clone https://github.com/pgvector/pgvector.git
export PG_CONFIG=/path/to/agens/bin/pg_config
cd pgvector && make && make install

The vector storage runs CREATE EXTENSION IF NOT EXISTS vector in its database the first time it starts. pgvector is not a trusted extension, so that succeeds only when the storages connect as a superuser. Otherwise have a superuser enable it once:

-- in the AgensGraph database LightRAG will use:
CREATE EXTENSION IF NOT EXISTS vector;

Configure the connection#

The storages read the AgensGraph connection from environment variables. One connection pool serves every store of a workspace.

Variable	Required	Default	Notes
`AGENSGRAPH_DB`	Yes	—	Database name
`AGENSGRAPH_USER`	Yes	—	Database user
`AGENSGRAPH_PASSWORD`	Yes	—	Must be set; may be empty under trust auth
`AGENSGRAPH_HOST`	No	`localhost`
`AGENSGRAPH_PORT`	No	`5432`
`AGENSGRAPH_URI`	No	—	A full libpq connection string
`AGENSGRAPH_GRAPHNAME`	No	`chunk_entity_relation`	The graph’s name. A workspace is prefixed to it
`AGENSGRAPH_WORKSPACE`	No	(empty)	The workspace

AGENSGRAPH_URI: when set, the storages connect with it and ignore the five variables above it in the table.
AGENSGRAPH_WORKSPACE: when set, it takes precedence over LightRAG(workspace=...); see Usage.

LightRAG checks at start-up that AGENSGRAPH_DB, AGENSGRAPH_USER, and AGENSGRAPH_PASSWORD exist, so set them even when you connect with AGENSGRAPH_URI.

export AGENSGRAPH_DB="lightrag"
export AGENSGRAPH_USER="postgres"
export AGENSGRAPH_PASSWORD="postgres"
export AGENSGRAPH_HOST="localhost"
export AGENSGRAPH_PORT="5432"

You will also need credentials for whatever LLM and embedding model you pass to LightRAG (for example, OPENAI_API_KEY). With the package installed, the extension available, and the connection configured, continue to Usage.

Vector store settings#

The vector storage reads two more settings from LightRAG’s vector_db_storage_cls_kwargs: hnsw_m (default 16) and hnsw_ef_construction (default 64), the HNSW build parameters. They apply when an index is created (CREATE INDEX IF NOT EXISTS), so an existing index, including one carried over from 0.2.0, keeps the parameters it was built with.

The vector tables are created for the width of the embedding function they first see. A store started with an embedding function of a different width refuses to run. To change embedding models, drop the LIGHTRAG_VDB_* tables.

Upgrading from 0.2.0#

Upgrade lightrag-agensgraph and lightrag-hku together: 0.2.0 does not start on lightrag-hku 1.5.5 or later, and 0.3 requires 1.5.6 or later. Python 3.10 is no longer supported; 0.3 needs 3.11 or later.

pip install -U lightrag-agensgraph lightrag-hku

The graph name can change. 0.2.0’s graph store ignored AGENSGRAPH_GRAPHNAME and AGENSGRAPH_WORKSPACE; 0.3 honours both. If you set either one, 0.3 uses a different graph from the one 0.2.0 wrote.

The document-status table and the vector tables written by 0.2.0 are brought to the current layout in place, keeping their rows, the first time a store starts.

The graph is not. 0.2.0 stored relations in extraction order and could hold the same relation twice, and the unique index on each pair of entities refuses such a graph. Drop the graph and clear the workspace’s other rows, then ingest again. LightRAG skips a document it has already recorded, so dropping only the graph leaves it empty. Run this in the AGENSGRAPH_DB database.

Replace '' with the workspace 0.2.0 wrote the rows under: AGENSGRAPH_WORKSPACE if it was set, otherwise LightRAG’s workspace.
The graph to drop is chunk_entity_relation, or <workspace>_chunk_entity_relation if LightRAG had a workspace, from LightRAG(workspace=...) or LightRAG’s WORKSPACE variable. 0.2.0’s graph store did not read AGENSGRAPH_WORKSPACE.
If unsure, list the graphs with SELECT graphname FROM ag_graph;.

DROP GRAPH chunk_entity_relation CASCADE;
DELETE FROM lightrag_doc_status   WHERE workspace = '';
DELETE FROM lightrag_kv           WHERE workspace = '' AND namespace <> 'llm_response_cache';
DELETE FROM lightrag_vdb_entity   WHERE workspace = '';
DELETE FROM lightrag_vdb_relation WHERE workspace = '';
DELETE FROM lightrag_vdb_chunks   WHERE workspace = '';

The LLM response cache is kept, so the re-ingest can reuse cached extraction answers.