`@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.

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)

Open n8n, go to Settings → Community Nodes → Install.
Enter the package name @falkordb/n8n-nodes-graphrag and confirm.
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:

Merge one or more Conventional-Commit PRs into main.
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.
Merge the release PR — this tags the commit and publishes a GitHub Release.
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

Name		Name	Last commit message	Last commit date
Latest commit History 61 Commits
.github		.github
credentials		credentials
nodes/GraphRagAction		nodes/GraphRagAction
scripts		scripts
src		src
tests		tests
workflows		workflows
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
.release-please-manifest.json		.release-please-manifest.json
CHANGELOG.md		CHANGELOG.md
Justfile		Justfile
LICENSE		LICENSE
README.md		README.md
index.ts		index.ts
package-lock.json		package-lock.json
package.json		package.json
release-please-config.json		release-please-config.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Uh oh!

Repository files navigation

`@falkordb/n8n-nodes-graphrag`

Table of contents

What is GraphRAG?

Features

How it works

Prerequisites

Installation

From the n8n UI (recommended)

Manually (self-hosted)

Credentials

Usage

Pipeline node — FalkorDB GraphRAG

AI Agent tool — FalkorDB GraphRAG Tool

Operations reference

Ask Question

Ingest Text

Ingest GitHub Repo

List Documents

Update Document

Delete Document

Advanced ingest options

Example workflows

Contributing

Set up

Development recipes

Conventions

Continuous integration

Releases

Required repository secrets

License

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

@falkordb/n8n-nodes-graphrag

Table of contents

What is GraphRAG?

Features

How it works

Prerequisites

Installation

From the n8n UI (recommended)

Manually (self-hosted)

Credentials

Usage

Pipeline node — FalkorDB GraphRAG

AI Agent tool — FalkorDB GraphRAG Tool

Operations reference

Ask Question

Ingest Text

Ingest GitHub Repo

List Documents

Update Document

Delete Document

Advanced ingest options

Example workflows

Contributing

Set up

Development recipes

Conventions

Continuous integration

Releases

Required repository secrets

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`@falkordb/n8n-nodes-graphrag`