{"id":35911619,"url":"https://github.com/platano78/faulkner-db","last_synced_at":"2026-06-09T21:00:53.908Z","repository":{"id":328269485,"uuid":"1112765206","full_name":"Platano78/faulkner-db","owner":"Platano78","description":"Temporal Knowledge Graph System for Architectural Memory - Track decisions, patterns, and failures with MCP integration for Claude Code/Desktop","archived":false,"fork":false,"pushed_at":"2026-05-06T13:22:33.000Z","size":1991,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T15:30:52.065Z","etag":null,"topics":["architectural-decisions","claude-code","falkordb","graph-database","knowledge-graph","mcp-server","temporal-database"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Platano78.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-09T04:21:55.000Z","updated_at":"2026-05-06T13:22:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Platano78/faulkner-db","commit_stats":null,"previous_names":["platano78/faulkner-db"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/Platano78/faulkner-db","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Platano78%2Ffaulkner-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Platano78%2Ffaulkner-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Platano78%2Ffaulkner-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Platano78%2Ffaulkner-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Platano78","download_url":"https://codeload.github.com/Platano78/faulkner-db/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Platano78%2Ffaulkner-db/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34125332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architectural-decisions","claude-code","falkordb","graph-database","knowledge-graph","mcp-server","temporal-database"],"created_at":"2026-01-10T03:35:07.486Z","updated_at":"2026-06-09T21:00:53.902Z","avatar_url":"https://github.com/Platano78.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Faulkner DB - Temporal Knowledge Graph System\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/downloads/)\n[![Docker](https://img.shields.io/badge/docker-required-blue.svg)](https://docs.docker.com/get-docker/)\n[![npm version](https://img.shields.io/npm/v/faulkner-db-config.svg)](https://www.npmjs.com/package/faulkner-db-config)\n[![CI Status](https://github.com/platano78/faulkner-db/workflows/CI/badge.svg)](https://github.com/platano78/faulkner-db/actions)\n[![GitHub stars](https://img.shields.io/github/stars/platano78/faulkner-db.svg)](https://github.com/platano78/faulkner-db/stargazers)\n\n**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.\n\n## 🎯 Value Proposition\n\n- **Improved Decision Tracking** - Capture the rationale behind architectural choices and their impact over time\n- **Enhanced Collaboration** - Facilitate knowledge sharing and alignment across teams\n- **Reduced Technical Debt** - Identify and address problematic patterns early\n- **Faster Onboarding** - Accelerate learning for new team members with comprehensive project history\n- **AI-Ready Knowledge Base** - Structure knowledge for AI-powered development tools (Claude Code/Desktop)\n\n## ✨ Key Features\n\n- **Temporal Knowledge Graph** - Track changes to decisions and patterns over time\n- **Hybrid Search** - Graph traversal + vector embeddings + CrossEncoder reranking (\u003c2s queries)\n- **Gap Detection** - NetworkX-based structural analysis to identify knowledge gaps\n- **MCP Integration** - 12 tools for seamless Claude Desktop/Code integration\n- **Docker Deployment** - One-command startup with auto-restart support\n- **CPU-Friendly** - Built on FalkorDB, no GPU required (gaming-friendly memory footprint)\n\n## 📖 Documentation\n\n- **[Integration Setup Guide](docs/INTEGRATION-SETUP.md)** - Set up Agent Genesis + Faulkner-DB sync\n- **[Contributing Guidelines](CONTRIBUTING.md)** - How to contribute\n\n## 🚀 Quick Start\n\n### Option 1: Automated NPM Setup (Recommended)\n\n```bash\n# Configure Claude Desktop/Code automatically\nnpx faulkner-db-config setup\n\n# Clone and start the stack\ngit clone https://github.com/platano78/faulkner-db.git\ncd faulkner-db/docker\ndocker-compose up -d\n\n# Restart Claude Desktop/Code\n```\n\n### Option 2: Manual Setup\n\n**1. Start FalkorDB Stack**\n\n```bash\ngit clone https://github.com/platano78/faulkner-db.git\ncd faulkner-db/docker\n\n# Copy environment template\ncp .env.example .env\n\n# Edit .env and set POSTGRES_PASSWORD\n\n# Start services\ndocker-compose up -d\n```\n\n**2. Configure Claude (Manual)**\n\nAdd to `~/.config/Claude/claude_desktop_config.json` (Linux) or equivalent:\n\n```json\n{\n  \"mcpServers\": {\n    \"faulkner-db\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"mcp_server.server_fastmcp\"],\n      \"env\": {\n        \"PYTHONPATH\": \"/path/to/faulkner-db\",\n        \"FALKORDB_HOST\": \"localhost\",\n        \"FALKORDB_PORT\": \"6380\",\n        \"FALKORDB_PASSWORD\": \"changeme\"\n      }\n    }\n  }\n}\n```\n\n**3. Access Services**\n\n- **Network Graph**: http://localhost:VISUALIZATION_PORT/static/index.html\n- **Timeline View**: http://localhost:VISUALIZATION_PORT/static/timeline.html\n- **Dashboard**: http://localhost:VISUALIZATION_PORT/static/dashboard.html\n- **API Health**: http://localhost:VISUALIZATION_PORT/health\n\nSet `VISUALIZATION_PORT` and `FALKORDB_REST_PORT` in `docker/.env`. See `.env.example` for defaults.\n\n## Security Configuration\n\n### Authentication\n\nFalkorDB now requires password authentication for all connections.\n\n| Setting | Value |\n|---------|-------|\n| **Environment Variable** | `FALKORDB_PASSWORD` |\n| **Default (local dev)** | `changeme` |\n\n### Port Configuration\n\nThe default port has been changed from 6379 to 6380 to avoid conflicts with standard Redis installations.\n\n| Setting | Value |\n|---------|-------|\n| **Environment Variable** | `FALKORDB_PORT` |\n| **Default Port** | `6380` |\n\n### Connection Examples\n\n**Python**\n```python\nimport os\nfrom core.graphiti_client import GraphitiClient\n\npassword = os.environ.get('FALKORDB_PASSWORD')\nclient = GraphitiClient(host='localhost', port=6380, password=password)\n```\n\n**redis-cli**\n```bash\nredis-cli -p 6380 -a $FALKORDB_PASSWORD\n```\n\n**Docker Compose Environment**\n```yaml\nenvironment:\n  FALKORDB_HOST: falkordb\n  FALKORDB_PORT: 6380\n  FALKORDB_PASSWORD: ${FALKORDB_PASSWORD}\n```\n\n### Destructive Commands Disabled\n\nTo prevent accidental data loss, the following commands are disabled in the FalkorDB configuration:\n\n- `FLUSHALL` - Renamed to an obscure command (not directly callable)\n- `FLUSHDB` - Renamed to an obscure command (not directly callable)\n\nIf you need to clear data during development, recreate the container with a fresh volume.\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐\n│   Claude Code/      │    │   Faulkner DB       │    │     FalkorDB        │\n│   Desktop           │───▶│   (MCP Server)      │───▶│   (Graph DB)        │\n│                     │    │   Temporal Logic     │    │   CPU-Friendly      │\n└─────────────────────┘    └─────────────────────┘    └─────────────────────┘\n         │                          │                           │\n         │                          │                           │\n         ▼                          ▼                           ▼\n┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐\n│   12 MCP Tools      │    │   Hybrid Search      │    │   PostgreSQL        │\n│   - add_decision    │    │   Graph + Vector     │    │   (Metadata Store)  │\n│   - query_decisions │    │   + Reranking        │    │                     │\n│   - detect_gaps     │    │                      │    │                     │\n│   - get_timeline    │    │                      │    │                     │\n│   - graph_summary   │    │                      │    │                     │\n└─────────────────────┘    └─────────────────────┘    └─────────────────────┘\n```\n\n## 📚 MCP Tools Documentation\n\n### 1. add_decision\nRecord architectural decision with full context and rationale.\n\n```json\n{\n  \"description\": \"Use FalkorDB for temporal graphs\",\n  \"rationale\": \"CPU-friendly, Redis-compatible, excellent temporal support\",\n  \"alternatives\": [\"Neo4j\", \"ArangoDB\"],\n  \"related_to\": [],\n  \"source\": \"manual\"\n}\n```\n\n\u003e **`source` is required as of v1.7.0** unless `FAULKNER_ALLOW_AUTOMATED=true`.\n\u003e Allowed values: `\"manual\"` (human-curated) or `\"reviewed_automated\"`\n\u003e (LLM-drafted, human-reviewed). See [Ingestion Guards](#-ingestion-guards-v170).\n\n### 2. query_decisions\nHybrid search for decisions by topic/timeframe.\n\n```json\n{\n  \"query\": \"authentication decisions\",\n  \"timeframe\": {\n    \"start\": \"2024-01-01\",\n    \"end\": \"2024-12-31\"\n  }\n}\n```\n\n### 3. add_pattern\nStore successful implementation pattern.\n\n```json\n{\n  \"name\": \"CQRS Pattern\",\n  \"implementation\": \"Separate read/write models with event sourcing\",\n  \"use_cases\": [\"High-scale systems\", \"Event-driven architecture\"],\n  \"context\": \"Microservices with async communication\",\n  \"source\": \"manual\"\n}\n```\n\n### 4. add_failure\nDocument what didn't work and lessons learned.\n\n```json\n{\n  \"attempt\": \"Used RabbitMQ with 50+ queues\",\n  \"reason_failed\": \"Performance degradation under load\",\n  \"lesson_learned\": \"Use Kafka for high-throughput streaming\",\n  \"alternative_solution\": \"Migrated to Kafka with topic partitioning\",\n  \"source\": \"manual\"\n}\n```\n\n### 5. find_related\nGraph traversal to discover related knowledge nodes.\n\n```json\n{\n  \"node_id\": \"D-abc123\",\n  \"depth\": 2\n}\n```\n\n### 6. detect_gaps\nRun NetworkX structural analysis to identify knowledge gaps (\u003e85% accuracy).\n\n```json\n{}\n```\n\n### 7. get_timeline\nTemporal view showing how understanding evolved over time.\n\n```json\n{\n  \"topic\": \"Authentication System\",\n  \"start_date\": \"2023-01-01\",\n  \"end_date\": \"2024-12-31\"\n}\n```\n\n### 8. find_influential_patterns\nFind the most connected/influential patterns using degree centrality.\n\n```json\n{\n  \"limit\": 10\n}\n```\n\n### 9. find_knowledge_communities\nDetect communities of related knowledge using connected components analysis.\n\n```json\n{\n  \"min_community_size\": 3\n}\n```\n\n### 10. find_bridge_patterns\nFind bridge patterns that connect different knowledge domains.\n\n```json\n{\n  \"limit\": 10\n}\n```\n\n### 11. get_graph_summary\nGet comprehensive summary of the knowledge graph structure, including node counts, edge counts, and connectivity metrics.\n\n```json\n{}\n```\n\n### 12. query_patterns_semantic\nSemantic search for patterns using sentence-transformers embeddings. More intelligent than keyword matching.\n\n```json\n{\n  \"query\": \"authentication middleware\",\n  \"limit\": 10\n}\n```\n\n## 🛡️ Ingestion Guards (v1.7.0)\n\nEvery write through `add_decision` / `add_pattern` / `add_failure` is now\ngated to prevent re-introduction of two pollution patterns that historically\nballooned the graph (10,781 nodes purged in v1.7.0):\n\n1. **Blocklist regex** on `name` / `context` / `description` / `attempt`\n   fields. Defaults block `^playbook-.*-\\d{13}$` (MKG playbook signature)\n   and `.*-\\d{13}$` (any unix-ms timestamp suffix, defensive). Override\n   the list via `FAULKNER_INGESTION_BLOCKLIST_FILE` (JSON\n   `{\"patterns\": [...]}` or one regex per line).\n2. **`source_files` containing `agent-genesis`** — historically the\n   conversation-fragment auto-ingest path. Hard-rejected.\n3. **`source` parameter required** — must be `\"manual\"` or\n   `\"reviewed_automated\"`. Set `FAULKNER_ALLOW_AUTOMATED=true` to bypass\n   when running an authorized automated reviewer.\n\nRejections are logged as one JSON line each to `logs/rejected_writes.jsonl`\n(timestamp, label, reason, truncated sample fields, matched pattern).\nOverride the path via `FAULKNER_REJECTION_LOG`.\n\n## 🩺 Graph Health Check (v1.7.0)\n\n`scripts/health_check.py` is a read-only diagnostic over the live graph:\n\n```bash\nFALKORDB_HOST=192.168.1.79 FALKORDB_PORT=6380 FALKORDB_PASSWORD=... \\\n  python scripts/health_check.py            # human-readable\n  python scripts/health_check.py --json     # machine-readable\n  python scripts/health_check.py --strict   # exit 1 on any warning\n```\n\nReports node/edge totals, `Failure:Decision` ratio (warn \u003e 5),\n`SEMANTICALLY_SIMILAR / structural_edges` ratio (warn \u003e 1.0), avg/max\nPattern degree (warn \u003e 20 / \u003e 50), and the top-10 most-connected\npatterns flagged HUMAN-CURATED vs TELEMETRY.\n\n### Schedule via systemd user timer\n\n```bash\nmkdir -p ~/.config/faulkner-health\ncat \u003e ~/.config/faulkner-health/env \u003c\u003c'EOF'\nFALKORDB_HOST=192.168.1.79\nFALKORDB_PORT=6380\nFALKORDB_PASSWORD=YOUR_PASSWORD\nEOF\nchmod 600 ~/.config/faulkner-health/env\n\ncp scripts/faulkner-health-graph.{service,timer} ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable --now faulkner-health-graph.timer\n```\n\nRuns every 6 hours; output in `journalctl --user -u faulkner-health-graph`.\n\n## 🧪 Maintenance scripts (v1.7.0)\n\n| Script | Purpose |\n|---|---|\n| `scripts/audit_mkg_pollution.py` | Read-only audit; JSON pollution report by signature \u0026 node label. |\n| `scripts/migrate_mkg_to_sqlite.py` | One-shot migration of MKG playbook Patterns to MKG's SQLite store. Idempotent on re-run. |\n| `scripts/purge_migrated_nodes.py` | Manifest-driven delete (paired with the migration). |\n| `scripts/purge_auto_ingest.py` | Criteria-driven delete of Agent Genesis–ingested nodes. |\n| `scripts/regenerate_semantic_edges.py` | Re-run sentence-transformers + FAISS at the env-tunable threshold. |\n\nAll destructive scripts default to `--dry-run`, take a server-side BGSAVE\nplus a paginated local JSON dump before any mutation, and emit a\nJSON manifest under `logs/` for traceability.\n\n## 🛠️ Technical Stack\n\n| Component | Technology |\n|-----------|------------|\n| **Graph Database** | FalkorDB (CPU-only) |\n| **Metadata Store** | PostgreSQL |\n| **Embeddings** | sentence-transformers (all-MiniLM-L6-v2) |\n| **Reranking** | cross-encoder/ms-marco-MiniLM-L-6-v2 |\n| **Graph Analysis** | NetworkX |\n| **MCP Server** | Python 3.9+ (FastMCP) |\n| **Deployment** | Docker Compose |\n\n## ⚡ Performance\n\n- **Query Time**: \u003c2s (hybrid search with reranking)\n- **Accuracy**: 90%+ on decision queries\n- **Gap Detection**: \u003e85% accuracy\n- **Memory**: Gaming-friendly (FalkorDB: 2GB, PostgreSQL: 1GB)\n- **Scalability**: Tested with 10,000+ nodes\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate `docker/.env` from `.env.example`:\n\n```bash\n# FalkorDB Configuration\nFALKORDB_HOST=falkordb\nFALKORDB_PORT=6380\nFALKORDB_PASSWORD=changeme\nFALKORDB_MEMORY_LIMIT=2gb\nFALKORDB_REST_PORT=8082\n\n# PostgreSQL Configuration\nPOSTGRES_HOST=postgres\nPOSTGRES_PORT=5432\nPOSTGRES_USER=graphiti\nPOSTGRES_PASSWORD=YOUR_SECURE_PASSWORD\nPOSTGRES_DB=graphiti\n\n# Visualization\nVISUALIZATION_PORT=8086\n```\n\n**Note**: The `FALKORDB_PASSWORD` is required for authentication. Change the default password in production environments.\n\n### MCP Server Configuration\n\nThe MCP server automatically connects to FalkorDB and PostgreSQL using environment variables. No additional configuration needed.\n\n## 🐛 Troubleshooting\n\n### Docker containers not starting\n```bash\n# Check container status\ndocker-compose ps\n\n# View logs\ndocker-compose logs -f\n\n# Restart services\ndocker-compose restart\n```\n\n### FalkorDB connection errors\n- Verify FalkorDB is running: `docker-compose ps`\n- Check port 6380 is not in use: `lsof -i :6380`\n- Verify password is set: `echo $FALKORDB_PASSWORD`\n- Review FalkorDB logs: `docker-compose logs falkordb`\n\n### MCP server not detected in Claude\n1. Verify configuration path matches your OS (see npm package docs)\n2. Restart Claude Desktop/Code after config changes\n3. Check Python path in MCP config is correct\n4. Ensure Docker stack is running\n\n### Data persistence issues\n- Verify `docker/data/` directory has correct permissions\n- Check `FALKORDB_PERSISTENCE=true` in `.env`\n- Backup data: `docker-compose exec falkordb redis-cli -a $FALKORDB_PASSWORD BGSAVE`\n\n## 🤝 Contributing\n\nWe welcome contributions! Please follow these guidelines:\n\n1. **Fork the repository** and create a feature branch\n2. **Write tests** for new features (pytest)\n3. **Follow code style** (PEP 8 for Python)\n4. **Document changes** in code and README\n5. **Submit pull request** with clear description\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/platano78/faulkner-db.git\ncd faulkner-db\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run tests\npytest tests/ -v\n\n# Run with coverage\npytest tests/ --cov=core --cov=mcp_server\n```\n\nSee `CONTRIBUTING.md` for detailed guidelines.\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🗺️ Roadmap\n\n- [x] Phase 1: Core Knowledge Graph\n- [x] Phase 2: Hybrid Search\n- [x] Phase 3: Gap Detection\n- [x] Phase 4: MCP Server Integration\n- [x] Phase 5: Docker Deployment\n- [x] Phase 6: Testing \u0026 Validation\n- [ ] Phase 7: Advanced Analytics Dashboard\n- [ ] Phase 8: Multi-tenant Support\n- [ ] Phase 9: Cloud Deployment Options\n\n## 📞 Support\n\n- **Issues**: https://github.com/platano78/faulkner-db/issues\n- **Discussions**: https://github.com/platano78/faulkner-db/discussions\n- **Documentation**: https://github.com/platano78/faulkner-db/wiki\n\n## 🙏 Acknowledgments\n\nBuilt with:\n- [FalkorDB](https://www.falkordb.com/) - Graph database with temporal support\n- [ChromaDB](https://www.trychroma.com/) - Vector embeddings (previous iteration)\n- [sentence-transformers](https://www.sbert.net/) - Semantic embeddings\n- [NetworkX](https://networkx.org/) - Graph analysis algorithms\n- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework\n\n---\n\n**Made with ❤️ for software teams who value architectural knowledge**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplatano78%2Ffaulkner-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplatano78%2Ffaulkner-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplatano78%2Ffaulkner-db/lists"}