seamless docs

Run research trials

The lab loop for systematic debugging - recording what was tried, letting parallel agents share dead ends, and distilling the result into memory.

On this page

Some problems are not solved by thinking harder; they are solved by trying twelve things and keeping track. Firmware that boots sometimes. A race that reproduces one time in thirty. A config that works on one machine.

Agents are bad at this in a specific way: each one starts fresh, re-derives the same first three hypotheses, and tries them again. A lab is where that stops.

Turn it on first

Labs and trials are an optional feature, and optional features ship off. On a fresh install the screens and the three tools below are not there until you enable research, in any one of three places:

  • The console - Settings → Features, the fastest route. It applies to the console immediately; agents pick it up on their next session.
  • The config file - features: research: true in seamless.yaml.
  • The environment - SEAMLESS_FEATURES_RESEARCH=1.

A console toggle stores an override that wins over the file and the environment until you reset it, so if the YAML says one thing and the tools disagree, check the console first. An installation that was already recording trials before this became optional keeps it on across the upgrade - the feature is never switched off underneath existing data, and switching it off later hides the screens and the tools without deleting a single trial. See Configuration.

The loop

Evidence loop
1 · lab_openName and bind the investigationSeveral sessions can share the same lab.
2 · trial_queryRead before tryingSee prior outcomes and avoid repeated dead ends.
3 · trial_recordExpected vs actualRecord the change, outcome, evidence, and metrics; query again before the next trial.
4 · memory_writeDistill the durable findingClose the loop with a gotcha, decision, or protocol.
Trials are the working evidence; memory is the compact conclusion that future agents need.

lab_open binds the lab to the connection the same way session_start binds a project, so trial_record inherits it without you naming the lab every time.

Record the expectation, not just the result

The field that earns its keep is what you expected. A trial that says "tried X, it failed" is worth little. One that says "expected the firmware to enumerate after DFU because the descriptor changed; it enumerated but with the old PID" tells the next agent which model of the system was wrong - and that is the actual product of debugging.

Record trials that succeeded too. "This worked" is what stops the next agent from redesigning a thing that already works.

Parallel agents in one lab

This is the reason the lab exists rather than a scratch note.

Several agents can open the same lab and work the same problem concurrently. Each one calls trial_query first and sees what the others have already eliminated. Where a fleet of independent agents would explore the same three obvious hypotheses three times, a fleet sharing a lab divides the space.

Pair it with the ready queue when the trials are enumerable up front: one task per hypothesis, tasks_claim to avoid two agents testing the same one. See Coordinate multiple agents.

Watching a lab

The console has a twin for this surface: /console/labs lists each investigation with its trial and outcome counts, and /console/trials shows every trial with expected and actual side by side - which is where a mis-predicted expectation is easiest to spot. Watch there while a fleet works a lab; nothing on either screen writes.

Distil, then stop

A lab is a working record, not a conclusion. When the investigation resolves, write one memory that captures what is now known:

  • The thing that was wrong, as a gotcha - with the symptom in the description, so the next agent recognizes it before diagnosing it.
  • The thing you decided, as a decision - with the alternatives you rejected.
  • The thing you believed that turned out false, as refuted - this is the kind people skip, and it is what stops the fleet re-deriving the dead end.

Do not copy the trial log into memory. The trials stay in the lab, queryable; the memory carries the conclusion. A briefing has a token budget, and twelve trials of a solved problem are not what an agent needs injected before it starts work. See Write memories that get recalled.

The skill

While the feature is on, the installer drops the portable seam-research package into the selected client's skill home - and while it is off, seamlessd install-hooks skips it and removes a copy it previously delivered, so no agent reads about tools its server will refuse. A toggle in the console cannot reach a client's skill home on its own, so seamlessd doctor raises an info line until the next install run reconciles the two. From a clone, use make install-research-skill CLIENT=claude for Claude Code or make install-research-skill CLIENT=codex for Codex (CLIENT=detect is the default). It wraps this loop

  • open the lab, query before trying, predict before running, record once with the outcome, distill decisions into memory - and can activate when an investigation becomes repeated experiments. Start or resume one explicitly with /seam-research <lab-name> <problem> in Claude Code or $seam-research <lab-name> <problem> in Codex.

The tools

lab_open, trial_record, and trial_query are documented in Lab, gardener & usage.