Description

n8n-nodes-falkordb

⚠️ Development Warning: This package is currently under active development and should NOT be used in production environments. Features may be incomplete, unstable, or subject to breaking changes without notice.

This is an n8n community node package that provides FalkorDB-based memory management for AI Agent workflows in n8n.

FalkorDB is a graph database that provides powerful knowledge graph capabilities through its REST API, making it ideal for AI memory applications that require rich relationship modeling and context understanding.

Installation

Follow the installation guide in the n8n community nodes documentation.

Node

This package includes one specialized cluster node designed for AI Agent memory management:

FalkorDB Knowledge Graph Node (AI Agent Memory)

A cluster node that leverages AI models to build and query knowledge graphs for intelligent memory management in AI workflows.

Features:

• AI-powered entity and relationship extraction from conversations
• Knowledge graph construction in FalkorDB
• AI-generated Cypher queries for context retrieval
• Session-based memory management
• Integration with n8n AI Agent nodes
• LangChain compatibility for seamless workflow integration

Connection Types:

• Inputs:
  • AiLanguageModel (required) – AI model for entity extraction and query generation
  • Main (optional) – Text input for processing
• Outputs:
  • AiVectorStore (connects to AI Agent nodes for memory)
  • Main – Processing results and statistics

Key Operations:

• Extract entities and relationships from natural language using AI
• Build knowledge graphs with rich relationship modeling
• Generate intelligent context queries for memory retrieval
• Dual functionality: standalone processing and AI Agent memory integration

Credentials

You need to create a FalkorDB API credential with the following information:

• Host: FalkorDB server hostname or IP address (default: localhost)
• Port: FalkorDB REST API port (default: 3000)
• Username: Username for authentication (optional)
• Password: Password for authentication (optional)
• SSL/TLS: Whether to use SSL/TLS connection (default: false)

Example Usage

AI Agent Memory Integration

1. Add AI Language Model

   • Add your preferred AI model node (OpenAI, Claude, etc.)
   • Configure with appropriate credentials

2. Add FalkorDB Knowledge Graph Node

   • Drag the FalkorDB Knowledge Graph node into your workflow
   • Configure the FalkorDB API credentials
   • Set graph name (e.g., ai-memory)
   • Connect the AI model to the Knowledge Graph node

3. Connect to AI Agent

   • Connect the FalkorDB Knowledge Graph node output to your AI Agent node
   • The AI Agent will automatically use the knowledge graph for memory
   • Memory is persisted and enriched across workflow executions

Sample Workflow

[OpenAI Model] ──┐
                 │
Chat Trigger ────┤── [FalkorDB Knowledge Graph] ──── [AI Agent] ──── Response
                 │          (Memory)
[FalkorDB Creds] ─┘

The AI Agent will:

• Extract entities and relationships from conversations using the connected AI model
• Build a knowledge graph in FalkorDB with rich relationship modeling
• Generate intelligent context queries for memory retrieval
• Maintain persistent, queryable memory across sessions

Example Knowledge Graph Construction

Human Input: "I, Laurent, love apples and work at Google"

AI Extraction:

{
  "entities": [
    {"name": "Laurent", "type": "Person", "id": "person_laurent"},
    {"name": "apples", "type": "Food", "id": "food_apples"},
    {"name": "Google", "type": "Company", "id": "company_google"}
  ],
  "relationships": [
    {"from": "person_laurent", "to": "food_apples", "type": "LOVES"},
    {"from": "person_laurent", "to": "company_google", "type": "WORKS_AT"}
  ]
}

Knowledge Graph Result:

(Laurent:Person)-[:LOVES]->(apples:Food)
(Laurent:Person)-[:WORKS_AT]->(Google:Company)

Future Context Query: "What should I eat for lunch?"

AI-Generated Cypher Query:

MATCH (p:Person)-[r:LOVES|LIKES]->(f:Food) 
WHERE p.name = 'Laurent'
RETURN f.name, f.type, r.type
LIMIT 20

Context Retrieved: "Laurent loves apples"

