@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:

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:

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.

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.

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.

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

List Documents

Returns a list of all documents that have been ingested into the knowledge 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.

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.

Output — { status, documentId }

Advanced ingest options

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

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.

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:

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

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

GITHUB_TOKEN is provided automatically by GitHub Actions.

License

MIT © FalkorDB