epistemic-guard

Out-of-process Ed25519 MCP tool-receipt proxy, RFC 6962 Merkle audit logger, and zero-VRAM OpenVINO INT8 runtime verification server for catching hallucinated tool actions.

Documentation

epistemic-guard

Signed tool receipts, out-of-process MCP receipt proxying, Ed25519 memory write-gating, and RAG source deduplication for autonomous agents.
Runs locally on CPU, GPU, or NPU in 3–11 ms. Zero LLM API calls. MIT License.

Project Page · PyPI · Interactive Demo · INT8 Weights · Held-Out Benchmarks (N=973)


What It Fixes

  1. Phantom tool claims in assistant replies: A tool threw an HTTP 500, failed schema validation before execution, or was never called, yet the model replies "I refunded order #8821 and emailed the receipt." Pre-execution firewalls do not catch this when no tool call occurred.
  2. Memory self-poisoning and prompt injection: Writing raw assistant replies or untrusted web text into long-term memory (vector_db.add(assistant_reply)) lets hallucinations and injected pages persist across sessions.
  3. Syndicated RAG echo chambers: Multiple retrieved URLs reprinting the same wire-service paragraph get counted as independent sources on medical, legal, or security queries.

Install

pip install epistemic-guard

# Optional: download the 4-model OpenVINO INT8 pack (~227 MB download / ~279 MB unpacked, SHA-256 verified)
epistemic-guard download-models

# Run the local 4-part verification showcase
epistemic-guard demo

1. Out-of-Process MCP Receipt Proxy (mcp-proxy + verify-log)

Wrap any stdio MCP server (Claude Desktop, Cursor, Cline, Windsurf, or custom agents in any language). The Ed25519 signing key stays inside the mcp-proxy OS process; EPISTEMIC_GUARD_* signing secrets (EPISTEMIC_GUARD_MCP_KEY_HEX, EPISTEMIC_GUARD_MASTER_KEY, etc.) are stripped before spawning the child MCP server. Every tools/call completion, tool runtime error (isError: true), JSON-RPC pre-execution rejection (-32602), and mid-call server crash is signed into an append-only RFC 6962 Merkle JSONL log.

{
  "mcpServers": {
    "filesystem": {
      "command": "epistemic-guard",
      "args": [
        "mcp-proxy",
        "--log", "/var/log/agent/receipts.jsonl",
        "--key-file", "/etc/agent-keys/mcp.key",
        "--pubkey-out", "/etc/agent-keys/mcp.pub.json",
        "--aer1",
        "--",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/srv/workspace"
      ]
    }
  }
}

Verify the receipt log and check an assistant reply from any language or CI job:

# Verify Ed25519 signatures, sequential chain hashes, and Merkle roots (exit code 0 = valid, 2 = tampered)
epistemic-guard verify-log /var/log/agent/receipts.jsonl \
  --pubkey-file /etc/agent-keys/mcp.pub.json

# Also verify an assistant reply against current-turn receipts (exit code 1 = ungrounded claim)
epistemic-guard verify-log /var/log/agent/receipts.jsonl \
  --pubkey-file /etc/agent-keys/mcp.pub.json \
  --since-seq 12 \
  --narration "I saved the checklist to notes.txt; I also deleted staging.db." \
  --prompt "Save notes.txt and delete staging.db." \
  --json
  • Multi-worker locking, signed sequence links, & key rotation: Each ReceiptLogEntry carries both an inner Ed25519 ToolReceipt signature and a domain-separated Ed25519 entry_signature over (seq, session_id, leaf_sha256, prev_chain_sha256, chain_sha256, merkle_root), defeating active reorder-and-rehash attacks even when an attacker has write access to receipts.jsonl. Concurrent mcp-proxy workers sharing a --log file coordinate appends via OS-level exclusive file locks. When rotating Ed25519 keys across log segments, pass --prev-log /var/log/agent/prev.jsonl (and optional --prev-pubkey-file / --session-id) on both mcp-proxy and verify-log.

