Zephr Docs

Memory

Memory owns the write path and lifecycle of Zephr's belief base: how observations enter the system, how they are triaged into atomic beliefs, anchored to code, consolidated, disputed, revised, and retired. Memory is maintained as a belief base — with justifications, provenance, and disputes — not a store to be cleaned. Read-side ranking and abstention live in Retrieval; review state lives in Trust.

Availability

SurfaceTierResidencyNotes
zephr_remember (MCP)coreresidentCapture, review, or mutate a governed cloud memory
zephr_recall (MCP)coreresidentEntry point of the recall ladder (Layer 1)
zephr_timeline (MCP)coredeferredLayer 2: chronological session handles
zephr_get_observations (MCP)coredeferredLayer 3: verbatim L0 by explicit ID
zephr_why / zephr_verify (MCP)searchresident / deferredProvenance and version-chain integrity
zephr remember, why, verify, timeline, observations, memory, pack, unpack (CLI)——See the CLI reference

Full parameter detail: MCP tools.

How it works

  1. Capture. Every write — passive producers, zephr_remember, CLI paths — transits the capture lattice (L0/L1) or a documented explicit-capture surface. A write that reaches L2 without transiting the lattice is rejected and recorded as a capture-policy violation.
  2. Extraction. Candidates are triaged and extracted into atomic beliefs. The triage gate drops the majority of episodes; task-specific claims are rejected.
  3. Anchoring. Beliefs bind to content-addressed anchors with ordered locators; binding verifies every anchor. Missing provenance quarantines the record — it cannot be promoted.
  4. Promotion. L0→L1, L1→L2, and L2→L3 each require distinct evidence, not restatement, and every promotion is recorded as a revision with an explicit reason. Agents never self-confirm a promotion.
  5. Lifecycle. Consolidation, contradiction tracking, and revision append immutable revisions; delete tombstones the active version.

Layered taxonomy and status

Seven ordered layers, each with its own retention policy, retrieval eligibility, and promotion gate:

  • L0 observation ledger, L1 capture candidates, L1.5 salience, L2 atomic belief — shipped (schema migration 0025).
  • L3 derived consolidation, L4 working set, L5 policy memory — planned. Consumers get an explicit layer_unavailable result, never a silent substitution with L2 beliefs.

Two honesty notes. L0 is verbatim and non-retrievable — it crosses the trust boundary into agent context only via Layer 3 (zephr_get_observations), only for IDs the caller already holds, and reports missing rather than fabricate. And live capture is wired but partial: the 2026-08-17 wiring audit (ZEP-1975) found the passive producers disconnected, and ZEP-2007 closed that for the lifecycle host — admitted tool events now flow through the governed L0 producers (toolstream tap + edit provenance), bounded by a per-session ledger budget, and session-boundary events are drained from the daemon hook spool via zephr hook drain. When a readiness surface is bound, zephr_status reports per-producer readiness (ready | degraded | absent), and producers with no wired client seam still report absent — passive capture is real on the wired seams, not universal.

Data flow and persistence

Capture → L0 → gated promotion → L2 belief → read via retrieval. Storage topology (local SQLite, cloud Postgres) and the replication story are covered in Architecture; note that local stores are not encrypted by Zephr at rest. zephr pack exports a signed Memory Pack of a worktree's beliefs and zephr unpack verifies and imports one — the supported export/recovery path.

Observability

Every L0 observation records a provenance atom (tier, actor, session, workspace context, source span, extractor name + version + prompt hash, observed timestamp), so any belief can be traced back to what produced it. Revisions are appended with change reasons; capture-policy violations are recorded, not dropped.

Limits and failures

  • Layer 1 recall rows are compact (~50–100 tokens) by design; full content requires the explicit Layer 3 handle.
  • Restatement by the same extractor does not satisfy the distinct-evidence promotion requirement.
  • Observations lacking actor or source span are quarantined and cannot be promoted.
  • A write bypassing the lattice is rejected and recorded as a capture-policy violation — it never lands, and the violation is producer telemetry, not a daemon log to consult. Operational visibility is the producer-readiness report in zephr_status where a readiness surface is bound.

For symptom → fix coverage, see Troubleshooting.