The Next Leader Shouldn't Start from Zero: Building an Evidence-Grounded Institutional Continuity Engine with FastMCP, Switch, and Gemini

The Next Leader Shouldn't Start from Zero: Building an Evidence-Grounded Institutional Continuity Engine with FastMCP, Switch, and Gemini Tags: #ai #devtools #architecture #python #webdev GitHub Repository: https://github.com/Amankumar0018/Relay Hackathon: Flip the Switch — WeMakeDevs × DevTools Academy × Switch Target Track: Best Business Workflow Author: Aman Kumar (Lead Full-Stack & Systems Architect) Published: November 7, 2026 The Short Version The Organizational Fracture: When technical founders, lead architects, or senior executives depart, institutional memory evaporates. Decisions lose their rationale, conflicting project dates persist uncorrected across competing memos, and mission-critical cloud assets sit silently orphaned. What Relay Does: Relay ingests unstructured organizational records (PDFs, memos, charters, roadmaps), anchors every statement to character-exact coordinates in primary text, continuously cross-examines records for contradictions and unassigned infrastructure, and compiles a comprehensive 9-Chapter Executive Handover Dossier with a Day 1–30 Operational Roadmap. The Defining Architectural Principle: The platform enforces an unbreachable distinction between what the primary evidence proves, what an AI model infers, what remains unknown, and what only an authorized human has the institutional legitimacy to decide. The Agent & Governance Model: Autonomous AI agents running inside Switch and OpenCode investigate discrepancies using five registered FastMCP tools, but are cryptographically barred from unilateral conflict resolution. Every resolution requires a single-use token adjudicated by an authenticated human reviewer via Mattermost. Verified Benchmark: Backed by a verified 229-test automated test suite (0 failures), 16 prerendered static frontend routes, deterministic SHA-256 archival provenance, and a local-first SQLite Write-Ahead Logging architecture that stores zero sensitive documents on commercial cloud vectors. Figure A: The Relay Institutional Continuity Platform — synthesizing primary organizational records into an audited, evidence-grounded transition intelligence system. 1. The Anatomy of Organizational Amnesia Every growing organization eventually suffers from structural amnesia. It rarely happens with a catastrophic announcement; it happens quietly, across two dozen Google Drive folders, three archived Slack channels, and a departing executive’s hard drive. Consider what actually transpires when a Director of Engineering or Chief Technology Officer leaves an organization: Decisions lose their lineage. A memo from six months ago specifies that the flagship product release is scheduled for November 15. A technical amendment dated three weeks later casually references December 20 following stress tests on a staging cluster. Both documents remain active in the file repository. Junior engineers build against November; vendor contracts assume December. Neither document references the other. Infrastructure becomes orphaned. Operational memos casually instruct teams to "route telemetry through Kubernetes cluster Alpha-9." But who pays the cloud provider invoice? Who manages the cluster access certificates? Who is on call when pod evictions spiral? Nowhere in the formal org chart is Alpha-9 assigned to a living human being. Incoming leaders spend 90 days rediscovering the wheel. The successor arrives on Day 1. Instead of executing strategy, they embark on an archaeological expedition: scheduling twenty "context-download" meetings, parsing contradictory spreadsheets, and dreading the silent auto-renewal of a \$140,000 lab services contract that triggers fifteen days before anyone notices. Conventional Transition Reality: [Departing Leader] ──(Unwritten Context)──> [Evaporates] │ ├── Memos & Binders ───────────────> "Digital Landfill" (Google Drive / Wiki) ├── Slack / Mattermost Channels ───> Ephemeral Search Noise (Lost Rationale) └── Orphaned Cloud Assets ─────────> Silent Failure / Compliance Penalty │ ▼ [Incoming Leader] (Starts from Zero on Day 1) Why don't conventional tools solve this? Cloud drives and wikis are passive digital landfills. They store bytes, not truth. They cannot tell you that Document C supersedes Paragraph 4 of Document A. Enterprise chatbots make the problem worse. Standard Retrieval-Augmented Generation (RAG) models smooth over contradictions. If you feed an LLM two documents claiming different release dates, it will either hallucinate a compromise, pick one arbitrarily based on embedding similarity, or confidently present outdated policies as active reality. We built Relay to solve this. Relay is an active, evidence-grounded institutional memory platform designed to guarantee that when leadership changes, institutional knowledge survives intact. 2. What We Built From the user's perspective, Relay operates as an autonomous forensic intelligence desk that transforms disorganized organizational archives into an audited continuity graph: Figure B: The 8-stage organizational continuity lifecycle — from cryptographic archive deposition to human-governed conflict adjudication and 9-chapter briefing book synthesis. The end-to-end lifecycle follows an 8-stage deterministic pipeline: ┌─────────────────────────────────────────────────────────────────────────────┐ │ RELAY END-TO-END PIPELINE │ ├─────────────────────────────────────────────────────────────────────────────┤ │ 1. ARCHIVE DEPOSITION: Cryptographic SHA-256 ingestion of PDF, TXT, DOCX. │ │ 2. STRUCTURED EXTRACTION: Multimodal Gemini models extract triples & facts. │ │ 3. EXACT CITATION ANCHORING: Every assertion bound to [char_start, char_end]│ │ 4. CONTRADICTION SCANNING: Property-aware detection of semantic conflicts. │ │ 5. AGENT INVESTIGATION: OpenCode agents query records via FastMCP tools. │ │ 6. HUMAN-IN-THE-LOOP SWITCH GATE: Two-phase token-governed adjudication. │ │ 7. HANDOVER SYNTHESIS: Automated 9-Chapter Briefing Book + Day 1-30 Roadmap │ │ 8. CITATION-GROUNDED Q&A: Natural-language queries with honest refusals. │ └─────────────────────────────────────────────────────────────────────────────┘ The system is built upon a non-negotiable architectural doctrine: The Relay Grounding Axiom: An AI agent may discover discrepancies, map relationships, and propose adjudications. But an AI agent must never possess the authority to unilaterally decide what an organization's truth is. Authority belongs exclusively to authenticated human decision-makers. 3. A Concrete Continuity Scenario To understand Relay in action, let us examine a concrete operational transition scenario from our synthetic verification suite (all names and projects are synthetic demonstration fixtures from the test suite): The Transition: Outgoing executive Aman Kumar is transferring operational leadership to incoming engineering lead Marcus Vance. Key department stewards include Elena Rostova (Product Steward), Dr. Aris Thorne (Security Lead), and Priya Sharma (Infrastructure Lead). Document 1 (Project Odyssey Launch Plan.txt): Formally states that Beta Release for Project Odyssey is scheduled for November 15, 2026. Document 2 (Project Odyssey Schedule Amendment Memo.txt): States that following load testing on Kubernetes cluster Alpha-9, the Project Odyssey deployment roadmap has been amended and Beta Release is set for December 20, 2026. Document 3 (Project Aegis Transition Briefing.txt): Establishes Project Aegis Beta Launch for December 15, 2026. Document 4 (Project Aegis Schedule Postponement.txt): Formally states that Project Aegis Beta has been postponed to February 1, 2027. When these archives are deposited into Relay: Extraction: Relay extracts 32 distinct factual assertions, 15 unique organizational entities, and 13 relational dependencies. Every single assertion is bound to its exact character span. Contradiction Discovery: The intelligence analyzer compares the two Odyssey launch statements. Because both specify the property milestone:beta for entity Project Odyssey with incompatible date values, Relay flags a Direct Contradiction (Severity: Critical). Superseded Decision Identification: The analyzer inspects the Aegis postponement. Because Document 4 explicitly uses amendment syntax ("officially postponed"), Relay categorizes this as a Superseded Decision (Severity: Medium), preserving the historical decision lineage while marking the new February date as active. Ownership Gap Detection: The system identifies that Kubernetes cluster Alpha-9 is repeatedly cited as a critical dependency, yet has zero incoming OWNS or STEWARDS relationships. Relay automatically creates an Ownership Gap (Severity: High). When incoming leader Marcus Vance opens the Relay Workspace, they do not see a chaotic folder of files. They see an actionable audit: 6 flagged matters requiring immediate governance, an ownership topology, and an uncorrupted audit trail. 4. System Architecture & Engineering Implementation Relay is architectured as a decoupled, local-first platform designed to run in air-gapped or high-security corporate environments. Figure C: Relay full-stack systems architecture and integration topology — connecting Mattermost human authentication, the Switch desktop workspace, OpenCode agents, FastMCP JSON-RPC tools, FastAPI core services, and local SQLite WAL storage. flowchart TD subgraph HumanLayer["Human Collaboration & Control (Ports 52066 / 52067)"] MM["Mattermost Team Edition\n(Port :52067)"] SW["Switch Console Desktop\n(Port :52066)"] UI["Relay Brutalist Web UI\n(Next.js 15 / Port :3000)"] end subgraph AgentLayer["Agent Execution & MCP Protocol"] OCA["OpenCode Agent\n(relay-knowledge-extractor)"] MCP["Relay FastMCP Server\n(Stdio Transport / JSON-RPC)"] end subgraph BackendCore["Relay Core Engine (Port :8000)"] API["FastAPI 0.115+ Router\n(/api/v1)"] EXT["Extraction & Ingestion Pipeline"] INT["Organizational Intelligence Analyzer"] APP["Two-Phase Human Approval Handler"] DOS["9-Chapter Dossier Compiler"] QA["Grounded Q&A Engine"] LLM["Google GenAI SDK\n(Gemini 2.5 Flash Multimodal)"] end subgraph StorageLayer["Persistence & Cryptographic Verification"] DB[("SQLite 3.45 WAL Database\n(relay.db)")] SHA["SHA-256 Storage Vault\n(/data/uploads)"] end UI -->|REST / JSON| API SW |Webhooks / Events| OCA MM |Auth Tokens / Webhooks| APP OCA |Stdio JSON-RPC| MCP MCP -->|Internal HTTP Client| API API --> EXT API --> INT API --> APP API --> DOS API --> QA EXT --> LLM EXT --> SHA EXT --> DB INT --> DB APP --> DB DOS --> DB QA --> DB 4.1 How Organizational Knowledge is Structured Relay avoids the opacity of vector-only databases by maintaining a rigorous relational model of institutional truth. Extracted facts and entities are first-class relational citizens directly linked to raw textual coordinates: erDiagram DOCUMENT ||--o{ DOCUMENT_SEGMENT : contains DOCUMENT_SEGMENT ||--o{ FACT_CITATION : grounds EXTRACTED_ENTITY ||--o{ ENTITY_MENTION : references DOCUMENT_SEGMENT ||--o{ ENTITY_MENTION : locates EXTRACTED_ENTITY ||--o{ ENTITY_RELATIONSHIP : originates EXTRACTED_ENTITY ||--o{ ENTITY_RELATIONSHIP : targets EXTRACTED_FACT ||--o{ FACT_CITATION : supported_by EXTRACTED_ENTITY ||--o{ EXTRACTED_FACT : anchors EXTRACTED_FACT ||--o{ KNOWLEDGE_CONFLICT : involves_a EXTRACTED_FACT ||--o{ KNOWLEDGE_CONFLICT : involves_b KNOWLEDGE_CONFLICT ||--o{ CONFLICT_APPROVAL_TOKEN : protected_by KNOWLEDGE_CONFLICT ||--o{ CONFLICT_RESOLUTION_AUDIT : audited_by Every ExtractedFact persisted in Relay requires: An exact category (decision, milestone, deadline, responsibility, financial). An anchor primary_entity_id. A verification score and reviewer status (evidence-backed, in-flight, rejected). At least one FactCitation record containing the exact segment ID, character offsets (char_start, char_end), and verbatim quotation from the primary document. 4.2 Evidence-Grounded Extraction Pipeline Raw document processing in Relay follows a strict, multi-stage deterministic pipeline. Raw Archive File (.txt / .pdf) │ ▼ [Deterministic Chunking & Character Offsets] ──> DocumentSegment [char_start, char_end] │ ▼ [Gemini Structured Extraction (Pydantic Schema)] │ ├── Extracted Entities (person, project, asset, organization) ├── Entity Relationships (OWNS, STEWARDS, REPORTS_TO, SUPERSEDES) └── Candidate Facts with Verbatim Quotes │ ▼ [Strict Verification Gate] │ ├── Locate verbatim quote inside segment text ├── Validate exact offset coordinates └── REJECT any candidate fact where quotation cannot be matched Here is the actual implementation from our grounding and extraction services (backend/app/services/grounding.py and backend/app/services/intelligence_service.py): # Verbatim Citation Offset Validation & Invariant Gate # backend/app/services/intelligence_service.py if cit_res.is_valid: cit_key = (cit_res.segment_id, cit_res.char_start, cit_res.char_end, "valid") if cit_key in existing_cit_keys: continue # Exact slicing invariant verification before persistence seg = segment_map.get(cit_res.segment_id) if seg: assert seg.content[cit_res.char_start:cit_res.char_end] == cit_res.verbatim_quote citation = FactCitation( id=str(uuid.uuid4()), fact_id=fact_record.id, document_segment_id=cit_res.segment_id, verbatim_quote=cit_res.verbatim_quote or raw_quote, source_location=cit_res.source_location, char_start=cit_res.char_start, char_end=cit_res.char_end, verification_status="valid", rejection_reason=None, ) db.add(citation) existing_cit_keys.add(cit_key) persisted_citations.append(citation) else: # Explicit rejection: preserve ungrounded claims with rejection reason citation = FactCitation( id=str(uuid.uuid4()), fact_id=fact_record.id, document_segment_id=cit_res.segment_id, verbatim_quote=raw_quote, source_location=cit_res.source_location, char_start=None, char_end=None, verification_status="rejected", rejection_reason=cit_res.rejection_reason, ) db.add(citation) If an LLM hallucinates an assertion that cannot be verified byte-for-byte in the uploaded file, the citation verification gate rejects it immediately. 4.3 Property-Aware Conflict Detection A major failure mode of naive AI systems is string-matching contradiction detection. If Document A says "The team is targeting November 15 for launch" and Document B says "November 15 is our target launch date", naive text comparison models frequently flag them as contradictory simply because the sentences use different words. Relay implements Property-Aware Semantic Matching in backend/app/services/intelligence_analyzer.py: Semantic Profile Extraction: Every fact is broken down into a structured profile: entity_key: e.g. project:odyssey prop_key: e.g. project:odyssey:milestone:beta normalized_value: e.g. date:2026-11-15 amendment_markers: regex detection of words like amend, supersede, postpone, reschedule, extend. Category-Specific Conflict Logic: Contradiction: Two facts share identical entity_key and prop_key, but have incompatible normalized_values, and neither fact contains an amendment marker. Superseded Decision: Incompatible values exist, but one fact contains an explicit amendment marker or comes from an amendment memo. Ownership Gap: Entities categorized as asset or project that have zero incoming stewardship relations. Evidence Gap: Facts with verification status rejected or lacking supporting citations. flowchart TD FactPair["Compare Fact A & Fact B"] --> MatchEntity{"Same Entity &\nSame Property?"} MatchEntity -- No --> Corroborating["Different Subjects\n(No Conflict)"] MatchEntity -- Yes --> MatchValue{"Identical Normalized\nValues?"} MatchValue -- Yes --> CorroboratingFacts["Corroborating Evidence\n(Reinforces Fact)"] MatchValue -- No --> CheckAmendment{"Contains Explicit\nAmendment Language?"} CheckAmendment -- Yes --> Superseded["Superseded Decision\n(Severity: Medium)"] CheckAmendment -- No --> Contradiction["Direct Contradiction\n(Severity: Critical)"] Superseded --> QueueReview["Queue in Adjudication Desk"] Contradiction --> QueueReview 4.4 The Relay FastMCP Server Relay exposes five dedicated tools to autonomous agents via the Model Context Protocol (MCP) using stdio JSON-RPC transport (backend/app/integrations/switch/mcp_server.py): Tool Name Parameters Purpose Permission & Security Model relay_deposit_document title: str, text: str Ingests, segments, extracts facts, and scans conflicts for new records. Agent-executable; triggers automated extraction and indexing. relay_ask_question question: str Queries institutional memory using natural language with strict grounding. Agent-executable; returns answers, verbatim quotes, and confidence scores. relay_get_conflicts status: str, severity: Optional[str] Lists active organizational contradictions, gaps, and discrepancies. Agent-executable; read-only audit of institutional discrepancies. relay_request_conflict_resolution conflict_id: str, resolution_notes: str, proposed_status: str Initiates two-phase human review; returns a secure review URL and token ID. Agent-executable; cannot resolve conflict; queues pending human review. relay_resolve_conflict conflict_id: str, resolution_notes: str, approval_token: str Finalizes conflict adjudication and seals the immutable audit log. Hard Security Gate: Strictly requires a valid, unconsumed, human approval token. Here is the exact agent configuration from our Switch/OpenCode workspace (opencode.jsonc): { "$schema": "https://opencode.ai/config.json", "mcp": { "relay": { "type": "local", "command": [ "python", "-m", "app.integrations.switch.mcp_server" ], "environment": { "RELAY_API_URL": "http://127.0.0.1:8000" } } }, "permission": { "*": "allow", "relay_*": "allow" } } 4.5 How the Switch Agent Investigates When an incoming leader asks a question in the Switch chat interface (e.g. "What is the confirmed launch timeline for Project Odyssey?"), the OpenCode agent does not guess. It performs a multi-step investigation across Relay's MCP tools: [Incoming Leader] ──> Switch Room: "What is the confirmed timeline for Project Odyssey?" │ ▼ [OpenCode Agent] ──> Tool Call: relay_get_conflicts(status="open") │ ▼ [Relay MCP] ──> Returns: Conflict #f11b799f (Direct Contradiction: Nov 15 vs Dec 20) │ ▼ [OpenCode Agent] ──> Tool Call: relay_ask_question("Odyssey schedule amendment reason") │ ▼ [Relay MCP] ──> Returns: "Amended following testing on Kubernetes cluster Alpha-9" │ ▼ [OpenCode Agent] ──> Formulates Grounded Response in Switch: "Project Odyssey has two conflicting recorded dates: 1. Nov 15, 2026 (Project Odyssey Launch Plan.txt) 2. Dec 20, 2026 (Project Odyssey Schedule Amendment Memo.txt) This discrepancy is currently FLAGGED as Conflict #f11b799f. Would you like me to request human adjudication to ratify Dec 20?" The agent actively recognizes when institutional records disagree, accurately explains the context, and guides the human toward formal adjudication rather than smoothing over the discrepancy. 4.6 Two-Phase Human Approval & Zero-Trust Governance If an AI agent could resolve conflicts unilaterally, an adversary could prompt-inject an agent to overwrite company policies, reassign intellectual property, or dismiss financial liabilities. Relay eliminates this vulnerability with Two-Phase Human Governance: sequenceDiagram autonumber actor Agent as Switch AI Agent (OpenCode) participant RelayAPI as Relay API Gateway participant TokenService as Approval Token Service participant DB as SQLite Storage (relay.db) actor Reviewer as Human Reviewer participant MM as Mattermost Auth Server Agent->>RelayAPI: POST /conflicts/{id}/request-resolution Note over RelayAPI: Validate conflict is open & valid RelayAPI->>TokenService: Generate 32-byte Cryptographic Token TokenService->>TokenService: Compute SHA-256 Hash of Token TokenService->>DB: Store Token Record (Hash only, status: pending, ttl: 24h) RelayAPI-->>Agent: Return Request ID & Human Review URL Agent-->>Reviewer: Post Review URL in Switch/Mattermost channel Reviewer->>RelayAPI: Open Review Desk (GET /approvals/review?request_id=...) RelayAPI-->>Reviewer: Render Claim A vs Claim B with verbatim citations Reviewer->>RelayAPI: Submit Credentials (Username/Password or PAT) RelayAPI->>MM: Server-to-Server Authentication (POST /api/v4/users/login) MM-->>RelayAPI: Auth Confirmed (User: human-reviewer) Note over RelayAPI: Rate Limiter Enforced (5 max attempts, 300s lockout) Reviewer->>RelayAPI: Click "Approve Resolution" + Justification Notes RelayAPI->>DB: Validate Token: Unconsumed, Not Expired, Conflict Bound RelayAPI->>DB: Set Token Status -> consumed RelayAPI->>DB: Set Conflict Status -> resolved RelayAPI->>DB: Insert Immutable Record in conflict_resolution_audits RelayAPI-->>Reviewer: Adjudication Complete & Audit Sealed Replay Protection & Identity Verification Implementation # backend/app/services/approval_service.py @classmethod def human_adjudicate_request( cls, db: Session, request_id: str, decision: str, approver_id: Optional[str] = None, mattermost_token: Optional[str] = None, operator_secret: Optional[str] = None, decision_notes: Optional[str] = None, ) -> Tuple[ConflictApprovalToken, Optional[KnowledgeConflict]]: # 1. Anti-Spoofing Gate: Derive approver identity strictly from Mattermost session # Caller-supplied approver_id strings in the JSON body are strictly ignored if mattermost_token and mattermost_token.strip(): profile = MattermostAuthService.verify_session_token(mattermost_token) verified_approver = profile["verified_approver_id"] verified_auth_type = "mattermost_session" elif operator_secret and operator_secret.strip() == settings.SWITCH_OPERATOR_SECRET: verified_approver = approver_id.strip() if approver_id and approver_id.strip() else "switch_operator" verified_auth_type = "switch_operator_secret" else: raise UnauthorizedApproverError("Authentication required: Invalid credentials.") record = db.query(ConflictApprovalToken).filter(ConflictApprovalToken.id == request_id).first() if not record: raise ApprovalRequestNotFoundError(f"Approval request '{request_id}' not found.") # 2. Replay Protection: Check if already consumed or rejected if record.status == "consumed": raise TokenAlreadyConsumedError("Approval token has already been consumed.") if record.status == "rejected": raise TokenRejectedError("Approval request was already rejected.") # 3. Expiration Check now = datetime.now(timezone.utc) exp = record.expires_at.replace(tzinfo=timezone.utc) if record.expires_at.tzinfo is None else record.expires_at if exp < now: record.status = "expired" db.commit() raise TokenExpiredError("Approval request has expired.") # 4. Atomic Consumption & Immutable Audit Logging record.status = "consumed" record.consumed_at = now conflict = db.query(KnowledgeConflict).filter(KnowledgeConflict.id == record.conflict_id).first() conflict.status = record.proposed_status conflict.resolved_by = verified_approver conflict.resolved_at = now audit = ConflictResolutionAudit( id=str(uuid.uuid4()), conflict_id=record.conflict_id, approval_token_id=record.id, decision="approved", approver_id=verified_approver, approver_auth_type=verified_auth_type, resolution_notes=f"[APPROVED by {verified_approver}] {decision_notes or record.resolution_notes}", token_hash=record.token_hash, ) db.add(audit) db.commit() return record, conflict Raw tokens are generated using Python's secrets.token_urlsafe(32). The raw token is returned to the client once; only its SHA-256 hash is persisted in the database. 4.7 Nine-Chapter Handover Dossier & Roadmap Generation Relay compiles institutional memory into a boardroom-ready 9-Chapter Executive Briefing Book (backend/app/services/dossier_service.py): Chapter Title Focus & Contents 01 Executive Mandate & Operational Health Total records ingested, entities indexed, readiness telemetry, baseline health metrics. 02 Active Initiatives & Milestone Delivery Detailed delivery tracking for Project Odyssey, Project Aegis, Project Nova. 03 Responsibility Matrix & Stewardship Hierarchy Reporting relationships, active owners, and RACI delegations. 04 Strategic Decisions & Amendment Lineage Chronological ledger of ratified strategic decisions alongside superseded history. 05 Pending Deliverables & Critical Commitments Time-sensitive deliverables, financial thresholds, and contractual obligations. 06 Discrepancy Ledger & Adjudication Queue Unresolved contradictions segregated from human-adjudicated resolutions. 07 Ownership Gaps & Institutional Hazards Unassigned infrastructure assets (e.g. Kubernetes cluster Alpha-9). 08 Institutional Contacts & System Dependencies Verified directory of key personnel and infrastructure dependencies. 09 Source Document Archive & Citation Register Complete bibliographic provenance register of all deposited primary sources. Accompanying the dossier is a chronological Day 1–30 Operational Roadmap: Phase 1 (Days 1–7: Orientation & Bilateral Briefing): Formal bilateral handover sessions between outgoing leader Aman Kumar and incoming successor Marcus Vance. Phase 2 (Days 8–14: Discrepancy Adjudication & Infrastructure Stewardship): Formal assignment of Kubernetes cluster Alpha-9 ownership. Phase 3 (Days 15–21: Stakeholder Alignment & Architecture Review): Align engineering units on the postponed February 1, 2027 Project Aegis Beta date. Phase 4 (Days 22–30: Operational Autonomy & Readiness Gate): Pre-flight verification for Project Nova reliability testing and formal signing of the transition book. 4.8 Grounded Q&A with Honest Refusal: The Three Knowledge States A critical requirement for institutional intelligence is knowing when to say "I don't know." Standard enterprise chatbots and conversational RAG pipelines suffer from dangerous over-confidence: they smooth over logical contradictions, interpolate between conflicting dates, or synthesize plausible-sounding fiction when records are silent. Relay eliminates this vulnerability by enforcing three unambiguous knowledge states: Figure D: The Three Knowledge States of Relay — distinguishing grounded affirmation with character offsets, semantic contradiction review, and honest refusal. State 1: Evidence Available (Grounded Affirmation with Citations) When deposited institutional records contain evidence-backed assertions, Relay formulates an exact, concise response. Crucially, the response is bound to exact character offsets ([char_start, char_end]) in primary document segments, verified by the runtime slicing invariant assert seg.content[start:end] == verbatim_quote. State 2: Conflicting Evidence (Surface Contradiction & Request Review) When multiple records claim incompatible values for the same institutional property (such as two conflicting launch dates for Project Odyssey), Relay strictly refuses to arbitrarily pick one or hallucinate a compromise. Instead, it surfaces both competing claims side-by-side with full bibliographic context and issues a 32-byte single-use cryptographic approval token so an authorized human can ratify the active reality. State 3: Insufficient Evidence (Honest Refusal / Zero Hallucination) When an incoming leader queries topics not supported by deposited archives, Relay evaluates domain token matches against statements and canonical entity names. If token scores fall below the minimum grounding threshold, Relay returns an explicit, honest refusal rather than guessing: In backend/app/services/qa_service.py, when a user queries Relay: Relay extracts specific domain tokens, discarding common stop words and generic domain terms. It scores facts based on exact token matches against statements, categories, and canonical entity names. If no facts achieve a minimum grounding threshold, Relay returns: { "answer": "Insufficient evidence in current institutional records. The deposited documentation does not contain verified claims regarding this topic.", "confidence_score": 0.0, "has_sufficient_evidence": false, "citations": [] } The system never hallucinates answers to fill gaps. 5. Technology Stack & Architectural Fit Every tool in Relay's stack was selected to solve a concrete engineering requirement: Technology Responsibility Engineering Rationale Python 3.12 & FastAPI Core REST API & Business Services Native async support, high performance, clean Pydantic v2 data validation schemas. SQLite 3.45 with WAL Local-First Persistent Relational Engine Single-file zero-configuration database; Write-Ahead Logging allows concurrent reads during writes. Google GenAI SDK (Gemini Flash) Multimodal Structured Knowledge Extraction Native JSON schema enforcement with fast inference speeds and large token context windows. FastMCP (Model Context Protocol) AI Agent Interface Standard Open standard protocol connecting autonomous agents to local tools via clean stdio JSON-RPC. Switch Console & OpenCode Agent Orchestration & Workspace Collaboration Developer-native environment allowing AI agents and human reviewers to collaborate in chat rooms. Mattermost Team Edition Human Authentication & Webhook Target Secure, open-source enterprise chat supporting server-to-server user verification via Personal Access Tokens. Next.js 15 (App Router) & React 19 Industrial Editorial Brutalist UI Server-side rendering, instant page transitions, strict TypeScript type safety, and custom SVG visualizers. Docker & Docker Compose Reproducible Deployment Encapsulates the Python backend and database environment with zero host configuration drift. 5.1 Architectural Decisions & Engineering Trade-Offs Building an institutional memory platform requires choosing between competing engineering trade-offs. The following table details the core architectural decisions made during Relay's development: Architectural Dimension Chosen Implementation Alternative Rejected Engineering Trade-Off & Rationale Knowledge Representation Relational SQLite WAL Schema (facts, citations, entities, conflicts) Vector-Only Database / Embedding Index Vector similarity cannot enforce exact logical constraints or character-level auditability. Relational schemas enable deterministic conflict detection, explicit foreign key cascades, and single-file zero-configuration local deployment. Evidence Provenance Byte-Exact Slicing Gate (char_start, char_end) Loose Paragraph / Document-Level Citations Unanchored citations allow AI models to hallucinate plausible facts with fake references. Enforcing seg.content[start:end] == quote at ingestion guarantees an uncorrupted chain of custody back to primary documents. Conflict Discovery Property-Aware Semantic Categorization (entity:prop:val) LLM Prompt Comparison / Vector Cosine Distance Semantic embedding distance flags different wordings of identical dates as contradictions and misses actual date incompatibilities. Property profiling categorizes conflicts deterministically into contradictions, superseded decisions, and ownership voids. Governance & Authority Two-Phase 32-Byte Cryptographic Tokens & Mattermost Auth Autonomous Agent Direct Database Writes Allowing an LLM agent write access to resolve corporate records introduces prompt injection and unauthorized policy alteration risks. Agents only propose resolutions; ratification requires authenticated human token consumption. Information Retrieval Grounded Refusal with Token Match Scoring Generative RAG with Conversational Smoothing Conversational chatbots attempt to please the user by guessing answers when context is sparse. In leadership transitions, an honest refusal ("Zero records found") prevents costly operational failures. 6. A Visual Tour of the Application 6.1 The Executive Continuity Dashboard The primary command center displays real-time continuity scores, dynamic knowledge metrics, and direct alerts for open contradictions. Figure 1: The Relay Executive Dashboard rendering real-time readiness telemetry, indexed entity counts, and active conflict tallies. 6.2 Document Ingestion & Verbatim Evidence Inspector Depositing records automatically triggers segmentation and citation anchoring. Every statement can be inspected down to its verbatim offset. Document Archive Index Extracted Evidence & Citations Figure 2: Ingested documents with SHA-256 verification hashes. Figure 3: Inspecting extracted facts linked to character offsets. 6.3 Discrepancy Intelligence & Investigations Relay cross-examines competing claims side-by-side, displaying exact source documents and highlighting conflicting dates. Direct Contradiction Comparison Unassigned Ownership Gap Figure 4: Comparing conflicting Odyssey launch dates (Nov 15 vs Dec 20). Figure 5: Highlighting Kubernetes cluster Alpha-9 as an unassigned asset. 6.4 The Dynamic Continuity Map An interactive SVG topological radar that maps relationships between people, documents, projects, and unresolved gaps. Topology Radar Mode Accessible Entity Ledger Mode Figure 6: Interactive radar with zoom/pan controls and node subduing focus. Figure 7: Tabular entity ledger offering accessible table navigation. 6.5 Two-Phase Human Review Desk & Mattermost Authentication When an agent requests conflict resolution, human reviewers authenticate server-to-server through Mattermost to ratify decisions. Two-Phase Human Review Screen Mattermost Reviewer Login Figure 8: Human review desk showing competing claims and evidence. Figure 9: Secure server-to-server Mattermost credential verification. 6.6 The 9-Chapter Handover Dossier & Grounded Q&A The platform synthesizes institutional memory into an evidence-backed briefing book paired with a grounded natural-language search desk. 9-Chapter Executive Briefing Book Zero-Hallucination Grounded Q&A Figure 10: Chapter navigation across projects, decisions, and roadmaps. Figure 11: Grounded question answering returning verbatim quotations. 7. How to Run Relay Locally (Try Relay Yourself) Relay is built as an open, local-first platform designed to run in air-gapped or developer environments with zero cloud vector dependencies. You can spin up the full stack in under five minutes. GitHub Repository: https://github.com/Amankumar0018/Relay License: MIT Open Source License Target Environment: Windows, macOS, or Linux (Docker / Native Python 3.12 + Node 18+) Prerequisites Python: v3.11 or v3.12 Node.js: v18.0.0 or higher (v20+ recommended) Docker Desktop: With Docker Compose v2+ (optional for native runs) Git: Installed and configured Step 1: Clone the Repository git clone https://github.com/Amankumar0018/Relay.git cd Relay Step 2: Environment Configuration Copy the environment template files: cp .env.example .env cp backend/.env.example backend/.env Configure your backend/.env with your Google Gemini API key: GEMINI_API_KEY=your_google_gemini_api_key SWITCH_OPERATOR_SECRET=generate_a_random_32_char_secret_string DATABASE_URL=sqlite:///./relay.db Step 3: Run the Backend & Verified Test Suite You can run the backend via Docker Compose: docker compose up -d --build Or run natively with Python: cd backend python -m venv venv source venv/bin/activate # On Windows: .\venv\Scripts\activate pip install -r requirements.txt uvicorn app.main:app --reload --port 8000 Verify backend health and run the 229-test automated regression suite: # Health check curl http://localhost:8000/health # Expected: {"status":"ok","database":"connected","environment":"development","version":"0.1.0"} # Execute test suite (229 verified unit and integration tests) pytest backend/tests -v Step 4: Run the Next.js Frontend cd frontend npm install npm run build npm run start Open http://localhost:3000 in your browser. Step 5: Configure OpenCode / Switch Agent Add the Relay FastMCP server to your Switch agent's opencode.jsonc: { "mcp": { "relay": { "type": "local", "command": ["python", "-m", "app.integrations.switch.mcp_server"], "environment": { "RELAY_API_URL": "http://127.0.0.1:8000" } } } } Once registered, the Switch agent can autonomously query relay_get_conflicts, relay_ask_question, and initiate relay_request_conflict_resolution with token-governed human ratification. 8. What Relay Still Gets Wrong (Genuine Limitations) Engineering integrity requires acknowledging where a system currently reaches its boundaries: Dependence on Source Document Cleanliness: Relay performs exceptionally on digital text memos and PDFs with clean typography. However, poorly scanned PDFs with heavy OCR noise can produce fragmented character offsets, causing the strict citation verification gate to reject valid facts. Synchronous Extraction Latency: Document extraction currently runs synchronously during HTTP requests. Ingesting an 80-page financial contract can take 25–40 seconds while Gemini processes structured entity schemas. A production deployment requires an asynchronous Celery/Redis task queue. Local SQLite Concurrency Constraints: SQLite in WAL mode easily handles concurrent reads, but write transactions (such as bulk uploads during active human adjudication) are serialized. Enterprise enterprise multi-tenant deployments must migrate to PostgreSQL. Local Mattermost Instance Binding: The current implementation authenticates against a local Mattermost container on port :52067. Production enterprise rollouts require configuring OAuth 2.0 PKCE with corporate Okta/Azure AD identity providers. False Positive Sensitivity in Semantic Clustering: Relay intentionally biases toward over-flagging potential contradictions rather than missing a genuine discrepancy. In rare edge cases, two loosely related tasks sharing a property key may trigger a review flag that requires human dismissal. 9. What We Learned Building Relay produced five concrete engineering takeaways: Extraction without character offsets is hallucination waiting to happen. Summarizing a document into bullet points without binding each point to exact source coordinates (char_start, char_end) breaks the chain of custody. When executives make high-stakes decisions, they need to see the exact paragraph in the primary record. Contradiction detection requires property-aware categorization, not vector similarity. Embedding models measure semantic relatedness, not logical consistency. Two sentences claiming opposite dates are semantically almost identical, yet logically contradictory. Explicit property profiling (entity:property:value) is essential. AI agents should never possess authority over human decisions. Giving an LLM agent write access to resolve company conflicts is an architectural anti-pattern. The agent's role is forensic discovery and recommendation; ratification must remain human. Approval workflows require cryptographic single-use tokens. Simple webhook calls or string parameters (e.g. authorized_by="admin") can be forged or replayed by compromised agent runtimes. Cryptographically random single-use tokens with stored hashes eliminate agent impersonation. Grounded refusal is more valuable than a guess. An incoming executive would rather be told "The archives do not contain documentation regarding this server cluster" than receive a plausible-sounding hallucination that causes a production outage. 10. Where Relay Goes Next Hybrid Dense-Sparse Concordance (pgvector + BM25): Combining keyword-exact coordinate retrieval with vector embeddings to scale across hundreds of thousands of institutional records. Real-Time WebSocket Conflict Feeds: Pushing immediate contradiction alerts into active Mattermost and Switch rooms the second an inconsistent memo is uploaded. Automated Spoken Meeting Grounding: Ingesting recorded transition handover meetings via the Gemini Live API, converting spoken commitments into verified citations. Multi-Tenant Workspace Partitioning: Cryptographic multi-tenant organization boundaries for private enterprise advisory and M&A due diligence. 11. Closing & Discussion Organizations do not fail because they lack data. They fail because their institutional truth fragments across departures, unlinked cloud drives, and undocumented assumptions. When a leader moves on, their successor shouldn't have to start from zero. By combining deterministic citation grounding, continuous contradiction detection, cryptographic human governance, and structured dossier synthesis, Relay transforms ephemeral organizational context into an uncorrupted institutional memory. A Question for Discussion: Where should the line be drawn between what an AI agent can autonomously decide and what must require cryptographic human approval in enterprise operations? Let me know your thoughts in the comments below! 12. Verified Links & References Relay GitHub Repository: https://github.com/Amankumar0018/Relay Flip the Switch Hackathon: WeMakeDevs Hackathon Portal Model Context Protocol (MCP): Anthropic MCP Specification Google GenAI Python SDK: Google DeepMind Gemini Documentation FastAPI Framework: FastAPI Documentation Mattermost API Reference: Mattermost Developer Documentation