ZMem Docs

Build a private summary, inspect its live lineage, then explicitly admit or discard it.

ZMem can turn a reviewed live-memory source set into a deterministic summary without silently changing agent memory. The complete flow is explicit: preview a source set, materialize a private review copy, inspect it against live receipts, then admit or discard it.

Run A Preview

zmem consolidation preview \
  --scope project \
  --min-sources 3 \
  --summary-only

Use --out preview.json to retain the full zerker.live_consolidation_preview.v1 report. Existing files require --force, and written reports use mode 0600.

What Becomes A Source

A source is included only when all of these are true:

its scope exactly matches --scope;
its status is active;
its type is episodic or semantic;
it has origin actor, environment, and session provenance;
its complete write-receipt chain verifies;
its latest memory event is covered by that receipt chain;
its current type, scope, source kind, trust, authority, status, and content still agree with those receipts.

Included sources are grouped by the exact origin actor, environment, and session tuple. A group becomes ready-for-review when it reaches --min-sources; smaller groups remain visible as waiting.

What The Report Proves

The report contains:

the verified event Merkle root;
exact source memory ids;
source content digests, receipt ids, and receipt hashes;
a deterministic source-set hash and candidate id;
a stable source-set preview identity;
a separate confirmation identity bound to the database path and evaluation time;
the weakest source trust and authority ceilings;
explicit omitted memory ids and reason codes.

It does not contain raw memory text.

Confirm One Candidate

Review the preview's confirmation_id, the selected candidate_id, its source ids, omissions, and weakest-source ceilings. Then materialize exactly that pair:

zmem consolidation materialize preview.json \
  --select <candidate-id> \
  --actor-id <operator-id> \
  --confirm-preview <confirmation-id> \
  --summary-only

The operator id is recorded audit metadata; this command does not authenticate that identity. The confirmation id prevents a reviewed preview from being silently retimed or pointed at a different database.

Materialization:

holds the SQLite writer lock while reading through a query-only snapshot, so source state cannot change during commit;
re-verifies the event root, source receipts, current rows, exact candidate, and content digests;
writes one pending/completed job transition and one summary to private append-only ledgers;
binds the completed job to the summary content digest, source digests, review, admission contract, and preview confirmation;
starts the summary quarantined at trust 0 and authority none;
locks both ledgers across local processes, is idempotent on replay, and repairs an interrupted trailing fragment only after recording a durable local recovery receipt.

By default, the ledgers live beside the database under consolidation/jobs.jsonl and consolidation/summaries.jsonl. The summary ledger contains the local summary text and is created with mode 0600; the compact result artifact contains hashes and metadata rather than source or summary text.

Audit The Ledgers

zmem consolidation audit --summary-only

Audit fails on pending or incomplete jobs, missing or orphan summaries, duplicate summary records, invalid job histories, changed content, broken preview/admission/review bindings, or a summary that no longer matches the content digest committed by its job.

Inspect The Review Queue

List summaries without printing their private text:

zmem consolidation inspect --summary-only

Inspect one exact summary and retain its mode-0600 review artifact:

zmem consolidation inspect <summary-id> \
  --out inspection.json \
  --summary-only

Inspection audits the ledgers, verifies every current source receipt chain, checks that each source is still active and unchanged, and independently recomputes the deterministic summary from live source text. The resulting zerker.consolidation_inspection.v1 artifact binds the database, job and summary records, source heads, content digest, weakest-source ceilings, and deterministic canonical target. It contains the private summary text, so keep it private.

The reported operator identity is not authenticated. The confirmation proves which local artifact was reviewed, not who controlled the terminal.

Admit Or Discard

To make the reviewed summary available as canonical memory:

zmem consolidation admit inspection.json \
  --actor-id <operator-id> \
  --confirm-inspection <confirmation-id> \
  --summary-only

Admission is the only command in this flow that writes canonical memory. It creates one deterministic active semantic memory, keeps the exact source ids as parents, binds parents and labels into its write receipt, and uses the recorded weakest-source trust and authority ceilings. It does not call the generic promotion path or raise either ceiling. Normal policy still decides whether the admitted memory may enter a later agent context.

To reject the private summary without deleting its evidence:

zmem consolidation discard inspection.json \
  --actor-id <operator-id> \
  --confirm-inspection <confirmation-id> \
  --reason "Not useful for future recall" \
  --summary-only

Admission and discard are terminal, mutually exclusive decisions recorded in the local Merkle event chain. Exact replay is idempotent. A changed summary, source receipt head, source status, audit record, target, database binding, or confirmation fails before mutation. Discard writes no canonical memory and deletes no source, ledger, or summary evidence.

After admission, use the normal receipted lifecycle to remove the canonical memory:

zmem revoke <canonical-memory-id> --reason "No longer valid"

Safety Boundary

The preview and inspection are read-only. Materialization writes only private consolidation ledgers and a compact result artifact. None of those commands writes a canonical memory row, changes retrieval, promotes trust, grants authority, or injects the summary into an agent context. Only an exact admit confirmation crosses that boundary. Policy and procedural memories are excluded because lossy summarization must not silently rewrite instructions or authority.

A materialized summary uses this output contract:

non-blocking and reversible;
initially quarantined with trust 0 and authority none;
no canonical-memory write without a separate confirmed admit action;
trust and authority no higher than the weakest source.

This is source admissibility and transition integrity, not a semantic-truth judgment. A verified source or deterministic summary may still be wrong.

The ledgers, inspections, receipts, and decision events are private local proof. They detect ordinary corruption and inconsistent transitions; they do not defend against a principal who can replace the database and every local artifact, then recompute every hash. That stronger boundary requires an external signature or Treeship anchor. Treeship anchoring is not automatic in this review loop, and neither local nor external proof establishes semantic truth.

Consolidation Review