Zephr
Read the quick start
Developers / Docs

Install it, point a client at it, read the contract.

The MCP tool surface, the client configuration, the architecture decisions behind it, and an explicit list of what is not built.

29 tools · names frozen
Build from sourceLinux x64Managed cloud — open signup
Doc index

Every surface, with a liveness dot.

The sections below are the committed documentation, indexed here with the build SHA they were produced from and the date each file was last edited. A drift dot is derived from that date — fresh means edited recently, stale means re-check before quoting.

Doc index · live surfaces

build SHA · 47f0f28f61d94e2c176369c86521b9845bebef6f

● fresh◐ stalerecency from committed file mtimes — not a content review

Liveness is derived from committed file metadata at build time — not a live-service health check.

Install

Build from source

@zephr-ai/cli is not on npm yet. The honest path today is a source build — five lines, one toolchain. The npx @zephr-ai/cli one-liner is the designed entry point and is badged not-yet-published beside it.

Why from source

A registry one-liner would imply a package that is not published. The CLI and client adapters are real; npm distribution is not yet published. The current path keeps those facts separate.

Source build · 5 lines

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

illustrative command sequence — seepackages/cli for the real one

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

Needs Node 20+, pnpm 11, and a working Rust toolchain for the optional daemon. Linux x64 is the only CI-proven platform.

Designed entry point · not yet published

One line, when it is on npm.

The npx @zephr-ai/cli one-liner is the designed entry point. It is badged not-yet- published today; build from source until the package ships.

Not on npmbuild from source today

Designed entry point · not yet published

npx @zephr-ai/cli connect

The CLI has 42 command modules under packages/cli/src/commands/. A few you will reach for first:

  • zephr connect

    Cold start: auth, project, admission, MCP config, recall

  • zephr login

    Authenticate through the RFC 8628 device flow

  • zephr status

    Show connection and active role state

  • zephr health

    Check the daemon and the MCP handshake

  • zephr recall

    Run a recall against your memories from the terminal

Configure

Point a client at it

The CLI detects and writes the config for the clients already on your machine. Claude Code, Cursor, and Codex adapters are shipped; opencode conformance is in progress; any MCP client works over stdio in the meantime.

  • Claude Code

    Adapter shipped

    JSON · mcpServers

    The reference client. `zephr connect` detects and writes the mcpServers block.

  • Cursor

    Adapter shipped

    JSON · mcpServers

    Library, not an editor integration — the rules and MCP config are written for you.

  • Codex

    Adapter shipped

    TOML · mcp_servers

    OpenAI Codex CLI. TOML dialect, written to ~/.codex/config.toml.

  • opencode

    Conformance in progress

    JSON · mcp

    Conformance against the contract is in progress; any MCP client works over stdio.

Tool contract

The 32-tool MCP surface

24 first-party core tools plus 8 hosted metered extras. Names are frozen; every tool has bounded inputs, structured errors, and provenance on the read path. Grouped here by tier — never reported as eight.

Core · Memory

First-party · shipped
  • zephr_rememberCapture a belief with provenance and confidence.
  • zephr_recallRetrieve memories by lexical + semantic rank.
  • zephr_whyShow the provenance chain behind a recalled belief.
  • zephr_verifyRe-validate a belief against its source anchor.
  • zephr_sessionRead and resume a session by id.
  • zephr_rulesRead the active hook + scope rules for this binding.
  • zephr_statusReport connection, role, and daemon health.
  • zephr_adminOperator-only: install scope, revoke, rotate keys.

Core · Search

First-party · shipped
  • zephr_searchSemantic codebase search over the indexed ref.
  • zephr_grepLexical ripgrep over the indexed ref.
  • zephr_lspStructural code navigation via LSP symbols.

Core · Docs + Graph

First-party · shipped
  • zephr_docsProject docs catalog with freshness signals.
  • zephr_graph_queryEntity-relation edge graph (indexed layer).
  • zephr_sync_statusReport workspace sync state + drift.

Core · Review

First-party · shipped
  • zephr_review_usageMetered review usage read.
  • zephr_reviewLLM-augmented governed review surface.

Hosted · Metered extras

Hosted · BYOK metered
  • context7_callCurated library docs lookup.
  • firecrawl_scrapeWeb scrape to clean markdown.
  • tavily_searchWeb search with ranked snippets.
  • browser_renderHeadless browser render of a URL.
  • sentry_queryProduction error stream query.
  • github_apiGitHub REST/GraphQL passthrough.

Tool names read verbatim from packages/protocol/src/mcp-tools.ts · 32 total

Architecture

The decisions behind the contract

Zephr is not a coding agent, scope is immutable, and memory is bi-temporal. The ADRs are text references here, not dead links — read them in the repo at docs/architecture/.

ADR-Z-01Zephr is not a coding agent
Zephr is continuity infrastructure. It captures and recalls; it does not write your code.
ADR-Z-06Scope binding is immutable
A tool call outside the admitted scope is refused, and the refusal is auditable.
ADR-Z-08Memory is bi-temporal
Beliefs revise rather than overwrite; the superseded record stays readable.
ADR-Z-09Immutable MCP scope binding
The scope a client was admitted under is frozen for the life of the binding.

See the platform page for the full system, and /platform for the product-cluster map. Qdrant is retired; pgvector is the primary vector engine.

Limitations

What is not shipped yet

Every entry below is badged with the honest status — not a quiet omission. The npm package, the managed cloud, the Windows/macOS CI, and the opencode conformance are the real gaps.

  • npm distribution

    Not on npm

    @zephr-ai/cli is not published to npm yet. The npx @zephr-ai/cli one-liner is the designed entry point, badged not-yet-published; build from source today.

  • Managed cloud

    Open signup

    Signup is open at app.zephr.ai — create an account, no invite required. Local self-host needs no account and runs on your own infrastructure.

  • Platform support

    Linux x64 only

    Linux x64 is the only CI-proven platform. Windows and macOS are not blocked, but are not CI-proven.

  • opencode adapter

    Conformance in progress

    Claude Code, Cursor, and Codex adapters are shipped. opencode conformance is in progress; any MCP client works over stdio in the meantime.

Close

Walk the whole journey.

The step-by-step guide takes you from a clone to a signed handoff, and the trust page shows the evidence behind every claim on this site.

See how it worksRead the trust model →