Receipts

Receipts are the core ZMem wedge. A memory system that only retrieves facts can be useful; a memory system that proves what influenced an action can be trusted, debugged, benchmarked, and audited.

Action Explanation

After zmem inject returns an action id:

zmem why <action-id>
zmem verify <action-id>

Memory Context Commitment

Every new inject receipt carries a compact zerker.memory_context.v1 commitment. Its sha256: digest binds the task and agent identifiers, policy digest and decisions, retrieved/admitted/withheld/budget-dropped ids, temporal envelope, memory Merkle roots, and the exact memory records supplied as ZMem context.

zmem inject --summary-only and zmem why <action-id> --summary-only show the commitment. zmem run also writes the full context artifact to ZERKER_MEMORY_CONTEXT and exposes the matching digest as ZERKER_MEMORY_CONTEXT_DIGEST.

Retain a context with zmem run --context-path <file> ..., then verify it locally or after handoff:

zmem context verify <file> --summary-only

Changing the context artifact causes verification to fail. The commitment proves the ZMem context supplied at the decision boundary; it does not prove semantic truth, hidden model reasoning, or provider prompt material outside that artifact.

Receipt Bundle

zmem bundle <action-id> --out-dir .zerker/exports
zmem bundle verify .zerker/exports/<bundle>.bundle.json

A receipt bundle proves which governed memories were available before the action and whether their supporting write events belong to the event log committed by the action receipt.

New bundles use zerker.receipt_bundle.v2. They include the bundle hash, action receipt, supporting memories and write receipts, a commitment to the complete pre-action event log, and compact Merkle inclusion witnesses for the supporting write events and final pre-action event. They do not repeat every historical event payload.

Older zerker.receipt_bundle.v1 artifacts remain verifiable. V1 embeds the full pre-action event list; v2 is the default for CLI exports, handoffs, Treeship statements, and normal benchmark artifacts.

The proof verifies inclusion, lineage, and tamper evidence relative to the receipt root. It does not claim that remembered content is semantically true.

Treeship Statement

zmem export <action-id> --format treeship --out-dir .zerker/exports
zmem treeship doctor
zmem treeship publish <action-id> --dry-run --command-template "treeship prove {statement} --action {action_id}"

The Treeship export is a portable statement derived from a verified receipt bundle. For new receipts it includes the compact memory-context and policy digests, without adding raw context to the commitment. It records enough evidence to make the proof shareable without turning local memory into a hosted dependency.

Write Attestation

For deployments that want every write to be signed as it happens, initialize Treeship locally and enable automatic write attestation:

export ZMEM_TREESHIP_AUTO_SIGN=1
export ZMEM_TREESHIP_CONFIG=/path/to/treeship/config.json

Each memory write still stores the local ZMem receipt and Merkle lineage. When signing is enabled, ZMem asks Treeship to attest only the compact sha256:<receipt_hash> digest as system://zmem / kind=memory.write, then stores the returned artifact id and signed timestamp with the write receipt. Raw memory content is not duplicated into the Treeship attestation.

New write receipts also commit the memory's exact parent ids, labels, and canonical digests for both lists into the source event and Treeship statement. Receipt-chain verification compares those fields with the current memory row, so out-of-band lineage edits fail verification. Older receipts remain verifiable under their original contract when those additive fields are absent.

Set ZMEM_TREESHIP_STRICT=1 when an environment should fail the write if Treeship signing fails.

The consolidation review loop deliberately commits its local admission and discard decision before any external work. Treeship anchoring is therefore separate rather than automatic for that loop; the local decision result reports treeship_anchor_status: not_requested.

Provenance Direction

The next security demo should make write provenance vivid: inject a poisoned memory, let an agent act on it in a later session, then walk the receipt chain back to the source session and tool call that introduced the belief.