Faulkner Db

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 - 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": [],
  "source": "manual"
}

source is required as of v1.7.0 unless FAULKNER_ALLOW_AUTOMATED=true. Allowed values: "manual" (human-curated) or "reviewed_automated" (LLM-drafted, human-reviewed). See Ingestion Guards.

2. query_decisions

Hybrid search for decisions by topic/timeframe. Results are scoped to Decision nodes (the label predicate is pushed into the graph query, so selective scoping does not cost recall). limit (1-50, default 15) bounds the number of reranked results returned.

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

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",
  "source": "manual"
}

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",
  "source": "manual"
}

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
}

🛡️ Ingestion Guards (v1.7.0)

Every write through add_decision / add_pattern / add_failure is now gated to prevent re-introduction of two pollution patterns that historically ballooned the graph (10,781 nodes purged in v1.7.0):

1. Blocklist regex on name / context / description / attempt fields. Defaults block ^playbook-.*-\d{13}$ (MKG playbook signature) and .*-\d{13}$ (any unix-ms timestamp suffix, defensive). Override the list via FAULKNER_INGESTION_BLOCKLIST_FILE (JSON {"patterns": [...]} or one regex per line).
2. source_files containing agent-genesis — historically the conversation-fragment auto-ingest path. Hard-rejected.
3. source parameter required — must be "manual" or "reviewed_automated". Set FAULKNER_ALLOW_AUTOMATED=true to bypass when running an authorized automated reviewer.

Rejections are logged as one JSON line each to logs/rejected_writes.jsonl (timestamp, label, reason, truncated sample fields, matched pattern). Override the path via FAULKNER_REJECTION_LOG.

🩺 Graph Health Check (v1.7.0)

scripts/health_check.py is a read-only diagnostic over the live graph:

FALKORDB_HOST=192.168.1.79 FALKORDB_PORT=6380 FALKORDB_PASSWORD=... \
  python scripts/health_check.py            # human-readable
  python scripts/health_check.py --json     # machine-readable
  python scripts/health_check.py --strict   # exit 1 on any warning

Reports node/edge totals, Failure:Decision ratio (warn > 5), SEMANTICALLY_SIMILAR / structural_edges ratio (warn > 1.0), avg/max Pattern degree (warn > 20 / > 50), and the top-10 most-connected patterns flagged HUMAN-CURATED vs TELEMETRY.

Schedule via systemd user timer

mkdir -p ~/.config/faulkner-health
cat > ~/.config/faulkner-health/env <<'EOF'
FALKORDB_HOST=192.168.1.79
FALKORDB_PORT=6380
FALKORDB_PASSWORD=YOUR_PASSWORD
EOF
chmod 600 ~/.config/faulkner-health/env

cp scripts/faulkner-health-graph.{service,timer} ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now faulkner-health-graph.timer

Runs every 6 hours; output in journalctl --user -u faulkner-health-graph.

🧪 Maintenance scripts (v1.7.0)

Script	Purpose
scripts/audit_mkg_pollution.py	Read-only audit; JSON pollution report by signature & node label.
scripts/migrate_mkg_to_sqlite.py	One-shot migration of MKG playbook Patterns to MKG's SQLite store. Idempotent on re-run.
scripts/purge_migrated_nodes.py	Manifest-driven delete (paired with the migration).
scripts/purge_auto_ingest.py	Criteria-driven delete of Agent Genesis–ingested nodes.
scripts/regenerate_semantic_edges.py	Re-run sentence-transformers + FAISS at the env-tunable threshold.

All destructive scripts default to --dry-run, take a server-side BGSAVE plus a paginated local JSON dump before any mutation, and emit a JSON manifest under logs/ for traceability.

🛠️ 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 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

1. Verify configuration path matches your OS (see npm package docs)
2. Restart Claude Desktop/Code after config changes
3. Check Python path in MCP config is correct
4. 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 -a $FALKORDB_PASSWORD BGSAVE

🤝 Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository and create a feature branch
2. Write tests for new features (pytest)
3. Follow code style (PEP 8 for Python)
4. Document changes in code and README
5. 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