Stop re-sending context. Reference it.
Persistent agents carry the same instructions, tool definitions, and history on every turn. Zumik turns the stable parts into opaque, tenant-safe handles you reference instead of retransmit, and keeps physical KV-cache details out of the API entirely.
A small set of formal objects with explicit invariants.
| Object | Prefix | Purpose |
|---|---|---|
| Artifact | art_ | Immutable content unit, a policy, tool bundle, document, or checkpoint. |
| Bundle | bnd_ | Immutable, ordered list of artifact references. Order is semantic and preserved. |
| Session | ses_ | Causal container for an agent workflow. Mutable metadata, not a cache entry. |
| Branch | br_ | Append-only event line within a session, with optimistic concurrency. |
| Event | evt_ | Immutable message, tool result, retrieval result, checkpoint, or note. |
| Snapshot | snp_ | Compiled, ordered logical state for a branch head, pins ordering and versions. |
Append-only history, explicit merges.
Branches are causal lines you can fork for speculative or alternative agent paths. Appends use optimistic concurrency, so two workers never silently clobber each other. Zumik never merges automatically, you choose a strategy: append a checkpoint, compact to a summary, rebase, or fork.
Branch a sessionPOST /v2/sessions/ses_…/branches/br_…/events
{
"expected_version": 17,
"expected_head_event_id": "evt_…",
"event": { "type": "tool_result", "content": "build green" }
}
# head moved? -> 409 branch_version_conflictThe rules that keep state trustworthy.
Artifacts and bundles are immutable after creation.
Public ids are opaque, random, and tenant-scoped.
A branch event has exactly one causal parent, except the root.
A snapshot pins ordering, artifact versions, prompt-compiler version, and branch head.
A response pins one snapshot and one model-alias release.
Purging an artifact increments a namespace generation, so stale cache entries cannot be resurrected.
These invariants are what let Zumik reuse state aggressively without ever leaking cache internals or risking cross-tenant correlation. Reuse is safe because the model is strict.
Stable first, dynamic last.
Zumik recommends a prefix-friendly ordering but never silently reorders semantically meaningful events. This order maximizes provider cache hits across every scheme.
- System policy
- Developer policy
- Stable tool bundle
- Response schema
- Stable tenant or workspace context
- Compacted checkpoints
- Ordered branch history
- Dynamic retrieval blocks
- Latest user input
- Latest tool result
Stateful sessions, answered.
How is a session different from a cache entry?
A session is a causal state container with a history, not a key/value cache record. Caching is an implementation detail underneath; sessions, branches, and snapshots are the stable, customer-facing model.
Why are handles opaque instead of content hashes?
Exposing raw content hashes would leak equality relationships across tenants, complicate deletion, and let re-uploaded content resurrect old cache links. Opaque, tenant-scoped ids avoid all of that.
How do concurrent appends stay safe?
Every branch append carries expected_version and expected_head_event_id. If the head moved, Zumik returns 409 branch_version_conflict instead of corrupting history. Merges are always explicit.
Does this lock me into a provider?
No. Logical state is independent of provider, model, and tokenizer. The same artifacts and bundles can materialize differently across backends without changing your handles.
Give your agents real, reusable state.
Create artifacts and bundles in minutes, reference them by handle, and stop paying to recompute the same context.