项目定位与核心能力

inspeximus 是一个聚焦于"可验证智能体记忆（verifiable agent memory）"的代码仓库，核心包为 mnemo。自 mnemo 1.0.0 起，公共 API 已在 mnemo.__all__ 中冻结，治理与擦除工具下放到子模块 deletion_manifest、erasure_auditor，标志着该项目进入"成熟里程碑"阶段，而非新增功能阶段。设计上的两个基本约束是：零依赖（无需外部云服务或第三方库即可跑通测试套件）与 cloud-free CI（在 py3.9 / 3.11 / 3.12 上由 GitHub Actions 持续集成 16 个测试用例）。

围绕"治理 / 时间"支柱，mnemo 自 0.7.22 起提供 CT 风格外部锚点（RFC 6962）与绑定授权主体的擦除墓碑；自 1.2.0 起提供 spend_irreversible 与 is_universal_executor 的通用执行器闸门；自 1.4.0 起在 ErasureAuditor 中加入软删除残留探针；自 1.5.0 起通过 ErasureAuditor.compliance_receipt(...) 签发可对外分享的"擦除证明（proof-of-erasure）"收据，作为 GDPR Art. 17 / EU AI Act 记录留存场景下交付给监管方的工件。

资料来源：README.md:1-60，pyproject.toml:1-30，inspeximus/__init__.py:1-20

安装

仓库通过 pyproject.toml 进行包定义，可直接以可编辑模式从源码安装到任意 Python 3.9+ 环境中：

git clone https://github.com/DanceNitra/inspeximus.git
cd inspeximus
pip install -e .

由于 mnemo 默认行为即"零依赖、本地可跑"，安装完成后无需任何 .env 或外部凭据即可启动 MCP stdio 服务（暴露 12 个工具）。需要注意的是，1.1.0 中引入的安全加固特性（如 Mnemo(max_text=N)、verify_writes(warn_unpinned=True)）均为 OPT-IN，默认行为与 1.0.0 完全一致，由 5 个测试用例锁定。

资料来源：pyproject.toml:1-30，inspeximus/__init__.py:1-20

快速上手

最小可运行示例以 Mnemo(...) 实例开始，使用 remember() 写入、按值排序召回，再以 verify_writes() 完成自校验：

from inspeximus import Mnemo

m = Mnemo()                       # 默认行为：与 1.0.0 一致
m.remember("user", "topic", "首条记忆")
hits = m.recall("topic")
m.verify_writes()                 # 自校验哈希链收据

进阶示例见 examples/01_basics.py，覆盖了值排序召回、按类型衰减、词汇+语义自动模式整合，以及由 revert() / retract_lineage() / echo_guard / forget_subject() 构成的纠错与擦除通道。底层逻辑（如哈希链构造、影响闸门判定）封装于 inspeximus/core.py，可通过直接阅读该文件理解收据串联、forget_subject 授权绑定与 verify_writes 报告自指公钥陷阱的实现细节。

资料来源：examples/01_basics.py:1-80，inspeximus/core.py:1-120

插件形态与已知限制

仓库同时提供 Claude 插件描述符 .claude-plugin/plugin.json，定义插件元数据，便于在 Claude Code / Claude Desktop 中以 MCP stdio 形式直接加载 mnemo，无需编写额外胶水代码。

社区已记录一个安装即用层面的陷阱：README 中宣传的"本地即可跑"完整性基准命令 python mnemo/probes/integrity_bench_revert.py --systems mnemo，在全新克隆并以仓库根目录执行时，会因 server/.env 缺失而在参数解析前失败；即便绕过加载阶段，评分仍依赖 OpenAI judge，因此并非完全离线（参见 issue #1）。建议在 1.5.0 引入合规收据后，参考对应发行说明评估新功能对现有取证链的影响。

资料来源：.claude-plugin/plugin.json:1-20，README.md:80-140

1. 核心内存操作：`Mnemo.remember()` 与 `recall()`

Mnemo 类是整个库的入口。remember(text, type=..., meta=...) 接收一段文本及其类型、附加元数据并写入本地 JSON 存储，同时产出可签名的 receipt（收据）对象。recall(query, k=..., type=...) 在写入集合上做值排序（value-ranked）的语义/词法混合检索，支持按类型过滤。

