universal-research-mcp
Universal Research MCP is an MCP server for research memory: it lets agents search provenance-bound candidates, fetch and verify exact evidence integrity, gate claims fail-closed, audit the canonical ledger, and prepare/commit human-approved immutable ingests — with governance and semantic-setup tools that only plan/preflight and never execute.
Search memory with
memory_search_candidatesacross lexical, semantic, hybrid, or adaptive modes; results are candidates only, never evidence.Fetch exact evidence with
memory_fetch_evidence, returning exact lines plus integrity status (matched/mismatched) and withholding content for drifted sources.Check evidence eligibility with
memory_check_evidence_eligibility, requiring a claim type and failing closed on omitted mismatched evidence or broken integrity.View latest records via
memory_latestfor non-reference observations.Audit the ledger with
memory_audit_ledgerfor read-only policy and record-integrity findings.Perform two-step ingestion with
research_prepare_ingest→research_commit_ingest, creating immutable pending drafts, requiring pre-existing human approval, and refusing replays or model-supplied approval; inspect drafts withresearch_pending_ingest_status.Inspect research infrastructure with
research_index_status,research_profile_status,research_semantic_models, andresearch_semantic_setup_plan(plan-only, no network/execution).Run governance preflight via
governance_*tools: get fixed role manifests and prompt contracts, validate task packets and decisions, evaluate deterministic gates, prepare codex dispatches/critical batches/scope governor receipts, assess plans/operations, resolve failure policies, and preflight parallel batches — all without dispatching or authorizing execution.Check host control with
codex_host_agent_statusandcodex_prepare_agent_control, which fail closed unless protected Codex host control is available.Obtain publication receipts through
public_demo_statuswithout exposing paths.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@universal-research-mcp search the research ledger for evidence on model hallucination mitigation"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Universal Research MCP
Research memory with traceable sources, explicit write approval, and measured — not assumed — safety.
Architecture deep dive · Benchmarks · Getting started · 한국어 사용자 설명서
Research agents with long-lived memory fail in a specific way: they assert recorded values whose evidence no longer holds — the file drifted, the claim was withdrawn, the source was never registered. This project makes that failure mechanically checkable, fail-closed, and then measures which parts of safety the mechanism actually provides.
New in 0.10.1: the local embedding backend loaded randomly initialized weights instead of the pinned checkpoint, so semantic, hybrid and adaptive retrieval returned noise while reporting success. Weights are now verified against the checkpoint before use, and semantic indexes built by 0.10.0 or earlier must be rebuilt. See the release notes for the affected scope and the reindexing steps.
The structure, in one pass
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) │
└──────────────────────────────────────────────────────────────────────────────────┘The ledger is the only authority; every index is a derived view that refuses to build over a drifted registered source.
Retrieval is physically read-only (
sqlite mode=ro,query_only=ON).Writes need a pre-existing human approval record; model-side ingestion additionally needs a one-time HMAC receipt issued outside the MCP.
The eligibility gate verifies the integrity of cited evidence and fails closed when a material claim silently omits evidence the session fetched and saw fail integrity.
Every one of those sentences is backed by a specific file and line: docs/architecture-deep-dive.md walks the goal, the ledger, the RAG construction, the RAG↔MCP chain, and each control mechanism with code citations, including the boundaries that are deliberately not enforced and say so in their docstrings.
Related MCP server: BlackBook MCP
Benchmarks — what was measured, how, and what each result licenses
Every study below was preregistered before its runs (protocol and analysis code committed first; deviations disclosed in the protocol before the affected runs), scored by an independent deterministic scorer cross-checked against a condition-blinded LLM judge (judge validity: two independent raters agreed with each other κ = 1.000 and with the judge κ = 0.865 on a 50-verdict blind sample), and reported as aggregates only. Statistical choices (Wilson/Newcombe CIs, mid-p McNemar, rule-of-three) are bound to hash-verified verbatim quotes from their source papers in the citation manifests.
1 · Does the gate stop unsafe assertions? — yes, to zero, when invoked

