n8n-nodes-lightrag

This package provides n8n community nodes for LightRAG-style knowledge graph indexing and retrieval backed by Azure Cosmos DB for MongoDB vCore.

It currently includes two nodes:

• LightRAG: a standard workflow node for indexing, querying, deleting documents, inspecting graph stats, and initializing a database.
• LightRAG Tool: an AI Agent tool node that performs hybrid knowledge-graph retrieval and returns structured entities, relations, and chunks directly to the agent.

Installation

Follow the n8n community nodes installation guide, then install:

npm install @boazlai/n8n-nodes-lightrag

Operations

The LightRAG node supports:

• Insert Text
• Insert Chunks
• Query
• Create Database
• Delete Document
• Graph Stats

The LightRAG Tool node is retrieval-only and designed for AI Agent tool use. It connects directly to the agent's tool bus (AiTool output) alongside an Embeddings model and an optional Reranker.

Retrieval modes available on both nodes:

| Mode | Description | | ------------- | ------------------------------------------------------------ | | Hybrid KG | Hybrid chunk retrieval + knowledge graph expansion (default) | | Hybrid Chunks | Hybrid vector + full-text chunk retrieval only | | KG + Vector | Entity vector retrieval + graph context | | Naive | Vector chunk retrieval only | | Entity Only | Entity vector retrieval only |

The tool node returns three structured fields to the agent per invocation:

• entities — matched knowledge-graph entities (name, type, description)
• relations — matched graph relations (source, target, description, weight)
• chunks — matched document chunks (docId, chunkIndex, content, chunkDoc metadata)

Credentials

Use the LightRAG Cosmos DB credential with:

• a MongoDB connection string for Azure Cosmos DB for MongoDB vCore
• a default workspace name

The database is selected on the node itself so one credential can be reused across multiple databases.

Usage Notes

• Create Database initializes the collections required by the node.
• Query can combine vector retrieval, full-text retrieval, and graph augmentation.
• The tool node is intended for agent flows where you want structured retrieval results instead of a final generated answer.
• The tool node uses a two-phase architecture: supplyData() registers the tool schema with the agent at setup, and execute() runs the actual retrieval at invocation time. This matches the pattern used by native n8n vector store tool nodes.
• Connect an Embeddings model to the Embeddings input and optionally a Reranker to the Reranker input.

Resources

• n8n community nodes documentation
• LightRAG
• Repository

Version History

0.2.0

• LightRAG Tool: refactored to the two-phase AiTool architecture matching native n8n vector store tool nodes (supplyData for schema registration, execute for retrieval at runtime).
• LightRAG Tool: switched from DynamicTool to DynamicStructuredTool with a plain JSON Schema — fixes Bad request errors from OpenAI caused by Zod cross-instance mismatches.
• LightRAG Tool: execute() now returns structured items (entities, relations, chunks) directly instead of wrapping everything in a JSON string, making results usable in downstream nodes without parsing.
• LightRAG Tool: embeddings and reranker connections are resolved inside execute() on each invocation rather than being captured in a closure at setup time.

0.1.0

Initial release with standard LightRAG and LightRAG Tool nodes for Cosmos DB MongoDB vCore.