Skip to main content
Glama
README.md
# `epistemic-guard`

<!-- mcp-name: io.github.AlienatedAliens/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](https://rollsolo.app/epistemic-guard) · [PyPI](https://pypi.org/project/epistemic-guard/) · [Interactive Demo](https://huggingface.co/spaces/RollSolo/epistemic-guard) · [INT8 Weights](https://huggingface.co/RollSolo/epistemic-guard-int8) · [Held-Out Benchmarks (`N=973`)](https://huggingface.co/datasets/RollSolo/epistemic-guard-benchmarks)

---

## 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

```bash
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.

```json
{
  "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:

```bash
# 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`):

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

---

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

```python
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.

```python
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`)

```python
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`](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](https://github.com/pipelab-org/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](https://github.com/nabaos/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](https://huggingface.co/datasets/RollSolo/epistemic-guard-benchmarks)), and $\kappa$ agreement figures come from blinded LLM raters rather than human crowdworkers.

---

## License

- **Source Code:** [MIT License](LICENSE) (`Copyright (c) 2026 Sean Maxwell` · [ORCID `0009-0004-0133-0463`](https://orcid.org/0009-0004-0133-0463) · Built by [RollSolo](https://rollsolo.app), Member of NVIDIA Inception).
- **INT8 Model Weights:** Derived from `Apache-2.0` / `MIT` upstream checkpoints (`cross-encoder/nli-MiniLM2-L6-H768`, `cross-encoder/ms-marco-MiniLM-L-6-v2`, `cross-encoder/nli-deberta-v3-xsmall`); see [`MODEL_NOTICES.md`](MODEL_NOTICES.md).
- **Citation & Preprints:** [`CITATION.cff`](CITATION.cff) · Zenodo DOIs [`10.5281/zenodo.23649049`](https://doi.org/10.5281/zenodo.23649049), [`10.5281/zenodo.23901452`](https://doi.org/10.5281/zenodo.23901452), [`10.5281/zenodo.23901605`](https://doi.org/10.5281/zenodo.23901605), [`10.5281/zenodo.23901683`](https://doi.org/10.5281/zenodo.23901683).

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