Zephr Docs

Claude Code memory plugin

Distribution status: sideload (experimental developer preview). This plugin is not yet published to Anthropic's public plugin directory or signed via sigstore. Status: scripts/host-plugin-status.json -> claude-code: sideload.

Prerequisites & Availability: This guide documents the native host plugin architecture and proxy runtime (T-4054). Running the complete proxy binary workflow requires PR #2025 landed on main, or a checkout of branch feat/T-4054-claude-plugin-manifest-hooks alongside this guide (PR #2026). The proxy binary (zephr-memory / zephr-memory-mcp) does not yet exist on main; current main provides standard sideload via claude --plugin-dir ./extensions/claude-code or direct MCP execution via npx @zephr-ai/mcp.

The Claude Code memory plugin connects Claude Code directly to Zephr's memory kernel via an MCP facade and lifecycle hooks.


1. Installation

The installation workflow follows the standard Claude Code plugin architecture:

Step 1: Add the marketplace

Register the marketplace source once with Claude Code:

claude plugin marketplace add ./

Step 2: Install the plugin (marketplace-qualified)

Install with the marketplace-qualified identifier:

claude plugin install zephr@zephr-host-plugins

(Or in session: /plugin install zephr@zephr-host-plugins)

Step 3: Authenticate

Authenticate through the plugin proxy (planned architecture; current sideload onboarding uses zephr login / npx @zephr-ai/cli project approve):

${CLAUDE_PLUGIN_ROOT}/bin/zephr-memory auth login
  • No shell profile edits: No entries in ~/.zshrc or ~/.profile.
  • No background daemons: No launchctl service or systemd daemon required.
  • Zero secrets in config: .mcp.json runs ${CLAUDE_PLUGIN_ROOT}/bin/zephr-memory-mcp with no plaintext tokens or secrets.

2. Rollback & kill switch

Instant local kill switch

Create the sentinel file ~/.zephr-memory/OFF:

touch ~/.zephr-memory/OFF
  • All lifecycle hooks exit 0 with empty output.
  • Facade tools return { "error": { "code": "disabled" } }.
  • Zero network requests are initiated.
  • Remove ~/.zephr-memory/OFF to re-enable.

Re-enabling mem0

  1. Touch the kill switch: touch ~/.zephr-memory/OFF
  2. Re-enable mem0 in your client configuration.
  3. Restart your Claude Code session.

3. Troubleshooting & GUI-env traps

  • Dock-launched Cursor / IDE empty ${VAR}: GUI applications launched via macOS LaunchServices do not inherit shell environment variables. Credentials resolve from the system credential store (macOS Keychain service zephr-memory), and binary paths use ${CLAUDE_PLUGIN_ROOT} rather than relying on PATH. Check status: run bin/zephr-memory status.
  • HTTP 401 vs unreachable vs hook timeout: Check ~/.zephr-memory/hooks.log and run bin/zephr-memory status. A 401 indicates token expiration (run zephr-memory auth login). On network unreachable/5xx, the proxy fails open (exits 0, injects nothing), and add_memory returns an error saying the memory was not stored; nothing is queued for later. Note the hook timeout semantics per live documentation: for plugin command hooks, UserPromptSubmit times out after 30s (default), discarding output/additionalContext while the prompt still reaches Claude (unless configured with onFailure: block); in the programmatic Agent SDK, callback timeout on UserPromptSubmit blocks the prompt. In all cases SessionStart timeout yields no output and continues. The proxy enforces internal latency budgets (e.g. rapid local spooling, SessionEnd path under 1.5s) to operate well within host timeouts.
  • Banner probe honesty: The SessionStart banner displays Active only when probed live; otherwise it reports backend=cached.

4. Privacy & data retention

  • Zephr stores structured summaries and redacted memories, never raw interaction transcripts.
  • Every capture is scrubbed by the in-tree redactor prior to classification, embedding, or storage (packages/mcp-server/src/tools/remember.ts:640-643 filterContent).
  • Session summaries are retained for 90 days by default unless pinned; decisions are preserved permanently.