{"id":"d1328712-161c-45bb-9028-4b665e29235c","slug":"quorum-falkordb","kind":"mcp","name":"Quorum-falkordb","summary":"Git revert for AI agent beliefs: shared memory for AI agents and teammates on FalkorDB. One correction quarantines a wrong fact and everything built on it, blocks and compensates actions. Set up from","owner":"HamzaShaikh-source","repoUrl":"https://github.com/HamzaShaikh-source/Quorum-falkordb","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-15T04:56:28.000Z","addedAt":"2026-10-21T06:56:09.013Z","logoUrl":"https://avatars.githubusercontent.com/u/267696657?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","databases","developer-tools"],"tags":["agent-memory","ai-agents","cypher","falkordb","fastapi","graph-database","hackathon","knowledge-graph"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T07:00:26.124Z","sample":false,"url":"https://conduits.dev/tools/quorum-falkordb","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# 🛡️ Quorum: Git-Revert for AI Agent Beliefs on FalkorDB\n\n[![Track 02](https://img.shields.io/badge/Track%2002-Agent%20Memory%20%26%20Coordination-blueviolet?style=for-the-badge)](https://www.wemakedevs.org/hackathons/falkordb)\n[![Track 03](https://img.shields.io/badge/Track%2003-Company%20Brain-blue?style=for-the-badge)](https://www.wemakedevs.org/hackathons/falkordb)\n[![Graph](https://img.shields.io/badge/Graph-FalkorDB-crimson?style=for-the-badge)](https://falkordb.com/)\n[![MCP tools](https://img.shields.io/badge/MCP%20tools-28-14181a?style=for-the-badge)](docs/MCP.md)\n[![Live Demo](https://img.shields.io/badge/Live%20Demo-34.100.151.44:5173-success?style=for-the-badge)](http://34.100.151.44:5173/)\n[![YouTube](https://img.shields.io/badge/YouTube-Demo%20Video-red?style=for-the-badge&logo=youtube)](https://youtu.be/lrZKJ4tmo-o)\n\n> **When an AI agent acts on a hallucination, poisoned webhook, or outdated policy, vector databases leave you stranded. Quorum brings Git-like rollback, epistemic causal tracking, and automated compensation to multi-agent systems using FalkorDB.**\n\n---\n\n## ⚡ Quick Links for Evaluators\n- 🌐 **Live Demo Sandbox:** [http://34.100.151.44:5173/](http://34.100.151.44:5173/) *(Instant 1-Click Access — pre-authenticated as Admin)*\n- 🎬 **Demo Video:** [Watch on YouTube (2 Minutes)](https://youtu.be/lrZKJ4tmo-o)\n- 🔌 **Live Backend API & MCP Server:** `http://34.100.151.44:8000` (FastAPI docs at `/docs`, embedded MCP at `/mcp` with 28 MCP tools)\n- 📊 **Empirical Proof & Benchmark Suite:** [`docs/PROOF.md`](docs/PROOF.md)\n\n---\n\n## 🗺️ 1. Epistemic Graph Schema & Architecture\n\nFalkorDB is not a passive cache in Quorum—it is the **epistemic causal ground truth**. Agents cannot execute stateful actions without citing valid graph facts, and invalidating a root node initiates sub-millisecond topological graph cascades.\n\n```mermaid\ngraph TD\n    S[Source: Ingestion Webhook / Document] -->|PROV_SOURCE| E[Event: Policy Change]\n    E -->|EXTRACTED_FROM| F1[Fact: Return Window = 90d]\n    F0[Fact: Baseline Return = 30d] -.->|SUPERSEDES| F1\n    F1 -->|SUPPORTS| B[Belief: High-Risk Policy Active]\n    B -->|LEADS_TO| D[Decision: Issue Refund #4092]\n    D -->|PRODUCES| A[Action: Helpdesk Call]\n    A -->|EMITS| O[OutboxSaga: Refund Clawback]\n\n    classDef invalid fill:#ff4d4f,stroke:#a8071a,stroke-width:2px,color:#fff;\n    classDef valid fill:#52c41a,stroke:#237804,stroke-width:2px,color:#fff;\n    classDef source fill:#1890ff,stroke:#0050b3,stroke-width:2px,color:#fff;\n    class F1,B,D,A invalid;\n    class F0 valid;\n    class S,E,O source;\n```\n\n### Graph Primitives\n\n| Node Label | Purpose | Key Properties |\n| :--- | :--- | :--- |\n| `(:Source)` | Ingestion origin & audit anchor | source_id, uri, tenant_id, verified_at |\n| `(:Event)` | Temporal context or policy update | event_id, type, occurred_at |\n| `(:Fact)` | Discrete atomic belief unit | fact_id, claim, validity_state (valid, quarantined, invalid), confidence |\n| `(:Belief)` | Synthesized agent context | belief_id, tenant_id, strength, stale |\n| `(:Decision)` | Agent reasoning trace citing facts | decision_id, agent_id, cited_fact_ids, rationale |\n| `(:Action)` | Stateful external side-effect | action_id, target_system, status, idempotency_key |\n| `(:OutboxSaga)` | Deterministic compensation hook | saga_id, action_id, compensation_endpoint, state |\n\n---\n\n## ⚙️ 2. How the Graph Does the Work (Cypher Deep-Dive)\n\nQuorum uses pure FalkorDB Cypher traversals to execute epistemic governance in real time:\n\n### A. Pre-Execution Epistemic Gating (Quorum Gate)\nBefore an agent can call an external tool (e.g. process refund, send email), the Quorum Gate inspects the causal chain of all cited facts. If any fact is quarantined or invalid, the action is blocked before execution:\n\n```cypher\nMATCH (d:Decision {id: $decision_id})-[:CITES]->(f:Fact)\nWHERE f.validity_state IN ['quarantined', 'invalid'] OR f.stale = true\nRETURN count(f) AS violations, collect(f.claim) AS tainted_claims\n```\n\n### B. Cascading Red-Wave Invalidation (Topological Rollback)\nWhen an auditor quarantines a rogue fact (or when an event is superseded), Quorum traverses causal edges up to 10 hops deep in < 5ms, marking all downstream beliefs, decisions, and pending actions as invalidated:\n\n```cypher\nMATCH (f:Fact {id: $tainted_fact_id})-[:LEADS_TO|SUPPORTS*1..10]->(downstream)\nSET downstream.validity_state = 'invalid',\n    downstream.invalidated_at = timestamp(),\n    downstream.invalidation_reason = $reason\nRETURN labels(downstream) AS type, downstream.id AS id\n```\n\n### C. Outbox Saga Compensation & Retraction\nFor actions already executed externally, Quorum queries the downstream saga graph to trigger automated API compensations and compose Damage Control retraction notices:\n\n```cypher\nMATCH (d:Decision {validity_state: 'invalid'})-[:PRODUCES]->(a:Action)-[:EMITS]->(s:OutboxSaga)\nWHERE s.state = 'pending'\nRETURN s.saga_id, a.target_system, s.compensation_payload, a.idempotency_key\n```\n\n---\n\n## 🛡️ 3. The 4-Layer Defense Engine\n\n- **Quorum Gate:** Synchronous pre-flight epistemic policy check for every agent tool invocation.\n- **Execute Guard:** Verifies execution permissions against tenant RBAC (admin, auditor, agent).\n- **Outbox Sagas:** Guaranteed at-least-once compensation for external side-effects when underlying facts collapse.\n- **Damage Control Room:** Human-in-the-loop review interface providing one-click customer retraction emails, audit trails, and graph time-travel.\n\n---\n\n## What your AI gets\n\nWhen an AI agent connects to Quorum via MCP, it receives access to the full epistemic governance toolset across 28 MCP tools:\n\n| Tool | Description |\n| :--- | :--- |\n| `announce_work` | Broadcasts active task intent to peer agents to prevent conflicting actions. |\n| `claim_handoff` | Coordinates multi-agent handoffs with shared epistemic state across agents. |\n| `delta` | Computes graph mutations and invalidated nodes between two timestamps. |\n| `derive` | Derives a conclusion or belief supported by active facts. |\n| `execute_action` | Executes a previously approved action with idempotency and saga registration. |\n| `explain_blast_radius` | Calculates downstream impact and affected decisions for a belief. |\n| `find_path` | Finds causal provenance paths between facts and actions. |\n| `get_map` | Retrieves the local causal subgraph map for a given entity or root. |\n| `get_node` | Inspects detailed graph properties, timestamps, and validity states of any node. |\n| `observe` | Records an external system state or sensor observation. |\n| `peer_retrieve` | Securely queries shared memory from an authorized peer Quorum instance. |\n| `quarantine` | Quarantines a fact or belief and triggers a cascading red-wave invalidation. |\n| `quorum_connect` | Establishes authorized peering connection with an external Quorum instance. |\n| `quorum_connections` | Lists currently active and authorized peer hub connections. |\n| `quorum_discover` | Discovers peer Quorum instances available across the local network. |\n| `quorum_guide` | Interactive guide and client agreement reference for agent coordination. |\n| `quorum_help` | Returns capability manifest and usage guidelines for connected agents. |\n| `quorum_inbox` | Checks pending inter-hub connection requests and permission handoffs. |\n| `quorum_manage` | Manages team member tokens, permission roles, and workspace seats. |\n| `quorum_respond` | Approves or declines incoming inter-hub connection requests. |\n| `quorum_start` | Initializes team workspace settings and onboarding configurations. |\n| `quorum_status` | Reports active graph statistics, quarantine counts, and connection health. |\n| `recall_as_of` | Performs time-travel belief retrieval as of a historical timestamp. |\n| `remember_fact` | Saves an atomic fact with causal source provenance into FalkorDB. |\n| `restore` | Restores a quarantined fact and reactivates healthy downstream descendants. |\n| `retrieve_context` | Retrieves active, non-quarantined context subgraphs for safe prompt construction. |\n| `review_handoff` | Inspects pending handoffs and verifies approval preconditions. |\n| `stage_action` | Proposes a stateful action to the Quorum Gate along with cited fact IDs. |\n\n---\n\n## 🏆 4. Empirical Evaluation & Benchmark Results\n\nTested across a paired synthetic & real-agent benchmark against standard vector/RAG memory architectures (see [`docs/PROOF.md`](docs/PROOF.md)):\n\n- **Preventing Unsafe Actions After Correction:** 28/28 (100%) prevented in Quorum vs. 0/28 (0%) in standard vector memory.\n- **Topological Invalidation Speed:** < 4.2ms median cascade latency across 10-hop subgraphs on FalkorDB.\n- **Concurrent Writer Durability:** Group-commit shared sync ensures zero lost updates under high concurrency.\n- **Test Suite:** 669 backend unit & integration tests, 218 frontend tests passing (100% green).\n\n---\n\n## 🚀 5. Local Setup & Reproduction\n\n### Prerequisites\n- Docker & Docker Compose\n- Python 3.11+\n- Node.js 18+\n\n### 1-Command Docker Launch\n\n```bash\ngit clone https://github.com/HamzaShaikh-source/Quorum-falkordb.git\ncd Quorum-falkordb\ndocker compose up -d\n```\n\n- Open console: `http://localhost:5173/`\n- Backend API docs: `http://localhost:8000/docs`\n\n---\n\n## 👥 6. Team & Hackathon Disclosures\n\n- **Hamza Shaikh** ([@HamzaShaikh-source](https://github.com/HamzaShaikh-source)) — Frontend & Cytoscape Console Lead\n- **Aaditya Arunpal** ([@AsteroidHH](https://github.com/AsteroidHH)) — Backend, Epistemic Engine & MCP Lead\n- **Janani** — FalkorDB & Cypher Graph Architecture Lead\n\n**AI Usage Disclosure:** In compliance with Hackathon Rule 11, LLM assistance was utilized for test-case expansion, UI styling scaffolding, and drafting documentation. Core Cypher schemas, causal graph algorithms, group-commit logic, and defense gate architectures were developed by the team.\n"}