persist

name	persist
type	primitive
description	Mark a Note or Collection as persistent so it survives goal-completion cleanup

Persist

INPUT CONTRACT

• target (required): $variable, resource ID (Note_123, Collection_456, Relation_7), or named resource
• name (optional): Stable name to register for later load(target="my-name")
• out (optional): $variable aliased to the persisted resource

REQUIREMENTS:

• Target must resolve to an existing Note, Collection, or Relation

BEHAVIOR

Marks the resource as persistent on disk so it is not swept by the transient-resource cleanup that runs after goal completion. Persistence is in-place — the same resource ID before and after. If name is given, the resource is also registered for load-by-name. If out is given, the variable is aliased to the same resource ID (equivalent to bind after persist).

Use persist for any output a subsequent goal will need to read.

EXAMPLES

{"type": "persist", "target": "$matches", "name": "transformer_attention_matches"}

{"type": "persist", "target": "Collection_17", "name": "weather_report", "out": "$report"}

OUTPUT

Returns success with the persisted resource's ID in resource_id.

FAILURE SEMANTICS

• Missing target
• Target does not resolve to a Note, Collection, or Relation
• Underlying mark_persistent failed (e.g. disk write error)

ANTI-PATTERNS

• Persisting transient scratch resources — only persist deliverables.
• Assuming persist copies or clones — it flips a flag on the existing resource. Both pre- and post-persist variables point to the same ID.
• Passing out= expecting a new resource. The binding points to the same resource; use bind explicitly if that is clearer at the call site.