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 branchfeat/T-4054-claude-plugin-manifest-hooksalongside this guide (PR #2026). The proxy binary (zephr-memory/zephr-memory-mcp) does not yet exist onmain; currentmainprovides standard sideload viaclaude --plugin-dir ./extensions/claude-codeor direct MCP execution vianpx @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
~/.zshrcor~/.profile. - No background daemons: No
launchctlservice or systemd daemon required. - Zero secrets in config:
.mcp.jsonruns${CLAUDE_PLUGIN_ROOT}/bin/zephr-memory-mcpwith 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
0with empty output. - Facade tools return
{ "error": { "code": "disabled" } }. - Zero network requests are initiated.
- Remove
~/.zephr-memory/OFFto re-enable.
Re-enabling mem0
- Touch the kill switch:
touch ~/.zephr-memory/OFF - Re-enable mem0 in your client configuration.
- 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 servicezephr-memory), and binary paths use${CLAUDE_PLUGIN_ROOT}rather than relying onPATH. Check status: runbin/zephr-memory status. - HTTP 401 vs unreachable vs hook timeout: Check
~/.zephr-memory/hooks.logand runbin/zephr-memory status. A 401 indicates token expiration (runzephr-memory auth login). On network unreachable/5xx, the proxy fails open (exits 0, injects nothing), andadd_memoryreturns 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,UserPromptSubmittimes out after 30s (default), discarding output/additionalContext while the prompt still reaches Claude (unless configured withonFailure: block); in the programmatic Agent SDK, callback timeout onUserPromptSubmitblocks the prompt. In all casesSessionStarttimeout yields no output and continues. The proxy enforces internal latency budgets (e.g. rapid local spooling,SessionEndpath under 1.5s) to operate well within host timeouts. - Banner probe honesty: The
SessionStartbanner displaysActiveonly when probed live; otherwise it reportsbackend=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-643filterContent). - Session summaries are retained for 90 days by default unless pinned; decisions are preserved permanently.