@falkordb/n8n-nodes-graphrag

An n8n community node that connects your workflows to a FalkorDB GraphRAG-Server. Ingest documents into a knowledge graph and answer natural-language questions against it — either as a normal pipeline step or as a tool an AI Agent can call autonomously.

Table of contents

• What is GraphRAG?
• Features
• How it works
• Prerequisites
• Installation
• Credentials
• Usage
  • Pipeline node — FalkorDB GraphRAG
  • AI Agent tool — FalkorDB GraphRAG Tool
  • Operations reference
  • Advanced ingest options
  • Example workflows
• Contributing
• Continuous integration
• Releases
• License

What is GraphRAG?

GraphRAG (graph-based retrieval-augmented generation) turns your documents into a knowledge graph of entities and relationships, then answers questions by retrieving the relevant sub-graph and feeding it to an LLM. Compared to plain vector RAG, the graph captures how facts connect, which improves multi-hop reasoning and grounding. FalkorDB provides the graph database and the GraphRAG-Server handles ingestion, entity extraction, embedding, and retrieval.

Features

• Pipeline operations — Ask Question, Ingest Text, Ingest GitHub Repo, List Documents, Update Document, and Delete Document.

• Same operations as an AI Agent tool — the node is marked usableAsTool, so n8n automatically publishes a FalkorDB GraphRAG Tool variant with every operation available.

• Named graph targeting — every operation includes a Graph Name field so you can target a specific FalkorDB graph. It defaults to n8n-graph.

• Flexible GitHub ingestion — specify a branch, tag, or commit SHA to pin the exact revision you want to ingest.

• Advanced ingest options — chunking strategy, chunk size and overlap, entity types to extract, and duplicate-resolution strategy.

• Three retrieval strategies — auto, local (fast, single-hop), or multi_path (deeper, multi-hop).

• Retriever/generator split support — set Ask Question to Retrieve Only to retrieve context in FalkorDB and generate the final answer in your own n8n chat model.

• AI Agent-ready — the tool variant accepts $fromAI() expressions so the LLM can fill parameters from the conversation automatically.

• Ten importable example workflows covering all operations and end-to-end patterns (see workflows/).

How it works

 n8n workflow ──▶ FalkorDB GraphRAG node ──HTTP──▶ GraphRAG-Server ──▶ FalkorDB
   (you)            (this package)                    (you run it)       (graph DB)

The node is a thin HTTP client. It never talks to FalkorDB directly; it calls the GraphRAG-Server REST API (/api/ingest, /api/query, /api/documents, …) and returns the structured JSON response as n8n item data.

Prerequisites

