Faulkner DB - Temporal Knowledge Graph System

Faulkner DB empowers software teams to capture, query, and analyze architectural decisions, implementation patterns, and failures as they evolve over time. Built on FalkorDB (CPU-friendly graph database) with hybrid search capabilities, it provides unparalleled insights into your project's history, fostering better decision-making and reducing technical debt.

🎯 Value Proposition

Improved Decision Tracking - Capture the rationale behind architectural choices and their impact over time
Enhanced Collaboration - Facilitate knowledge sharing and alignment across teams
Reduced Technical Debt - Identify and address problematic patterns early
Faster Onboarding - Accelerate learning for new team members with comprehensive project history
AI-Ready Knowledge Base - Structure knowledge for AI-powered development tools (Claude Code/Desktop)

✨ Key Features

Temporal Knowledge Graph - Track changes to decisions and patterns over time
Hybrid Search - Graph traversal + vector embeddings + CrossEncoder reranking (<2s queries)
Gap Detection - NetworkX-based structural analysis to identify knowledge gaps
MCP Integration - 12 tools for seamless Claude Desktop/Code integration
Docker Deployment - One-command startup with auto-restart support
CPU-Friendly - Built on FalkorDB, no GPU required (gaming-friendly memory footprint)

📖 Documentation

Integration Setup Guide - Set up Agent Genesis + Faulkner-DB sync
Contributing Guidelines - How to contribute

🚀 Quick Start

Option 1: Automated NPM Setup (Recommended)

# Configure Claude Desktop/Code automatically
npx faulkner-db-config setup

# Clone and start the stack
git clone https://github.com/platano78/faulkner-db.git
cd faulkner-db/docker
docker-compose up -d

# Restart Claude Desktop/Code

Option 2: Manual Setup

1. Start FalkorDB Stack

git clone https://github.com/platano78/faulkner-db.git
cd faulkner-db/docker

# Copy environment template
cp .env.example .env

# Edit .env and set POSTGRES_PASSWORD

# Start services
docker-compose up -d

2. Configure Claude (Manual)

Add to ~/.config/Claude/claude_desktop_config.json (Linux) or equivalent:

{
  "mcpServers": {
    "faulkner-db": {
      "command": "python3",
      "args": ["-m", "mcp_server.server_fastmcp"],
      "env": {
        "PYTHONPATH": "/path/to/faulkner-db",
        "FALKORDB_HOST": "localhost",
        "FALKORDB_PORT": "6380",
        "FALKORDB_PASSWORD": "changeme"
      }
    }
  }
}

3. Access Services

Network Graph: http://localhost:VISUALIZATION_PORT/static/index.html
Timeline View: http://localhost:VISUALIZATION_PORT/static/timeline.html
Dashboard: http://localhost:VISUALIZATION_PORT/static/dashboard.html
API Health: http://localhost:VISUALIZATION_PORT/health

Set VISUALIZATION_PORT and FALKORDB_REST_PORT in docker/.env. See .env.example for defaults.

Security Configuration

Authentication

FalkorDB now requires password authentication for all connections.

| Setting | Value | |---------|-------| | Environment Variable | FALKORDB_PASSWORD | | Default (local dev) | changeme |

Port Configuration

The default port has been changed from 6379 to 6380 to avoid conflicts with standard Redis installations.

| Setting | Value | |---------|-------| | Environment Variable | FALKORDB_PORT | | Default Port | 6380 |

Connection Examples

Python

import os
from core.graphiti_client import GraphitiClient

password = os.environ.get('FALKORDB_PASSWORD')
client = GraphitiClient(host='localhost', port=6380, password=password)

redis-cli

redis-cli -p 6380 -a $FALKORDB_PASSWORD

Docker Compose Environment

environment:
  FALKORDB_HOST: falkordb
  FALKORDB_PORT: 6380
  FALKORDB_PASSWORD: ${FALKORDB_PASSWORD}

Destructive Commands Disabled

To prevent accidental data loss, the following commands are disabled in the FalkorDB configuration:

FLUSHALL - Renamed to an obscure command (not directly callable)
FLUSHDB - Renamed to an obscure command (not directly callable)

If you need to clear data during development, recreate the container with a fresh volume.

