universal-research-mcp

長期間にわたるメモリーを持つ研究エージェントは、特定の問題に直面します。記録された値を、その根拠がもはや成立しないにもかかわらず断定するのです。ファイルが変化していたり、主張が撤回されていたり、情報源がそもそも登録されていなかったりします。このプロジェクトでは、この問題を機械的に検証できるようにし、フェイルクローズで処理するとともに、安全性のどの部分をこの仕組みが実際に提供しているかを測定します。

**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）。
• 書き込みには、事前に作成された人間による承認記録が必要です。さらに、モデル側での取り込みには、MCP の外部で発行された一度限りの HMAC レシートも必要です。
• 適格性ゲートは、引用された証拠の完全性を検証します。また、重要な主張で、セッションが取得し完全性の検証に失敗した証拠が黙って省略されている場合は、フェイルクローズで処理します。

これらの説明はすべて、具体的なファイルと行によって裏付けられています。docs/architecture-deep-dive.mdでは、目標、台帳、RAG の構築、RAG↔MCP の連携、各制御メカニズムを、コードの引用とともに順を追って解説しています。意図的に強制していない境界についても、ドキュメント文字列でその旨を明示しています。

ベンチマーク — 測定内容、測定方法、各結果が裏付ける範囲

以下の各研究は、実行前に事前登録されました（プロトコルと分析コードを先にコミットし、変更点は影響する実行の前にプロトコルで開示）。独立した決定論的スコアラーで評価し、条件を伏せた LLM 評価者との照合も行いました（評価者の妥当性：独立した 2 名の評価者は互いに κ = 1.000、50 件のブラインドサンプルにおける評価者との一致度は κ = 0.865）。報告は集計値のみに限定しています。統計手法（Wilson/Newcombe の信頼区間、mid-p McNemar 検定、rule-of-three）は、引用マニフェストにある出典論文からの、ハッシュ検証済みの逐語引用に基づいています。

1 · ゲートは安全でない断定を防げますか？ — 呼び出された場合、ゼロにできます

設定。 2組のペア実行を行いました。1つは合成データ、もう1つは実データです。合成データ：24個のタスク × 2つの条件 × 3回の反復（144回の実行）。各タスクでは、整合性障害を注入したコーパスに、正しい値と改変した値を1つずつ仕込みました（インデックス作成後の変更、行ずれ、古いインデックス、撤回・欠落・未登録のエビデンス、競合、さらにネガティブコントロール）。実データ：実際の8か月間にわたる研究プロジェクトの台帳を対象に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によってエージェントが安全になる」とまでは言えません。ベンチマーク4を参照してください。

2 · どのようなコストがかかりますか？ — ブロックではなく、検索の手間です

設定。 同じペア実行について、回答可能なタスクでの誤ブロック、キャッシュされないトークン数、エビデンスの紐付けの妥当性という副次評価項目を調べました。 結果。 実コーパスでの誤ブロックは9/54件でした。この9件はすべて、ソース参照を伴わずに記録されたレガシーイベントに起因していました（制約となっているのはエビデンスチェーンの品質であり、ゲートではありません）。トークン数はファイルシステム条件の約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 つの指示文 ＋ 登録時のハッシュマニフェスト）です。 この設定の理由。 ベンチマーク 1 の 0/45 は、モデルにワークフローを 使うよう指示するオペレーターのプロンプトのもとで測定されました。レビュー担当者の 「ゲートが呼び出されなければ、保護はありません」という疑問に答えるには、 ツール使用の認識に関する文献に基づき、アクティベーション自体を測定する必要がありました。 結果。 自然条件では、72/72 回すべてで MCP 呼び出しが一度もありませんでした （30 個のツールすべてが利用可能であることを検証済み）。unsafe は 24/45 で、 ファイルシステム条件と同一でした（RD は正確に 0.000）。マニフェストの ベースラインで修正できたのはハッシュで検出可能な障害のみ（10/45）で、 意味的な問題はすべて見逃しました。 この結果から示されること。 実効的な保護 ＝ アクティベーション × エンフォースメントであり、プロンプトによる指示のないアクティベーションは 0％です。エージェントのメモリツールに関する安全性の主張は、すべて アクティベーションを条件として提示しなければなりません。 これは論文の 中心的な誠実な知見であり、欠陥の開示ではありません。