from inspeximus import Mnemo
m = Mnemo()
m.remember("server URL is https://api.example.com", type="config")
hits = m.recall("server url", k=3)

关键设计点：

• 零依赖：仅依赖标准库，存储为本地 JSON。
• 可签名收据：每条 remember() 都产出 hash-chained 的 receipt，可选 Ed25519 签名（依赖 cryptography，缺省时降级为非签名模式）。
• 可选软上限：Mnemo(max_text=N) 在 1.1.0 中加入，超长文本会被截断并在 meta.truncated_from 打戳。

资料来源：inspeximus/core.py:1-120, examples/03_semantic_recall.py:1-80。

2. 超取代通道：`revert()` / `retract_lineage()` / `forget_subject()`

"超取代"（super-replacement）指的是不仅改写当前值，还能沿因果链向上回滚并发布不可磨灭的撤销证据。

forget_subject 在 0.7.22 引入，在 1.5.0 中升级为 ErasureAuditor.compliance_receipt()，输出带签名的"擦除证明"（proof-of-erasure）凭证，可直接提交监管方。1.4.0 新增 soft-delete residual probes，专门探测后端在 API 返回 200 后但物理介质尚未真正回收的残留数据。

资料来源：examples/02_correction_and_erasure.py:1-120, inspeximus/core.py:200-360。

3. 代码守护：`code_guard` 与 `is_universal_executor()`

inspeximus.code_guard 提供静态层面的危险调用检测：

from inspeximus.code_guard import is_universal_executor
is_universal_executor("shell", "subprocess.run(cmd)")  # True

它识别动词多态的"万能执行器"（universal executor），例如 subprocess.run / eval / exec / SQL 透传 / HTTP 透传——这类工具的可逆性从签名层面无法判定。结合 spend_irreversible(tool=..., contained=...)（1.2.0 引入）：

• 若 contained=True：放行，但要求执行被沙箱包裹。
• 若 contained=False：直接拒绝（denied outright），因为一旦生效不可逆。

flowchart TD
  A[spend_irreversible tool=T] --> B{is_universal_executor T?}
  B -- 否 --> C[放行]
  B -- 是 --> D{contained?}
  D -- 是 --> E[沙箱内放行]
  D -- 否 --> F[拒绝]

资料来源：inspeximus/code_guard.py:1-90, examples/08_code_guard.py:1-60。

4. 评审触发与整体协作

examples/05_review_trigger.py 展示了上述三层的协作模式：当 recall() 返回高价值记忆但 confidence 偏低、或出现 REVERTED 标记、或检测到 universal executor 时，自动生成待人工评审条目。该机制确保：

1. 写入 → recall 检索（核心操作）
2. 出错 → revert / retract_lineage / forget_subject（超取代）
3. 执行危险代码 → code_guard 拒绝（代码守护）
4. 异常状态 → 触发人工 review（闭环）

社区关注点：当前 probes/integrity_bench_revert.py 在仓库根目录以 python mnemo/probes/integrity_bench_revert.py 调用时，会因 server/.env 缺失与默认依赖 OpenAI judge 而在参数解析前失败（见 issue #1）。本地纯 mnemo 路径建议在 mnemo/ 子目录下运行或显式 --systems mnemo --no-judge。

资料来源：examples/05_review_trigger.py:1-100, inspeximus/code_guard.py:30-90, examples/02_correction_and_erasure.py:40-120。

1. 设计目的与作用域

inspeximus 项目将"可验证擦除"作为其治理与时间维度的核心支柱（Pillar 2），目标是把数据主体的删除请求转化为可向监管方（GDPR Art. 17 / EU AI Act）出示的签名证据。区别于仅返回 HTTP 200 的"软删除"语义，系统通过多个存储后端（mnemo 主体、可选第三方存储）联合探测残余，并打包为可离线核验的审计包。

资料来源：inspeximus/erasure_auditor.py:1-40

2. 核心组件构成

ErasureAuditor 是入口类，它将擦除审计拆分为三个职责：

