Commit structured data as an artifact

For anyone whose agent sessions produce structured data — measurements, query plans,
computation outputs, structured inputs and outputs — that a later session must retrieve whole.

Outcome

By the end of this playbook you will have committed structured output as a data artifact owned
by a resource, retrieved it whole in a later session, and understood when to reach for this
instead of writing fenced JSON into a resource body.

Prerequisites

Temper installed — see Install Temper.

Authenticated — you have signed in and your access is approved. See
Authenticate.

Familiar with contexts and refs — data artifacts are owned by resources, which live in
contexts.

The problem: why fenced JSON in resource bodies fails

Agents already persist structured data in Temper. The instinct is to write JSON or YAML into a
fenced code block inside a resource body — a session note, a task, a research document. This
works well enough for a human reading the note, but it fails the next agent session that needs
the data whole:

The chunker shreds it. Temper's ingest pipeline chunks resource bodies for search, and it
has no fence-state tracking. A YAML comment at column 0 is parsed as a markdown heading, so a
structured block is split at its own comment lines. Reassembling the original is not reliably
possible.

The fragments pollute the corpus. Every chunk gets a 768-dim vector and a full-text search
entry. JSON and YAML fragments are semantic noise in a corpus built for prose.

There is no shape. A fence inside prose has no declared family, no selection intent, and
no way to say "this one supersedes that one." A reader must guess which fence is the right one
and infer a shape nobody declared.

Data artifacts solve all three: the content is stored whole (never chunked, never embedded),
carries a family and selection intent, and is reached only through the resource that owns it.

Commit a data artifact

Create a JSON file with structured output — for example, a measurement:

{
  "metric": "p95_latency_ms",
  "value": 142.3,
  "endpoint": "/api/search",
  "timestamp": "2026-08-21T22:00:00Z"
}

Commit it to a resource you have write standing on — a task, a session, a research document:

--kind — the bare family name. Free-form, but be consistent within a family
("measurement", "query-plan", "computation-output").

--intent — current (this is the one to take by default), member (one of several,
ordered by --precedence), or pinned (explicitly held). A closed vocabulary — the system
refuses an unrecognized value and tells you what is accepted.

--content — @path/to/file.json (file), - (stdin), or omit for implicit stdin. Must be
valid JSON.

The commit returns the artifact with its server-assigned ID, content hash, and shape state.

Declaring a shape

A shape is a field tree — a JSON Schema (draft 2020-12) document that uses only type, properties,
required, additionalProperties, items, enum, const, pattern, the length, item-count and
numeric bounds, and the annotation keywords — that you declare for a family within a context.
format is one of those annotations: it is accepted but not enforced, so

"format":
"date-time"

documents a field without checking it (use pattern to check a form). Keys beginning
x- are carried as written and ignored. Keywords such as $ref, $defs, allOf, anyOf and
oneOf are refused at declare; the refusal names the first keyword or cap that failed and where —
for example keyword allOf at /properties/when — and lists what is allowed. A const and every
enum member must be a scalar — a string of at most 256 bytes (JSON-escaped), a number, a boolean
or null — and a shape's schema holds at most 12,288 JSON values in all, at most 3,072 of them
objects, counted with default, examples and x- values included. The declare routes hold the
request body to 512 KiB, and the MCP declare tool relays through them, so the same limit applies
to what it declares. Declaring is a
separate act from committing data — you never need to declare a shape to commit an artifact.
The system persists your data whether or not a shape exists. never_declared is a first-class
state, not a gate.

If you declare a shape after artifacts already exist, the system reconciles them asynchronously —
they read as declared_not_yet_checked until the sweep reaches them, never as silently conforming.

The schema file is a field tree:

{
  "type": "object",
  "properties": {
    "metric": { "type": "string" },
    "value": { "type": "number" },
    "endpoint": { "type": "string" },
    "timestamp": { "type": "string", "minLength": 20 }
  },
  "required": ["metric", "value", "timestamp"]
}

Enforcement modes

A shape carries an enforcement mode — a closed vocabulary:

advisory (default) — a non-conforming commit succeeds and is recorded as
declared_not_satisfied. The shape informs; it does not gate.

enforcing — a non-conforming commit is refused, and the refusal carries what failed.

advisory is the default because the registry exists to make shapes discoverable and informative,
not to force a writer to be right up front. Switch to enforcing only when you want a hard
contract.

A shape governs its home

The shape in force for a family is keyed per home (a context or a cogmap), not globally. So the
same family can carry different shapes in different contexts — a measurement in one context may
have a different schema than a measurement in another. This is by construction: a shape declared
in a context you cannot read must not verdict your data.

Listing and inspecting shapes

Shapes are not searchable — they are reached only through the context they govern, like artifacts
themselves.

Retrieve it later

A later, unrelated session retrieves the artifact by its ID:

Or lists the artifacts owned by a resource, a bounded page at a time, with optional filters:

With --limit, the answer is {"artifacts": [...], "next": {"created": ..., "artifact_id": ...}}.
When next is not null, more follow: pass next.created and next.artifact_id back as
--after-created and --after-id, with the same filters. Without --limit, the answer is every
artifact as a bare array, an unbounded default that is retiring.

The content round-trips byte-identical — the same JSON value the writer committed, without
reconstruction, reassembly, or inference about its shape. This is the core guarantee: what
survives the gap between sessions is the data itself, whole.

Selection among many

When a resource owns several artifacts of one family, the selection vocabulary lets a reader
decide which to take from the stored record alone:

Supersession

When a new measurement replaces an old one, the writer declares it:

The old artifact is folded out of the default list — --include-folded returns it. The system
never infers supersession from recency or ordering; a writer must declare it.

When not to use this

Data artifacts are for structured content a later session must retrieve whole. They are not
a replacement for:

Resource bodies — session notes, problem statements, design rationale, and prose of any
kind belong in the body. The body is chunked, embedded, and searchable; that is the right
treatment for prose.

open_meta — small, key-scoped metadata values (a status, a verified date, a
descriptor) belong in open metadata. Data artifacts are for structured content of any size
that does not fit in a property value.

The distinction is not about format — it is about whether the content is data that a later
session must retrieve whole, or prose that a reader must understand. A fenced JSON block in a
session note is prose with a shape; a data artifact is the shape without the prose.

Shapes are not "just schema validation" either. The why-anchor is still that the writer and the
reader are different sessions separated in time. A shape tells the reader whether the data they
retrieved conforms to anything the writer declared — it bridges the gap, it does not gate it.

Commit structured data as an artifact

Outcome#

Prerequisites#

The problem: why fenced JSON in resource bodies fails#

Commit a data artifact#

Declaring a shape#

Enforcement modes#

A shape governs its home#

Listing and inspecting shapes#

Retrieve it later#

Selection among many#

Supersession#

When not to use this#

Further reading#