GnosisLab
GnosisLab's Episteme server is the experiment runtime and laboratory notebook — it structures research into programmes, falsifiable hypotheses, sealed trials, observations, and auditable conclusions, with RSI candidate governance, archives, and content-addressed provenance.
Programmes — create (goal, typed constraints, budget, metric direction, candidate/investigation attribution), list active or paginated with filters, close as completed/abandoned, update metric direction.
Hypotheses — formulate a falsifiable hypothesis (failure criterion required), list by programme, conclude as accepted/rejected/inconclusive (immutable, mints a claim), or abandon with attribution.
Trial design — design_experiment creates a trial with a config; list_trials recovers trial ids and statuses.
Bundle sealing — capture_bundle (pre-registration of code/env/seeds/splits/data refs, plus extra code refs) or capture_bundle_from_code_hash to rerun from an archive by content address.
Execution — run_trial (sealed executor, timeout override), get_trial_status / wait_trial (single-call polling), cancel_trial, mark_retryable, and correct_trial_status with a mandatory audit-trail reason.
Observations & belief — record_observation (metrics + per-seed variance required; all-zero rejected), update_belief (optimizer posterior), assess_programme health, get_next_experiment from the optimizer.
Data provenance — prepare_data (generated via executor, or captured external URI with capture windows) and verify_data hash re-check.
RSI Phase 0 candidates — register_candidate with parent lineage and digests, list/get candidates, get_incumbent (derived from decisions), get_candidate_lineage, get_candidate_scorecard.
Evaluation governance — create/get versioned evaluation contracts (metrics, holdouts, promotion policy) and record insert-only promotion decisions (promote/reject/hold/rollback) with rung and evidence refs.
Archives — list_archives, get_archive, verify_archive (hash or structural), get_archived_programme (read-only), archive_pending_programmes and capture_pending_artifacts migration tools.
Integrity — check_invariants audits the store (orphans, unsealed runs, missing observations, budget overruns); acknowledge_violation records dispositions insert-only.
Blobs & resources — describe_blob (metadata/existence) and get_blob (verified bytes by digest), plus read_resource for tool-only access to protocol://, executor://, programme://, trial://, artifact://, dataref://, and code:// URIs.
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., "@GnosisLab test if higher temperature improves forecast accuracy with a sealed experiment"
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.
GnosisLab
A scientific-method runtime for AI agents
Turn hypotheses into experiments, experiments into evidence, and evidence into auditable conclusions.
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 gnosislabor:
pip install gnosislabFull 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 allPorts 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 allSealed trial execution needs Linux tooling. The executor isolates trials with
bubblewrapmount namespaces and traces reads withstrace. Neither exists on Windows (or macOS) — there is no bwrap package to install. With the defaultsandbox = "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, addsealed_enforcement = "audit"—denyneeds a mount namespace to arm. Coding agents often offer to "disable sandboxing" when they hit this error; the knob they should set issandbox, shown above.On Debian/Ubuntu the full experience is:
sudo apt install bubblewrap straceThe 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 -.-> RThe 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 --> ANDefault service ports
Service | GUI | MCP |
Agora |
|
|
Arete |
|
|
Zetesis |
|
|
Episteme |
|
|
Anamnesis |
|
|
Defaults can be overridden with:
~/.config/gnosislab/ports.envor 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-mcpThis 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 allResident 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 consoleThe 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/shutdownops;ready/turn_end/sessionevents). 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 → answerGnosisLab makes the scientific structure explicit:
question
↓
hypothesis
↓
search / prior evidence
↓
experiment design
↓
sealed execution
↓
observations + artifacts
↓
evidence-linked claims
↓
conclusion
↓
critique / adaptation
↓
next hypothesisThat 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.mdThe repository root is the runnable project:
uv syncConfiguration
Per-service configuration lives under:
ml-*.tomlPort configuration:
ports.envUser overrides:
~/.config/gnosislab/ports.envInspect the resolved configuration at any time:
gnosislab configObservability
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:28091Use:
gnosislab statusfor process, port and health information.
Use:
gnosislab logs <service>to inspect a service directly.
Testing
Run the full suite:
uv run pytest -qThe repository currently contains 1,289 tests.
For a serial run:
uv run pytest -n0Development 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 statusDocumentation: https://loop.cloudcell.workers.dev/docs
PyPI: https://pypi.org/project/gnosislab/
Repository: https://github.com/cloudcell/gnosislab
Related projects
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 gnosislabGnosisLab — hypothesis in, auditable conclusion out.
Available Tools
46 toolsabandon_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
Scored across 46 tools
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.
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.
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.
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
Related MCP Connectors
Machine-native research commons for agent evidence, discovery, rooms, and bounded research quests.
Plan and verify evidence-aware research workflows with specialist execution receipts.
Governed MCP: agent audit, provenance, deterministic checks, and receipt-backed FragGate execution.
Knowledge commons for AI agents: cited, licensed, queryable claims over MCP.
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 gradedqualityCmaintenanceEnables 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
- AlicenseCqualityBmaintenanceAn 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.30MIT
- 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.423 npm468AGPL 3.0