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": [],
  "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.

{
  "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",
  "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):

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).
source_files containing agent-genesis — historically the conversation-fragment auto-ingest path. Hard-rejected.
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

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 -a $FALKORDB_PASSWORD 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

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
.github/workflows		.github/workflows
analysis		analysis
common		common
config		config
core		core
docker		docker
docs		docs
ingestion		ingestion
mcp_server		mcp_server
npm		npm
scripts		scripts
tests		tests
visualization		visualization
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
USAGE_GUIDE.md		USAGE_GUIDE.md
requirements.txt		requirements.txt
validate_persistence.sh		validate_persistence.sh

Folders and files

Latest commit

History

Repository files navigation

Faulkner DB - Temporal Knowledge Graph System

🎯 Value Proposition

✨ Key Features

📖 Documentation

🚀 Quick Start

Option 1: Automated NPM Setup (Recommended)

Option 2: Manual Setup

Security Configuration

Authentication

Port Configuration

Connection Examples

Destructive Commands Disabled

🏗️ Architecture

📚 MCP Tools Documentation

1. add_decision

2. query_decisions

3. add_pattern

4. add_failure

5. find_related

6. detect_gaps

7. get_timeline

8. find_influential_patterns

9. find_knowledge_communities

10. find_bridge_patterns

11. get_graph_summary

12. query_patterns_semantic

🛡️ Ingestion Guards (v1.7.0)

🩺 Graph Health Check (v1.7.0)

Schedule via systemd user timer

🧪 Maintenance scripts (v1.7.0)

🛠️ Technical Stack

⚡ Performance

🔧 Configuration

Environment Variables

MCP Server Configuration

🐛 Troubleshooting

Docker containers not starting

FalkorDB connection errors

MCP server not detected in Claude

Data persistence issues

🤝 Contributing

Development Setup

📄 License

🗺️ Roadmap

📞 Support

🙏 Acknowledgments

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages