§4. Intent Envelope
What this section covers
A structured message expressing desired transitions. Where atomic facts (§2) record what is known, an intent envelope records what an agent (or human) wants to happen — a goal plus the rules and context needed to act on it.
Status: Experimental / deferred indefinitely
Source material: Archived evolutionary spec snapshots. This page preserves the maintained Spec-X home for intent-envelope semantics.
Each subsection below shows the most recent normative text from the spec source. When earlier spec drafts also contained text for the same subsection, those revisions are collapsed under a Revisions accordion beneath it — open one to see what changed. Subsections that only appear in one draft render as plain text with no accordion.
Envelopes are the unit Stigmem uses to coordinate multi-agent work.
Without inventing a bespoke handshake protocol per pair of participants.
The envelope shape is fixed:
IntentEnvelope {
id: UUID
from: URI
to: URI[]
goal: string
constraint: Constraint[]
preference: Preference[]
deference: DeferenceRule[]
escalation: EscalationPolicy
handoff: HandoffPayload?
created_at: ISO 8601 UTC
expires_at: ISO 8601 UTC?
}
The fields split cleanly by purpose:
Routing
from / to carry routing.
Work description
goal, constraint, preference, deference describe the work.
Off-happy-path
escalation, handoff, expires_at describe what to do when execution falls off the happy path.
§4.1 goal
A free-text statement of what the sender wants done. Free-text is acceptable because the goal is read by an agent that already has access to the same fact substrate the sender does — full natural-language is more expressive than any enumerated set of intents, and the recipient can interrogate the substrate to fill in context.
So that the goal is also queryable by other agents (not just the recipient), agents SHOULD additionally assert a machine-readable goal fact at envelope creation time:
(entity=<intent-id>, relation="intent:goal", value={type:"string", v:"..."}, ...)
The entity is the envelope's id; the relation is the reserved intent:goal; the value is the same string as the envelope's goal field. Asserting this fact lets observers query for "what intents are currently in flight against goal X?" without needing direct access to envelope traffic.
§4.2 constraint
Constraint violations are failures.
Unlike preferences, a constraint is a hard limit the recipient MUST respect. If the recipient cannot satisfy all listed constraints, it MUST escalate (§4.5) rather than partially satisfy.
Constraint { kind: string, limit: FactValue, unit: string? }
kindbudget, deadline, latency_ms, max_calls — see §9 namespace registry).limitFactValue shape so units and types are explicit.unitkind doesn't imply one.§4.3 preference
A preference is a soft-weighted hint. Unlike constraints, the recipient MAY violate preferences if doing so is necessary to satisfy a constraint; it SHOULD optimize against them otherwise:
Preference { kind: string, value: FactValue, weight: float [0,1] }
weight allows expressing relative importance when multiple preferences compete (e.g. "minimize cost weight=0.9, minimize latency weight=0.3" tells the recipient to prefer cost optimization roughly 3× more than latency).
§4.4 deference
A deference rule names another agent or system to consult before deciding on a particular axis. Use it when the sender has specialised authority but wants a second opinion on certain dimensions:
DeferenceRule { condition: string, defer_to: URI, timeout_s: integer? }
conditioncost > 100, requires_legal_review).defer_totimeout_s§4.5 escalation
The escalation policy fires when the recipient cannot satisfy the envelope within its own authority — typically because a constraint can't be met or no deference target responded in time:
EscalationPolicy {
escalate_to: URI
channel: string // "stigmem" | "email" | "slack" (v0.1: stigmem only)
priority: "low" | "medium" | "high" | "critical"
include_context: boolean
}
escalate_tochannel"stigmem" (escalation arrives as a fact in the escalator's inbox).priorityinclude_contexttrue) or just the envelope ID with a query hint (false); set false when escalations travel over channels with size limits.§4.6 handoff
A handoff is the payload sent to the next agent in a multi-step plan. It exists separately from the envelope itself because handoffs MAY carry artefacts (files, structured documents) that aren't appropriate to embed in every envelope:
HandoffPayload {
summary: string
fact_refs: URI[]
continuation: string?
artifacts: { name: string, ref: URI }[]
}
summaryfact_refscontinuationartifactshandoff MUST include fact_refs for context reconstitution.
This is what lets handoffs be terse — the receiver has the same fact substrate as the sender.