Zephr Docs

Architecture

Zephr's architecture is documented in the ADRs and design docs under docs/. This page is the documentation-site landing that links them.

Core mechanism

  • Hybrid retrieval — SQLite with FTS5 for lexical search and sqlite-vec for semantic retrieval, fused by reciprocal rank.
  • Provenance chain — every recalled belief carries a full provenance chain and bi-temporal recording; recall abstains rather than guessing.
  • Separated capabilities — the store, the read view, and the admin capability are separated per ADR-Z-02; destructive operations need a minted capability.
  • Scoped by worktree — one SQLite file holds a project → repository → worktree hierarchy. The launcher admits a connection to one worktree before any tool call.

Repository structure

PathRole
packages/protocolMCP tool contracts (mcp-tools.ts) + canonical catalog (catalog.ts)
packages/mcp-serverThe MCP server library (main() in cli.ts, stdio transport)
apps/mcpThe public zephr-mcp binary (@zephr-ai/mcp)
packages/coreStore, admission, lifecycle, version-chain, Trust Firewall
packages/evalsTrustBench evaluation suite (@zephr-ai/evals)
docs/Full engineering docs (audits, trust, security, operations, clients)

Design docs

  • App architecture — docs/design/app-architecture-2026/ (clusters: foundations, codebase, knowledge, operations, job runtime, local gateway, CLI, protocol, assurance, evals, admin).
  • ADR index — see docs/architecture/adr/ (generated catalog; ADR-Z-09 covers admission scope, ADR-Z-11 the local gateway, ADR-Z-17 integrations, ADR-Z-20 the docs catalog).

Key invariants (do not regress)

  • Single catalog — every MCP edge advertises tools from packages/protocol/src/catalog.ts; no hardcoded tool lists elsewhere.
  • CI-asserted surface — scripts/check-mcp-tool-invariant.mjs + scripts/tier-manifest.json enforce the registered tool surface with matching descriptors.
  • Admission-scope enforced — non-admitted worktreeId → scope_violation.