FalkorDB Graph Storage

The @graphrag-js/falkordb package provides lightweight graph storage using FalkorDB, a Redis-based graph database with Cypher query support.

Installation

pnpm add @graphrag-js/falkordb

Features

• ✅ Redis-Based - Built on Redis for reliability
• ✅ Cypher Queries - Familiar query language
• ✅ Low Latency - In-memory graph operations
• ✅ Horizontal Scaling - Redis cluster support
• ✅ Simple Deployment - Single Docker container
• ✅ Cost-Effective - Lightweight alternative to Neo4j

Prerequisites

FalkorDB Instance

Option 1: Docker (Recommended)

docker run -d \
  --name falkordb \
  -p 6379:6379 \
  -v falkordb-data:/data \
  falkordb/falkordb:latest

Option 2: Docker Compose

version: '3.8'
services:
  falkordb:
    image: falkordb/falkordb:latest
    ports:
      - "6379:6379"
    volumes:
      - falkordb-data:/data
    restart: unless-stopped

volumes:
  falkordb-data:

Verify Installation

redis-cli ping
# PONG

redis-cli GRAPH.QUERY test "CREATE (n:Node {id: 'test'})"

Quick Start

import { createGraph } from '@graphrag-js/core';
import { fastGraph } from '@graphrag-js/fast';
import { falkorGraph } from '@graphrag-js/falkordb';
import { openai } from '@ai-sdk/openai';

const graph = createGraph({
  model: openai('gpt-4o-mini'),
  embedding: openai.embedding('text-embedding-3-small'),
  provider: fastGraph(), // FalkorDB works well with Fast GraphRAG
  storage: {
    graph: falkorGraph({
      host: 'localhost',
      port: 6379,
      password: undefined, // Optional
    }),
  }
});

await graph.insert('Your documents...');
const result = await graph.query('Your question?');

Configuration

falkorGraph(config)

interface FalkorGraphConfig {
  host?: string;       // Redis host (default: 'localhost')
  port?: number;       // Redis port (default: 6379)
  password?: string;   // Redis password (optional)
  workingDir?: string; // Namespace prefix (default: 'default')
}

Connection Examples

// Local instance
falkorGraph({
  host: 'localhost',
  port: 6379,
})

// Password-protected
falkorGraph({
  host: 'localhost',
  port: 6379,
  password: 'your-password',
})

// Remote instance
falkorGraph({
  host: 'falkordb.example.com',
  port: 6379,
  password: 'secure-password',
})

Usage Examples

Basic Graph Operations

import { falkorGraph } from '@graphrag-js/falkordb';

const graphStore = falkorGraph({
  host: 'localhost',
  port: 6379,
})('my-namespace');

// Add nodes
await graphStore.upsertNode('entity-1', {
  entity_type: 'person',
  description: 'Alice, data scientist',
  source_id: 'doc-1',
});

// Add edges
await graphStore.upsertEdge('entity-1', 'entity-2', {
  relationship: 'works_with',
  weight: 0.9,
  description: 'Collaborates on ML projects',
});

// Get node
const node = await graphStore.getNode('entity-1');

// Traverse graph
const edges = await graphStore.getNodeEdges('entity-1');

With Fast GraphRAG

FalkorDB is ideal for Fast GraphRAG's PageRank-based retrieval:

import { fastGraph } from '@graphrag-js/fast';
import { falkorGraph } from '@graphrag-js/falkordb';

const graph = createGraph({
  model: openai('gpt-4o-mini'),
  embedding: openai.embedding('text-embedding-3-small'),
  provider: fastGraph({
    entityTypes: ['PERSON', 'ORGANIZATION', 'CONCEPT'],
    pagerank: {
      damping: 0.85,
      maxIterations: 100,
    },
  }),
  storage: {
    graph: falkorGraph({
      host: 'localhost',
      port: 6379,
    }),
  }
});

Knowledge Graph Extraction

const kg = await graphStore.getKnowledgeGraph(
  'person',      // Node label
  2,             // Max depth
  1,             // Min degree
  true           // Inclusive
);

// Returns nodes and edges
console.log(kg.nodes.length);
console.log(kg.edges.length);

Direct Cypher Queries

For advanced use cases, use the FalkorDB SDK directly:

import FalkorDB from 'falkordb';

const client = FalkorDB.connect({
  host: 'localhost',
  port: 6379,
});

const graph = client.selectGraph('my-graph');

