Zephr Docs

Your first recall

Once your client is connected and admitted to a worktree, the core loop is two tool calls: capture a belief, then retrieve it.

1. Capture — zephr_remember

zephr_remember captures an unreviewed belief with provenance, or uses the local review capability to confirm or reject its current open version. An agent records what it has learned with the source and anchor it came from.

2. Retrieve — zephr_recall

zephr_recall retrieves eligible belief versions via hybrid lexical + semantic search (SQLite FTS5 for lexical, sqlite-vec for semantic, fused by reciprocal rank). It returns ranked items with a final score and contradiction belief IDs.

3. Explain — zephr_why

zephr_why explains a belief version: its content, kind, review state, validity, version count, worktree-scoped relationships, and provenance when recorded.

What you should observe

  • Recalled beliefs carry a provenance chain, not bare text.
  • Recall surfaces only eligible states — by default confirmed and valid beliefs — and abstains rather than guessing when evidence is missing, stale, or contradictory.
  • The Trust Firewall (zephr_rules) can only narrow retrieval, never broaden it.

Smoke test without persistence

If you omit ZEPHR_DB_PATH, the server falls back to an in-memory store — fine for a smoke test, but everything is discarded when the process exits. Use a real file path for any work you want to keep.

Next

Read Beliefs to understand review states and version chains, or the MCP tools reference for the quick-start subset and generated inventory.