@everme/mcp-desktop

EverMe memory plugin for desktop AI hosts — Claude Desktop and Codex (OpenAI Codex CLI / Desktop). Bundles:

1. an MCP stdio server (wire-compatible with @everme/memory-mcp: mem_search, mem_context, mem_save_turn); and
2. a one-shot install wizard (everme-mcp-desktop-install) that registers the server into each host's config and stores credentials at ~/.everme/desktop.env (mode 0600).

If you are on:

• Claude Code (terminal CLI) → use @everme/claude-code (native plugin: hooks + commands + skills).
• Cursor / Cline / generic MCP host → use @everme/memory-mcp.
• Claude Desktop / Codex → this package.

One-shot install

npx -y --package @everme/mcp-desktop everme-mcp-desktop-install

The wizard will:

1. Prompt for your account API key (an emk_* from https://everme.evermind.ai).
2. Write ~/.everme/desktop.env (mode 0600) with that key.
3. Register an mcpServers.everme-memory entry in:
   • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows), ~/.config/Claude/claude_desktop_config.json (Linux).
   • Codex: ~/.codex/config.toml.
4. Tell you to restart each host so it re-reads its config.

Flags

--host=claude-desktop|codex|all   Limit which host(s) to register in. Default: all.
--no-prompt                        Skip the emk prompt (key must already be in env/file).
--api-base=<url>                   Override EVERME_API_BASE for self-hosted EverMe.
--print-only                       Show what would change; don't write any files.

What the wizard writes

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "everme-memory": {
      "command": "npx",
      "args": ["-y", "@everme/mcp-desktop"],
      "env": {}
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.everme-memory]
command = "npx"
args = ["-y", "@everme/mcp-desktop"]

env is intentionally empty in both files — the server reads credentials from ~/.everme/desktop.env at boot, keeping secrets out of the 0644 host configs (which users sometimes commit to dotfiles repos).

Auth modes

• emk mode (default) — EVERME_API_KEY=emk_… is used as the Bearer token. The MCP server plants a placeholder EVERME_AGENT_ID=desktop-mcp for the User-Agent header (auth itself is by token).
• evt mode — if you've provisioned a per-machine evt_* via evercli, set EVERME_AGENT_TOKEN=evt_… and EVERME_AGENT_ID=agt_…; the wizard leaves them alone.

Both modes are wire-compatible with the EverMe gateway.

Tools exposed

Same as @everme/memory-mcp:

mem_search         hybrid memory search (text + vector)
mem_context        server-rendered context block (profile + episodes)
mem_save_turn      realtime write to /mem/agent-memory (no records)

See the memory-mcp README for the per-tool input schemas.

Verifying

For local repo checks before publishing:

npm install
npm test
npm run pack:dry-run

After install, restart your host and try one of:

• Claude Desktop: in a new chat, type "search my EverMe memory for X" — the host should invoke mem_search and show results in the tool-use panel.
• Codex: ask it to look up something in your memory; it will call the same tools.

If the server fails to boot, the host displays the stderr — usually a missing or invalid EVERME_API_KEY. Re-run the install wizard to fix.

Uninstall

# Remove credentials
rm ~/.everme/desktop.env

# Remove the mcpServers.everme-memory entry from each host's config file by hand
# (Claude Desktop JSON, Codex TOML). Restart the host afterward.

License

Apache-2.0