Potencialize seu agente
Instalação do publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
Ainda não há uma versão empacotada no registro. Siga o README do repositório.
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirFaulkner 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.
Installation: see INSTALL.md for setup instructions covering humans, agentic coders, and MCP-consumer agents.
# 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
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
Set VISUALIZATION_PORT and FALKORDB_REST_PORT in docker/.env. See .env.example for defaults.
FalkorDB now requires password authentication for all connections.
The default port has been changed from 6379 to 6380 to avoid conflicts with standard Redis installations.
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}
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.
flowchart LR
subgraph clients["MCP Clients"]
CC["Claude Code / Desktop"]
AG["Agentic coders"]
HM["Consumer agents<br/>(e.g. Hermes)"]
end
subgraph server["Faulkner DB — FastMCP server (13 tools)"]
TOOLS["Write: add_decision · add_decision_json<br/>add_pattern · add_failure"]
QUERY["Query: query_decisions · query_patterns_semantic<br/>find_related · get_timeline"]
ANALYSIS["Structural analysis (NetworkX):<br/>detect_gaps · find_bridge_patterns<br/>find_influential_patterns · find_knowledge_communities<br/>get_graph_summary"]
HS["Hybrid search:<br/>graph + vector + reranking"]
end
subgraph storage["Storage"]
FK[("FalkorDB<br/>temporal knowledge graph")]
CH[("ChromaDB<br/>embeddings")]
PG[("PostgreSQL<br/>metadata")]
end
CC & AG & HM -->|"MCP (HTTP gateway)"| server
TOOLS --> FK
QUERY --> HS
HS --> FK & CH
ANALYSIS --> FK
server --> PG
Three node types connected by typed, timestamped edges — the temporal record of what was decided, what patterns emerged, and what failed:
graph LR
D["Decision<br/>description · rationale · alternatives"]
P["Pattern<br/>recurring approach"]
F["Failure<br/>what went wrong"]
D -->|RELATES_TO / REFERENCES| D
P -->|IMPLEMENTS| D
D -->|ADDRESSES / SOLVES| F
D -->|CONTRADICTS / ALTERNATIVE_TO| D
P -->|EXTENDS| P
P -.->|SEMANTICALLY_SIMILAR| P
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"
}
sourceis required as of v1.7.0 unlessFAULKNER_ALLOW_AUTOMATED=true. Allowed values:"manual"(human-curated) or"reviewed_automated"(LLM-drafted, human-reviewed). See Ingestion Guards.
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
}
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"
}
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"
}
Graph traversal to discover related knowledge nodes.
{
"node_id": "D-abc123",
"depth": 2
}
Run NetworkX structural analysis to identify knowledge gaps (>85% accuracy).
{}
Temporal view showing how understanding evolved over time.
{
"topic": "Authentication System",
"start_date": "2023-01-01",
"end_date": "2024-12-31"
}
Find the most connected/influential patterns using degree centrality.
{
"limit": 10
}
Detect communities of related knowledge using connected components analysis.
{
"min_community_size": 3
}
Find bridge patterns that connect different knowledge domains.
{
"limit": 10
}
Get comprehensive summary of the knowledge graph structure, including node counts, edge counts, and connectivity metrics.
{}
Semantic search for patterns using sentence-transformers embeddings. More intelligent than keyword matching.
{
"query": "authentication middleware",
"limit": 10
}
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):
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.
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.
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.
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.
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.
The MCP server automatically connects to FalkorDB and PostgreSQL using environment variables. No additional configuration needed.
# Check container status
docker-compose ps
# View logs
docker-compose logs -f
# Restart services
docker-compose restart
docker-compose pslsof -i :6380echo $FALKORDB_PASSWORDdocker-compose logs falkordbdocker/data/ directory has correct permissionsFALKORDB_PERSISTENCE=true in .envdocker-compose exec falkordb redis-cli -a $FALKORDB_PASSWORD BGSAVEWe welcome contributions! Please follow these guidelines:
# 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.
MIT License - see LICENSE for details.
Built with:
Made with ❤️ for software teams who value architectural knowledge
Temporal Knowledge Graph System for Architectural Memory - Track decisions, patterns, and failures with MCP integration for Claude Code/Desktop
Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
Faulkner Db roda localmente via stdio.
Última verificação: 2026-10-28. Temporal Knowledge Graph System for Architectural Memory - Track decisions, patterns, and failures with MCP integration for Claude Code/Desktop