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
| Path | Role |
|---|---|
packages/protocol | MCP tool contracts (mcp-tools.ts) + canonical catalog (catalog.ts) |
packages/mcp-server | The MCP server library (main() in cli.ts, stdio transport) |
apps/mcp | The public zephr-mcp binary (@zephr-ai/mcp) |
packages/core | Store, admission, lifecycle, version-chain, Trust Firewall |
packages/evals | TrustBench 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.jsonenforce the registered tool surface with matching descriptors. - Admission-scope enforced — non-admitted
worktreeId→scope_violation.