Everything you needto run Zephr.

Clone the repository and build the workspace. Requires Node.js 24.x and pnpm; Linux x64 is the only CI-proven platform today.

git clone https://github.com/DigitalSoftDistribution/zephr.git
cd zephr
pnpm install --frozen-lockfile
pnpm --filter @zephr/protocol build && pnpm --filter @zephr/core build
pnpm --filter @zephr/mcp-server build && pnpm --filter @zephr/mcp build

The build produces apps/mcp/dist/main.js, which is the entry point your MCP client launches. There is no global install step and no published package, so the absolute path to that file is what you configure in the next section.

Add Zephr to your client's MCP server list. Claude Code reads this shape from its settings file; Cursor reads the same shape from its own MCP settings.

{
  "mcpServers": {
    "zephr": {
      "command": "node",
      "args": ["/absolute/path/to/zephr/apps/mcp/dist/main.js", "--stdio"],
      "env": {
        "ZEPHR_DB_PATH": "/absolute/path/to/zephr.sqlite"
      }
    }
  }
}

Both paths must be absolute. ZEPHR_DB_PATH is optional — without it the server falls back to an in-memory store, which is useful for a smoke test but discards everything when the process exits.

Destructive operations (zephr_admin purge and migrate) require a capability minted from ZEPHR_ADMIN_TOKEN. Without it, read-only stats still work and the destructive actions are refused.

Keeping the surface at eight names is deliberate. When a tool needs to do more, it gains an action enum or an optional argument rather than a sibling tool, so a client written against this contract keeps working as the product grows.

Zephr is a server, not a plugin. Every client above talks to the same stdio JSON-RPC process, and every capture is an explicit tool call the agent chose to make — there is no background indexer and no editor-state scraper.

That distinction matters most for Cursor, where the adapter ships as a first-party mapper package rather than something the editor bundles. An operator wires it into the process that brokers tool calls, and Zephr still never reads private editor state.

Retrieval and trust are separate concerns that meet at recall. Lexical and semantic search each produce a ranking; reciprocal rank fusion combines them. The trust layer then decides whether the fused result is answerable at all — and abstains when the evidence is missing, stale, or contradictory.

Because the two layers are separate, a retrieval improvement can never quietly weaken an abstention rule, and an abstention rule can never be satisfied by ranking a weak result higher.

Each constraint above is a present-tense fact, not a roadmap apology. They are listed here because a reader deciding whether to adopt Zephr needs them before the install step, not after it.

When one of these changes, the badge changes with it — and the change lands in the changelog with a real date and SHA.