5 · デプロイ可能な成果物でアクティベーションを回復できるでしょうか？ — ポリシーなら可能、スキーマでは不可能です

設定。 事前登録済みの改訂実験として、さらに 216 回実施しました。 リポジトリの AGENTS.md ポリシーファイル（ワークフローの義務化 ＋ セッションスコープの事前承認）、製品側だけでの対策（2 つのツール説明文に アクティベーショントリガーを追加）、およびフィクスチャの汚染を開示した後の 自然条件のクリーンな再実行を検証しました。 結果。 ツール説明文のトリガーでは、アクティベーションは 0/45 で、 効果のない対策でした。AGENTS.md では、アクティベーションが 42/45 （93％） に回復し、unsafe は 12/45 と半減しました。しかし、12 件すべてに 適格な レシートがありました。そのうち 9 件では、モデルが障害のあるソースを取得し、 不一致を確認したうえで、それを黙って除外し、完全性が保たれた証拠だけを引用しました。 この結果から示されること。 リポジトリのポリシーファイル 1 つで採用を 回復できますが、ツールスキーマだけではできません。また、3 つ目の保護レイヤー ——引用規律——が存在します。ゲートが判定できるのは、与えられた引用セットだけだからです。

6 · 引用規律の徹底 — 情報よりもエンフォースメントが有効です

設定。 さらに 2 段階の事前登録済み実験（各 72 回）を実施しました。v1.2： サーバーがセッション中の取得内容を記録し、レシートで、取得されたものの引用されて いない不一致の証拠を開示し、回答を控えるか、問題に対処するよう指示します。v1.3： 同じ検出機能に加え、重要なクレームが有効な場合はフェイルクローズ （OMITTED-MISMATCHED-EVIDENCE）とし、不一致の参照先を引用するとブロックが解除されます。 結果。 開示は完全な精度で作動しました（障害あり 13/45、クリーン 0/21、 ネガティブコントロール 0/6）が、13 件中 9 件で覆されました。これは 事前登録済みの判定ルールによって反証されました。エンフォースメントでは、 unsafe は 4/45（基準の ≤ 4 を達成）、ブロックが作動したケースでは unsafe は 0/12、誤ブロックはゼロ、クリーン条件は 21/21 でした。残る 4 件は、 完全性ゲートが判定対象外と文書化している、ハッシュは完全でも意味的に問題のある 状態（撤回済み、無関係）です。 この結果から示されること。 測定された順序——情報 ＜ 指示 ＜ エンフォースメント——は、検証したすべてのレイヤーで一貫していました。 エンフォースメントはこのパッケージに含まれており、インストール済みビルドで 実環境検証済みです。 ガバナンス／取り込み面の敵対的監査では、敵対的な入力 25/25 がすべてフェイルクローズしました （監査）。

この結果から主張できないこと

1 つのモデルファミリーと 1 つの実際のコーパスを超えた一般化。 ハッシュが一致していても発生する障害（撤回済み、古いが有効、 無関係な証拠への対策。すべての条件群を無効化できることを測定済み）。 登録前に発生する破損に関すること（設計上、両方の条件群で 6/6 が失敗）。 マルチエージェントのガバナンス契約下でのエージェントの振る舞い （直接的な敵対的入力に対して、制御機構はフェイルクローズしますが、 モデルを介したガバナンスベンチマークはまだありません）。

はじめに — 2 つのコマンドで検証済みのリサーチメモリを作成

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"]

エージェントが実行すべき証拠のループ

このセクションの執筆前に、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 をプロジェクトに追加してください。この 1 つのファイルにより、 ゲートの有効化率は 0% から 93% に上がりました （詳細）。

引用

リリースをまたいでソフトウェアを引用する際は、コンセプト DOI 10.5281/zenodo.22118223を 使用してください。この DOI は常に最新のアーカイブ済みリリースを参照し、 各 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