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
| Surface | Tier | Residency | Notes |
|---|---|---|---|
zephr_remember (MCP) | core | resident | Capture, review, or mutate a governed cloud memory |
zephr_recall (MCP) | core | resident | Entry point of the recall ladder (Layer 1) |
zephr_timeline (MCP) | core | deferred | Layer 2: chronological session handles |
zephr_get_observations (MCP) | core | deferred | Layer 3: verbatim L0 by explicit ID |
zephr_why / zephr_verify (MCP) | search | resident / deferred | Provenance 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
- 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. - Extraction. Candidates are triaged and extracted into atomic beliefs. The triage gate drops the majority of episodes; task-specific claims are rejected.
- Anchoring. Beliefs bind to content-addressed anchors with ordered locators; binding verifies every anchor. Missing provenance quarantines the record — it cannot be promoted.
- 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.
- 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_unavailableresult, 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_statuswhere a readiness surface is bound.
For symptom → fix coverage, see Troubleshooting.