Zephr Docs

Continuity

Continuity makes working state survive a tool switch, a machine switch, and a vendor switch. The unit of continuity is not the conversation — it is a reconstructable mental model multiplied by a verified world state, so transcripts are treated as lossy provenance rather than the payload.

flowchart LR
    A[Working session] -->|zephr handoff| P[Signed Continuity packet]
    P -->|file, registry, or claim code| T[Transfer]
    T -->|zephr resume| I[Ordered import pipeline]
    I --> V[Authenticate before parse]
    V --> C[Consume-once claim]
    C --> S[Scope proof + anchor revalidation]
    S --> R[Apply + demote moved evidence]
    R --> Q[Resume: reconciled state + signed receipt]

What a packet carries (shipped)

zephr handoff produces a signed ContinuityEnvelopeV1 (zephr-continuity, version 1) carrying:

  • a mental-model ledger of portable beliefs, each with its review state and revalidation anchors — path, content hash, and an optional re-verification command;
  • a decision log with accepted/rejected/deferred decisions and their rejected alternatives;
  • next actions with order, state, and blocking relationships;
  • per-file change claims with before/after content digests;
  • redaction and omission manifests, so what was left out is itself recorded.

An unrecognized envelope version is refused at ingest, never partially interpreted. The aspirational CPX section names (world, attention, a first-class dead-end registry) are exported with an honest alias map — those sections are designed, not on the wire.

Lifecycle

  1. Sign (shipped). Ed25519 signature over canonical bytes plus a recipient-binding HMAC; authentication failures surface before parsing. Issued-at validation tolerates five minutes of clock skew.
  2. Transfer (shipped, three modes). A self-contained packet file (offline), a registry publish, or a claim code — short, single-use, expiring, redeemed atomically exactly once. A relay sees only AES-256-GCM ciphertext.
  3. Resume (shipped, ordered). zephr resume runs a fixed pipeline: authenticate before parsing, atomically consume the claim once, verify a scope proof (project, binding epoch, roots digest), check the destination tool contract, apply review-state rules, then revalidate every belief against its anchors.
  4. Honest demotion (shipped). A belief whose anchor content hash no longer matches the current file is demoted to suspect (content_hash_mismatch); a missing file demotes it (anchor_file_missing). Demotion returns the belief as a separate record with a reason — it never silently mutates the belief. Instruction-injection heuristics can also demote to suspect.
  5. Receipt (shipped). A signed transfer receipt reports what moved, what was demoted, and what degraded; the pipeline exits non-zero on strict refusal. Imports honor a belief budget (default 40 per source) in strict or truncate mode.

Designed, not built — do not assume

  • Patch bundles: uncommitted changes do not travel as a three-way-merge bundle yet; the packet records per-file digests and a patch receipt reference only.
  • World-state sections: VCS head binding, environment fingerprint, running services, and last-check results have no wire fields yet.
  • Re-verification commands: anchors may carry a verifyCmd, but it is display-only — resume compares hashes, it never executes your command.
  • Human-edited packets: the specified reseal-on-edit mechanism is not implemented; treat any packet you did not mint as untrusted until signed verification says otherwise.
  • zephr pack / zephr unpack move a signed Memory Pack of a worktree's beliefs through the same format; zephr prove verifies a packet and emits a provenance assertion.
  • zephr continuity shows per-agent state and a convergence score.
  • Sync is the sibling capability: where continuity moves working state on demand, zephr sync keeps agent setup (MCP configs, rules, hooks, skills) reconciled across every client on the machine. Its verbs are status, push, adopt, watch, revoke, and reconcile — the exact command inventory is in the CLI reference.

Sources

  • openspec/specs/continuity/spec.md — the packet envelope, lifecycle, and designed-not-built markers.
  • packages/continuity-format/src/ — envelope, signing, alias map, import pipeline.
  • packages/cli/src/commands/handoff.ts, resume.ts — the shipped transfer surfaces.