Lab Notes

Research Artifacts

How the Research Agent stores, tracks, and structures mission outputs — the artifact lifecycle and the purpose of each file.

Purpose

Each research mission produces a set of typed output files (artifacts) stored in an isolated run directory. This makes research missions reproducible, inspectable, and easier to debug. The artifact structure defines a clear contract between phases and downstream consumers.

Within OpenClaw, artifacts are the durable outputs of a mission. The Research Agent specializes this model into phase-level files such as candidates, reviews, transcripts, synthesis outputs, and the final report.

Status: Implemented (artifact store and file conventions operational)

Artifact lifecycle

Loading diagram…
Research Agent artifact lifecycle — from task input to final report

Artifact descriptions

task.json

Created at mission start. Contains the original task definition as provided to the task queue. This file is the source of truth for what the mission was asked to do. Never modified after creation.

candidates.json

Produced by phase F1 (Candidates). Contains the list of candidate items discovered through the primary search. All subsequent research phases read from this file to scope their work.

reviews.jsonl

Produced by phase F2 (Reviews). Contains one JSON entry per line, each representing review and analysis data for a single candidate. The JSONL format allows streaming writes and incremental inspection.

price_analysis.json

Produced by phase F4 (Price Analysis). Contains pricing and availability information for each candidate across queried platforms.

youtube_transcripts.json

Produced by phase Y2 (Transcript Extract). Contains transcript content for YouTube videos associated with each candidate.

synthesis.json

Produced by an optional deep synthesis step. Not present in all missions. When present, contains a higher-level synthesis of findings across candidates. F6 includes it if available.

final_report.md

Produced by phase F6 (Final Report). The primary deliverable of a research mission. Aggregates findings from reviews.jsonl, price_analysis.json, youtube_transcripts.json, and optionally synthesis.json into a structured Markdown report.

The report includes:

  • Mission summary
  • Candidate ranking or shortlist
  • Key findings per candidate
  • Price and availability summary
  • Source notes and confidence indicators

state.json

Maintained throughout the mission lifecycle. Tracks:

  • Current phase
  • Phase completion status
  • Error messages for failed phases
  • Mission start and end timestamps

Provides the basis for future mission resumption or retry capabilities.

Run directory structure

Each mission creates an isolated run directory:

missions/
└── {mission-id}/
    ├── task.json
    ├── candidates.json
    ├── reviews.jsonl
    ├── price_analysis.json
    ├── youtube_transcripts.json
    ├── synthesis.json          (optional)
    ├── final_report.md
    └── state.json

Why this structure

  • Reproducibility — given the same task input, the artifact set is predictable and auditable
  • Debuggability — individual phase outputs can be inspected independently
  • Isolation — multiple missions do not interfere with each other
  • Auditability — the full research chain is preserved, not just the final output

A current limitation

Artifact files are currently written as flat files with no schema validation at write time. Type checking and schema enforcement are planned for a future version of the pipeline.

→ OpenClaw Framework Overview — the artifact model this page specializes
→ Research Mission DAG — phase dependency graph and artifact production sequence → Research Framework — full pipeline overview → Research Agent — agent overview