Skip to main content
Glama

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.


Related MCP server: APEX PSI MCP Server

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.

Component

INT8 Size

CPU p50 Latency

Held-Out Result

Known Limitations

web_evidence_int8 + nli_int8 (corroborate_sources)

23.1 MB + 91.1 MB

3.0 ms / 9.9 ms

47/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_120

Implicit 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 MB

10.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 MB

3.2 ms

128/130 (98.5%) safe tier assignment on multi-clause R-21 (2 blinded LLM raters); 44/50 (88.0%) exact on HZD_50

Over-escalates ~12–15% of benign technical queries containing clinical or security nouns to higher proof tiers.

ProvenanceGate (Ed25519)

0 MB

< 0.3 ms

0/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 writes

Verifies 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:

System

Hardware & Memory

Accuracy ([95% Wilson CI])

Recall / FPR

Turn p50 Latency

Organic_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 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%)

  • 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

Available Tools

4 tools
corroborate_sourcesA
Read-onlyIdempotent

Evaluate independent evidentiary support across retrieved RAG or web snippets by collapsing syndicated wire-copy duplicates and checking cross-domain contradictions. Call before answering factual queries from retrieved passages; do not use to fetch web URLs (URLs are parsed offline solely for domain grouping and never contacted over the network) or to audit tool-execution prose (use verify_narration). Supply at least two sources from distinct domains to reach multi-source proof standards (sources=[] yields speculation with meets_casual_burden=false); contradictions set disputed=true without failing, whereas an empty query or malformed sources item returns isError=true.

Inputs: query (required), sources (required). Returns: hazard, disputed, dispute_sources, achieved_standard, +5 more

inspect_receiptA
Read-onlyIdempotent

Retrieve individual signed receipt records, standalone RFC 6962 Merkle inclusion proofs, and optional AER-1 envelopes from an on-disk JSONL receipt log, whereas verify_receipt_log returns only a whole-log summary. Call when auditing a specific tool invocation or exporting portable inclusion proofs; do not use for a fast whole-file pass/fail check (use verify_receipt_log) or assistant reply checking (use verify_narration). Cryptographically verifies the entire log before returning data: filters seq, call_id, and tool combine via logical AND (omitting all three lists from seq=0 truncated to limit), while a missing/tampered file, key mismatch, or out-of-range seq returns isError=true.

Inputs: log_path (required), seq, tool, limit, +4 more. Returns: entries, log_valid, key_pinned, entry_count, +3 more

verify_narrationA
Read-onlyIdempotent

Audit an assistant draft reply clause-by-clause against in-memory turn receipts to flag fabricated tool-action claims, unlike verify_receipt_log and inspect_receipt which read on-disk JSONL logs. Call before sending a tool-using reply (pass receipts=[] when zero tools ran to reject any claimed side effects); do not use for RAG citation checking (use corroborate_sources) or log-file cryptography. Runs offline with zero network calls: ungrounded claims return is_valid=false with character offsets and retry_prompt rather than raising an error, whereas malformed receipt objects return isError=true.

Inputs: receipts (required), narration (required), user_prompt. Returns: device, is_valid, latency_ms, retry_prompt, +2 more

verify_receipt_logA
Read-onlyIdempotent

Validate whole-file cryptographic integrity of an on-disk JSONL receipt log written by epistemic-guard mcp-proxy, returning aggregate chain and Merkle root status rather than individual entries (use inspect_receipt to fetch entries). Call in CI gates or post-session audits; do not use to check assistant prose (use verify_narration) or mint receipts (signing is confined to the isolated mcp-proxy parent process). Passing both pubkey_file and expected_pubkey_hex requires them to encode the identical 32-byte key (omitting both checks self-consistency against entry 0), and any missing file, key conflict, sequence gap, or tampered digest returns isError=true naming the failing seq.

Inputs: log_path (required), pubkey_file, expected_pubkey_hex. Returns: log_valid, key_pinned, entry_count, merkle_root, +2 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct epistemic check: in-memory narration audit, whole-log crypto integrity, individual receipt/proof retrieval, and source corroboration. Descriptions explicitly delimit boundaries by naming the sibling tool to use instead, leaving no realistic chance of misselection.

    Naming Consistency5/5

    All four names are snake_case verb_noun (verify_narration, verify_receipt_log, inspect_receipt, corroborate_sources). The differing verbs are meaningful rather than arbitrary, and even the shared verify_ prefix maps to a shared notion of validation.

    Tool Count4/5

    Four tools is on the lean side but each maps to a genuinely separate concern (narration, log integrity, entry export, evidence corroboration), with no filler. Receipt signing is deliberately excluded to the proxy process, so the surface is not artificially padded.

    Completeness4/5

    Covers the full read/verify lifecycle: verify narration, verify whole log, inspect entries plus Merkle proofs, and corroborate retrieved sources. The main omission is key discovery/rotation or any tooling around the mcp-proxy signing identity, which agents must handle out of band.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Gives AI agents verifiable, tamper-evident receipts for their actions — attest_action signs a cryptographic receipt for what the agent did (email sent, payment made, form filed), verify_receipt checks it offline, get_identity returns the agent's did:key. Sign locally, verify anywhere, zero backend.
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Append-only evidence receipts for AI records: seal, verify, cite, chain-check, anchor status. A seal proves a record existed at a time, not that its contents are true. Five tools over stdio with npx -y apex-psi-mcp — no account, no key, verification free forever.
      5
      458 npm
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Contributors: dengyier & Tim Shing(成孝添) Check what an AI agent was authorized to do and what its signed evidence supports. Includes reference SOC alert review and a separately enabled Codex preview-directory Guard; installing MCP does not activate Guard.
      32
      97 PyPI
      261
      Apache 2.0