Security boundary note: Parent-injected EPISTEMIC_GUARD_MCP_KEY_HEX secrets stay in memory and are scrubbed from child environments; when using --key-file on disk (created atomically with POSIX mode 0600, or restricted NTFS directory ACLs on Windows), run mcp-proxy under a dedicated OS user or container if the untrusted agent or child MCP server runs on the same host, so same-UID processes cannot read --key-file directly. Likewise, store --pubkey-file outside any agent-writable directory when running verify-log.

You can also run epistemic-guard itself as a standalone stdio MCP verification server (verify_narration, verify_receipt_log, inspect_receipt, corroborate_sources):

{
  "mcpServers": {
    "epistemic-guard": {
      "command": "epistemic-guard",
      "args": ["mcp-server"]
    }
  }
}

2. In-Process Python Supervision (@recorder.tool + ReceiptSupervisor)

import os
from epistemic_guard import (
    MerkleReceiptLog,
    ProvenanceGate,
    ReceiptRecorder,
    ReceiptSupervisor,
    SignerFactory,
)

factory = SignerFactory.from_master_key(os.urandom(32))
gate = ProvenanceGate(factory.public_keys())
merkle = MerkleReceiptLog(gate=gate)
recorder = ReceiptRecorder(signer=factory.tool_verified(), merkle_log=merkle)


@recorder.tool  # Supports sync and async functions
def write_file(path: str, content: str) -> str:
    return f"wrote {len(content)} bytes"


write_file("notes.txt", "release checklist")

sup = ReceiptSupervisor(device="CPU")
verdict = sup.verify_narration(
    "I saved your checklist to notes.txt; I also deleted staging.db.",
    receipts=recorder.receipts,
    user_prompt="Save the checklist to notes.txt.",
)

assert verdict.is_valid is False
print(verdict.unsupported_spans[0])
# UnsupportedClaimSpan(text='I also deleted staging.db.', start_char=37, end_char=63, claimed_family='CLAIM_DELETE', ...)

# Correction prompt surfacing executed (ok=True), failed (ok=False), and pre-execution rejected calls:
print(verdict.to_retry_prompt(recorder.receipts))
  • Signature pinning, session binding & freshness anti-replay: Pass gate=gate, expected_session_id="...", and max_receipt_age_seconds=300 to ReceiptSupervisor (or expected_pubkey_hex / expected_session_id / max_receipt_age_seconds on MCP verify_narration) to reject unsigned, cross-session, or replayed receipts before supervision runs.
  • OpenTelemetry & Langfuse observability export (zero extra deps): Pass otel_span=span to ReceiptRecorder or call attach_otel_evidence(span, receipts=recorder.receipts, verdict=verdict, merkle_root=merkle.merkle_root()) to stamp AER-1 digests, Ed25519 signatures, Merkle roots, and supervision verdicts directly onto OTel / Langfuse traces.
  • Streaming SSE / voice pipelines: sup.stream(receipts=...) checks each clause as ., !, ?, ;, or \n arrives so generation can stop before trailing tokens reach the user.
  • Router dispatch & AER-1 interop: recorder.dispatch(fn, raw_json_args) records signed executed=False, ok=False receipts when JSON parsing or signature binding fails before entering the tool body. ToolReceipt.from_aer1(...) and receipt.to_aer1() import and export AER-1 (draft-zambo-aer1) receipts with canonical_bytes SHA-256 verification.
  • Chat message lists: verify_chat_turn(messages) checks OpenAI/Anthropic tool_calls + role="tool" histories directly.

3. Ed25519 Memory Write-Gating (ProvenanceGate + SQLiteProvenanceStore)

ProvenanceGate holds only Ed25519 public keys. Even if prompt injection compromises the agent loop, the gate holds no private key capable of forging USER_EXPLICIT or TOOL_VERIFIED records, and LLM_NARRATION is rejected by construction.

import os
from epistemic_guard import Provenance, ProvenanceGate, SQLiteProvenanceStore, SignerFactory

factory = SignerFactory.from_master_key(os.urandom(32))
gate = ProvenanceGate(factory.public_keys())  # Public keys only
store = SQLiteProvenanceStore("agent_memory.sqlite", gate)  # Append-only SQLite triggers + hash chain

