Zephr Docs

Data lifecycle

Zephr's data model makes safe backups and deletions possible because its writes are append-only and verifiable: beliefs are revised, never mutated; every durable mutation goes through the store contract. This page is the operator's map of retention, backup, export, restore, deletion, schema migrations, and crash recovery.

The store file

The store is a single SQLite file (WAL journaling, mode 0600 with its -wal/-shm siblings) at the path your configuration selects — see Configuration. A plain server process without ZEPHR_DB_PATH falls back to an in-memory store that discards everything at exit; the trusted launcher falls back to the platform data directory instead.

Retention and decay

  • Decay never deletes. Memory and trust decay change visibility and ranking eligibility only. No decay threshold drops provenance, makes history unreachable, or removes a belief.
  • Physical garbage collection is a separate, gated operation. It requires dormancy, absence of dependents in the justification graph, a retention floor, nuance-carrier status, and a legal-hold check.
  • Share links expire. zephr share mints a signed, read-only URL for a memory excerpt with a default 7-day TTL (maximum 365 days). Sharing is not a backup.
  • Hosted surfaces follow the hosted plane's retention rules. If a hosted surface holds the only copy of something you care about, export it to a packet you own.

Backup

Verified recovery snapshots

The on-box tooling creates verified recovery snapshots: a WAL-consistent copy is written, its integrity and schema are checked against the live store, and only then is it published atomically beside the store as <name>-zephr-snapshot.db with a .ready.json sidecar. A published snapshot is never overwritten — a second snapshot attempt refuses rather than clobbering the first.

Snapshots happen automatically before every store schema migration through the upgrade path. If the snapshot cannot be created, the migration refuses to start and the store is not modified; if the migration then fails, the snapshot is preserved for repair.

Portable signed exports

For a backup you can move between machines or restore into a fresh installation, export a signed packet:

CommandWhat it producesWhere it works
zephr pack <worktreeId> <outputPath>A signed Memory Pack of a worktree's beliefs and edges (Ed25519 signature over canonical JSON)Needs your account to fetch the worktree state
zephr handoff <worktreeId> --file <path>A self-contained, signed Continuity v1.1 handoff packet file (mode 0600)Needs your account for the source state
zephr receipts export --out <path>The installation's audit receipts as a JSON bundleLocal-only — reads the local receipt store
zephr prove <packet.json>Verifies a packet and emits a JSON provenance assertionLocal-only

Exports are honest audit trails: refused imports (those that did not verify a full chain) are included in receipt bundles rather than hidden, so a receipt export can show imports that failed verification — it never papers over the mismatch.

Restore

  • Memory Pack import — zephr pack import <file> [scope] --trust-signer <sha256:fingerprint> (the unpack verb routes here). Import verifies the Ed25519 signature and the signer fingerprint you pinned, then consumes the pack atomically and exactly once — a consumed pack is not replayable — importing each belief through the everyday store write boundary.
  • Handoff import — zephr resume <claim-code|packet-id|file-path> runs the shared ordered import pipeline (authenticate-before-parse → consume-once → scope proof → review-state rules → revalidation anchors → signed transfer receipt). A file path is read directly and offline; a claim code is redeemed locally and is single-use.
  • Snapshot restore — recovery snapshots are the file-level restore path after a crash or failed migration.
  • Verification — zephr prove <packet.json> verifies a Continuity packet and emits a JSON provenance assertion. It is explicitly not a C2PA-certified or C2PA-conformant manifest — an honest alignment claim, not a certification claim.

Success output is explicit: pack import prints Imported pack <packId> into worktree <targetWorktreeId>, handoff writes Handoff packet written to <path> and tells the recipient to run zephr resume <path>.

Schema-migration safety

Schema migrations are forward-only and there is no rollback path — the discipline exists so the schema stays honest. What protects you:

  • Migrations apply on open, ordered by a checksummed manifest.
  • A verified recovery snapshot is created before migrating (see above); failure to create it means the store is not modified.
  • Failure is loud: a failed migration does not half-apply, and repair starts from the preserved snapshot.

Because migrations are forward-only, "roll back an upgrade" means restore the recovery snapshot — never open a migrated store with an older binary and treat that as a rollback. zephr upgrade --check reports whether a newer zephrd release exists and never downloads; a real self-update is not implemented.

Delete

Deletion semantics differ by surface — this table is the rule:

SurfaceDelete meansHow
Memory (belief)Tombstone the active versionUpdate appends an immutable revision; delete tombstones. The chain stays verifiable — history is not physically removed
Memory (physical)Purgezephr_admin purge is an MCP action requiring both the operator-set token and trusted user presence. Local stdio has no presence binding and refuses it; use zephr memory retract <id> or zephr files rm --id <id> locally, or export then zephr uninstall --force for full local removal
FilesGoverned erasezephr_files rm (CLI zephr files rm --id <id>) — tenant-scoped, recorded
Beliefs of a principalRetractzephr memory retract <id>; zephr continuity retract <id> retracts across agents
Whole installationUninstallzephr uninstall (below)

zephr uninstall

zephr uninstall removes local Zephr data while preserving SQLite backups:

  • It removes the ~/.zephr config directory (credentials, pack key, pack-consumed registry) and the project-local .mcp.json Zephr entry.
  • SQLite files (.db, .sqlite, .sqlite3) present in the config directory are preserved, and the config directory itself is kept if only backups remain.
  • It is a dry run by default: it prints what will be removed and what will be preserved, then tells you to run with --force to execute. --keep-mcp leaves .mcp.json untouched.
  • The final message reports the counts: "Uninstalled. Removed N file(s), preserved N SQLite backup(s)."

The daemon binary is a separate artifact and is not removed by zephr uninstall.

Crash and store recovery

The store uses SQLite WAL journaling with normal synchronous durability. What the crash guarantees are, and are not:

  • Mid-write crashes are atomic. A belief interrupted mid-write is either fully committed or fully absent — never partial or corrupt.
  • WAL corruption does not crash the process. The store either opens cleanly (WAL recovered) or reports a specific integrity error.
  • Concurrent writes plus a crash do not duplicate. Writes are idempotent through the store contract.
  • Restore from the verified recovery snapshot when a store must be recovered.

Never hand-edit the SQLite file, its -wal/-shm siblings, or a snapshot while a process may hold the store — the store contract is the only writer, and the file permissions exist to protect it.

After an interrupted compaction the daemon decides recovery from its durable pre-compact seal, never by guessing: a complete seal means it re-scores a subset of handles from it; a missing or incomplete seal means it reinitializes from the authoritative store. Do not delete or hand-edit seal files to "force" a path.

Export before you delete

The ordering rule: export before you delete. A tombstoned belief or an erased file is not recoverable through the product; a consumed pack is not replayable. When in doubt, export first with zephr pack or zephr handoff --file, then act on the deletion path you intend.