@catalogicus-international/n8n-nodes-light-rag

An n8n community package for LightRAG workflows, AI Agent retrieval, document
management, and live query progress in n8n Chat. Current release: 0.5.3.

Release 0.5.3 fixes credential validation by testing a protected, read-only LightRAG
endpoint instead of the public health check, so invalid API keys and bearer tokens no
longer appear valid.

Release 0.5.2 republishes the 0.5.1 behavior under a fresh patch version so npm
and self-hosted n8n installations can resolve the latest package metadata consistently.

Release 0.5.1 replaces raw source file names and front matter in live Chat progress
with compact Markdown materials. Public HTTP(S) sources use the front-matter title and
canonical/source URL as a clickable link, internal sources remain clearly labelled
plain text, and each item includes a cleaned preview of at most 180 characters.

Release 0.5.0 adds Chat Stream Response, a credential-free companion node for
streaming prepared Markdown replies from workflow branches that do not execute a
stream-capable AI or LightRAG node. This lets one Chat Trigger use Streaming response
without losing deterministic greeting, routing, contact, or fallback replies.

Release 0.4.0 adds opt-in LightRAG query progress, source excerpts, and answer
streaming for n8n Chat while preserving the regular workflow node's default buffered
behavior. LightRAG Tool remains retrieval-only through POST /query/data: LightRAG
retrieves text chunks and the connected AI agent writes the final answer.

Release 0.4.1 synchronizes the npm and node descriptions and the repository skills
with the streaming behavior introduced in 0.4.0; runtime behavior is unchanged.

Nodes

Chat Stream Response

Use Chat Stream Response in branches that already have a complete Markdown reply but
run under a Chat Trigger configured with Streaming response. Set Message to the
prepared text, for example {{$json.output}}. The node sends one begin, item, and
end sequence for every input item and then passes that item through its normal Main
output, preserving item pairing. It requires no credentials.

Do not place this node after a branch that already streamed the same answer. For mixed
flows, send only the deterministic suffix that was not emitted by the upstream streaming
node. An empty message or a non-streaming execution is treated as a node configuration
error; standard Continue On Fail behavior remains available.

LightRAG

Use LightRAG in a regular n8n workflow. It has standard Main input and output
connections and processes every incoming item.

The node reads only parameters that belong to the selected operation. Parameters hidden
by n8n displayOptions are never requested during execution. Operations such as
health, pipelineStatus, and scanDocuments therefore require no placeholder fields.

Choose an operation in the node UI. Operations that send JSON use the complete current
input item ({{$json}}) as the request body by default. For example, an input item for
the Query operation can be:

{
  "query": "What does the knowledge base say about LightRAG?",
  "mode": "mix",
  "include_references": true
}

You can replace the Request Body expression with a manually configured object or map
individual fields from previous nodes. Responses are emitted through the normal Main
output and retain n8n item pairing.

Stream Query progress to n8n Chat

Enable Stream Progress to Chat on the Query operation to remove the silent wait in
an n8n chat workflow. The Chat Trigger must use Streaming response, and the LightRAG
server must support POST /query/stream, include_progress, and
include_chunk_content.

The node immediately displays a request-start message, then translates LightRAG's live
retrieval stages into short Russian status messages. Once retrieval completes, it shows
up to three unique materials using title, canonical_url, and source_url from each
reference's front matter. Safe public HTTP(S) sources become Markdown links; identifiers
such as internal:* remain plain text. Each material includes a cleaned preview of at
most 180 Unicode characters. Raw front matter, file extensions, and internal directory
paths are not displayed. The streamed LightRAG answer follows under an Ответ heading.
These messages remain together in the final Markdown chat response.

In this mode the node forces stream, include_progress, include_references, and
include_chunk_content to true and parses the NDJSON response incrementally. Its Main
output remains an aggregated query result containing response, references, and any
response_time or llm_generated metadata returned by LightRAG. Outside a streaming
Chat Trigger workflow, the same mode still parses and returns the complete result but
does not emit UI chunks.

LightRAG Tool

Connect LightRAG Tool to the tool input of an n8n AI Agent. This node is dedicated
to querying the knowledge base, so the agent only sees one required Query field.
The endpoint is always POST /query/data.

The tool supports the standard n8n AI Agent and the main GigaChat AI node from
n8n-nodes-gigachat. Connect the nodes
through the AI Tool connection:

