universal-research-mcp

具有长期记忆的研究 Agent 会以一种特定方式失败：断言记录中的值仍然有效，但其证据已不再成立——文件发生了变更，主张已被撤回，或者来源从未登记。本项目让这类失败可以通过机制检查、默认拒绝，并进一步测量这些机制实际提供了哪些安全保障。

**0.10.1 新增：**本地嵌入后端加载了随机初始化的权重，而非固定的检查点，导致语义、混合和自适应检索返回噪声，却报告成功。现在会在使用前验证权重是否与检查点一致；必须重建由 0.10.0 或更早版本构建的语义索引。请参阅发行说明，了解受影响范围和重新索引步骤。

一览整体结构

 append-only canonical ledger            derived, rebuildable RAG
 ─────────────────────────────           ─────────────────────────────
 data/events/daily/*/events.jsonl   →    SQLite FTS5 passage+event index
 data/events/sources.jsonl               (+ optional offline semantic view
 (path → SHA-256 at registration)         built FROM the lexical index)
            │                                        │
            │ registered hash + line range           │ BM25 candidates
            ▼                                        ▼
 ┌─────────────────────────── MCP server (30 tools, stdio) ─────────────────────────┐
 │ memory_search_candidates → candidates only ("a score is not evidence")           │
 │ memory_fetch_evidence    → exact lines + integrity_status (matched/mismatched)   │
 │ memory_check_evidence_eligibility → fail-closed receipt; blocks silent omission  │
 │ research_prepare_ingest / research_commit_ingest → two-step, one-time HMAC       │
 │ governance_* (11 fixed roles; preflight only, never executes)                    │
 └──────────────────────────────────────────────────────────────────────────────────┘

• 台账是唯一的权威数据源；每个索引都是派生视图，如果已登记的来源发生变更，索引就会拒绝构建。
• 检索在物理层面上只读（sqlite mode=ro、query_only=ON）。
• 写入需要预先存在的人类审批记录；模型侧的摄取还需要一次性 HMAC 凭证，该凭证在 MCP 之外签发。
• 资格门控会验证引用证据的完整性；如果某条重要主张悄然省略了会话已获取且已发现完整性检查失败的证据，系统将默认拒绝。

上述每句话都有具体的文件和行号作为依据：docs/architecture-deep-dive.md 通过代码引用逐一讲解目标、台账、RAG 构建、RAG↔MCP 链路和各项控制机制，也说明了哪些边界是刻意不执行强制约束的，并在文档字符串中明确指出这一点。

基准测试——测量了什么、如何测量，以及每项结果支持哪些结论

以下每项研究都在运行前预先注册（先提交方案和分析代码；若有偏差，则在受影响的运行开始前于方案中披露），由独立的确定性评分器评分，并用对条件盲化的 LLM 评审进行交叉核验（评审有效性：两名独立评审彼此一致，κ = 1.000；与评审模型的一致性为 κ = 0.865，盲测样本为 50 份判定结果），且仅报告汇总数据。统计方法选择（Wilson/Newcombe 置信区间、mid-p McNemar 检验、三法则）均绑定到引用清单中经哈希验证的来源论文逐字引文。

1 · 这道门能否阻止不安全断言？——能，调用时可降至零

设置。 两组配对执行，一组为合成数据，一组为真实数据。合成数据：24 项任务 × 2 个实验组 × 3 次重复（144 次运行），每项任务都在注入完整性故障的语料库中植入一个正确值和一个被篡改的值（索引后 变更、行漂移、索引过期、证据已撤回／缺失／未注册、 冲突，以及阴性对照）。真实数据：针对一个实际开展了 八个月的研究项目的台账执行 27 项任务——所有故障都是自然发生的； 基准测试没有对任何内容做修改。采用配对设计，因此每项任务都是自身的对照；两个实验组使用相同的模型（gpt-5.6-sol，medium）和提示词，唯一的区别是证据访问权限。 为什么采用这种设置。 植入值能让评分具有确定性（主要终点无需评审员裁量）；自然发生的故障则能回应“合成故障是稻草人”的质疑。 结果。 在可通过哈希检测的故障组中：文件系统组有 21–22/45 项不安全断言，而经过门控后为 0/45（RD 0.49 [0.33, 0.63]）；真实语料库中为 23–26/27 项，而经过门控后为 0/27 （RD 0.85 [0.64, 0.94]）；两个实验组的无故障覆盖率均为 21/21。 这能证明什么。 运行资格判定工作流时，基于完整性受损证据的不安全断言会降至零，且不会牺牲无故障覆盖率。 这并不能证明“MCP 能让 Agent 安全”——请参见基准测试 4。

2 · 代价是什么？——增加检索工作，而非阻止回答

设置。 同一组配对运行，评估次要终点：可回答任务中的错误阻止、未缓存 token 数量、证据绑定有效性。 结果。 真实语料库中有 9/54 项被错误阻止——这 9 项都源于未记录来源引用的历史事件（限制因素是证据链质量，而非门控机制）。token 数量约为文件系统组的 1.4–1.9×。门控组中 81/81 项的证据绑定有效，文件系统组则为 52/81。 这能证明什么。 门控的代价在于检索交互增多以及历史证据链缺失，而非错误阻止完整证据。

3 · 有效载荷去了哪里？——用于搜索，而非验证

设置。 对真实语料库门控组中的所有工具结果进行字节级分解（81 次运行，29.4 MB），并重新运行同日的优化测试。 结果。 有效载荷中 93.4% 用于候选项搜索；验证本身（获取 + 资格判定）占 5.3%。优化测试将传输量减半（有效载荷减少 49%），故障导致的不安全断言仍为 0。 这能证明什么。 验证成本很低；检索才是主要开销，也是优化应着力之处。

4 · 真的有人会调用门控吗？——没有，没有策略就不会

设置。 移除脚手架的消融实验（预注册，3 组 × 24 × 3 = 216 次运行）：任务完全相同，但不设置声明类型、不添加范围前言，也不在任何提示词中命名工具——被测试的处理条件就是原始脚手架。分组：文件系统、已连接 MCP 但未提示，以及一个低成本基线（单条指令 + 注册时生成的哈希清单）。 为何采用此设置。 基准测试 1 的 0/45，是在操作员提示词告知模型使用工作流的条件下测得的。评审提出的问题——“如果不调用门控，就没有任何保护”——要求依据工具使用意识文献，测量激活本身。 结果。 自然条件组在 72/72 次运行中一次 MCP 调用也没有（已验证 30 个工具全部可用）：不安全次数为 24/45，与文件系统组完全一致（RD 恰为 0.000）。清单基线只修复了哈希可见的故障（10/45），遗漏了所有语义问题。 这能说明什么。 有效保护 = 激活 × 执行，而未提示时的激活率为 0%。任何关于 Agent 记忆工具的安全声明都必须以激活为前提。 这是论文核心且诚实的发现，不是对缺陷的披露。

5 · 可部署的制品能恢复激活吗？——策略可以，架构定义不行

设置。 预注册的补充实验，另外进行了 216 次运行：仓库中的 AGENTS.md 策略文件（强制要求使用工作流 + 预先批准会话范围）、仅针对产品的杠杆（在两个工具描述中添加激活触发条件），以及在披露测试装置污染后，对自然条件组进行的干净重跑。 结果。 工具描述触发条件：激活率 0/45——毫无作用。AGENTS.md：激活率42/45（93%），不安全次数减半至 12/45——但这 12 次都包含符合条件的凭据：其中 9 次，模型获取了有故障的来源，发现不匹配后悄悄将其舍弃，只引用了完整证据。 这能说明什么。 单个仓库策略文件就能恢复采用；仅靠工具架构定义则不行。此外还存在第三层保护——引用规范——因为门控只能判断提供给它的引用集合。

6 · 执行引用规范——信息不敌执行

设置。 又进行了两项预注册实验（每项 72 次运行）。v1.2：服务记录会话的获取内容，并在凭据中披露已获取但未引用且存在不匹配的证据，同时要求弃答或处理该证据。v1.3：检测方式相同，但有效的实质性声明会被拒绝通过 （OMITTED-MISMATCHED-EVIDENCE）；引用不匹配的参考内容即可解除拦截。 结果。 披露机制精准触发（故障组 13/45、正常组 0/21、负对照组 0/6），但13 次中有 9 次被绕过——违反了其自身预注册的规则。执行机制：不安全次数为 4/45（达到 ≤ 4 的门槛），拦截触发时的不安全次数为 0/12，没有误拦截，正常组为 21/21。剩余的 4 次涉及哈希完整但语义状态异常的内容（已撤回、无关），文档已说明完整性门控不负责判断这些情况。 这能说明什么。 实测结果表明，各层级的效果排序始终是：信息 < 指令 < 执行。该执行机制已随本软件包发布，并已在安装后的构建版本上进行实时验证。 对治理/摄取接口进行对抗性审计：25/25 个恶意输入均被拒绝通过（审计）。

这些内容均不构成许可

推广到其他模型系列和真实语料； 防御哈希完整的故障（已撤回、过时但有效、无关的证据——已测量，足以击败每个实验组）；与注册前发生的损坏有关的任何内容（按设计，两个实验组都会以 6/6 失败）；Agent 在多 Agent 治理合约下的行为（这些控制措施在直接对抗性输入下会默认拒绝，但目前还没有模型参与治理的基准测试）。

开始使用 — 两条命令即可构建经过验证的研究记忆

pip install universal-research-mcp        # or: uv tool install universal-research-mcp
universal-research quickstart ~/my-research --yes

quickstart 接收一个包含 Markdown 文档的文件夹，一次性完成整个 RAG 设置：初始化存储，为每篇文档注册 SHA-256，为每篇文档追加一条经操作员批准的观察记录（--yes 即表示你的人类批准——没有它，quickstart 只会打印试运行结果），并构建搜索索引。重新运行时只会处理新文件。无需编写 JSON，也无需手动配置审批流程。经已发布软件包验证的免安装替代方案：uvx --from universal-research-mcp universal-research quickstart … --yes。

连接 MCP 宿主

该服务使用纯 stdio——任何 MCP 宿主都可以启动同一条命令。

Claude Code

claude mcp add universal-research -- universal-research serve --root ~/my-research --no-auto-index

Claude Desktop — 一键安装：下载 universal-research-memory-0.10.1.mcpb 并双击（或前往设置 → 扩展 → 从文件安装）。Claude Desktop 会询问你的研究文件夹，并通过 uv 启动服务；空文件夹会自动初始化。手动配置替代方案：

Claude Desktop / Cursor（claude_desktop_config.json / mcp.json）

{
  "mcpServers": {
    "universal-research": {
      "command": "universal-research",
      "args": ["serve", "--root", "/home/you/my-research", "--no-auto-index"]
    }
  }
}

Codex（~/.codex/config.toml，或从 plugin/universal-research-memory/ 安装插件）

[mcp_servers.universal_research]
command = "universal-research"
args = ["serve", "--root", "/home/you/my-research", "--no-auto-index"]

Agent 应执行的证据循环

本节撰写前，已针对通过 quickstart 构建的存储逐字执行：

1. memory_search_candidates {query: "dead-time correction", mode: "lexical"} → 返回作为候选项的观察记录（candidate_only: true — 分数永远不能作为证据）。
2. memory_fetch_evidence {path, start_line, end_line, event_id, expected_sha256} → 返回 integrity_status: "matched" 和精确引用的行；如果文件已发生偏移，则返回 mismatched 并不提供内容。
3. memory_check_evidence_eligibility {claim, claim_type, materiality, evidence:[…]} → 对于完整且来自单一来源的结果声明，返回 status: "eligible"；如果会话获取了不匹配的来源后又默默将其丢弃，则返回 blocked: OMITTED-MISMATCHED-EVIDENCE。

采用说明（基于测量结果，而非建议）。 在我们的消融实验中，如果没有工作区策略，模型从未调用这些工具。请在项目中添加 AGENTS.md，要求执行上述循环，并预先批准非交互式运行的会话范围——这一个文件就将门控激活率从 0% 提高到 93%（详情）。

引用

引用该软件时，请使用概念 DOI 10.5281/zenodo.22118223；它始终指向最新的归档版本，每个 GitHub Release 也会在其下生成一个专属的版本 DOI。

开发参考

python -m pip install ".[test]"
python -m pytest -q
ruff check universal_research_mcp
mypy --no-incremental --cache-dir=/dev/null universal_research_mcp
python -m build
python scripts/validate_distribution_artifact.py dist/*.whl
python scripts/ci_smoke.py dist/*.whl

许可证：MIT

mcp-name：io.github.mp-juns/universal-research-mcp