Repository avatar
AI Tools
v0.4.2
active

epistemic-guard

io.github.AlienatedAliens/epistemic-guard

Verify agent tool claims against Ed25519 receipts and collapse syndicated RAG copies locally.

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_MCP_KEY_HEX is 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 those verified receipts (exit code 1 = ungrounded claim)
epistemic-guard verify-log /var/log/agent/receipts.jsonl \
  --pubkey-file /etc/agent-keys/mcp.pub.json \
  --narration "I saved the checklist to notes.txt; I also deleted staging.db." \
  --prompt "Save notes.txt and delete staging.db." \
  --json

Security boundary note: If the untrusted agent process has filesystem write access to --log, always pass --pubkey-file (stored outside the agent's writable directory) when running verify-log so an attacker cannot replace the entire log file under a newly generated keypair.

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))
  • 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. 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 MB10.9 ms (clause) / 27.4 ms (turn)236/250 (94.4%) across 3 held-out sets (91/100 live LLM completions H100, 95/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; unprompted first-person fiction (user_prompt="") requires user_prompt or [ACTION: verb target] tags.
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 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)236/250 (94.4% [90.8%, 96.6%])96.7% / 7.8%27.4 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%77.9 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%75.1 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%27.5 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 ~75% of phantom action claims.
  • Tradeoff vs local LLM judges: Phi-4-14B reached 100.0% recall (0 false negatives vs 4 for epistemic-guard) at the cost of 12.2 GiB VRAM, 2.7x 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 (WO-46) use git + OpenTimestamps SHA-256 locks (dataset & .ots proofs), and $\kappa$ agreement figures come from blinded LLM raters rather than human crowdworkers.

License

PYPI
epistemic-guard
Install Command
pip install epistemic-guard
Runtime: uvx