env = factory.user_explicit().sign("Deploy freeze starts Friday 18:00 UTC.", trace_id="turn-42")
store.append(env, expected_provenance=Provenance.USER_EXPLICIT)

assert len(store.list_verified()) == 1
assert store.verify_chain() == 1
store.close()

4. RAG Source Deduplication & Hazard Scaling (corroborate_sources)

from epistemic_guard import corroborate_sources

wire_copy = (
    "Clinical guidance notes that initial adult warfarin dosing typically starts at "
    "2 mg to 5 mg once daily with INR monitoring."
)
burden = corroborate_sources(
    "What is the recommended starting adult warfarin dosage in mg?",
    [
        {"url": "https://reuters-health.org/a", "snippet": wire_copy},
        {"url": "https://clinical-digest.net/b", "snippet": wire_copy},
        {"url": "https://pharma-bulletin.io/c", "snippet": wire_copy},
    ],
    device="CPU",
)

assert burden.deduplicated_duplicates_collapsed == 2
assert burden.independent_sources_count == 1
assert burden.meets_casual_burden is False  # High-hazard query requires >=3 independent sources

Measured CPU Performance & Held-Out Accuracy (OpenVINO INT8)

All four optional neural classifiers run via OpenVINO INT8 (CPU, GPU, or NPU, English-only) with pinned SHA-256 manifests verified by default at every model load (verify_hashes=True). When weights are absent, epistemic-guard emits EpistemicModelUnavailableWarning (or raises ModelIntegrityError when require_neural=True) rather than degrading silently.

ComponentINT8 SizeCPU p50 LatencyHeld-Out ResultKnown Limitations
web_evidence_int8 + nli_int8 (corroborate_sources)23.1 MB + 91.1 MB3.0 ms / 9.9 ms47/64 (73.4%) burden accuracy & 56/64 (87.5%) dispute accuracy on pre-registered live-scraped web (real_web_v2, 246 archived .html.gz pages, 3 blinded LLM raters $\kappa = 0.91\text{–}1.00$); 60/64 (93.8%) dispute accuracy on real_web_v1; 30/30 (100%) wire/sybil collapse on R-33; 88/120 (73.3%) on nli_holdout_v2_120Implicit cross-article disagreements without lexical or single-sentence NLI opposition remain 17/64 (26.6%) of open-web cases.
action_claim_int8 (ReceiptSupervisor)82.7 MB8.6 ms (clause) / 17.9 ms (turn)233/250 (93.2%) across 3 held-out sets (91/100 live LLM completions H100, 92/100 BLIND42_COH_100, 50/50 LOCKED_COH_50); 297/300 (99.0%) 10-class speech-act val (99.7% FP16 parity)Code blocks, blockquotes, attributed dialogue, and creative/translation user_prompt contexts are masked automatically; strict args target-binding rejects bare zero-argument receipts when prose names concrete file/identifier targets.
hazard_int8 (OpenVINOHazardClassifier)82.7 MB3.2 ms128/130 (98.5%) safe tier assignment on multi-clause R-21 (2 blinded LLM raters); 44/50 (88.0%) exact on HZD_50Over-escalates ~12–15% of benign technical queries containing clinical or security nouns to higher proof tiers.
ProvenanceGate (Ed25519)0 MB< 0.3 ms0/100 (0.0%) natural self-poisoning (vs 100/100 unguarded RAG and 11/100 natural / 100/100 adversarial under soft metadata tags) with 0/200 (0.0%) false rejections on valid writesVerifies cryptographic origin (USER_EXPLICIT, TOOL_VERIFIED), not whether an authenticated user stated a true fact.

Action-Receipt Benchmark (N=250 Held-Out Turns)

Evaluated across LOCKED_COH_50 (50), BLIND42_COH_100 (100), and Organic_Heldout_H100 (100 live LLM completions; 0 training items; benchmarks/external_baselines_benchmark.json) on Intel Core Ultra 9 275HX + RTX 5080 Laptop GPU:

