Credence — Epistemic Guard

Credence

AI 不会记住自己曾经不确定的内容。Credence 会。

pip install credence-guard
credence demo   # 30-second smoke test, no API key required

[mcp] 会为 Claude Code 添加 FastMCP 服务。核心包没有任何强制依赖。

---

问题

你说：“速率限制大概是 50——我还没确认。”

十五轮对话后，Claude 写道：

RATE_LIMIT = 50   # no warning. no flag. shipped.

凌晨 2 点，API 拒绝了所有请求。真实限制是 10。Claude 忘了你并不确定。

这不是幻觉。模型准确复述了它读到的内容。而它读到的内容中的限定语已被剥除——这是上下文压缩造成的，发生在十五轮对话之前。

---

Credence 的作用

在你说出不确定值时立即记录下来。在你确认之前，阻止写入包含这些值的内容。

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

其他工具只会警告。Credence 会强制拦截。

---

效果展示

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

确认后："Confirmed — rate limit is 100 req/min per stripe.com/docs" → 拦截解除。

---

设置

1. 添加到 .mcp.json：

{ "mcpServers": { "credence": { "command": "credence-server" } } }

2. 添加到 .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" }]
      }
    ]
  }
}

完成。无需 API 密钥。

注册表： Credence 会在你的工作目录中创建 epistemic_registry.db。将 *.db 添加到 .gitignore，或设置 CREDENCE_DB=~/.credence/registry.db 以将其保存在全局位置。

会话跟踪： 设置 CREDENCE_SESSION_ID=my-project，以便在切换目录和重启终端后保持约束不变。

事件日志： 拦截器会将拦截/放行事件写入 ~/.credence/events.jsonl（仅保存在本地，不会发送到任何地方）。设置 CREDENCE_NO_LOG=1 可禁用日志。

约束上限： 默认情况下，注册表每个会话最多允许 500 条约束。使用 CREDENCE_MAX_CONSTRAINTS=<n> 可更改上限。

---

工作原理

两层机制，均不需要模型配合：

层	钩子	作用
观察器	UserPromptSubmit	被动监听器——在 Claude 生成任何内容之前，记录不确定的值
拦截器	PreToolUse	阻止写入包含未经验证值的内容

观察器会在模型处理你的消息之前触发。如果你说“我觉得速率限制是 50”，那么在 Claude 生成第一个 token 之前，注册表中就已有相应条目。

---

会拦截哪些内容

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.

验证通过后，拦截器即解除拦截。

---

Credence 不会做什么

• 不会验证事实——它无法判断某个值是否正确
• 不会捕捉从未明说的不确定性
• 不会阻止模型在文字中说出错误值——只会阻止它将错误值写入文件或命令

---

测量结果

在上下文压缩期间，Claude Haiku 会剥除 46% 的不确定性限定语。Credence 会拦截其中 100% 的写入（n=50，自助法置信区间：[0%–0%]）。

已在来自 5 个组织的 7 个开放权重模型（Qwen、Mistral、Llama、Phi、Gemma）上验证：失败模式相同，拦截率相同。

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

完整方法说明：docs/TECHNICAL_REPORT.md

---

项目结构

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

---

研究

Credence 的科学依据记录在 paper/ 中（EQL / EQLR / FCR）。

配套的几何学论文探讨了虚构内容检测，以及为何检测轴可与因果控制轴分离；该论文位于单独的代码仓库中： → 无控制的检测

---

Built by

Lakshmi Chakradhar Vijayarao — GitHub · LinkedIn · X

Apache 2.0 License