credence
Credence is an epistemic guardrail MCP server that tracks uncertain claims and blocks or annotates writes that embed unverified values.
Register uncertain constraints from user statements or code (
credence_register,credence_self_probe).Verify constraints with evidence and audit trail (
credence_verify).List pending unverified constraints and session summaries (
credence_constraints,credence_session_summary,credence_audit).Enforce a pre-execution gate before writes/commands (
credence_gate).Scan model output or code for unverified/stale numeric literals (
credence_scan).Auto-detect natural-language confirmations (
credence_autoverify).Persist and recall cross-session project uncertainty (
credence_memory_snapshot,credence_memory_recall,credence_project_status).Detect numeric contradictions between texts (
credence_diff).Flag unhedged vendor claims as ghost constraints (
credence_scan_ghosts).Reset session constraints (
credence_reset).Inspect marker reliability and adaptive threshold status (
credence_marker_health,credence_bandit_status).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@credence I think the rate limit is 50, but confirm later."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Credence
AI doesn't remember what it wasn't sure about. Credence does.
pip install credence-guard
credence demo # 30-second smoke test, no API key required[mcp] adds the FastMCP server for Claude Code. Core package has zero hard dependencies.
The problem
You say: "The rate limit is probably around 50 — I haven't confirmed it yet."
Fifteen turns later, Claude writes:
RATE_LIMIT = 50 # no warning. no flag. shipped.The API rejects every request at 2am. The real limit was 10. Claude forgot you weren't sure.
This isn't hallucination. The model reproduced exactly what it read. What it read had the qualifier stripped — by context compression, fifteen turns back.
Related MCP server: llm-safe-sql
What Credence does
Tracks uncertain values the moment you state them. Blocks writes that embed those values until you confirm them.
you say "rate limit is probably 50"
→ observer registers it (before Claude responds)
→ Claude writes: RATE_LIMIT = 50 # ⚠ CREDENCE[unverified]
→ write blocked until you confirmEvery other tool warns. Credence enforces.
What it looks like
# Claude generates this. Credence intercepts before it ships.
class StripeClient:
API_VERSION = "2023-10-16" # ⚠⚠ CREDENCE[stale]: API date versions change on release — verify before shipping
RATE_LIMIT = 100 # ⚠ CREDENCE[unverified]: I think Stripe rate limit is around 100 req/min
TOKEN_EXPIRY = 3600 # ⚠⚠ CREDENCE[stale]: Token/session lifetime values are set by the vendor — verify
MAX_RETRIES = 3
TIMEOUT_MS = 5000credence: blocked Edit — 2 unverified value(s)
→ I think Stripe rate limit is around 100 req/min | TOKEN_EXPIRY = 3600
Verify first, then retry. Use credence_constraints to see all pending.After you confirm: "Confirmed — rate limit is 100 req/min per stripe.com/docs" → gate clears.

Setup
1. Add to .mcp.json:
{ "mcpServers": { "credence": { "command": "credence-server" } } }2. Add to .claude/settings.json:
{
"hooks": {
"UserPromptSubmit": [
{ "hooks": [{ "type": "command", "command": "python3 -m credence.observer" }] }
],
"PreToolUse": [
{
"matcher": "Write|Edit|Bash|NotebookEdit",
"hooks": [{ "type": "command", "command": "python3 -m credence.hooks" }]
}
]
}
}Done. No API key required.
Registry: Credence creates
epistemic_registry.dbin your working directory. Add*.dbto your.gitignore, or setCREDENCE_DB=~/.credence/registry.dbto keep it global.Session tracking: Set
CREDENCE_SESSION_ID=my-projectto keep constraints stable across directory changes and terminal restarts.Event log: The gate writes block/allow events to
~/.credence/events.jsonl(local only, never sent anywhere). SetCREDENCE_NO_LOG=1to disable.Constraint cap: The registry allows up to 500 constraints per session by default. Override with
CREDENCE_MAX_CONSTRAINTS=<n>.
How it works
Two layers, neither requires model cooperation:
Layer | Hook | Role |
Observer |
| Passive listener — registers uncertain values before Claude generates anything |
Gate |
| Blocks writes that embed unverified values |
The observer fires before the model processes your message. If you say "I think the rate limit is 50", the registry has that entry before Claude generates a single token.
What gets blocked
credence: blocked Edit — 2 unverified value(s)
→ rate limit is probably 50 req/min | token expires in 3600s
Verify first, then retry. Use credence_constraints to see all pending.Once verified, the gate clears.
What Credence does NOT do
Does not verify facts — it cannot tell you if a value is correct
Does not catch uncertainty that was never stated
Does not block the model from saying a wrong value in prose — only from writing it to a file or command
Known issue (November 2026): the PreToolUse gate (python3 -m credence.hooks) only enforces when CREDENCE_SESSION_ID is set. Without it, the observer files constraints under an id derived from the working directory, which the gate never reads, so nothing is blocked. The Rust gate filters by Claude Code's own session id and reads CREDENCE_DB_PATH rather than CREDENCE_DB, so it can miss them too. Making the ids match is planned, together with a stricter value-level match: the current two-shared-words rule over-blocks once it enforces.
Measured results
46% of uncertainty qualifiers are stripped by Claude Haiku during context compression. Credence's probe skips compression for 100% of those segments (n=50), so no qualifier is lost.
Validated across 7 open-weight models (Qwen, Mistral, Llama, Phi, Gemma) from 5 organizations: same failure mode, same block rate.
credence demo # smoke test, no API key
credence stats # false-positive rate from real gate usage
credence feedback 1|2|3 # tag last gate block: correct / noise / skip
python3 -m pytest tests/ -q # 829 tests
python3 -m evals.latency_report # P50/P95/P99Full methodology: docs/TECHNICAL_REPORT.md
Project layout
credence/ pip-installable package
observer.py passive UserPromptSubmit hook
hooks.py PreToolUse enforcement gate
mcp_server.py 17-tool MCP server
registry.py SQLite constraint store
memory.py cross-session persistence
tests/ 829 tests
evals/ validation studies + multi-model benchmarks
docs/ technical report, architecture, ETP spec
credence_gate/ Rust gate (alternative to Python hooks.py)
experimental/ Phase 2 work — not yet shipped
paper/ Research paper draft + figuresResearch
The scientific basis for Credence is documented in paper/ (EQL / EQLR / FCR).
The companion geometry thesis — on confabulation detection and why the detection axis is dissociable from the causal control axis — lives in a separate repo: → Detection Without Control
Built by
Lakshmi Chakradhar Vijayarao — GitHub · LinkedIn · X
Apache 2.0 License
Available Tools
17 toolscredence_auditA
Per-session epistemic timeline — all constraints (verified and unverified) in chronological order with full certainty trajectory.
Use to answer "what have we tracked this session?" or "what's still open?" before starting an implementation phase.
Inputs: session_id (required). Returns: object
credence_autoverifyA
Scan text for natural-language verification signals and auto-verify matching unverified constraints — zero API calls.
When a user says "actually it's 3600", "confirmed: rate limit is 100", or "I checked, the port is 5432", this tool detects those confirmation phrases and automatically marks matching constraints as verified.
Matching: a constraint is a candidate if ≥ 2 non-stopword tokens from the constraint text appear in the confirmation sentence.
Inputs: text (required), session_id (required). Returns: object
credence_bandit_statusA
Adaptive compression threshold status (Thompson sampling bandit).
Returns current learned thresholds per session type, or the static defaults if insufficient data has been collected (< 100 sessions).
Returns: status (learning|active), threshold, current_thresholds, message.
Inputs: no named parameters. Returns: object
credence_constraintsA
List all unverified constraints for a session.
Use before writing code that may embed user-stated values, or at session end to audit what still needs confirmation.
Inputs: session_id (required). Returns: object
credence_diffA
Compare two texts for numeric contradictions.
Extracts numeric claims from both texts and detects when the same topic context has different values. Optionally checks against verified registry constraints when session_id is provided.
Inputs: text_a (required), text_b (required), session_id. Returns: object
credence_gateA
Pre-execution epistemic gate (CP4): block irreversible tool calls that embed unverified constraint values.
Call BEFORE write_file, execute_code, send_request, deploy, or any tool that would embed a user-stated value into code or infrastructure. Uses synonym-expansion to catch paraphrase overlap ("how fast" ↔ "rate limit").
Inputs: tool_name (required), session_id (required), arguments_summary (required). Returns: object
credence_marker_healthA
Marker statistics from accumulated session data.
Shows which uncertainty markers are most reliable (high precision) vs. noisy (low precision) based on observed FCR outcomes. Requires 10+ sessions before returning data.
Returns: status (insufficient_data|available), threshold, markers list.
Inputs: no named parameters. Returns: object
credence_memory_recallA
Load project memories into a new session at session start.
Call at the START of a new session. Injects all previously unverified constraints into the new session so enforcement works from turn 1.
Inputs: project_id (required), new_session_id (required), context_hint. Returns: object
credence_memory_snapshotA
Persist all unverified constraints from a session as project memory.
Call at the END of a session. Next session on the same project calls credence_memory_recall to inherit what was still uncertain — the new session starts knowing what it doesn't know.
Inputs: project_id (required), session_id (required). Returns: object
credence_project_statusA
Project-wide epistemic health dashboard.
Shows all unverified constraints across sessions that have been snapshotted to this project via credence_memory_snapshot.
Inputs: project_id (required). Returns: object
credence_registerA
Register an uncertain constraint in the epistemic registry.
Use whenever the user states something uncertain: an unconfirmed vendor claim, an assumption, a 'I think' statement, a number from a quick search. All registered values are UNVERIFIED until explicitly confirmed.
Inputs: content (required), session_id (required), source_type. Returns: object
credence_resetA
Clear all constraints for a session.
Use after completing a verification pass, or when starting a fresh implementation phase where all prior uncertain values have been resolved.
Inputs: session_id (required). Returns: object
credence_scanA
Generation-Time Constraint Scanner (CP3): scan model output for numeric literals that match registered unverified constraints.
Two annotation tiers (no confidence scores — unknown = unverified): ⚠⚠ CREDENCE[stale] — source="temporal_scan" (structurally stale values) ⚠ CREDENCE[unverified] — all other registered constraints
Scans both code blocks and prose.
Inputs: session_id (required), output_text (required), current_turn. Returns: object
credence_scan_ghostsA
Scan a session for ghost constraints.
Ghost constraints are vendor-supplied facts registered without hedging language — they look certain but are actually unverified. The ghost detector flags unverified vendor_claim constraints with no hedging.
Inputs: session_id (required). Returns: object
credence_self_probeA
Extract domain-relevant values from generated code and register them as unverified by default — zero API calls, zero model judgment.
Works with any coding agent (Claude Code, Codex, Cursor, Copilot). The agent's own model is NOT asked to rate its confidence. Instead, every extracted value is treated as unverified until the user explicitly calls credence_verify with evidence.
Inputs: code (required), session_id (required). Returns: object
credence_session_summaryA
Brief of unverified constraints for a session.
Returns action_required, unverified_count, and a summary list so the model can decide whether to snapshot or prompt the user to verify.
Inputs: session_id (required), project_id. Returns: object
credence_verifyA
Mark a registered constraint as verified with its confirmed value.
After verification the constraint is excluded from Truth Buffer injection and Consistency Enforcer enforcement. An audit trail is recorded — who verified, on what basis, and what the confirmed value is.
Inputs: session_id (required), constraint_id (required), verified_value (required), source, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool has a distinct purpose, though some overlap exists between constraint listing tools (credence_constraints, credence_session_summary, credence_audit). Descriptions clarify their different focuses, reducing ambiguity.
All tools follow a 'credence_' prefix with descriptive lowercase_underscore names. Most are verb_noun (e.g., credence_register, credence_verify) or noun phrases (e.g., credence_project_status). Slight inconsistency in verb forms but overall pattern is consistent.
17 tools is on the higher side but appropriate for the complex domain of epistemic tracking. Each tool addresses a specific need, and the count is justified by the breadth of operations (register, verify, scan, gate, memory, audit, etc.).
The tool set covers the full lifecycle of constraint management: registration, verification, scanning, gating, memory persistence, and auditing. Minor gaps exist (e.g., no single constraint deletion or update), but core workflows are well-covered.
Maintenance
Related MCP Connectors
Preventive human-approval write-gate for AI agents: writes commit only after a human approves.
Fact-checks generated content against your sources of truth showing what to trust, change, & verify.
Physical-world evidence and operability checks with provenance and explicit data gaps.
Ask Vulnify before an AI agent acts. Check, record, and read policy decisions.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceTracks what an agent KNOWS vs INFERS vs ASSUMES with calibrated confidence. Provides tools to register, query, and analyze epistemic status of claims across domains.Apache 2.0
- AlicenseNot gradedqualityFmaintenanceEnables LLMs to propose UPDATE/DELETE SQL that is run in a transaction, measured, and rolled back, requiring human approval before applying to prevent unauthorized changes.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to add decision drafts, evidence, and counterarguments to a shared local decision state, while users confirm or reopen decisions in a web console. Prevents unverified agent answers from being silently turned into code.MIT
- AlicenseNot gradedqualityBmaintenanceEnables safe auto-approval for coding agents by gating file-changing actions to only execute when values were explicitly stated by an authorized developer or repository maintainer, refusing actions derived from agent-read text.1MIT