LightRAG Tool ──ai_tool──> GigaChat AI (Tools)

Use GigaChat AI, which is the package's root conversational agent with a Tools
input. Do not use the deprecated GigaChat Model for this integration: that model node
does not support AI Agent workflows.

Query the knowledge base:

{
  "query": "What does the knowledge base say about LightRAG?"
}

Retrieval settings are controlled only by visible node fields. The defaults are
Mode: Naive, KG Top K: 5, Chunk Top K: 5, Max Entity Tokens: 2000,
Max Relation Tokens: 2000, Max Total Tokens: 2000, Enable Rerank: false, and
Request Timeout: 30 seconds. The agent cannot override these values through tool
arguments. Numeric fields accept any positive integer; the connected LightRAG server
still applies its own deployment limits. Max Total Tokens includes LightRAG's own
prompt, the query, and reserved tokens, so the available chunk budget is smaller than
the UI value.

Naive is the recommended low-latency mode because it performs vector retrieval only.
Local, Global, Hybrid, and Mix may call an LLM to extract keywords and can be
slower. Bypass is not available because it produces no retrieval chunks.

The request body for the default profile is:

{
  "query": "What does the knowledge base say about LightRAG?",
  "mode": "naive",
  "top_k": 5,
  "chunk_top_k": 5,
  "max_entity_tokens": 2000,
  "max_relation_tokens": 2000,
  "max_total_tokens": 2000,
  "enable_rerank": false
}

The timeout is an HTTP client setting in milliseconds and is not sent in this body.

The tool exposes execute, invoke, and call compatibility methods. In particular,
execute allows GigaChat AI to pass the structured { "query": "..." } arguments
without converting them into a plain string. The tool returns only numbered plain-text
fragments; entity data, metadata, references, IDs, and file paths are not sent to the
agent. A no-results response and retrieval timeout are returned as controlled
LIGHTRAG_NO_RESULTS and LIGHTRAG_TIMEOUT messages. Other failures remain workflow
errors.

Each tool run records safe diagnostics in the n8n execution: retrieval settings,
duration, outcome, chunk count, and an HTTP status when available. The LightRAG Tool
does not add the query, chunks, response body, headers, or credentials to its diagnostic
records or logs. The parent AI Agent can still retain function arguments and tool output
as part of its own execution data.

The regular LightRAG workflow node retains the full operation list for document
management and custom requests, but is not exposed as an AI Agent tool.

Supported operations

• query — POST /query, or POST /query/stream when Stream Progress to Chat is enabled;
• queryData — POST /query/data;
• insertText — POST /documents/text;
• insertTexts — POST /documents/texts;
• trackStatus — GET /documents/track_status/{track_id};
• pipelineStatus — GET /documents/pipeline_status;
• listDocuments — POST /documents/paginated;
• scanDocuments — POST /documents/scan;
• deleteDocuments — DELETE /documents/delete_document;
• health — GET /health;
• customRequest — a request to any relative LightRAG API path.

Example custom request:

{
  "operation": "customRequest",
  "method": "GET",
  "path": "documents/status_counts",
  "queryParameters": {}
}

Only relative paths are accepted, so credentials cannot be forwarded to another host.

Query modes

The query operations support LightRAG modes local, global, hybrid, naive,
mix, and bypass. mix is the LightRAG-recommended general-purpose mode.

All request fields supported by the LightRAG API can be passed in body, including
response_type, top_k, chunk_top_k, token budgets, keyword lists,
conversation_history, user_prompt, reranking options, and reference options.

Credentials

Create a LightRAG API credential:

• Base URL: normally http://localhost:9621;
• Authentication: API Key, Bearer Token, or None;
• API key authentication is sent using X-API-Key;
• include a configured reverse-proxy API prefix in the Base URL when applicable.

The credential test calls the protected, read-only GET /documents/pipeline_status
endpoint. API Key and Bearer Token therefore pass only when the secret is accepted, while
None passes only when the server actually permits unauthenticated API access. GET /health
is a liveness check and is not used to validate credentials because LightRAG can return
HTTP 200 there without authenticating the caller.

Development

pnpm install
pnpm run lint
pnpm test

Resources

• LightRAG API Server documentation
• n8n node documentation

License

MIT