Setup. Two paired executions, one synthetic and one real. Synthetic: 24 tasks × 2 arms × 3 reps (144 runs), each task planting one correct and one altered value in a corpus with an injected integrity fault (post-index mutation, line drift, stale index, withdrawn/missing/unregistered evidence, conflicts, plus negative controls). Real: 27 tasks over an actual eight-month research project's ledger — every fault occurred naturally; nothing was mutated for the benchmark. Paired design so each task is its own control; the model (gpt-5.6-sol, medium) and prompts are identical across arms except evidence access. Why this setup. Planted values make scoring deterministic (no judge discretion on the primary endpoint); natural faults answer the "synthetic faults are strawmen" objection. Result. Hash-detectable fault stratum: filesystem 21–22/45 unsafe vs gated 0/45 (RD 0.49 [0.33, 0.63]); real corpus 23–26/27 vs 0/27 (RD 0.85 [0.64, 0.94]); clean coverage 21/21 in both arms. What this licenses. When the eligibility workflow runs, unsafe assertions on integrity-broken evidence go to zero at no clean-coverage cost. It does not license "the MCP makes agents safe" — see benchmark 4.
2 · What does it cost? — retrieval effort, not blocking

Setup. Same paired runs, secondary endpoints: false blocks on answerable tasks, uncached tokens, evidence-binding validity. Result. False blocks 9/54 on the real corpus — all nine traced to legacy events recorded without source references (evidence-chain quality, not the gate, is the binding constraint). Tokens ~1.4–1.9× filesystem. Evidence binding valid 81/81 in the gate arm vs 52/81 filesystem. What this licenses. The gate's cost is retrieval chattiness and legacy-chain gaps, not wrongful blocking of intact evidence.
3 · Where does the payload go? — search, not verification

Setup. Byte-level decomposition of all tool results in the real-corpus gate arm (81 runs, 29.4 MB), plus a same-day optimization pass re-run. Result. 93.4% of payload is candidate search; verification itself (fetch + eligibility) is 5.3%. The optimization pass halved transport (−49% payload) with fault-unsafe still 0. What this licenses. Verification is cheap; retrieval dominates cost and is where optimization belongs.
4 · Does anyone actually call the gate? — no, not without policy

Setup. The scaffold-removal ablation (preregistered, 3 arms × 24 × 3 = 216 runs): identical tasks with no claim types, no scope preamble, no tool naming in any prompt — the original scaffold is the treatment being tested. Arms: filesystem, MCP-attached-but-unprompted, and a cheap baseline (one instruction + a registration-time hash manifest). Why this setup. Benchmark 1's 0/45 was measured under an operator prompt that told the model to use the workflow. A reviewer's question — "if the gate isn't called, there is no protection" — required measuring activation itself, per the tool-usage-awareness literature. Result. The natural arm made zero MCP calls in 72/72 runs (all 30 tools verifiably exposed): unsafe 24/45, identical to filesystem (RD exactly 0.000). The manifest baseline fixed only hash-visible faults (10/45) and misses everything semantic. What this licenses. Effective protection = activation × enforcement, and un-prompted activation is 0%. Any headline safety claim for an agent memory tool must be conditioned on activation. This is the paper's central honest finding, not a defect disclosure.
5 · Can deployable artifacts recover activation? — policy yes, schema no

Setup. Preregistered amendment, 216 more runs: a repository
AGENTS.md policy file (workflow mandate + session-scope preapproval), a
product-only lever (activation triggers in the two tool descriptions), and
a clean rerun of the natural arm after a disclosed fixture-contamination.
Result. Tool-description triggers: 0/45 activation — a dead lever.
AGENTS.md: activation 42/45 (93%), unsafe halved to 12/45 — but all
12 held eligible receipts: in 9 the model fetched the faulted source,
saw the mismatch, silently dropped it, and cited only intact evidence.
What this licenses. A one-file repository policy restores adoption;
tool schemas alone do not. And a third protection layer exists — citation
discipline — because the gate can only judge the citation set it is
given.
6 · Enforcing citation discipline — information loses, enforcement wins