• 探测清单：通过 deletion_manifest 声明待核验的存储后端与待擦除值；
• 跨库探测：在每个后端执行残余探测（残留记录、未压缩段、向量嵌入等）；
• 证据打包：调用 audit_bundle 把探测结果、签名、时间戳组装为可分发的 bundle。

compliance_receipt(subject, values, sign=, pubkey=, request_id=, basis=) 是 DPO（数据保护官）可直接对外出示的产物——一个带签名的"proof-of-erasure"，包含：哪些存储被检查、每个存储的逐项结论、签发者身份与请求 ID。

资料来源：inspeximus/erasure_auditor.py:42-110 inspeximus/deletion_manifest.py:1-30

3. 数据流与审计包结构

witness_pool 与 witness_server 共同提供去中心化的见证者集合：每个 witness 对同一 audit_bundle 给出独立签名，bundle 需达到阈值签名才被视为可信。这一设计防止单一审计员伪造证据。

资料来源：inspeximus/audit_bundle.py:1-60 inspeximus/witness_pool.py:1-50 inspeximus/witness_server.py:20-80

4. 合规层与时间维度

compliance 模块把审计包映射到具体法规条款，提供查询函数 lookup_basis(regulation, article)，供 compliance_receipt 在打包时自动引用对应法条作为 basis 字段。1.5.0 版本同时引入双时间（bitemporal）审计：业务时间（subject_time，数据主体声称的擦除时刻）与审计时间（audit_time，探测实际完成时刻）分别记录，避免"先宣称已删除、后探测"的争议。

flowchart LR
  A[forget_subject] --> B[DeletionManifest]
  B --> C[ErasureAuditor.probe]
  C --> D[per-store findings]
  D --> E[audit_bundle.build]
  W[WitnessPool] --> E
  E --> F[compliance_receipt]
  F --> G[DPO / Regulator]

签名密钥遵循 1.1.0 引入的自引用公钥防护：verify_writes(warn_unpinned=True) 在公钥未锚定到外部见证时告警，避免密钥持有者回滚历史。

资料来源：inspeximus/compliance.py:1-70 inspeximus/audit_bundle.py:60-120

5. 使用模式与已知限制

社区中报告的 Issue #1 指出，mnemo/probes/integrity_bench_revert.py --systems mnemo 在新克隆环境下会因缺失 server/.env 与 OpenAI judge 依赖而失败。这意味着即便 mnemo-only 配置是"本地可跑"的承诺，端到端基准仍依赖外部服务——选择 --systems mnemo 时应预期审计包仅包含 mnemo 自身存储的结论，不含 OpenAI 评判维度。

资料来源：inspeximus/erasure_auditor.py:110-160

6. 小结

可验证擦除管线由 deletion_manifest → erasure_auditor → audit_bundle → witness_pool → compliance 五段构成，最终以签名 compliance_receipt 形式落地。双时间记录、CT 风格外部锚定、阈值见证签名共同保证：DPO 拿到的不是"删除已执行"的承诺，而是可在事后被独立核验的密码学证据。

inspeximus（仓库原名 mnemo）是一套面向 agent 记忆层提供可验证治理能力（防遗忘、对账、影响门控）的基础库。本页聚焦三条对外暴露面：第三方 agent 框架集成、MCP（Model Context Protocol）服务器，以及完整性基准测试。三者在仓库中分别由 inspeximus/integrations/、inspeximus/mcp_server.py 与 inspeximus/probes/integrity_bench_revert.py 共同承担 资料来源：inspeximus/integrations/__init__.py:1-1。

1. 框架集成（LangGraph / CrewAI / LangChain）

inspeximus/integrations/ 子包通过轻量级适配器，将核心 Mnemo 记忆原语（remember、recall、revert、forget_subject、verify_writes 等）映射到主流 agent 编排框架的回调 / 工具接口：

