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.