PyPI v0.4.0 MIT License Python 3.11+
RollSolo Open-Source Infrastructure

epistemic-guard

Signed Ed25519 tool receipts, out-of-process MCP receipt proxying, provenance-gated memory stores, and RAG source deduplication for autonomous AI agents. Runs locally on CPU, GPU, or NPU in 3–11 ms with zero LLM API calls.

Built and maintained by RollSolo (Sean Maxwell), originating from RollSolo's deterministic state and narration-verification stack and released standalone under the MIT License for general MCP servers, tool-calling agents, and retrieval pipelines.

Action-Claim Accuracy
236 / 250 (94.4%)
3 held-out cohorts incl. 100 live H100 turns
Clause / Turn Latency
10.9 ms / 27.4 ms
0 MiB GPU VRAM required (82.7 MB INT8)
Memory Self-Poisoning
0 / 100 (0.0%)
Public-key-only Ed25519 write gate (< 0.3 ms)
Wire / Sybil Collapse
30 / 30 (100%)
RAG duplicate collapse + hazard proof tiers

What Problem It Solves

  • Phantom tool claims in assistant replies: A tool returns HTTP 500, fails JSON schema validation before execution, or is never invoked, yet the model tells the user "I refunded order #8821 and emailed the receipt." Pre-execution input/tool firewalls cannot catch post-execution prose hallucinations when no tool call ran.
  • Memory self-poisoning and prompt injection: Persisting raw assistant prose or untrusted scraped web content directly into vector/SQLite memory allows fabricated states and injected instructions to survive across sessions.
  • Syndicated RAG echo chambers: Multiple retrieved domains reprinting identical wire copy get counted as independent corroborating sources on clinical, legal, or security queries.

Four Core Capabilities

1. Out-of-Process CLI Proxy

MCP Stdio Receipt Proxy

epistemic-guard mcp-proxy wraps any stdio Model Context Protocol server in a separate OS process, strips signing keys from the child environment, and signs completions, tool runtime errors (isError: true), pre-execution rejections (-32602), and server EOF crashes into an append-only RFC 6962 Merkle JSONL log with optional AER-1 export.

2. Post-Execution Verification

ReceiptSupervisor & Streaming

@recorder.tool signs Python sync/async calls and router dispatch failures; ReceiptSupervisor checks assistant prose clause-by-clause (including live SSE/voice streams via sup.stream()) and generates structured retry prompts distinguishing executed, failed, and unexecuted actions.

3. Cryptographic Provenance

Ed25519 Memory Write-Gating

ProvenanceGate and SQLiteProvenanceStore hold only Ed25519 public keys and enforce append-only SQLite triggers plus sequential SHA-256 chain hashes. Even if prompt injection compromises the agent loop, untrusted LLM_NARRATION writes are rejected by construction.

4. Retrieval Corroboration

RAG Deduplication & Hazard Tiers

corroborate_sources collapses near-duplicate syndicated snippets, checks cross-domain NLI contradictions, and scales required independent source counts using an INT8 hazard classifier before an agent answers high-consequence queries.

Quickstart & MCP Configuration

Install from PyPI and fetch SHA-256-verified INT8 weights
pip install epistemic-guard
epistemic-guard download-models
epistemic-guard demo
Wrap any stdio MCP server (Claude Desktop, Cursor, Cline, Windsurf, or custom hosts)
{
  "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 signed Merkle log and audit an assistant reply from CLI or CI
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

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

Evaluated across three locked cohorts (LOCKED_COH_50, BLIND42_COH_100, and Organic_Heldout_H100 live LLM completions; 0 training overlap) on an Intel Core Ultra 9 275HX and NVIDIA RTX 5080 Laptop GPU. Full scripts, raw predictions, and OpenTimestamps SHA-256 pre-registration proofs are published in RollSolo/epistemic-guard-benchmarks.

Post-execution action-claim verification accuracy, memory footprint, and latency across 250 held-out turns
System Hardware & Memory Held-Out Accuracy Recall / FPR Turn p50 Latency Live H100 Split
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 ms 91/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 ms 84/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 ms 79/100 (79.0%)
Off-the-shelf DeBERTa-v3-xsmall NLI CPU (0 MiB VRAM, 91.1 MB RAM) 132/250 (52.8% [46.6%, 58.9%]) 24.6% / 20.3% 27.5 ms 51/100 (51.0%)

Scope, Limitations & Research Preprints

  • Complement to pre-execution guardrails: Input and tool-call firewalls (such as NVIDIA NeMo Guardrails or LlamaFirewall) filter unsafe prompts and unauthorized tool invocations before execution; epistemic-guard verifies post-execution assistant output and memory writes against signed execution receipts.
  • Known boundaries: Neural classifiers are English-only. When INT8 model weights are not installed locally, epistemic-guard emits EpistemicModelUnavailableWarning (or raises ModelIntegrityError when require_neural=True) rather than failing silently. If an untrusted agent has write access to a receipt log path, pin --pubkey-file outside the agent's writable directory when running verify-log.
  • Licensing & DOIs: Source code is MIT-licensed; INT8 weights derive from Apache-2.0 and MIT upstream encoders (MODEL_NOTICES.md). Archived preprints: Zenodo DOIs 10.5281/zenodo.23649049, 10.5281/zenodo.23901452, 10.5281/zenodo.23901605, and 10.5281/zenodo.23901683.