How it works
One session.Every boundary visible.
Follow one real session from source installation through cross-tool handoff. Each step below carries an artifact or a repository path — evidence at the boundary, not a picture of one. The core local journey is shipped; npm publication and the opencode adapter are still evolving.
Four boundaries, one session.
The four moments that carry evidence — install, admit, recall, handoff — are the ones where the session either gains or loses proof. Click a hotspot to jump to its section; the active hotspot follows you as you scroll.
Scroll-anchored overview of the four boundary moments this page walks through.
Build from source.
The designed entry point is a single command, but @zephr-ai/cli is not published to the public registry yet — npm returns 404. The build-from-source path beside it is the one that works today. Nothing else about the journey changes once the package publishes.
- 01
Clone
git clone …/zephr.gitSource tree available
- 02
Build
pnpm install --frozen-lockfileCLI and MCP server built
- 03
Connect
./packages/cli/bin/zephr connectClient configuration projected
Build from source
git clone https://github.com/DigitalSoftDistribution/zephr.git
cd zephr
pnpm install --frozen-lockfile
pnpm --filter @zephr-ai/protocol build && pnpm --filter @zephr-ai/core build
pnpm --filter @zephr-ai/mcp-server build && pnpm --filter @zephr-ai/mcp build./packages/cli/bin/zephr connectHonesty
@zephr-ai/cli is not published to npm. The public registry returns 404 for it. The one-liner npx @zephr-ai/cli connect is the designed entry point, shown here as a contract — not a working install path today.
Evidence: packages/cli/src/cli.ts · packages/cli/package.json
Illustrative example — not live data
Four clients, each with its own status.
Local mode can connect without signup; managed signup is live separately at app.zephr.ai. The adapter package existing does not mean the client is fully shipped — opencode is evolving, and the page says so.
Claude Code
shippedAdapter shipped; the CLI generates its mcpServers configuration. Inference stays on the host — your copy of Claude Code keeps its own model. Zephr adds memory + MCP.
packages/adapter-claude-code/
Cursor
shippedAdapter shipped; the CLI generates its mcpServers configuration. Inference stays on the host — your copy of Cursor keeps its own model. Zephr adds memory + MCP.
packages/adapter-cursor/
Codex
shippedAdapter shipped; the CLI generates its TOML mcp_servers configuration. Inference stays on the host — your copy of Codex keeps its own model. Zephr adds memory + MCP.
packages/adapter-codex/
opencode
evolvingAdapter written; conformance suite unfinished.
packages/adapter-opencode/
Immutable scope binding.
Admission happens before the first tool call, never on it. The connection is bound to one project, one repository, one worktree — immutably, for its whole life. The server derives scope from admission and rejects a mismatched worktreeId; request arguments do not widen the connection. Changing scope is not an edit — it requires a newly admitted connection with a new binding epoch.
Admitted
- installation
- one connection
- project
- billing-service
- repository
- origin/main
- worktree
- /home/dev/billing-service
- epoch
- 1 · immutable
Outside the binding
Refused
A sibling worktree on the same machine is not covered by this binding. The connection cannot read from it or write to it, and asking does not silently widen the scope.
- worktree
- /tmp/billing-hotfix
- verdict
- Outside the binding
Evidence: packages/core/src/admission.ts · packages/mcp-server/src/transport.ts
Illustrative example — not live data
The confirmation law.
The store enforces disposition rules, not the caller. Routine items may receive an automatic disposition only under user-defined rules and with a recorded reason. New, contested, or security-critical items wait for an authenticated human. Security-critical confirmation requires the stronger human path — an agent cannot self-confirm.
Store-enforced dispositions
- Routine — may receive an automatic disposition under user-defined rules, with a recorded reason.
- New or contested — wait for an authenticated human.
- Security-critical — require the stronger human path; an agent cannot self-confirm.
Capture record
- claim
- Auth is enforced in the gateway middleware, not per-route.
- source
- apps/gateway/src/middleware/auth.ts
- review state
- unreviewed — single source, no human confirmation
- reason
- routine · captured explicitly, not auto-disposed
Evidence: packages/mcp-server/src/tools/remember.ts · packages/core/src/identity/confirmation-facade.ts · packages/protocol/src/mcp-tools.ts
Illustrative example — not live data
A sourced answer, or an honest abstention.
Recall returns an answer with its sources, or it abstains and says why. The MCP surface totals 32 tools — 24 first-party plus 8 hosted metered. Semantic retrieval uses pgvector as primary. The 8 hosted tools are metered; the 24 first-party tools are not.
Query
“Where is auth enforced?”
Recalled claim
Auth is enforced in the gateway middleware, not per-route.
Source anchors
- apps/gateway/src/middleware/auth.ts L34–L71
- apps/gateway/src/server.ts L18–L24
Query
“What is the rate limit on the webhook endpoint?”
Serving mode
Unavailable — no answer is an answer.
Reason
Insufficient evidence — the one cited file changed since capture. Recall returns an explicit unavailable with that reason rather than guessing.
Evidence: packages/mcp-server/src/tools/ · packages/store-postgres/src/pg-backend.ts · packages/protocol/src/mcp-tools.ts
Illustrative example — not live data
A signed, one-time envelope.
A handoff serializes the claims, their source anchors, the review states, and the scope binding into one envelope and signs it. The receiving tool verifies the signature and the scope binding before it parses a single claim. A consumed envelope cannot be replayed.
Source tool
Claude Code session sealed
- payload
- 2 claims · 5 citations · 1 commit
- scope
- billing-service · origin/main
- signature
- Ed25519
- replay
- One-time — consumption is atomic
Destination tool
Cursor resumes the verified packet
The receiving client checks the signature, then the one-time destination code, then recomputes the manifest — all before any content is read. Same claims, same review states, same scope, same rules.
- review state
- Carried intact, origin recorded
- scope proof
- verified before parse
- tool contract
- mismatch downgrades visibly, never silently
- revoked
- a revoked handoff fails closed
Evidence: packages/continuity-format/src/import-pipeline.ts · packages/cli/src/commands/handoff.ts · packages/cli/src/commands/resume.ts · packages/cli/src/__tests__/handoff-resume.test.ts
Illustrative example — not live data
Walk it yourself.
No public signup exists. Local mode is free on one machine and needs no account — build from source and the journey above is the one you run. Or read the platform page for the architecture underneath it.