Zephr Docs

The product circuit

The architecture page summarizes the core mechanisms; this page shows how the capabilities connect as one circuit, and which parts ship today.

flowchart LR
    subgraph surfaces[Surfaces]
        CLI[zephr CLI]
        MCP[MCP server - zephr-mcp]
        D[zephrd daemon]
    end
    subgraph core[Memory core]
        C[Capture] --> M[Belief store L0-L2]
        M --> R[Retrieval: fusion + scope]
        R --> T[Trust gate]
        T -->|disclose or abstain| surfaces
    end
    C2[Continuity packets] --> M
    S[Sync engine] --> M
    P[Platform: tenancy, admission, storage] -.underpins.-> core

How the capabilities connect

  • Capture feeds memory: explicit zephr_remember calls and passive producers write observations; extraction promotes the durable ones into beliefs. The write path is a maintenance discipline, not a dump — see Beliefs for what it produces.
  • Retrieval is the read path: hybrid lexical + semantic search fused by reciprocal rank, then gated by trust before anything is disclosed.
  • Trust decides what an agent may act on. It can only ever narrow retrieval, never broaden it — Trust has the mechanisms.
  • Surfaces (CLI, MCP server, daemon) are the only doors. Every client talks to the same process, and every capture is an explicit tool call — see Clients.
  • Platform underpins every row: tenancy, identity, admission, storage, encryption, migrations. It owns no product semantics of its own — it guarantees that a row you read belongs to you, was admitted by a live credential, and can be destroyed on request.

The two planes

Every component runs in one of two planes, drawn exactly on Local and cloud: the local plane (MCP server over stdio, single-file SQLite store, CLI, zephrd daemon — no network egress in the default configuration) and the cloud plane (the /api/cloud application layer, managed Postgres with forced row-level security, envelope encryption, workers).

What ships, what is designed

The circuit is honestly uneven, and the capability map (openspec/CAPABILITIES.md) marks the uneven rows. In brief:

  • Shipped and load-bearing — local admission and scope binding, the belief store with version chains, hybrid recall with rank-only fusion, the review state machine, sync reconciliation, and the continuity packet format.
  • Designed, not built — cloud credential middleware, reranking, query-understanding, and dedicated-org provisioning. Pages in this section label designed items inline rather than implying they run.

The per-capability build states live in openspec/CAPABILITIES.md; the status page summarizes the user-facing parts.

Invariants worth knowing

Three invariants explain most of the circuit's shape, each carried by the platform baseline:

  1. Postgres (or the local store) is the only authority. A vector index or a cache is an optimization, never a source of truth; every vector hit is re-authorized before disclosure (spec: "Postgres is the only authority and every vector hit is re-authorized before disclosure" — enforced in crates/zephr-cloudd/src/query_joinback.rs).
  2. Local mode is a capture edge, never a second authority (spec: "Local mode is a capture edge and a compile target, never a second source of truth").
  3. TypeScript owns customer authority; Rust owns the data plane and never terminates customer trust (platform spec requirement of the same name, marked SATISFIED as designed and as built; the Rust roles wire only project/query duties in crates/zephr-cloudd/src/role.rs, everything else runs idle).

Sources

  • openspec/CAPABILITIES.md — the 55-capability map and honesty deltas.
  • openspec/specs/platform/spec.md — the foundation requirements quoted above.
  • packages/*/package.json — component names and binaries.