Skip to main content
Glama

GnosisLab

A scientific-method runtime for AI agents

Turn hypotheses into experiments, experiments into evidence, and evidence into auditable conclusions.

DOI SSRN CI PyPI Python License piwheel downloads PyPI downloads PyPI Downloads GnosisLab-VM for Linux GnosisLab-VM for Windows GnosisLab-VM for macOS Discord

VM edition available: GnosisLab-VM provides an optional isolated KVM/libvirt environment for GnosisLab research workflows.

Install · Documentation · How it works · Architecture · For researchers · For developers · Paper · Discord


What is GnosisLab?

Most AI agents are optimized to produce an answer.

GnosisLab is built to help an agent produce a defensible result.

It turns the scientific process into explicit software objects:

hypothesis → experiment → observation → evidence → claim → conclusion

Instead of leaving an agent's reasoning, experiments, and evidence scattered across prompts, shell history, notebooks, logs, and temporary files, GnosisLab gives the process a structured runtime.

Experiments are represented explicitly. Evidence is retained. Claims can be connected to their support. Execution is observable. State is separated by responsibility. The resulting research process can be inspected by a human rather than accepted as an opaque final answer.

GnosisLab is intended for machine-learning experimentation, computational research, autonomous research agents, evaluation systems, and other workflows where how a result was obtained matters as much as the result itself.


Related MCP server: Researcher AI

Why this exists

LLMs can generate code, search literature, run analyses, compare alternatives, and propose conclusions.

That creates a new problem:

How do we know what actually happened?

A useful research system needs more than tool access. It needs a disciplined process around tool use:

  • What hypothesis was being tested?

  • Which experiment addressed it?

  • What code actually ran?

  • What observations were produced?

  • Which evidence supports which claim?

  • Which conclusions remain uncertain?

  • What changed between one iteration and the next?

  • Can a human inspect the path from question to result?

GnosisLab makes those questions part of the system itself.


Quick start

Install from PyPI

uv tool install gnosislab

or:

pip install gnosislab

Full setup example

Register the five servers with your MCP client, then start the stack:

# see which clients are supported, preview without writing
gnosislab setup --list
gnosislab setup claude-code --dry-run    # or opencode, vscodium, vscode,
                                         # windsurf, cursor

# merge the server entries into the client's MCP config
gnosislab setup claude-code

# background all five servers (upstreams first)
gnosislab start all

# pid/ports/health per server
gnosislab status

# resolved ports + config file path
gnosislab config

# tail one server's log
gnosislab logs episteme

# open the lab status dashboard in your browser (agora by default)
gnosislab dashboard            # → ML_AGORA_GUI_URL (default http://localhost:28051)
gnosislab dashboard episteme   # any server's GUI works too

# stop everything (consumers first)
gnosislab stop all

Ports resolve as: built-in defaults < ~/.config/gnosislab/ports.env < environment variables — same KEY=VALUE format as the repo's ports.env. Runtime state always lives in ~/.ml-<name>/, regardless of install method. The dashboard URL comes from the resolved ML_<NAME>_GUI_URL, so remote/VM setups can point it at a reachable host without editing scripts.

Full documentation: https://loop.cloudcell.workers.dev/docs

Install from source

git clone https://github.com/cloudcell/gnosislab.git
cd gnosislab
uv sync
./gnosislab start all

Sealed trial execution needs Linux tooling. The executor isolates trials with bubblewrap mount namespaces and traces reads with strace. Neither exists on Windows (or macOS) — there is no bwrap package to install. With the default sandbox = "auto", trials on those platforms fail closed rather than silently running unsealed. To run trials without isolation, opt out explicitly in ~/.ml-episteme/config.toml:

[executor]
sandbox = "none"

(equivalently, ML_EPISTEME_SANDBOX=none). If you also configure [executor] sealed_path_patterns, add sealed_enforcement = "audit" — deny needs a mount namespace to arm. Coding agents often offer to "disable sandboxing" when they hit this error; the knob they should set is sandbox, shown above.

On Debian/Ubuntu the full experience is:

sudo apt install bubblewrap strace

The idea in one picture

flowchart LR
    Q["Research question"] --> H["Hypothesis"]
    H --> Z["Zetesis<br/>search & evidence discovery"]
    Z --> E["Episteme<br/>experiment & observation"]
    E --> X["Sealed execution"]
    X --> O["Artifacts & observations"]
    O --> A["Anamnesis<br/>claims, evidence & memory"]
    A --> C["Conclusion"]
    C --> R["Arete<br/>adaptation & improvement"]
    R --> H

    G["Agora<br/>coordination & lab-level view"] -.-> Z
    G -.-> E
    G -.-> A
    G -.-> R

The point is not the Greek names. The point is separation of scientific responsibilities.

Each subsystem owns a distinct part of the research process rather than collapsing everything into one agent loop and one unstructured memory.


How it works

GnosisLab is composed of five MCP services.

Service

Role

Think of it as

Episteme

experiments, trials, observations and experimental state

the laboratory notebook

Anamnesis

claims, evidence relationships and persistent research memory

the evidence graph

Zetesis

search, investigation campaigns and evidence discovery

the investigator

Arete

improvement, comparison and meta-level adaptation

the critic / improver

Agora

coordination and lab-level observability

the control room

The services deliberately keep their state boundaries separate. This makes ownership clearer, failures easier to isolate, schemas easier to evolve, and each subsystem independently inspectable.


Architecture