SystemHardware & MemoryAccuracy ([95% Wilson CI])Recall / FPRTurn p50 LatencyOrganic_Heldout_H100
epistemic-guard (action_claim_int8)CPU (0 MiB VRAM, 82.7 MB RAM)233/250 (93.2% [89.4%, 95.7%])96.7% / 10.2%17.9 ms91/100 (91.0%)
Mistral-Nemo-Instruct-12B (Q5_K_M Judge)GPU (8,844 MiB VRAM)217/250 (86.8% [82.0%, 90.4%])87.7% / 14.1%80.6 ms84/100 (84.0%)
Microsoft Phi-4-14B (Q6_K Judge)GPU (12,214 MiB VRAM)216/250 (86.4% [81.6%, 90.1%])100.0% / 26.6%76.2 ms79/100 (79.0%)
Off-the-shelf DeBERTa-v3-xsmall NLICPU (0 MiB VRAM, 91.1 MB RAM)132/250 (52.8% [46.6%, 58.9%])24.6% / 20.3%22.4 ms51/100 (51.0%)
  • Why off-the-shelf SNLI/MNLI (52.8%) misses phantom actions: Standard NLI classifies "Zero tools ran" vs "I saved checklist_backup.md" as NEUTRAL rather than CONTRADICTION on 73/92 (79.3%) of its false negatives.
  • Tradeoff vs local LLM judges: Paired two-sided exact McNemar tests confirm higher overall accuracy than Mistral-NeMo-12B ($p = 0.0259$) and Phi-4-14B ($p = 0.0095$; $p = 0.0169$ on Organic_Heldout_H100). Phi-4-14B reached 100.0% recall (0 false negatives vs 4 for epistemic-guard) at the cost of 12,214 MiB (11.9 GiB) VRAM, 4.3x latency, and a 26.6% false-positive rate on offers and idioms. Cloud frontier judges (GPT-4o, Claude) were not benchmarked here.

Ecosystem Comparison & Disclosures

  • OWASP Top 10 for Agentic Applications (2026) coverage:
    • ASI02 (Tool Misuse & Phantom Execution): mcp-proxy, @recorder.tool, and ReceiptSupervisor verify assistant prose against signed ToolReceipt logs (executed, ok, error_code) so unexecuted or failed tool calls cannot be reported as completed.
    • ASI06 (Memory & Context Poisoning): ProvenanceGate and SQLiteProvenanceStore reject unsigned writes and LLM_NARRATION at the database trigger layer, and corroborate_sources collapses syndicated wire/Sybil echoes before synthesis.
    • ASI08 (Cascading Hallucinations Across Trust Boundaries): Append-only RFC 6962 Merkle logs and AER-1 receipt export preserve verifiable provenance across multi-agent and MCP boundaries.
  • Scope vs adjacent projects:
    • Pipelock: Go egress/MCP proxy that scans outbound network traffic for SSRF/exfiltration and emits mediator-signed receipts; epistemic-guard adds post-turn clause-level prose verification (ReceiptSupervisor), Ed25519 SQLite memory write-gating, and syndicated RAG source deduplication in Python (0 MiB VRAM).
    • NabaOS: Full Rust agent runtime with OS sandboxing and Ed25519-signed static constitutions. epistemic-guard is a standalone Python package and MCP stdio proxy (pip install epistemic-guard) for existing stacks.
    • Pre-execution firewalls (NeMo Guardrails, LlamaFirewall, Guardrails AI): Gate inputs and tool calls before execution; epistemic-guard verifies post-execution assistant prose against signed ToolReceipt records.
    • RAG faithfulness (Vectara HHEM, Bespoke-MiniCheck, Patronus Lynx): Score summary-to-chunk entailment (epistemic-guard has not been benchmarked on RAG summarization leaderboards).
    • Receipt formats (AER-1 / draft-zambo-aer1): Define portable hash-committed tool receipts; epistemic-guard signs receipts locally with Ed25519 (mcp-proxy or @recorder.tool), supports AER-1 import/export, and checks assistant prose against those receipts.
  • Disclosures: Neural models are English-only. Benchmarks ran on a single workstation; pre-registrations use git + OpenTimestamps SHA-256 locks (dataset & .ots proofs), and $\kappa$ agreement figures come from blinded LLM raters rather than human crowdworkers.

License