// Execute Cypher
const result = await graph.query(`
  MATCH (n:person)-[r:works_with]->(m:person)
  WHERE n.id = $nodeId
  RETURN m.id AS colleague, r.weight AS strength
`, { nodeId: 'entity-1' });

console.log(result.data);

Performance Characteristics

Benchmarks

On 100K nodes (M1 Mac):

Operation	Latency
Node insert	2-5ms
Edge insert	2-5ms
Node lookup	1-3ms
Graph traversal (depth=2)	5-15ms
Cypher query (simple)	5-10ms

Memory Usage

FalkorDB stores graphs in Redis memory:

• Node: ~500 bytes per node
• Edge: ~300 bytes per edge

Example: 100K nodes + 200K edges:

• Nodes: 100K × 500 bytes = 50MB
• Edges: 200K × 300 bytes = 60MB
• Total: ~110MB

Limitations

Community Detection

FalkorDB does not currently support advanced graph algorithms like Leiden clustering. Use Neo4j if you need:

• Community detection
• Advanced centrality algorithms
• Graph data science workflows

When to Use FalkorDB

✅ Good for:

• Fast GraphRAG and lightweight providers
• Simple graph traversal
• Cost-effective graph storage
• Redis-familiar teams
• Moderate-scale graphs (< 1M nodes)

❌ Not recommended for:

• Microsoft GraphRAG (needs Leiden clustering)
• Complex graph analytics
• Very large graphs (> 1M nodes)
• Advanced graph algorithms

Production Deployment

Redis Persistence

Enable RDB and AOF for durability:

docker run -d \
  --name falkordb \
  -p 6379:6379 \
  -v falkordb-data:/data \
  falkordb/falkordb:latest \
  --appendonly yes \
  --save 900 1 \
  --save 300 10

Redis Cluster

For high availability:

version: '3.8'
services:
  falkordb-1:
    image: falkordb/falkordb:latest
    ports:
      - "6379:6379"
    volumes:
      - falkordb-1-data:/data

  falkordb-2:
    image: falkordb/falkordb:latest
    ports:
      - "6380:6379"
    volumes:
      - falkordb-2-data:/data

  falkordb-3:
    image: falkordb/falkordb:latest
    ports:
      - "6381:6379"
    volumes:
      - falkordb-3-data:/data

volumes:
  falkordb-1-data:
  falkordb-2-data:
  falkordb-3-data:

Monitoring

# Monitor memory usage
redis-cli info memory

# Monitor graph operations
redis-cli monitor

# Check graph stats
redis-cli GRAPH.QUERY my-graph "MATCH (n) RETURN count(n)"

Backup Strategy

# Manual backup (RDB)
redis-cli SAVE
cp /data/dump.rdb /backups/dump-$(date +%Y%m%d).rdb

# Restore
cp /backups/dump-20240101.rdb /data/dump.rdb
docker restart falkordb

Troubleshooting

Connection Refused

Error: Error: connect ECONNREFUSED

Solution:

1. Verify FalkorDB is running: docker ps | grep falkordb
2. Check port: 6379
3. Test: redis-cli ping

Out of Memory

Error: OOM command not allowed when used memory > 'maxmemory'

Solution:

# Increase memory limit
docker run -d \
  --name falkordb \
  -p 6379:6379 \
  falkordb/falkordb:latest \
  --maxmemory 4gb \
  --maxmemory-policy allkeys-lru

Graph Not Found

Error: Graph 'xxx' not found

Solution:

• Graphs are created automatically on first write
• Check namespace configuration
• Verify graph name matches

Cost Considerations

Deployment	Cost	Best For
Self-hosted	Free + hosting	Any scale, full control
Redis Cloud	$5+/month	Managed hosting
Redis Enterprise	Custom	Enterprise features

FalkorDB is significantly cheaper than Neo4j for simple graph workloads.

Comparison with Neo4j

Feature	FalkorDB	Neo4j
Query Language	Cypher	Cypher
Performance (small graphs)	Faster	Slower
Performance (large graphs)	Slower	Faster
Community Detection	❌	✅ (GDS)
Advanced Algorithms	❌	✅ (GDS)
Memory Usage	Lower	Higher
Setup Complexity	Lower	Higher
Cost	Lower	Higher

Recommendation: Use FalkorDB for Fast GraphRAG, LightRAG, or AWS GraphRAG. Use Neo4j for Microsoft GraphRAG.

Next Steps

• Neo4j Storage - For advanced graph analytics
• Redis Storage - For KV storage
• Fast GraphRAG Algorithm
• FalkorDB Documentation