flowchart TB
    U["Human / AI agent / MCP client"]

    subgraph GL["GnosisLab"]
        AG["Agora<br/>coordination"]
        ZE["Zetesis<br/>search"]
        EP["Episteme<br/>experiments"]
        AN["Anamnesis<br/>claims + evidence"]
        AR["Arete<br/>improvement"]

        AG --> ZE
        AG --> EP
        AG --> AN
        AG --> AR

        ZE --> EP
        EP --> AN
        AN --> AR
        AR --> ZE
    end

    subgraph EX["Execution boundary"]
        SE["Sealed experiment executor"]
        ART["Code, logs, outputs,<br/>observations, artifacts"]
        SE --> ART
    end

    U --> AG
    U --> ZE
    U --> EP
    U --> AN
    U --> AR

    EP --> SE
    ART --> EP
    ART --> AN

Default service ports

Service

GUI

MCP

Agora

28051

28050

Arete

28061

28060

Zetesis

28071

28070

Episteme

28081

28080

Anamnesis

28091

28090

Defaults can be overridden with:

~/.config/gnosislab/ports.env

or the corresponding ML_* environment variables.

Runtime state lives outside the repository under:

~/.ml-<name>/

For researchers

GnosisLab is designed around a simple principle:

A scientific result should remain inspectable after the agent that produced it has moved on.

That means treating research state as durable data rather than transient conversation context.

Explicit experimental structure

Research can be represented in terms of programmes, trials, observations, evidence and claims rather than buried inside a chat transcript.

Provenance

The system is designed to retain the relationship between experimental actions, artifacts, observations, evidence and downstream claims.

Reproducibility

Experiment execution is separated from conversational reasoning. The aim is to preserve the material needed to understand and reproduce what was actually done.

Human review

GnosisLab is not built around the assumption that an autonomous agent should be trusted by default. Its structure is intended to make intermediate state visible enough for review, correction and override.

Uncertainty belongs in the record

A research system should distinguish a claim from the evidence supporting it and should avoid turning an agent's confidence into an unexplained magic number.


For developers

GnosisLab is infrastructure, not a monolithic chatbot.

MCP-native

The distribution exposes five MCP server entry points:

ml-episteme-mcp
ml-anamnesis-mcp
ml-zetesis-mcp
ml-arete-mcp
ml-agora-mcp

This means an MCP-capable agent or client can work with the scientific process as a set of tools rather than requiring a proprietary frontend.

One command for lifecycle management

gnosislab start all
gnosislab status
gnosislab logs arete
gnosislab stop all

Resident experiment supervisor: gnosislab daemon

Each state root gets its own daemon — a persistent supervisor that drives existing CLI agents against an independent verifier, and exposes a local console plus the same service-lifecycle and export powers as this CLI:

# one daemon per experiment state root
gnosislab daemon serve --state-dir ~/exp-a/.daemon --port 38100
gnosislab daemon start --agent opencode --task task.md \
    --check ./verify.sh --state-dir ~/exp-a/.daemon
gnosislab daemon status --state-dir ~/exp-a/.daemon
gnosislab daemon open   --state-dir ~/exp-a/.daemon   # local console

The daemon never trusts an agent's claim of completion: after every invocation it runs the checker (exit 0 = verified, 1 = continue, other = check error) and resumes the agent's session — or restarts it with saved context — until verification passes or a limit parks the loop as BLOCKED. Agent profiles are argv templates in ~/.config/gnosislab/daemon.toml; adding an agent is config, not code. See examples/daemon.toml and gnosislab daemon --help.

Two agent backends fill the same verified-loop contract (src/gnosislab_daemon/backends/):

  • exec (default): one CLI subprocess per turn; process exit is the turn boundary. Strongest isolation.

  • session: a persistent driver process per loop, controlled over a stdio JSONL protocol (send/status/cancel/fork/shutdown ops; ready/turn_end/session events). The driver owns all vendor details — any agentic IDE or a bare LLM endpoint works by writing one small adaptor. gnosislab_daemon/drivers/ ships the protocol conformance fixture (fake_session_driver.py) plus reference drivers for opencode and an OpenAI-compatible chat endpoint.

Isolated workspaces

