# 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`](https://github.com/skaiworldwide-oss/agensgraph-python) driver (2.0 or later) and `psycopg[binary]` (3.3.4 or later). Every statement goes through the driver. ## Install ```bash 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: ```bash 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: ```python import lightrag_agensgraph # registers AgensgraphStorage, AgensgraphVectorStorage, # AgensgraphKVStorage, AgensgraphDocStatusStorage ``` ## Set up the pgvector extension The vector storage uses [pgvector](https://github.com/pgvector/pgvector). AgensGraph does not bundle it, so build it once against your AgensGraph install: ```bash 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: ```sql -- 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](usage.md). LightRAG checks at start-up that `AGENSGRAPH_DB`, `AGENSGRAPH_USER`, and `AGENSGRAPH_PASSWORD` exist, so set them even when you connect with `AGENSGRAPH_URI`. ```bash 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](usage.md). ### 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. ```bash 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 `_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;`. ```sql 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.