Skip to main content
Glama

Credence

AI doesn't remember what it wasn't sure about. Credence does.

PyPI CI Python License: Apache 2.0

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 confirm

Every 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   = 5000
credence: 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.

Gate demo


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.db in your working directory. Add *.db to your .gitignore, or set CREDENCE_DB=~/.credence/registry.db to keep it global.

Session tracking: Set CREDENCE_SESSION_ID=my-project to 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). Set CREDENCE_NO_LOG=1 to 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

UserPromptSubmit

Passive listener — registers uncertain values before Claude generates anything

Gate

PreToolUse

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/P99

Full 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 + figures

Research

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 tools
credence_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

    A3.9/5.0

    Scored across 17 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.).

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Tracks 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
    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT