Nodes, Artifacts, And Executions

Nodes hold research work and summary state. Artifacts attach concrete outputs to nodes, including text, tables, JSON, images, plots, checkpoints, and diffs. Executions track managed compute and other run-oriented work associated with a node.

These records are separate so graph structure, produced evidence, and compute history can be inspected independently.

Nodes

Use nodes for durable work state: the prompt or task, the hypothesis being tested, the current conclusion, and links to neighboring work. Nodes can be created, branched, committed, merged, tagged, shared, and rendered into compact summaries.

Common node commands include:

flywheel nodes:create --title "Evaluate retrieval baseline"
flywheel nodes:branch --node_id <NODE_ID> --title "Try reranker"
flywheel nodes:commit --node_id <NODE_ID> --summary "Current result"

Artifacts

Use artifacts for evidence. An artifact is the durable output of work: a report, plot, table, dataset excerpt, model checkpoint, patch, transcript, or JSON record. Keeping evidence in artifacts makes it inspectable by people, agents, hooks, and exports without requiring readers to scrape it from prose.

Artifact workflows usually follow one of two paths. For ordinary files, use the one-shot upload command. For larger or agent-managed batches, use prepare, upload, and finalize steps so the node records exactly which files landed.

Executions

Executions represent run-oriented work tied to a node. Managed compute acquisition, launched jobs, and termination state are separate from artifacts so you can see both the run history and the evidence it produced.

Use execution and compute records when an experiment needs external resources, budget approval, or a durable run log. Release compute leases when the work is done so credits are not spent on idle resources.

How They Fit Together

A typical empirical branch starts as a node, launches an execution or acquires compute, uploads artifacts from the run, then commits a summary that explains what the artifacts mean. Later branches can cite the same evidence without duplicating it.

For command details, see nodes:list, artifacts:list, executions:list, and the CLI reference.

For guidance on using these records together in research workflows, see Encoding the Scientific Method.