• n8n >= 1.0 running in self-hosted mode (required to install community nodes).
• A reachable FalkorDB GraphRAG-Server instance — see the server setup guide. Note the base URL (e.g. http://localhost:8000) and an API token if the server has authentication enabled. For hosted usage, use https://graphrag.falkordb.com and create a token in Settings → API Tokens.

Installation

From the n8n UI (recommended)

1. Open n8n, go to Settings → Community Nodes → Install.
2. Enter the package name @falkordb/n8n-nodes-graphrag and confirm.
3. After installation the FalkorDB GraphRAG node appears in the node panel under the FalkorDB category, and n8n also lists a FalkorDB GraphRAG Tool variant under Tools for use with AI Agents.

Manually (self-hosted)

# in your n8n custom-nodes folder, typically ~/.n8n/nodes
npm install @falkordb/n8n-nodes-graphrag

Restart n8n after installation. For more details see the n8n docs on installing community nodes.

Credentials

The node and its derived Tool variant share a single credential type — FalkorDB GraphRAG Server API:

| Field | Required | Description | | --- | --- | --- | | Server URL | yes | Base URL of your GraphRAG-Server, e.g. http://localhost:8000. | | API Token | no | Sent as Authorization: Bearer …. Create it in GraphRAG-Server Settings → API Tokens. | | Request Timeout (Seconds) | yes | Per-request timeout. Requests abort when this limit is reached. |

Create the credential once under Credentials → New → FalkorDB GraphRAG Server API and reuse it everywhere the node is used. Leave API Token blank only when your server does not require authentication.

Usage

Pipeline node — FalkorDB GraphRAG

The FalkorDB GraphRAG node fits into any regular workflow. It receives items on its main input, executes the chosen operation for each item, and passes results to the main output. Use it to ingest documents as part of a data pipeline, run scheduled question-answering jobs, or check the ingestion queue.

Pick a Resource first — Knowledge Graph to query, or Document to manage what has been ingested — then the Operation within it.

For Ask Question, choose a retrieval strategy and response mode:

• Answer mode returns the server-generated answer.
• Retrieve Only mode returns { question, documents, count } so your own chat model can generate the final answer.

The node intentionally returns retrieve-only context as received from GraphRAG-Server. If you see duplicated passages or score: null, verify with a direct server call first (outside n8n):

curl -sS -X POST "$SERVER/api/query?graph_name=<yourGraph>" \
  -H "Authorization: ******" -H "X-Requested-With: XMLHttpRequest" \
  -H "Content-Type: application/json" \
  -d '{"question":"What are the main components?","retrieve_only":true,"return_context":true,"strategy":"local"}' \
  | jq '.context'

See workflows/04_action_ask_question.json and workflows/05_action_retrieve_only.json.

[Trigger] ──▶ [FalkorDB GraphRAG] ──▶ [Send Email / Slack / …]

AI Agent tool — FalkorDB GraphRAG Tool

The package ships a single node. Because it declares usableAsTool: true, n8n automatically derives a FalkorDB GraphRAG Tool variant that connects to an AI Agent node's ai_tool input. It offers the same six operations, and its parameters accept $fromAI() expressions so the LLM fills them from the conversation automatically.

[Chat Trigger] ──▶ [AI Agent] ──ai_tool──▶ [FalkorDB GraphRAG Tool]
                      │
                      └──ai_language_model──▶ [OpenAI / Anthropic / …]

Operations reference

The node exposes six operations, grouped under two Resource values so the n8n node panel lists them in sections:

| Resource | Operations | | --- | --- | | Knowledge Graph | Ask Question | | Document | Ingest Text, Ingest GitHub Repo, List Documents, Update Document, Delete Document |

The tool variant exposes the same set, plus a Tool Description field that n8n adds automatically.

Every operation includes Graph Name and defaults it to n8n-graph.

Ask Question

Sends a natural-language question to the GraphRAG-Server and returns a structured answer grounded in the knowledge graph.

| Parameter | Description | Default | | --- | --- | --- | | Question | The question to ask. | — | | Response Mode | answer returns the server-generated answer. retrieveOnly returns ranked context documents for downstream generation. | answer | | Retrieval Strategy | auto — server picks best; local — fast, single-hop; multi_path — deeper, multi-hop. | auto | | Graph Name | Named graph to query. This value defaults to n8n-graph. | n8n-graph |

Output — { question, answer } or, for retrieveOnly, { question, documents, count }

Ingest Text

Sends a plain-text or Markdown document to the server for chunking, entity extraction, and graph insertion.

| Parameter | Description | Default | | --- | --- | --- | | Document Text | The text content to ingest. Supports plain text and Markdown. | — | | Document Name | Document name hint for the server — use .txt for plain text, .md for Markdown. | document.txt | | Graph Name | Named graph to ingest into. This value defaults to n8n-graph. | n8n-graph | | Advanced Options | Reveal chunking and extraction controls (see below). | off |

Output — { documentName, status, nodesCreated, relationshipsCreated, chunksIndexed }

Ingest GitHub Repo

Discovers every Markdown file in a public GitHub repository and ingests them all in a single operation.

| Parameter | Description | Default | | --- | --- | --- | | GitHub Repo URL | Public repository URL, e.g. https://github.com/FalkorDB/GraphRAG-SDK. | — | | Branch / Tag / Commit | Specific ref to ingest. Leave blank for the default branch. | (blank, uses default branch) | | Graph Name | Named graph to ingest into. This value defaults to n8n-graph. | n8n-graph | | Advanced Options | Reveal chunking and extraction controls (see below). | off |

Output — { repoUrl, filesIngested, totalNodesCreated, totalRelationshipsCreated, files, skippedFiles, finalized }

List Documents

Returns a list of all documents that have been ingested into the knowledge graph.

| Parameter | Description | Default | | --- | --- | --- | | Graph Name | Named graph to list documents from. This value defaults to n8n-graph. | n8n-graph |

Output — { documents: [...], count }

Update Document

Updates a previously-ingested document in place. The server diffs the new content against the stored version chunk by chunk — unchanged chunks are reused from the graph at zero LLM cost, and only changed chunks are re-extracted. Sending identical content short-circuits to a no-op. Requires GraphRAG-Server with the PUT /api/documents/{name} endpoint.

| Parameter | Description | Default | | --- | --- | --- | | Document Name | Display name (or ID) of the document to update, as shown by List Documents. | — | | Document Text | The complete new content — always the full document, not a partial diff. | — | | Upsert | Ingest as a new document when the name is unknown, instead of failing. | off | | Use Chunk Cache | Reuse graph data for unchanged chunks. Disable to force full re-extraction. | on | | Graph Name | Named graph to update. This value defaults to n8n-graph. | n8n-graph | | Advanced Options | Reveal chunking and extraction controls (see below). | off |

Output — { status, document, documentId, noOp, nodesCreated, relationshipsCreated, chunksIndexed, cachedChunks, extractedChunks }

See workflows/10_action_github_sync.json for a complete GitHub-push-to-knowledge-graph sync built on this operation.

Delete Document

Removes an ingested document from the knowledge graph, together with its chunks and any entities that are no longer referenced by other documents. This operation is destructive — the document must be re-ingested to restore it.

| Parameter | Description | Default | | --- | --- | --- | | Document ID | ID of the document to delete, as returned by List Documents. | — | | Graph Name | Named graph to delete from. This value defaults to n8n-graph. | n8n-graph |

Output — { status, documentId }

Advanced ingest options

Toggle Advanced Options on the Ingest Text, Ingest GitHub Repo, or Update Document operations to reveal these controls:

| Option | Description | Default | | --- | --- | --- | | Chunking Strategy | sentence_token_cap — sentence-aware chunks capped at a token limit; fixed_size — fixed-width token windows. | sentence_token_cap | | Max Tokens Per Chunk | Token cap per chunk (64–2048). Used with sentence_token_cap. | 256 | | Overlap Sentences | Number of sentences of overlap between consecutive chunks (0–10). Used with sentence_token_cap. | 1 | | Chunk Size (Tokens) | Tokens per chunk (100–5000). Used with fixed_size. | 1000 | | Chunk Overlap (Tokens) | Token overlap between consecutive fixed-size chunks (0–500). | 100 | | Resolution Strategy | How duplicate entities are resolved: exact, description_merge, semantic, llm_verified, or all for the pipeline node; exact or fuzzy for the AI tool node. | exact | | Entity Types | Comma-separated list of entity types to extract, e.g. Person,Organization. Leave blank to extract all types. | (blank, all types) |

Example workflows

Import any file from workflows/ via Workflows → Import from File in n8n.

After importing, update the credential references: pipeline examples (01–05, 10) need the FalkorDB GraphRAG Server API credential, the AI Agent tool examples (06–09) also need an AI model credential (e.g. OpenAI) attached to the Agent node, and the GitHub sync example (10) additionally needs a GitHub credential on its trigger.

| File | Node style | Operation | | --- | --- | --- | | 01_action_ingest_text.json | Pipeline | Ingest Text | | 02_action_ingest_github.json | Pipeline | Ingest GitHub Repo | | 03_action_list_documents.json | Pipeline | List Documents | | 04_action_ask_question.json | Pipeline | Ask Question | | 05_action_retrieve_only.json | Pipeline | Retrieve Only | | 06_tool_ingest_text.json | AI Agent tool | Ingest Text | | 07_tool_ingest_github.json | AI Agent tool | Ingest GitHub Repo | | 08_tool_list_documents.json | AI Agent tool | List Documents | | 09_tool_ask_question.json | AI Agent tool | Ask Question | | 10_action_github_sync.json | Pipeline | Update Document + List Documents (GitHub push sync) |

Contributing

Contributions are welcome! Every check — formatting, linting, building, testing — runs through just, so the command you run locally is identical to what CI runs.

Set up

git clone https://github.com/FalkorDB/GraphRAG-n8n.git
cd GraphRAG-n8n
just install        # npm ci --ignore-scripts

Development recipes

Run just --list to see all available recipes. The most useful ones:

| Recipe | What it does | | --- | --- | | just check | Fast pre-commit loop: fmt, lint, build. | | just ci | Full CI gate: fmt-check, lint, build, test. | | just done | Definition-of-done: ci + coverage + spellcheck. Run before opening a PR. | | just fmt / just fmt-check | Auto-format with Prettier / check formatting only. | | just lint / just lintfix | Lint with eslint-plugin-n8n-nodes-base / auto-fix. | | just build | Compile TypeScript to dist/ and copy node + credential icons. | | just test | Run Vitest once. | | just coverage | Run Vitest with V8 coverage (matches the CI coverage job). | | just spellcheck | Spellcheck Markdown docs with pyspelling + aspell. |

Conventions

• Conventional Commits. PR titles and commits use Conventional Commits prefixes (feat:, fix:, docs:, ci:, …). The PR title becomes the squash-merge subject and drives the automated release — keep it clean and spellcheck-friendly. Mark breaking changes with feat!:.
• Green before review. Run just done and confirm it passes before opening a PR.
• Spellcheck new terms. Add any new public term or type name that appears in docs to .github/wordlist.txt, or backtick it (`TypeName`) so the spellchecker ignores it.
• Never self-merge. Open the PR, get it green, and wait for maintainer approval.

Full contributor conventions are in .github/copilot-instructions.md.

Continuous integration

| Workflow | Trigger | What it runs | | --- | --- | --- | | pr-checks.yml | PRs to main | fmt-check, lint, build, test, coverage — all via just. | | spellcheck.yml | push / PR to main | Spellcheck Markdown docs and the PR title. | | release.yml | push to main | release-please release PR; npm publish on release tag. |

main is protected: all PR-check jobs must be green and one approving review is required before merge.

Releases

Releases are fully automated with release-please:

1. Merge one or more Conventional-Commit PRs into main.
2. release-please opens (or updates) a release PR that bumps the version in package.json and regenerates CHANGELOG.md from the commit history. Do not hand-edit released CHANGELOG sections.
3. Merge the release PR — this tags the commit and publishes a GitHub Release.
4. The release event triggers the publish-npm job, which runs npm publish.

Version-bump rules: feat: → minor, fix: → patch, feat!: / BREAKING CHANGE: footer → major.

Required repository secrets

| Secret | Purpose | Required | | --- | --- | --- | | NPM_TOKEN | Publish to the npm registry | Yes, to publish | | CODECOV_TOKEN | Upload coverage to Codecov | Optional |

GITHUB_TOKEN is provided automatically by GitHub Actions.

License

MIT © FalkorDB