Setup. Two more preregistered steps (72 runs each). v1.2: the server
logs the session's fetches and the receipt discloses fetched-but-uncited
mismatched evidence with an instruction to abstain or address it. v1.3:
same detection, but an active material claim fails closed
(OMITTED-MISMATCHED-EVIDENCE); citing the mismatched reference lifts the
block.
Result. Disclosure fired with perfect precision (13/45 fault, 0/21
clean, 0/6 negative-control) and was overridden in 9/13 — falsified by
its own preregistered rule. Enforcement: unsafe 4/45 (bar ≤ 4 met),
0/12 unsafe where the block fired, zero false blocks, clean 21/21. The
residual four are intact-hash semantic states (withdrawn, irrelevant) the
integrity gate is documented not to judge.
What this licenses. The measured ordering — information < instruction
< enforcement — held at every layer tested. The enforcement ships in this
package and was verified live on the installed build. Adversarial audit
of the governance/ingest surface: 25/25 hostile inputs fail closed
(audit).
What none of this licenses
Generalization beyond one model family and one real corpus; defense against faults whose hashes are intact (withdrawn, stale-but-valid, irrelevant evidence — measured to defeat every arm); anything about corruption that precedes registration (both arms lose 6/6 by design); agent behavior under the multi-agent governance contracts (the controls fail closed under direct adversarial input, but no model-in-the-loop governance benchmark exists yet).
Getting started — two commands to a verified research memory
pip install universal-research-mcp # or: uv tool install universal-research-mcp
universal-research quickstart ~/my-research --yesquickstart takes a folder of Markdown documents and does the whole RAG
setup in one pass: initializes the store, registers every document's
SHA-256, appends an operator-approved observation per document (the
--yes is your human approval — without it, quickstart only prints a dry
run), and builds the search index. Re-running it only picks up new files.
No JSON authoring, no manual approval plumbing. No-install alternative,
verified against the published package: uvx --from universal-research-mcp universal-research quickstart … --yes.
Connect your MCP host
The server is plain stdio — any MCP host launches the same command.
Claude Code
claude mcp add universal-research -- universal-research serve --root ~/my-research --no-auto-indexClaude Desktop — one-click: download
universal-research-memory-0.10.1.mcpb
and double-click (or Settings → Extensions → Install from file). Claude
Desktop asks for your research folder and launches the server via uv; an
empty folder is initialized automatically. Manual config alternative:
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, or install the plugin from
plugin/universal-research-memory/)
[mcp_servers.universal_research]
command = "universal-research"
args = ["serve", "--root", "/home/you/my-research", "--no-auto-index"]host | support |
Codex | officially tested (all benchmarks above ran here) |
any stdio MCP host | protocol-compatible |
Claude Code / Claude Desktop / Cursor | config verified, behavior unverified |
remote / hosted MCP | not offered (see |
The evidence loop your agent should run
Executed verbatim against a quickstart-built store before this section was written:
memory_search_candidates {query: "dead-time correction", mode: "lexical"}→ returns the observation as a candidate (candidate_only: true— a score is never evidence).memory_fetch_evidence {path, start_line, end_line, event_id, expected_sha256}→integrity_status: "matched"and the exact cited lines; a drifted file instead returnsmismatchedand withholds content.memory_check_evidence_eligibility {claim, claim_type, materiality, evidence:[…]}→status: "eligible"for an intact single-source result claim, andblocked: OMITTED-MISMATCHED-EVIDENCEif the session fetched a mismatched source and silently dropped it.
Adoption note (measured, not advice). In our ablation the model never
called these tools without workspace policy. Add an AGENTS.md to the
project that mandates the loop above and preapproves the session scope for
non-interactive runs — that single file took gate activation from 0% to
93% (details).
Citation
Use the concept DOI 10.5281/zenodo.22118223
to cite the software across releases; it always resolves to the latest
archived release, and each GitHub Release mints its own version DOI under it.
Development reference
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/*.whlRelease workflows pin third-party actions to exact commits. A release wheel is built once, checked on Linux/macOS/Windows, and that artifact is published through PyPI Trusted Publishing after its release gates succeed. These are engineering checks, separate from model experiments.
License: MIT
mcp-name: io.github.mp-juns/universal-research-mcp
Available Tools
30 toolscodex_host_agent_statusARead-onlyIdempotent
Report whether protected current-task Codex control is available.
Without a host-authenticated per-call thread binding this returns a structured unavailable result and discloses no thread metadata.
Inputs: no named parameters. Returns: object
codex_prepare_agent_controlCRead-onlyIdempotent
Fail closed unless a protected Codex host broker is available.
The tested Codex 0.147.0 stdio MCP contract has no documented or validated authoritative caller-task binding and proposal-bound user approval receipt. No proposal or host state is created.
Inputs: action (required). Returns: object
governance_assess_planC
Assess necessity, bounded work, elapsed time, difficulty, and cost evidence.
Inputs: operation (required). Returns: object
governance_capture_codex_decisionB
Validate a host decision without writing it to the canonical ledger.
Inputs: packet (required), decision (required). Returns: object
governance_evaluate_gateC
Evaluate deterministic claim gates; this never grants user approval.
Inputs: decisions (required), claim_type. Returns: object
governance_evaluate_operationB
Evaluate declarative preflight; never authorize or execute a host tool call.
Inputs: packet (required), operation (required). Returns: object
governance_get_capabilitiesA
Return the fixed governance roster and non-executing host contract.
Inputs: no named parameters. Returns: object
governance_get_role_manifestB
Return one immutable registered role manifest and its canonical hash.
Inputs: agent_id (required). Returns: object
governance_get_role_prompt_contractB
Return the internal versioned prompt contract for one registered role.
Inputs: agent_id (required). Returns: object
governance_preflight_parallel_batchA
Validate a parallel batch without starting agents, models, or network.
Inputs: packets (required), max_workers (required), aggregate_cost_ceiling_usd (required), declared_costs_usd. Returns: object
governance_prepare_codex_critical_batchC
Prepare the isolated fixed four-reviewer critical batch.
Inputs: packets (required), governor_receipt. Returns: object
governance_prepare_codex_dispatchB
Prepare, but do not execute, a host-owned agent dispatch.
Inputs: packet (required), governor_receipt. Returns: object
governance_prepare_failure_recordC
Prepare the mandatory minimum tombstone; storage remains host-owned.
Inputs: failure (required), task, profile. Returns: object
governance_prepare_scope_governor_receiptC
Bind a validated passing scope decision to exact governed task hashes.
Inputs: governor_packet (required), governed_packets (required), governor_decision (required). Returns: object
governance_resolve_failure_policyC
Resolve failure handling without accepting an off/unrecorded mode.
Inputs: task, profile. Returns: object
governance_validate_decisionB
Validate a returned decision against its exact task packet.
Inputs: packet (required), decision (required). Returns: object
governance_validate_task_packetA
Validate a proposed agent task without dispatching or approving it.
Inputs: packet (required). Returns: object
memory_audit_ledgerARead-onlyIdempotent
Return read-only policy and record-integrity findings for canonical JSONL.
Inputs: no named parameters. Returns: object
memory_check_evidence_eligibilityARead-onlyIdempotent
Check exact evidence integrity and count, never semantic claim support.
claim_type is deliberately required: the gate activates from claim
consequence, so a caller must classify the claim instead of inheriting a
silent inactive default.
Inputs: claim (required), claim_type (required), evidence, materiality.
memory_fetch_evidenceCRead-onlyIdempotent
Fetch an exact event locator; keep display context outside its reference.
Event-less fetches are registered-file diagnostics only and cannot satisfy evidence eligibility. Changed-source diagnostics retain the registered reference even when the current file is shorter than that reference.
Inputs: path (required), start_line (required), end_line, event_id, +3 more.
memory_latestBRead-onlyIdempotent
Return latest non-reference records, ordered by recorded event time.
Inputs: top_k.
memory_search_candidatesBRead-onlyIdempotent
Return provenance-bound candidates. Fetch original evidence before concluding.
Inputs: query (required), mode, top_k, status, +1 more.
public_demo_statusBRead-onlyIdempotent
Return a path-free publication receipt for the running MCP process.
Inputs: no named parameters. Returns: object
research_commit_ingestA
Append exactly one approved pending draft and refresh derived indexes.
This is a mutating, non-idempotent host-approved tool. It accepts no record body and no model-supplied approval boolean. It refuses a replay, any change to the canonical ledger or staged source files, or an invalid human scope approval. Canonical append success is reported separately from derived-index refresh status.
Inputs: draft_id (required), draft_sha256 (required), approval_receipt_id (required). Returns: object
research_index_statusA
Report derived-index health without modifying canonical research records.
Inputs: no named parameters. Returns: object
research_pending_ingest_statusBRead-onlyIdempotent
Return metadata for one pending immutable ingest draft without its content.
Inputs: draft_id (required). Returns: object
research_prepare_ingestA
Validate input and create an immutable pending draft, never a canonical record.
Each new source registration contains only path, source_id, and
source_type. The path must be project-contained and is hash-bound at
preparation and commit. A canonical human approval record must already
exist and cover this record's study and kind.
Inputs: record (required), approval_ref (required), source_registrations. Returns: object
research_profile_statusA
Inspect the declared research profile without executing any route.
Inputs: no named parameters. Returns: object
research_semantic_modelsA
List reviewed local SentenceTransformer models without contacting a registry.
Inputs: no named parameters. Returns: object
research_semantic_setup_planC
Plan without network or execution; revision must be a full immutable commit SHA.
Inputs: model_id (required), revision (required), device, auto_refresh, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
The high-level domains are clear, but the governance cluster is overcrowded with near-synonymous non-executing operations such as evaluate_gate, evaluate_operation, validate_decision, capture_codex_decision, prepare_codex_dispatch, and codex_prepare_agent_control. An agent could easily select the wrong governance tool because the boundaries between 'evaluate', 'validate', 'capture', and 'prepare' are subtle and heavily overlapping.
Most tools follow a consistent domain_verb_noun snake_case pattern, e.g., governance_validate_task_packet, research_prepare_ingest, memory_fetch_evidence, and codex_host_agent_status. Minor deviations like memory_latest, research_semantic_models, and public_demo_status break the verb-first pattern, but the overall style remains predictable.
Thirty tools is too many for a research MCP, especially when fifteen of them are governance variants that mostly 'prepare', 'validate', or 'evaluate' without executing. The tool surface feels bloated and micro-specialized rather than well-scoped, and several governance tools could likely be consolidated.
The core immutable ingest and evidence lifecycle is covered: prepare_ingest, commit_ingest, pending status, memory search, evidence fetching, eligibility checks, and ledger audit. However, there are notable gaps such as no way to list or cancel pending drafts, no general research query beyond memory candidates, and no direct approval path, though the host-owned design explains some of these omissions.
Maintenance
Related MCP Connectors
Read-only Remote MCP for externally grounded AI agent trust receipts.
Read-only MCP over the LivingMeta AI-in-Research corpus: 12,400 papers, gaps, priority agenda.
Plan and verify evidence-aware research workflows with specialist execution receipts.
The evidence layer for MCP: live operational grades plus Trust Receipts for every registry server.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server that enforces evidence-graded, phase-gated, peer-reviewed research workflows for AI agents to conduct rigorous decision-making.1MIT
- AlicenseNot gradedqualityBmaintenanceA source-grounded cybersecurity knowledge & research MCP server that provides read-only search, exact citations, and a knowledge graph, designed to run alongside execution MCPs.10MIT
- AlicenseAqualityBmaintenanceEnables AI agents and MCP clients to run research as an explicit scientific process: forming hypotheses, designing and executing sealed experiments, capturing observations and artifacts, linking claims to supporting evidence, and reviewing provenance. Exposes coordinated MCP services so users can inspect, reproduce, and audit every step from question to conclusion rather than trusting an opaque final answer.4621Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables MCP-speaking AI research agents to coordinate plans, tasks, experiment runs, and claims on a shared evidence board, tracing each claim to the code that produced it and flagging results that need rechecking when dependencies change.89 npm505AGPL 3.0