Zephr Docs

Workspaces

Zephr stores evidence in one SQLite file scoped by a project → repository → worktree hierarchy.

The hierarchy

  • Project — the top-level container, created with zephr-mcp project approve.
  • Repository — a repository bound to a project with path bind.
  • Worktree — an admitted working copy; a connection is bound to exactly one worktree at launch.

Admission binds to one worktree

The trusted launcher admits a connection to exactly one worktree before any tool call. Tool calls that pass a worktreeId outside the admitted scope are rejected with scope_violation. This is what makes memory reliable per working copy — an agent cannot read or write beliefs that belong to a different checkout.

Relationship to the database

The store, the read view, and the admin capability are separated per ADR-Z-02. The single SQLite file holds the full hierarchy; destructive operations (zephr_admin purge, migrate) require a minted ZEPHR_ADMIN_TOKEN capability.

See Connect your client for the exact launcher commands.