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 - 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": "6379"
}
}
}
}
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
🏗️ 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"
}
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"
}
🛠️ 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=6379
FALKORDB_MEMORY_LIMIT=2gb
# PostgreSQL Configuration
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_USER=graphiti
POSTGRES_PASSWORD=YOUR_SECURE_PASSWORD
POSTGRES_DB=graphiti
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 6379 is not in use:
lsof -i :6379 - 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=truein.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