Dana Edwards
Back to home

Case study

Research Kernel MCP: Keeping track of the research

I built Research Kernel MCP to keep questions, evidence, and failed approaches connected across research sessions. Models suggest ideas. The kernel enforces explicit requirements before a claim can be marked supported; an attached check or experiment supplies the evidence for the claim.

Summary

Research Kernel MCP stores claims, evidence records, refutation attempts, and alternative formulations as typed records in a persistent graph. I can query those records and resume an investigation in a later session. The kernel checks the requirements for claim promotion and keeps an append-only history of changes.

Research Kernel control boundary: a model proposes atoms, a deterministic kernel gates promotion, and only supported claims survive. Untrusted model claims · evidence · reformulations Deterministic kernel promotion gate evidence + refutation + provenance required Supported claim fail-closed · replayable proposes promoted Rejected: fail closed no evidence · no refutation · no provenance
The control boundary: the model proposes atoms, the kernel gates promotion, and only claims that pass evidence, refutation, provenance, and contradiction checks become supported. Missing evidence, missing refutation attempts, or missing provenance fail closed.
Research Kernel stores claims as structured records. Before marking a claim supported, it checks for evidence, a refutation attempt, and provenance. This makes the requirements for accepting a research record explicit.

Start here

  1. README.md - design specification, available tools, and scope.
  2. internal/research_kernel_mcp/kernel.py - the deterministic kernel: atom types, statuses, edge types, promotion gate, and SQLite persistence.
  3. internal/research_kernel_mcp/server.py - the tools, resources, and prompts available through MCP.
  4. tests/internal/test_research_kernel_mcp.py - the test suite covering start, atom add, link, retrieve, morph, refute, evidence, score, frontier, promote, and report.
  5. pytest.ini - focused test configuration.

A 10-minute review

Read the README, then open kernel.py and inspect ATOM_TYPES, STATUSES, EDGE_TYPES, and the promotion gate logic. Finally, run the self-test: .venv/bin/python internal/research_kernel_mcp/server.py --self-test.

Claims and evidence

ClaimEvidence to showStatus
Claim promotion is fail-closed: a claim cannot become SUPPORTED without support evidence, a refutation attempt, dependencies, provenance, and a rationale. The rk_promote tool and the promotion gate in kernel.py; the test that confirms promotion fails when evidence is missing. Supported / bounded
Every state-changing operation is appended to an event log for replay and external ledger ingestion. The events.jsonl append path in kernel.py; the test that confirms events are recorded. Supported / bounded
Artifacts are content-addressed by SHA-256 and restricted to allowlisted paths unless explicitly overridden. The artifact storage logic in kernel.py; the RK_ARTIFACT_ALLOWLIST and RK_ALLOW_OUTSIDE_ARTIFACTS behavior. Supported / bounded
Actual counterexamples create a COUNTEREXAMPLE atom, add a REFUTES edge, and mark the target REFUTED. The rk_refute tool with counterexample_is_actual=true; the corresponding test. Supported / bounded
The kernel is a complete research automation system ready for production deployment. Would require deployment hardening, load testing, multi-user isolation, and external review. Not claimed

What this does and doesn't establish

  • SUPPORTED means the local gate passed. Publication and deployment still require the relevant replay, review, and release checks.
  • Reformulations are suggestions for further investigation. Each needs its own tests.
  • The kernel stores research artifacts, evidence, and graph state. Hidden chain-of-thought stays outside the artifact store by design.
  • SQLite persistence is durable for single-user and small-team use; multi-tenant deployment would need a different storage backend.

Open Research Kernel MCP on GitHub