gnosislab init <dir> scaffolds a self-contained experiment sandbox in one command: its own HOME (service databases, opencode sessions), its own service port sub-block and daemon console (registered in ~/.config/gnosislab/workspaces.json so workspaces can't collide), its own driver copies, and a runnable task + verdict checker. source <dir>/env puts a shell inside it — gnosislab start all, daemon serve, and the opencode TUI all resolve the sandbox stack.

The turn boundary is never a verdict: turn_end (or process exit) only ends the turn — the independent checker still decides. Structured checker diagnostics are supported via a GNOSISLAB_VERDICT JSON line (bounded, sanitized; contradictions fail closed as CHECK_ERROR), stagnation can trigger a single capability-gated session fork with recorded lineage, and a driver that dies mid-turn parks the loop BLOCKED with uncertain_turn rather than risking a silent duplicate dispatch.

Sealed experiment execution

Trial execution uses Linux isolation primitives so experiments can run inside a constrained boundary rather than directly in the agent's host environment.

Observable by design

Every service exposes a local observability GUI. You can inspect the system while it is operating instead of treating agent activity as an invisible background process.

Separate state ownership

The major research loops keep their own persistent stores. This avoids turning one shared database into an ambiguous write boundary and lets each service evolve independently.

Small dependency surface

The published package targets Python 3.10+ and keeps the core runtime dependency set focused around MCP, Pydantic and HTTPX.


A research loop, expressed as software

A conventional agent loop often looks roughly like this:

prompt → tool calls → more prompting → answer

GnosisLab makes the scientific structure explicit:

question
  ↓
hypothesis
  ↓
search / prior evidence
  ↓
experiment design
  ↓
sealed execution
  ↓
observations + artifacts
  ↓
evidence-linked claims
  ↓
conclusion
  ↓
critique / adaptation
  ↓
next hypothesis

That difference matters when the work is long-running, iterative, expensive, safety-sensitive, or intended to survive peer review.


What GnosisLab is not

GnosisLab is not:

  • a replacement for a capable language model;

  • a claim that autonomous agents can replace scientific judgment;

  • a generic vector-memory wrapper;

  • a single prompt that tells an LLM to "act like a scientist";

  • an opaque autonomous system that asks you to trust the final answer.

It is an attempt to make the process around AI-assisted research explicit, inspectable and programmable.


How GnosisLab compares

Against adjacent systems, including autonomous-research agents, agent frameworks, reproducibility tools, and experiment trackers, GnosisLab is distinguished not by any single capability but by their integration: scientific objects are represented as first-class state, methodological constraints are enforced at runtime, execution provenance is bound to the research record, and the stored record is reconciled against what actually executed.

Legend: ✓ = native or core capability; ◐ = partial, indirect, configurable, or implementation-dependent; — = not a core capability or not evidenced in the compared system.

The comparison is intended to distinguish architectural emphasis rather than overall system capability. Systems such as autoresearch, EvoScientist, and AutoGPT are primarily designed to increase autonomous task or experiment execution, whereas GnosisLab places greater emphasis on representing and verifying the scientific process itself.


Example use cases

Machine-learning research

An agent can propose an architecture change, execute a controlled trial, capture metrics and artifacts, attach evidence to the resulting claim, and use the result to choose the next experiment.

Reproducible benchmarking

Benchmark runs can be treated as experiments with explicit observations rather than as disconnected terminal commands and copied numbers.

Literature-to-experiment workflows

Search and evidence discovery can feed hypotheses and experimental design while keeping source evidence distinct from experimentally generated evidence.

Long-running autonomous investigation

The system can preserve research state across many agent turns without relying on a single ever-growing context window.

Human-supervised research agents

A researcher can inspect intermediate claims, evidence, trial outcomes and service state rather than reviewing only a final generated report.


Project layout

gnosislab/
├── src/                # gnosislab CLI + five ml_*_mcp packages
├── tests/              # test suite (pytest-xdist)
├── constants/          # grounded-constants registry + disclosure
├── diagnostics/        # diagnostics corpus
├── gnosislab           # lifecycle CLI entry point
├── labloop             # transition compatibility symlink
├── ml-*.toml           # per-server config
├── ports.env           # port assignments
├── pyproject.toml      # distribution metadata
├── LICENSE
├── NOTICE
└── README.md

The repository root is the runnable project:

uv sync

Configuration

Per-service configuration lives under:

ml-*.toml

Port configuration:

ports.env

User overrides:

~/.config/gnosislab/ports.env

Inspect the resolved configuration at any time:

gnosislab config

Observability

After startup, each service exposes a local GUI.

For example:

Agora      http://localhost:28051
Arete      http://localhost:28061
Zetesis    http://localhost:28071
Episteme   http://localhost:28081
Anamnesis  http://localhost:28091

Use:

gnosislab status

for process, port and health information.

Use:

gnosislab logs <service>

to inspect a service directly.


Testing

Run the full suite:

uv run pytest -q

The repository currently contains 1,289 tests.

For a serial run:

uv run pytest -n0

Development status

GnosisLab is alpha software.

The architecture is usable and the package is published, but interfaces, schemas and internal boundaries may continue to evolve.

If you are evaluating it for serious research, inspect the code, test the failure modes, and treat the current release as research infrastructure under active development.


Install and explore

uv tool install gnosislab
gnosislab start all
gnosislab status

Documentation: https://loop.cloudcell.workers.dev/docs

PyPI: https://pypi.org/project/gnosislab/

Repository: https://github.com/cloudcell/gnosislab


LabLoop — a secure lab environment for running GnosisLab against untrusted, agent-generated code. It builds a VM partitioned into driver, mcp and hostile zones: the services and their stores live in the trusted mcp zone, the driving agent in driver, and experiment code executes only in hostile, returning results as inert data through a token-gated ingest surface. It is the containment model described in the GnosisLab architecture, packaged as a runnable environment.


Contributing

GnosisLab is most useful when challenged by people who care about scientific rigor, agent engineering, reproducibility, provenance, evaluation and research infrastructure.

Useful contributions include:

  • adversarial testing of the scientific state machine;

  • new experiment and evidence workflows;

  • integrations with MCP clients and research agents;

  • reproducibility and provenance improvements;

  • better observability;

  • failure-mode documentation;

  • benchmark suites;

  • documentation and examples.

Open an issue with a concrete failure case, proposed experiment, or implementation idea.


Philosophy

AI makes it dramatically cheaper to generate hypotheses, code, analyses and prose.

It does not automatically make those outputs scientific.

The difficult part is preserving the chain between:

what was proposed → what was done → what was observed → what counts as evidence → what may reasonably be concluded

GnosisLab exists to make that chain a first-class object.


Paper

The GnosisLab design and the evidence-policy machinery are described in:

Bikeyev, A. (2026). GnosisLab: A Verifiable Foundation for Autonomous Scientific Discovery. SSRN. https://doi.org/10.2139/ssrn.7573878

@misc{bikeyev2026gnosislab,
  author = {Bikeyev, Alexander},
  title  = {GnosisLab: A Verifiable Foundation for Autonomous Scientific Discovery},
  year   = {2026},
  howpublished = {SSRN},
  doi    = {10.2139/ssrn.7573878},
}

License

Apache License 2.0. See LICENSE.


Stop collecting runs. Start running programmes.

pip install gnosislab

GnosisLab — hypothesis in, auditable conclusion out.

Available Tools

46 tools
abandon_hypothesisA

Abandon a hypothesis — attributed, rationaled, never erased.

The exit for a hypothesis that can never conclude: falsified premises, superseded questions, trials that can only fail. Abandoning is NOT a verdict — no conclusion is recorded and no claim is minted; the hypothesis simply leaves the loop as 'abandoned', stamped with who decided and why. Trials already recorded stay on the record.

Applies to proposed and under_test hypotheses; terminal states (accepted|rejected|inconclusive|abandoned) refuse. To abandon every hypothesis in a programme at once, use close_programme(status="abandoned").

Inputs: rationale (required), decided_by (required), programme_id (required), hypothesis_id (required). Returns: status, decided_by, from_status, hypothesis_id

acknowledge_violationA

Acknowledge an open integrity violation — insert-only.

The check log is append-only; this records the disposition (remediated | accepted-with-reason) against (check_name, object_ref) so the finding stops gating writes and leaves the digest's blockers. The underlying record is never touched — remediation itself is done by the corrective tools first.

Inputs: check_name (required), decided_by (required), object_ref (required), disposition (required). Returns: ack_id, status, open_violations, matched_open_violation

archive_pending_programmesA

Archive terminal programmes that are still in the live DB.

This is a migration tool for programmes that were closed (completed or abandoned) before the automatic archiver was implemented. It scans the live DB for terminal programmes not yet archived and archives them.

dry_run=true reports the scan result ({would_archive, would_mark_archived, skipped}) without writing anything.

Under normal operation, this is a no-op — close_programme already archives automatically. This tool only catches programmes that slipped through (e.g. abandoned before Phase 3 was deployed).

Returns: {archived: [...], errors: [...], skipped: int}

Inputs: dry_run (required). Returns: errors, dry_run, skipped, archived, +3 more

assess_programmeB

Assess programme health: progressive vs degenerating (commitment 8).

Reads observations from state.db and best_trials from the optimizer.

Inputs: programme_id (required). Returns: health, programme_id, total_trials, completed_trials, +4 more

cancel_trialA

Cancel a running trial, or abandon a designed one.

running → failed: kills the subprocess, marks failed. The record's failed here reflects the cancellation act, not an observed execution failure — cancelled: true in the payload marks the distinction, and an already finished executor reply means the executor completed first. A cancel landing before the task registers tombstones the id so no child can spawn under the terminal row. designed → abandoned: no executor to kill, no evidence lost — the honest terminal for a design that will never run (e.g. a bundle locked to code that no longer exists). The FSM has always permitted designed → abandoned; close_programme uses the same transition for programme-scoped sweeps.

Enforcement: commitment 1 — the loop is the unit (orphan check).

Inputs: trial_id (required), programme_id (required). Returns: status, trial_id, cancelled, executor_output

capture_bundleA

Seal the auxiliary bundle for a DESIGNED trial (commitment 6).

ORDERING: call AFTER design_experiment and BEFORE run_trial. The seal is pre-registration — the bundle fixes the auxiliary assumptions (code/env/seeds/splits) before any observation, so they cannot be retro-fitted to results. Trials that have left 'designed' are rejected. The post-run counterpart is executed_code.json — what actually ran, captured at finalization from the strace read-trace.

code_ref MUST be a path to a Python file that exposes: def run_training(config: dict) -> dict returning {"metrics": {...}, "variance": {...}}. The config is the same dict passed to design_experiment. Read the executor://contract resource for the full contract.

data_refs is an optional list of DataRef IDs (from prepare_data). When provided, the bundle records structured data provenance. When omitted, splits is used (backward-compatible).

extra_code_refs is an optional list of additional .py file paths that the trial depends on but cannot be discovered by AST import analysis — e.g. scripts invoked via subprocess.run(). These are captured into code_snippets and stored in code_hash_extra_json so the bundle is fully self-contained and rerunnable from archive (commitment 2 + 5 — the bundle must contain ALL code needed to reproduce, not just the executor).

Enforcement: commitment 1 — the loop is the unit (trial must exist). Enforcement: commitment 6 — the bundle must be controlled (code_ref validated). Concurrency: rejects if trial already has a bundle (no double capture).

Structured params (seeds, splits, data_refs, extra_code_refs) may be sent as JSON-encoded strings; seeds also accepts a bare int.

Inputs: seeds (required), splits (required), env_ref (required), code_ref (required), +4 more. Returns: status, code_ref, warnings, bundle_id, +2 more

capture_bundle_from_code_hashA

Capture a bundle using a content address (code_hash) instead of a file path.

This is the rerun-from-archive path: the LLM reads an archived programme, gets the code_hash from the bundle, and captures a new bundle for a new trial using the same code content. No filesystem access is required — the code is loaded from code_snippets by hash, materialized as a real file next to the execution wrapper, and imported at run_trial time.

NOTE: code_hash is a "sha256:..." content address returned by a prior capture_bundle — it is NOT a bundle_id. To re-use an existing bundle's code, pass its code_hash field.

The code_hash must already exist in code_snippets (captured by a prior capture_bundle or prepare_data call). If it doesn't, the tool returns an error.

The bundle's code_ref is set to "code://{code_hash}" — a content address, not a file path. This is the carrier/content separation (Rule 5.4) made explicit: the bundle references the ICE directly.

code_hash_extra is an optional list of additional content addresses for locally-imported or subprocess-dispatched modules captured alongside the primary. Each must already exist in code_snippets. At run_trial time, these are materialized as real files under a _deps/ dir on sys.path, reconstructing each file's path suffix — so from src.mod import x resolves through the real import machinery (commitment 2 + 5).

All other parameters are identical to capture_bundle.

Structured params (seeds, splits, data_refs, code_hash_extra) may be sent as JSON-encoded strings; seeds also accepts a bare int.

Returns: {"bundle_id": "bundle-...", "status": "captured", "code_hash": ...}

Inputs: seeds (required), splits (required), env_ref (required), trial_id (required), +4 more. Returns: status, code_ref, warnings, bundle_id, +2 more

capture_pending_artifactsA

Capture artifact files for trials that predate artifact capture.

Scans all trials with an artifact_path but no rows in trial_artifacts. Reads files from disk and stores them in SQLite (gzip-compressed). Files over 50MB are skipped and marked oversized. Files that no longer exist on disk are marked lost.

dry_run=true reports the pending trial ids without reading or storing anything.

cleanup: when True, staging files are deleted after successful capture (the SQLite copy becomes authoritative). Default False keeps the originals — conservative for migration of old trials.

Under normal operation this is a no-op — _finalize_trial already captures artifacts automatically. This tool only catches trials that slipped through (finalized before artifact capture was implemented).

Returns: {captured: [...], oversized: [...], lost: [...], trials_scanned: int, trials_with_existing: int}

Inputs: dry_run (required), cleanup. Returns: lost, captured, oversized, trials_scanned, +1 more

check_invariantsA

Audit the experiment store against the loop's invariants.

Returns {status: ok|violations, checks: [{name, ok, violations, detail}]}. Detection complement to write-time enforcement: orphaned running trials, completed trials lacking observations, unsealed executions, strace divergence, undigested input data, budget overruns, stuck hypotheses, stalled trials. Report-only — nothing is repaired or mutated. The run is logged to <db_dir>/logs/ (retention: [integrity] log_max_files).

Inputs: no named parameters. Returns: checks, server, status, trigger, +3 more

close_programmeA

Close a programme by setting its status to completed or abandoned.

For status="completed": rejects if any hypothesis is still under_test — the agent must call conclude_hypothesis first. Auto-marks proposed → abandoned (no effort was expended).

For status="abandoned": auto-marks all unconcluded hypotheses as abandoned (the whole programme is being abandoned).

Enforcement: state machine — rejects if programme is not active. Enforcement: commitment 1 — the loop is the unit (no closing with unconcluded hypotheses when completing).

Inputs: programme_id (required), status. Returns: status, archived, auto_marked, programme_id, +2 more

conclude_hypothesisA

Conclude a hypothesis by accepting/rejecting it.

Creates an immutable conclusion (commitment 8: programmes, not runs). When a claims role is wired, also mints a semantic claim with provenance edges — a byproduct, never a gate on the verdict. Enforcement: commitment 8 — rejects duplicate conclusions for the same hypothesis. Enforcement: commitment 10 — rejects if hypothesis not found or not in this programme. Enforcement: commitment 1 — rejects if no completed trials for the hypothesis. Enforcement: commitment 7 — rejects if any completed trial has no observations.

Inputs: verdict (required), programme_id (required), hypothesis_id (required), evidence_summary (required). Returns: status, verdict, claim_error, claim_status, +2 more

correct_trial_statusA

Correct a terminal trial's status — the recorded repair act.

For mislabeled records: e.g. the executor's outer wrapper exited 0 while the recorded output documents a crash ("status": "error" / nonzero inner exit code in the payload). Source must be completed|failed|retryable (all terminal — a retryable source is a correction made in error or evidence re-read after the fact); target must be completed|failed|retryable. reason is mandatory. Correcting TO completed requires the record to evidence a completed run — a cancellation receipt, reaper note, or failure output does not qualify, so that direction is refused unless the executor record documents an actual completion.

The correction is appended to the trial's executor_output_json under 'corrections' — the record shows both what was claimed and what it was corrected to. Never hand-edit the database: a direct sqlite3 UPDATE bypasses this audit trail.

Enforcement: commitment 1 — the loop is the unit (orphan check).

Inputs: reason (required), trial_id (required), to_status (required), programme_id (required). Returns: to, from, trial_id, corrected_at

create_evaluation_contractA

Create an evaluation contract for a programme (RSI Phase 0).

Contracts are insert-only and versioned per programme: each new contract for the same programme gets version = max+1 and supersedes the previous. metrics and promotion_policy may be sent as JSON-encoded strings.

The powered-policy gate enforces presence of the design keys (sesoi_d, target_power, min_evidence_rung), not adequacy — target_power: 0.5 pre-registers fine; adequacy surfaces downstream as underpowered / power_acknowledged on the campaign, not as a mint refusal.

Enforcement: programme must exist.

Inputs: metrics (required), programme_id (required), promotion_policy (required), budget, +1 more. Returns: status, version, contract_id

create_programmeA

Create a research programme with a goal, constraints, and budget.

Constraints are typed fields, not strings (commitment 4). Wires the optimizer role for this programme.

Structured params (constraints, allowed_variables, budget) may be sent as JSON-encoded strings if your client cannot emit objects.

metric_direction: 'minimize' (e.g. perplexity, loss) or 'maximize' (e.g. accuracy). The optimizer uses this to steer search and rank best trials.

candidate_version_id: optional RSI Phase 0 correlation — which registered candidate created this programme. Must exist if given.

investigation_id: optional zetesis correlation — which open investigation declared this programme as its obligation (open_investigation requires_programme → link_programme). Recorded as claimed provenance: episteme has no read path into zetesis, so the id is stored, not verified.

Inputs: goal (required), budget (required), constraints (required), allowed_variables (required), +3 more. Returns: status, programme_id, budget_extras_not_enforced

describe_blobA

Describe a content-addressed blob by digest (read-only).

The resolution check behind digest claims: returns {exists, resolved_in, size_bytes, content_type, captured_at} across the content stores — artifact_files (HTTP ingest), code_snippets, bundles.code_hash. resolved_in names every store holding the hash; a digest may live in more than one. Existence + metadata only — bytes are never returned. This is the read upstream servers use to verify a digest before accepting it on a registration call. For the bytes themselves, get_blob.

Inputs: content_hash (required). Returns: exists, size_bytes, captured_at, resolved_in, +1 more

design_experimentB

Design an experiment: create a trial (data item) within the programme.

config may be sent as a JSON-encoded string if your client cannot emit objects.

Enforcement: commitment 5 — budget is an epistemic resource (trial count + wall time). Enforcement: commitment 10 — the agent is a scientist (hypothesis must exist).

Inputs: config (required), programme_id (required), hypothesis_id (required). Returns: status, trial_id

formulate_hypothesisB

Formulate a falsifiable hypothesis (commitment 3).

Rejects a hypothesis with no failure criterion. variables_involved may be sent as a JSON-encoded string list.

Inputs: statement (required), programme_id (required), failure_criterion (required), variables_involved (required). Returns: status, hypothesis_id

get_archiveB

Get details about an archive, including its programmes.

Returns the archive metadata (path, sealed status, hash) and the list of programmes archived in it.

Inputs: archive_id (required). Returns: archive

get_archived_programmeA

Get an archived programme's details from its archive file.

Returns the programme metadata, hypotheses, trials, beliefs, and conclusions from the archive SQLite file. The programme is read-only — it cannot be modified or restored to the live DB.

Inputs: programme_id (required). Returns: id, goal, status, trials, +22 more

get_blobA

Retrieve a content-addressed blob's bytes by digest (read-only).

The read-back half of describe_blob: returns the stored bytes (base64 in content_b64) plus {digest, size_bytes, content_type, captured_at, resolved_in, served_from}. The returned bytes are re-hashed and verified against the requested digest — a blob whose stored bytes don't match its key is refused with the computed digest reported, never served.

Errors: malformed_digest | not_found | no_bytes | digest_mismatch | too_large. Read-only: no state is mutated.

Inputs: content_hash (required), max_bytes. Returns: error, detail, digest, size_bytes, +6 more

get_candidateB

Read one candidate version (read-only).

Inputs: candidate_id (required). Returns: candidate

get_candidate_lineageA

Walk a candidate's parent chain to genesis (self first).

Returns {"lineage": [{id, parent_id, model_ref, code_artifact_digest, ...}, ...]} — the full ancestry that any result attributed to this candidate inherits.

Inputs: candidate_id (required). Returns: lineage

get_candidate_scorecardA

Descendant quality over attributed programmes (read-only).

For each programme created under this candidate (the Phase-0 candidate_version_id correlation), reports trial/observation counts and the best observed value per metric — 'best' read against the programme's metric_direction.

contract_id scopes the report to that contract's declared metrics (primary + secondary); without it all recorded metrics are reported per programme.

Inputs: candidate_id (required), contract_id. Returns: totals, programmes, contract_id, candidate_version_id

get_evaluation_contractA

Read one evaluation contract (read-only).

Contracts are insert-only and versioned per programme — the promotion pipeline reads them to learn which metrics a campaign is scored under.

Inputs: contract_id (required). Returns: contract

get_incumbentA

Derive the incumbent candidate from decisions (read-only).

Champion/challenger is derived from promotion_decisions, never stored: the latest 'promote' not superseded by a 'rollback' for the same candidate is the incumbent. Empty until the first promote — registered-but-undecided candidates are candidates, not the champion.

Inputs: no named parameters. Returns: candidate, candidate_id

get_next_experimentB

Get the next experiment configuration from the optimizer role.

Reports remaining budget (commitment 5: budget is an epistemic resource). Enforcement: commitment 5 — rejects when budget is exhausted.

Inputs: programme_id (required). Returns: next_config, programme_id, remaining_budget

get_trial_statusA

Check the status of a running or completed trial.

Returns: {"trial_id": ..., "status": "running"|"completed"|"failed", "executor_output": ...} # raw output once finalized

executor_output is persisted on the trial row at finalize time — it survives server restarts (the executor's async cache does not).

artifact_path is a transient staging directory — its contents are captured content-addressed into SQLite at finalize and the files deleted. An empty artifact_path is by design, not lost data: recover contents via get_blob / the code:// resource.

Enforcement: commitment 1 — the loop is the unit (orphan check).

Inputs: trial_id (required), programme_id (required). Returns: hint, reason, status, progress, +9 more

list_active_programmesA

List all active research programmes.

Call this BEFORE create_programme to check whether a programme already covers your goal. If one exists, add a hypothesis to it (formulate_hypothesis) instead of creating a duplicate programme.

Inputs: no named parameters. Returns: count, active_programmes

list_archivesA

List all archive files (open and sealed).

Returns a list of archives with their IDs, paths, programme counts, and sealed status. Sealed archives are read-only; open archives are still accepting new programmes.

Inputs: no named parameters. Returns: archives

list_candidatesA

Enumerate the candidate population, newest first (read-only).

The population listing the Loop-1 roster pulls — candidates are the researchers; champion/challenger status is derived from promotion_decisions (see get_incumbent), never stored.

Inputs: limit, offset. Returns: total, candidates

list_hypothesesA

List all hypotheses in a programme with their status.

Read-only enumeration — the tool-level counterpart of the programme://{id}/hypotheses resource. Use it to recover a hypothesis id (e.g. in a new session) rather than querying the state database directly.

Inputs: programme_id (required). Returns: hypotheses, programme_id

list_programmesA

List programmes with optional attribution/status filters (read-only).

candidate_version_id filters to programmes created under that candidate (the RSI Phase-0 correlation) — this is how a candidate's descendants are enumerated. Each row includes candidate_version_id. Unlike list_active_programmes this is a paginated general listing across all statuses.

Inputs: limit, offset, status, candidate_version_id. Returns: total, programmes

list_promotion_decisionsA

List a candidate's verdict trail, oldest first (read-only).

Decisions are insert-only — the trail is the record; reversal is a new 'rollback' verdict, never a mutation.

Inputs: candidate_id (required). Returns: decisions

list_trialsA

List all trials in a programme with configs and status.

Read-only enumeration — the tool-level counterpart of the programme://{id}/trials resource. Use it to recover a trial id (e.g. in a new session) rather than querying the state database directly.

Inputs: programme_id (required). Returns: trials, programme_id

mark_retryableA

Mark a running trial as retryable (infrastructure failure).

This is for trials that are stuck in 'running' due to infrastructure issues (server restart, executor state lost, timeout) — NOT for scientific failures. A retryable trial is terminal and does not count as evidence.

It does NOT unlock re-capture or re-run: a terminal trial's record is finished. To retry the work, design_experiment a new trial and capture_bundle on it (file-path or code://).

Enforcement: commitment 1 — the loop is the unit (orphan check).

Inputs: reason (required), trial_id (required), programme_id (required). Returns: reason, status, trial_id

prepare_dataA

Prepare a dataset and return a DataRef ID.

Two regimes:

  • generated: runs the generator (via executor), stores output, computes hash. Requires generator_code_ref, generator_seed. Generator contract: the file must expose generate_data(config, output_path) — config carries 'seed' AND 'generator_seed' (same value — either spelling works) plus generator_params flattened at the top level; a seed/generator_seed key inside generator_params is superseded so the recorded seed always equals the seed delivered. The dataset is written to output_path. A generator may print a single-line {"error": "..."} JSON object to stdout to report a structured failure. The generator runs under the executor's default interpreter ([executor] python) — not a bundle env; only packages installed there are importable.

  • captured: registers an external URI, computes hash if accessible. Requires source_uri.

For stream capture (captured + temporal), provide capture_window_start and capture_window_end.

The DataRef is stored in the state DB and the data is stored in data storage (separate from code storage). Access is read-only.

Returns: {"data_ref_id": "data-ref-...", "split": ..., "regime": ...}

generator_params and capture_source_metadata may be sent as JSON-encoded strings.

Inputs: split (required), regime (required), version, source_uri, +6 more. Returns: split, regime, data_ref_id, storage_uri, +2 more

read_resourceA

Read one of this server's resources by URI (read-only).

The MCP surface exposes resources only through resources/read — this tool gives tool-only clients the same read surface. Ownership is by construction: a URI outside this server's registered schemes resolves to nothing and errors rather than crossing the loop boundary. Never a write path.

Inputs: uri (required). Returns: uri, contents

record_observationA

Record an observation (data item about a quality).

metrics and variance may be sent as JSON-encoded strings.

Only completed trials can be observed — a failed trial produced no measurement; its failure lives in its status, executor_output, and artifacts, not here. All-zero variance is rejected (n identical outcomes are one effective measurement, not reproducibility). If nothing is concludable, close the programme 'abandoned' rather than fabricating variance.

Enforcement: commitment 7 — reproducibility is the price of admission. Rejects a single point estimate with no variance.

Inputs: metrics (required), trial_id (required), variance (required), spatiotemporal_region (required). Returns: status, observation_id

record_promotion_decisionA

Record an attributed verdict on a candidate (RSI Phase 0).

verdict: promote | reject | hold | rollback. Decisions are insert-only — reversal is a new decision ('rollback'), never a mutation. evidence_refs may be sent as a JSON-encoded string list. decided_by is required: attribution is first-class.

Enforcement: verdict enum, non-empty rationale/decided_by, candidate (and contract, if given) must exist.

Inputs: verdict (required), rationale (required), decided_by (required), candidate_id (required), +5 more. Returns: status, decision_id, claimed_rung, computed_rung, +2 more

register_candidateA

Register a researcher version with parent lineage (RSI Phase 0).

The thing doing the research becomes a durable object. parent_id links this candidate to its parent — omit for a genesis candidate. Lineage is never "latest wins": every candidate keeps its ancestry.

capability_profile describes the tools/roles available; it may be sent as a JSON-encoded string.

Enforcement: parent_id must name an existing candidate; code/harness digests must resolve to an ingested blob or be 'none' — a hash of nothing is a claim with no referent.

Inputs: model_ref (required), capability_profile (required), code_artifact_digest (required), parent_id, +2 more. Returns: status, candidate_id

run_trialA

Run a trial by calling the executor role.

Imports run_training from the bundle's code_ref and calls it with the trial config. The code_ref must be a path to a .py file exposing def run_training(config: dict) -> dict returning {"metrics": {...}, "variance": {...}}. Read the executor://contract resource for the full contract.

When the bundle carries data_refs, the config handed to run_training is extended with two injected keys: 'data_paths' ({split: resolved read-only path}) and 'data_ref_paths' ({data_ref_id: resolved read-only path}). The stored config_json keeps the designed config verbatim — the injection is runtime-only.

For long-running jobs, this returns quickly with status "running". Use get_trial_status to poll for completion. Note the return is not immediate — there is a consistent ~10 s handshake/settle before status "running" comes back; that settle window is what makes cancel-race behaviour reproducible.

Enforcement: commitment 6 — the bundle must be controlled. Rejects if the bundle is not fully captured. Concurrency: rejects if trial is already running (no double execution).

Inputs: trial_id (required), programme_id (required), timeout_seconds. Returns: error, status, message, trial_id, +1 more

update_beliefB

Update the belief state for a programme.

Calls the optimizer role's tell, then reads the updated posterior. Enforcement: commitment 2 — memory precedes optimization. Enforcement: commitment 9 — belief is a tracked quantity.

Inputs: trial_id (required), programme_id (required), observation_id (required). Returns: status, belief_id

update_metric_directionA

Update the optimization direction for an existing programme.

Use 'minimize' for loss-like metrics (perplexity, error rate) or 'maximize' for quality metrics (accuracy, F1). The optimizer uses this to rank best trials and steer the search.

This is needed for programmes created before the metric_direction parameter was added to create_programme.

Inputs: programme_id (required), metric_direction (required). Returns: status, programme_id, metric_direction

verify_archiveA

Verify an archive's integrity.

For sealed archives: recomputes SHA-256 of the .db file, compares to the recorded hash.

For open archives: verifies structural integrity (DB can be opened, row counts match the registry).

Returns: {verified: bool, recorded_hash, computed_hash (sealed only)}

Inputs: archive_id (required). Returns: error, sealed, verified

verify_dataA

Verify data provenance by re-computing the hash.

Returns: {"verified": bool, "recorded_hash": ..., "computed_hash": ...}

If verified is false, the data was modified after preparation — a provenance violation that invalidates any trial using this data.

Inputs: data_ref_id (required). Returns: error, verified, computed_hash, recorded_hash

wait_trialA

Wait for a trial to reach a terminal state — one call instead of a polling loop.

Polls get_trial_status internally every poll_seconds until the trial is completed/failed/retryable/abandoned or timeout_seconds elapses (server-side cap: 60s). Returns the final status payload plus 'waited_seconds' and 'timed_out'. Caps the get_trial_status amplification loop: a 60s wait replaces ~30 round-trips.

Inputs: trial_id (required), programme_id (required), poll_seconds, timeout_seconds. Returns: hint, reason, status, progress, +9 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 46 tools

    Disambiguation4/5

    Most tools target clearly distinct resources and lifecycle stages (programme/hypothesis/trial/candidate/contract/archive/blob). A few boundaries blur: list_active_programmes vs list_programmes, describe_blob vs get_blob, and the terminal-status cluster (mark_retryable, correct_trial_status, cancel_trial) require reading descriptions to separate. Descriptions do resolve the ambiguity, but an agent could misselect without care.

    Naming Consistency4/5

    Strong overall verb_noun snake_case convention (create_programme, conclude_hypothesis, record_observation, cancel_trial). Minor deviations: the get_ vs describe_ vs read_ prefix split (describe_blob/get_blob, read_resource) is semantically inconsistent, and capture_bundle vs capture_bundle_from_code_hash is a long variant. Still predictable and readable.

    Tool Count2/5

    46 tools is heavy for a single server, exceeding the 25+ threshold for concern. While the domain is genuinely broad (research loop + archives + integrity + blob store), operations like capture_pending_artifacts and archive_pending_programmes are migration one-offs that could be folded, and the trial-status family could be consolidated.

    Completeness5/5

    The surface covers the full research lifecycle: programme creation/closing, hypothesis formulate/conclude/abandon, experiment design/run/observe, candidate registration and lineage, evaluation contracts, promotion decisions, data prep/verify, archiving/verification, integrity auditing, and a resource/blob read path. Few obvious gaps remain.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that enforces evidence-graded, phase-gated, peer-reviewed research workflows for AI agents to conduct rigorous decision-making.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI-assisted scientific research workflow management through MCP, including project creation, ideation, experiment execution, and artifact handling, with integration for ChatGPT, Codex, and Claude Code.
      Apache 2.0
    • A
      license
      C
      quality
      B
      maintenance
      An append-only research operations framework and read-only MCP that tracks research plans, approvals, observations, claims, failures, revisions, and contributions with source-grounded evidence, providing search, evidence fetch, and audit capabilities without direct ledger writes.
      30
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      423 npm
      468
      AGPL 3.0