Configuration Options

Knowledge Graph Settings

• Graph Name: FalkorDB graph name for memory storage (default: memory)

The node uses sensible defaults and leverages the connected AI model for intelligent processing.

Memory Features

• AI-Powered Extraction: Uses connected AI models for sophisticated entity and relationship extraction
• Knowledge Graph Construction: Builds rich, queryable knowledge graphs in FalkorDB
• Intelligent Querying: AI-generated Cypher queries for context retrieval
• Session Management: Automatic session-based memory isolation
• Persistent Storage: Memory survives workflow restarts
• Dual Functionality: Works as both standalone processor and AI Agent memory

API Integration

FalkorDB REST API

This node integrates with FalkorDB's REST API available at http://<hostname>:3000/api:

• Endpoint: /api/graph/{graph_name}
• Method: POST
• Authentication: Cookie-based session authentication
• Content-Type: application/json

Request Format

{
  "query": "CYPHER_QUERY",
  "parameters": {
    "param1": "value1",
    "param2": "value2"
  }
}

AI Workflow Integration

LangChain Compatibility

• Memory Interface: Compatible with LangChain's BaseChatMemory
• Message Processing: Handles conversation flow and context
• Session Management: Automatic session handling for AI workflows
• Graph Integration: Seamless integration with n8n's AI ecosystem

Use Cases

• Conversational AI: Persistent, intelligent memory across chat sessions
• Knowledge Retention: Long-term memory with rich relationship modeling
• Multi-turn Conversations: Context-aware responses with graph-based memory
• Fact Extraction: Automatic knowledge graph construction from conversations
• Semantic Understanding: AI-powered entity and relationship recognition

Architecture

Knowledge Graph Memory Management

• Entities: People, objects, concepts stored as graph nodes
• Relationships: Connections between entities (LOVES, WORKS_AT, KNOWS, etc.)
• AI-Powered Processing: Leverages connected AI models for extraction and querying
• Rich Context: Graph relationships provide deeper context than simple vector similarity

Cluster Node Design

• Multiple Inputs: AI model and optional text input
• Dual Outputs: Memory interface for AI Agents and processing results
• Flexible Integration: Works with any LangChain-compatible AI model
• Scalable Architecture: Handles complex knowledge graphs efficiently

Resources

• FalkorDB Documentation
• FalkorDB REST API
• n8n Community Nodes
• n8n AI Agent Documentation

Development

Build Instructions

To build the package for development or publishing:

# Install dependencies
npm install

# Build the package (compiles TypeScript and copies assets)
npm run build

# Run linting checks
npm run lint

# Auto-fix linting issues
npm run lintfix

# Format code
npm run format

# Development with watch mode
npm run dev

Publishing to npm

To prepare and publish this package to npm:

1. Ensure all tests pass and code is clean:

   npm run build
   npm run lint
   npm run format
   

2. Update version in package.json:

   npm version patch  # for bug fixes
   npm version minor  # for new features
   npm version major  # for breaking changes
   

3. Run pre-publish checks:

   npm run prepublishOnly
   

4. Publish to npm:

   npm publish
   

   For first-time publishing, you may need to login:

   npm login
   npm publish
   

Development Guidelines

• All code must pass ESLint checks with n8n community standards
• TypeScript compilation must be error-free
• Follow existing code patterns and n8n conventions
• Test all node operations thoroughly before publishing

License

MIT

Version History

1.0.1 (Current)

• Complete Architecture Redesign: Cluster node with AI model integration
• AI-Powered Knowledge Graph: Entity and relationship extraction using connected AI models
• Intelligent Query Generation: AI-generated Cypher queries for context retrieval
• Dual Functionality: Standalone processing and AI Agent memory integration
• LangChain Compatibility: Proper integration with n8n's AI ecosystem
• Session Management: Rich session-based memory with graph relationships

0.1.6

• Vector store implementation (deprecated)
• Basic FalkorDB integration
• Placeholder embedding generation

0.1.0

• Initial release with multiple node types (consolidated)