适配层坚持零新增运行时依赖原则，导入即注册；因此默认不会引入框架的传递依赖，框架作为可选 peer 运行 资料来源：inspeximus/integrations/__init__.py:1-1。LangGraph 集成利用图节点拦截 messages/state 的写入路径，使每次 remember 都生成带哈希链的收据，便于事后回放；LangChain 集成则复用其 Memory 接口的 load_memory_variables / save_context 约定，对外保持兼容 资料来源：inspeximus/integrations/langchain.py:1-1。CrewAI 适配器把记忆原语暴露为 Tool，让 agent 在 ReAct 循环内显式调用 forget_subject 等高风险操作，从而通过审计 资料来源：inspeximus/integrations/crewai.py:1-1。

2. MCP 服务器（stdio / 12 个工具）

inspeximus/mcp_server.py 通过标准输入输出（stdio）暴露 MCP 协议，把记忆能力以工具的形式提供给任意 MCP 兼容 host（例如 Claude Desktop、其他 agent runtime）。该服务器随 mnemo 0.7.20 引入，默认提供 12 个工具，覆盖召回、纠正、撤销、遗忘、影响门控与凭证验证等核心能力 资料来源：inspeximus/mcp_server.py:1-1。

工具集合与 CLI 形成互补关系：mcp_server.py 面向进程内 / 跨进程调用，cli.py 则面向终端与脚本场景。两者共享同一组底层 API，因此开发者可以选择“以 MCP host 形式接入”或“以命令行管道形式接入”，而无需重复实现 资料来源：inspeximus/cli.py:1-1。

3. 完整性基准测试（integrity_bench_revert）

inspeximus/probes/integrity_bench_revert.py 是仓库内用于评估记忆回滚与可验证性的基准脚本。社区文档（README）将其宣传为“无需联网、本地可跑”的轻量级回归：

python mnemo/probes/integrity_bench_revert.py --systems mnemo

但 Issue #1 指出：在全新克隆的仓库中执行该命令时，脚本会在参数解析之前就因 server/.env 缺失而失败；即便绕过该依赖，裁判环节仍调用 OpenAI 作为 judge，因此并不是真正的“离线”基准 资料来源：inspeximus/probes/integrity_bench_revert.py:1-1。

下图给出完整的数据流与依赖边界：

flowchart LR
    Host[MCP Host / CLI] -->|stdio| MCP[mcp_server.py]
    Host -->|argparse| CLI[cli.py]
    MCP --> Core[(Mnemo 核心 API)]
    CLI --> Core
    LangChain[langchain.py] --> Core
    LangGraph[langgraph.py] --> Core
    CrewAI[crewai.py] --> Core
    Bench[integrity_bench_revert.py] -->|judge via LLM| OpenAI[(OpenAI API)]
    Bench --> Core
    Bench -.失败.-> Env[server/.env]

开发者若希望真正本地复跑，应事先检查：server/.env 是否存在、是否启用了 OPENAI_API_KEY 回退到内置启发式 judge，或在 PR 中增加离线 judge 路径（这是 Issue #1 当前讨论的核心）。

4. 选型建议与常见误区

• 零依赖运行时：核心包不强制安装框架，导入 inspeximus.integrations.langgraph 等才会触发对应框架的导入 资料来源：inspeximus/integrations/__init__.py:1-1。
• MCP 优先 vs CLI 优先：自动化 agent 集成建议走 MCP（结构化 JSON-RPC）；CI 流水线、批处理、回放脚本建议走 CLI 资料来源：inspeximus/cli.py:1-1。
• 基准测试可复现性：在未解决 Issue #1 之前，不要把 integrity_bench_revert.py 的输出作为唯一合规证据；推荐结合 verify_writes() 与外部锚点（anchor()）共同取证 资料来源：inspeximus/mcp_server.py:1-1。

Pitfall Log / 踩坑日志

项目：DanceNitra/inspeximus

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/DanceNitra/inspeximus | host_targets=mcp_host, claude_code, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/DanceNitra/inspeximus | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/DanceNitra/inspeximus | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/DanceNitra/inspeximus | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/DanceNitra/inspeximus | no_demo; severity=medium

6. 安全/权限坑 · 来源证据：Integrity benchmark local-only command requires missing server/.env and still needs OpenAI judge

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integrity benchmark local-only command requires missing server/.env and still needs OpenAI judge
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/DanceNitra/inspeximus/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/DanceNitra/inspeximus | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/DanceNitra/inspeximus | release_recency=unknown