🏗️ Architecture

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│   Claude Code/      │    │   Faulkner DB       │    │     FalkorDB        │
│   Desktop           │───▶│   (MCP Server)      │───▶│   (Graph DB)        │
│                     │    │   Temporal Logic     │    │   CPU-Friendly      │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘
         │                          │                           │
         │                          │                           │
         ▼                          ▼                           ▼
┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│   12 MCP Tools      │    │   Hybrid Search      │    │   PostgreSQL        │
│   - add_decision    │    │   Graph + Vector     │    │   (Metadata Store)  │
│   - query_decisions │    │   + Reranking        │    │                     │
│   - detect_gaps     │    │                      │    │                     │
│   - get_timeline    │    │                      │    │                     │
│   - graph_summary   │    │                      │    │                     │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘

📚 MCP Tools Documentation

1. add_decision

Record architectural decision with full context and rationale.

{
  "description": "Use FalkorDB for temporal graphs",
  "rationale": "CPU-friendly, Redis-compatible, excellent temporal support",
  "alternatives": ["Neo4j", "ArangoDB"],
  "related_to": []
}

2. query_decisions

Hybrid search for decisions by topic/timeframe.

{
  "query": "authentication decisions",
  "timeframe": {
    "start": "2024-01-01",
    "end": "2024-12-31"
  }
}

3. add_pattern

Store successful implementation pattern.

{
  "name": "CQRS Pattern",
  "implementation": "Separate read/write models with event sourcing",
  "use_cases": ["High-scale systems", "Event-driven architecture"],
  "context": "Microservices with async communication"
}

4. add_failure

Document what didn't work and lessons learned.

{
  "attempt": "Used RabbitMQ with 50+ queues",
  "reason_failed": "Performance degradation under load",
  "lesson_learned": "Use Kafka for high-throughput streaming",
  "alternative_solution": "Migrated to Kafka with topic partitioning"
}

5. find_related

Graph traversal to discover related knowledge nodes.

{
  "node_id": "D-abc123",
  "depth": 2
}

6. detect_gaps

Run NetworkX structural analysis to identify knowledge gaps (>85% accuracy).

{}

7. get_timeline

Temporal view showing how understanding evolved over time.

{
  "topic": "Authentication System",
  "start_date": "2023-01-01",
  "end_date": "2024-12-31"
}

8. find_influential_patterns

Find the most connected/influential patterns using degree centrality.

{
  "limit": 10
}

9. find_knowledge_communities

Detect communities of related knowledge using connected components analysis.

{
  "min_community_size": 3
}

10. find_bridge_patterns

Find bridge patterns that connect different knowledge domains.

{
  "limit": 10
}

11. get_graph_summary

Get comprehensive summary of the knowledge graph structure, including node counts, edge counts, and connectivity metrics.

{}

12. query_patterns_semantic

Semantic search for patterns using sentence-transformers embeddings. More intelligent than keyword matching.

{
  "query": "authentication middleware",
  "limit": 10
}

🛠️ Technical Stack

| Component | Technology | |-----------|------------| | Graph Database | FalkorDB (CPU-only) | | Metadata Store | PostgreSQL | | Embeddings | sentence-transformers (all-MiniLM-L6-v2) | | Reranking | cross-encoder/ms-marco-MiniLM-L-6-v2 | | Graph Analysis | NetworkX | | MCP Server | Python 3.9+ (FastMCP) | | Deployment | Docker Compose |

⚡ Performance

Query Time: <2s (hybrid search with reranking)
Accuracy: 90%+ on decision queries
Gap Detection: >85% accuracy
Memory: Gaming-friendly (FalkorDB: 2GB, PostgreSQL: 1GB)
Scalability: Tested with 10,000+ nodes

🔧 Configuration

Environment Variables

Create docker/.env from .env.example:

# FalkorDB Configuration
FALKORDB_HOST=falkordb
FALKORDB_PORT=6380
FALKORDB_PASSWORD=changeme
FALKORDB_MEMORY_LIMIT=2gb
FALKORDB_REST_PORT=8082

# PostgreSQL Configuration
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_USER=graphiti
POSTGRES_PASSWORD=YOUR_SECURE_PASSWORD
POSTGRES_DB=graphiti

# Visualization
VISUALIZATION_PORT=8086

Note: The FALKORDB_PASSWORD is required for authentication. Change the default password in production environments.

MCP Server Configuration

The MCP server a

Faulkner Db

Install / Use

README