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.

NodesCopy Anchor Link

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.

These hosted commands commit directly to the selected hosted repository:

flywheel hosted:node:create --repository-id <REPOSITORY_ID> --title "Evaluate retrieval baseline"
flywheel hosted:node:branch <NODE_ID> --repository-id <REPOSITORY_ID>
flywheel hosted:node:set <NODE_ID> --repository-id <REPOSITORY_ID> --field summary --value-file summary.txt

They do not stage changes in a local repository or require repo:push. For local authoring, use the repo: commands, then repo:commit and an explicit repo:push; see Quickstart. MCP editing uses a separate lease and node-commit sequence described in MCP tools.

ArtifactsCopy Anchor Link

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.

The repository CLI attaches files with hosted:artifact:attach, or stages an attachment with repo:artifact:attach for later local commit and publication. MCP supports prepare, raw-byte upload, and finalize operations; consult its artifact contract before uploading. These are different interfaces, not interchangeable command sequences.

ExecutionsCopy Anchor Link

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 TogetherCopy Anchor Link

A typical empirical branch starts as a node, launches an execution or acquires compute, attaches artifacts from the run, then saves a summary explaining the evidence. Use the commit/publication sequence for your chosen interface. Later branches can cite the same evidence without duplicating it.

For command details, see hosted:node:list, hosted:artifact:list, executions:list, and the CLI reference.

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