How do I use Faulkner DB?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Faulkner DB show me the timeline of decisions for our database architecture" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Faulkner DB - Temporal Knowledge Graph System

License: MIT Python Version Docker npm version CI Status GitHub stars

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 - 7 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"], "env": { "PYTHONPATH": "/path/to/faulkner-db", "FALKORDB_HOST": "localhost", "FALKORDB_PORT": "6380", "FALKORDB_PASSWORD": "faulkner_kg_2026_secure" } } } }

3. Access Services

Network Graph: http://localhost:8082/static/index.html
Timeline View: http://localhost:8082/static/timeline.html
Dashboard: http://localhost:8082/static/dashboard.html
API Health: http://localhost:8082/health
FalkorDB UI: http://localhost:8081

Security Configuration

Authentication

FalkorDB now requires password authentication for all connections.

Setting	Value
Environment Variable	`FALKORDB_PASSWORD`
Default (local dev)	`faulkner_kg_2026_secure`

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.falkor_adapter import FalkorDBAdapter password = os.environ.get('FALKORDB_PASSWORD') adapter = FalkorDBAdapter(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 - Disabled
FLUSHDB - Disabled

If you need to clear data during development, use the provided backup/restore scripts or recreate the container with a fresh volume.

🏗️ Architecture

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

📚 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" }

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" }

🛠️ 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.8+
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=faulkner_kg_2026_secure FALKORDB_MEMORY_LIMIT=2gb # PostgreSQL Configuration POSTGRES_HOST=postgres POSTGRES_PORT=5432 POSTGRES_USER=graphiti POSTGRES_PASSWORD=YOUR_SECURE_PASSWORD POSTGRES_DB=graphiti

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

MCP Server Configuration

The MCP server automatically connects to FalkorDB and PostgreSQL using environment variables. No additional configuration needed.

🐛 Troubleshooting

Docker containers not starting

# Check container status docker-compose ps # View logs docker-compose logs -f # Restart services docker-compose restart

FalkorDB connection errors

Verify FalkorDB is running: docker-compose ps
Check port 6380 is not in use: lsof -i :6380
Verify password is set: echo $FALKORDB_PASSWORD
Review FalkorDB logs: docker-compose logs falkordb

MCP server not detected in Claude

Verify configuration path matches your OS (see npm package docs)
Restart Claude Desktop/Code after config changes
Check Python path in MCP config is correct
Ensure Docker stack is running

Data persistence issues

Verify docker/data/ directory has correct permissions
Check FALKORDB_PERSISTENCE=true in .env
Backup data: docker-compose exec falkordb redis-cli BGSAVE

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Fork the repository and create a feature branch
Write tests for new features (pytest)
Follow code style (PEP 8 for Python)
Document changes in code and README
Submit pull request with clear description

Development Setup

# Clone repository git clone https://github.com/platano78/faulkner-db.git cd faulkner-db # Install dependencies pip install -r requirements.txt # Run tests pytest tests/ -v # Run with coverage pytest tests/ --cov=core --cov=mcp_server

See CONTRIBUTING.md for detailed guidelines.

📄 License

MIT License - see LICENSE for details.

🗺️ Roadmap

Phase 1: Core Knowledge Graph
Phase 2: Hybrid Search
Phase 3: Gap Detection
Phase 4: MCP Server Integration
Phase 5: Docker Deployment
Phase 6: Testing & Validation
Phase 7: Advanced Analytics Dashboard
Phase 8: Multi-tenant Support
Phase 9: Cloud Deployment Options

📞 Support

Issues: https://github.com/platano78/faulkner-db/issues
Discussions: https://github.com/platano78/faulkner-db/discussions
Documentation: https://github.com/platano78/faulkner-db/wiki

🙏 Acknowledgments

Built with:

FalkorDB - Graph database with temporal support
ChromaDB - Vector embeddings (previous iteration)
sentence-transformers - Semantic embeddings
NetworkX - Graph analysis algorithms
FastMCP - MCP server framework

Made with ❤️ for software teams who value architectural knowledge