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.
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
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.
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.
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.
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
pip install epistemic-guard
epistemic-guard download-models
epistemic-guard demo
{
"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"
]
}
}
}
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.
| 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-guardverifies 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-guardemitsEpistemicModelUnavailableWarning(or raisesModelIntegrityErrorwhenrequire_neural=True) rather than failing silently. If an untrusted agent has write access to a receipt log path, pin--pubkey-fileoutside the agent's writable directory when runningverify-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.