EchoMem Cloud-First MCP Server

This package implements a stateless, cloud-first Model Context Protocol (MCP) server for EchoMem. It allows local IDE agents (like Cursor, Windsurf, Claude Desktop, and VS Code) to interact with the user's secure EchoMem personal backend without risk of file-locking or sandbox conflict with the running Chrome Extension's local database.

Architecture

This MCP Server bridges local tools and your EchoMem Cloud API entirely via authenticated REST fetch() calls.

• search_memories: Calls the deep-search candidate phase, resolves the retrieved memory rows, and returns those memories only by default
• save_conversation: Connects to POST /api/extension/memories/ingest
• get_memories_by_time_range: Connects to POST /api/extension/memories/time-range
• search_memories_by_keywords: Connects to POST /api/extension/memories/keywords
• search_others_memories: Connects to MemoryFeed public search without sending the authenticated Echo user id
• delete_memory: Previews one personal memory and returns a confirmation token; only deletes after a second confirmed call

No direct access to the IndexedDB or local files is required.

Encryption — the local bridge is the encrypted surface

For zero-knowledge accounts, the key never leaves your machine. The bridge holds the key locally (exactly like the Chrome extension) and:

• reads: the server returns ciphertext; the bridge decrypts locally so the model only ever sees plaintext. The server never holds your key.
• writes: the key is handed to your own backend transiently in the X-Encryption-Key header so memories are encrypted at rest (the server processes plaintext for the request only — never stores the key).
• locked state: if the key is absent or past its TTL (7 days, matching the extension), tools return a 🔒 locked nudge to run echomem-mcp unlock — ciphertext is never handed to the model.

Unencrypted accounts are unaffected. search_memories returns retrieved memories by default so your MCP client does the final answer generation; pass includeAnswer: true only if you need the legacy EchoMem-synthesized recall answer.

Quick start (recommended)

# One command, everything: download the bridge + HUD, configure every coding agent you have
# installed (Codex, Claude Code, Claude Desktop, Cursor, Windsurf…), log in, and launch the HUD.
npm i -g @echomem/mcp@latest && echomem-mcp init

A global install (not npx) is recommended because it wires each editor to a stable path: a bare npx run resolves the bridge into a throwaway _npx/<hash> cache dir that npm later garbage-collects, which would break the MCP server after the fact (setup now refuses to pin such a path and falls back to the global install, but installing globally avoids the issue entirely). The context HUD's launch-at-login also runs from the installed path. init is the flagship one-liner — it wraps setup --all --with-hud: it writes each installed agent's MCP config (with no secret in it — credentials live in ~/.echomem/credentials.json, mode 0600), adds the EchoMem memory guidance to their global AGENTS.md / CLAUDE.md, opens the browser to approve the device (and unlock the vault for encrypted accounts), then launches the context HUD. Reload your editors and you're done.

Prefer to keep it minimal? echomem-mcp setup configures only the auto-detected editor and skips the HUD; the granular commands below still work.

| Command | What it does | |---|---| | npm i -g @echomem/mcp@latest && echomem-mcp init | Everything in one command — all installed agents + HUD + login | | npm i -g @echomem/mcp@latest && echomem-mcp setup | Install the CLI globally and configure just the detected editor | | npx -y @echomem/mcp@latest setup | One-off setup without keeping a global CLI command | | echomem-mcp setup [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex] | Write client config + log in | | echomem-mcp setup --skip-login [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex] | Write client config without opening the browser or changing credentials | | npx -y @echomem/mcp@latest update --all | One-shot update: repoint detected client configs to the latest bridge, with no browser login | | npx -y @echomem/mcp@latest update --client codex | Update one client only | | echomem-mcp setup --with-hud [--client codex] | Write client config + log in + launch the EchoMem context HUD | | echomem-mcp login | Approve device in browser (or use --token / --passphrase) | | echomem-mcp unlock | Re-derive the encryption key after its TTL (or --passphrase) | | echomem-mcp status | Show token / key / detected clients, configured bridge versions, and update guidance | | echomem-mcp doctor [--no-network] | Diagnose configured client bridge versions | | echomem-mcp logout | Remove stored credentials |

The bridge reports its package version in MCP server instructions and in tool descriptions. It also checks npm for a newer published bridge using a cached, non-blocking check. Agents can call echomem_update_status to show the user whether an update exists and then run npx -y @echomem/mcp@latest update --all if the user agrees. The bridge does not auto-update on every MCP startup.

EchoMem Context HUD

The package also ships echomem-hud, a local context-health sidecar for Codex and Claude. It reads local agent logs, computes a tracked lower-bound "clean vs dirty" context score, and renders a small HUD without adding tokens to the agent conversation.

echomem-hud app                 # Electron floating HUD
echomem-hud serve               # Browser fallback at http://127.0.0.1:17377
echomem-hud summary --json      # Machine-readable current score
echomem-hud status              # Show detected Codex/Claude sources

Supported local sources:

• Codex: ~/.codex/sessions/**/rollout-*.jsonl
• Claude Code: ~/.claude/echo-ctx/*.json first, then local transcripts when present
• Claude desktop agent/Cowork: local agent-mode transcripts under Application Support

The v1 metric counts range_redundant reads only and reports pollution as tracked dead-weight ≥ because exact context composition and provider eviction are not observable.

MCP fallback: agents can call echo_context_health to get the same score as markdown in-chat. This is on-demand; the passive HUD remains a separate local process.

Agent Doctor — local workspace forensics (new in 1.4.9)

echomem-mcp init / setup now ends with an Agent Doctor report: a local scan of your Codex and Claude Code session logs that shows what your AI coding actually cost and where the context went dirty — rendered as an interactive 3D "repo city" plus a full forensic breakdown.

• Unified cost ledger. Every provider request is priced individually from official API list rates (model, cache write/read, long-context premiums, intro-pricing windows), so the headline TOTAL SPENT, per-repo costs, per-model costs, and cost components all come from one path and reconcile exactly. It is an API-equivalent estimate of volume, not a bill you paid.
• Fail-closed validation. The report refuses to render unless every ledger reconciles (tokens, costs, canonical waste analysis). Stale or preview data can never appear as your data.
• Wasteful-context analysis. Canonical context windows label input tokens useful vs wasteful (re-reads of unchanged files, re-finding, dead work) and project the waste over your billed input.
• Fully local, zero upload. The scan reads local JSONL logs only: no transcripts are uploaded and no LLM calls are made to build the report.

Manual / headless (SSH, containers, CI)

No browser? Provide secrets directly — this is the documented headless path:

echomem-mcp login --token ec_xxx                       # unencrypted account
echomem-mcp login --token ec_xxx --passphrase '<vault>' # encrypted: derives + verifies the key
# or pre-provision via env: ECHO_API_TOKEN, ECHO_ENCRYPTION_KEY (base64)

The browser flow depends on the EchoMem "connect device" web page posting { token, key? } to the bridge's localhost callback. Until that page ships, use the manual flags above (same result).

Setup & Configuration (manual config)

Prerequisites

A valid EchoMem API key (ec_…). For encrypted accounts, your vault passphrase.

Building

cd packages/mcp-server
npm install
npm run build
npm test   # crypto compat + encrypted-local integration tests

Add to your IDE (Cursor or Windsurf)

Prefer npm i -g @echomem/mcp@latest && echomem-mcp init above — it writes these files for you and keeps secrets out of the client config. The manual steps below are the fallback.

For Cursor

In Cursor, go to Settings -> Features -> MCP Servers. Add a new MCP Server:

• Type: command
• Name: echomem
• Command: npx
• Args: -y @echomem/mcp@latest

Under the Environment Variables section of the server configuration, add:

• ECHO_API_TOKEN: ec_... (Required unless provisioned via login: your EchoMem API key)
• ECHO_API_BASE_URL: https://echo-mem-chrome.vercel.app (Optional: Defaults to production URL)
• MEMORY_FEED_API_URL: https://memory-feed.vercel.app (Optional: Defaults to production MemoryFeed URL)

For Windsurf

1. Open your global Windsurf MCP configuration file:
   • Mac/Linux: ~/.codeium/windsurf/mcp_config.json
   • Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
2. Add the echomem server beneath your existing configurations:

{
  "mcpServers": {
     "echomem": {
       "command": "npx",
       "args": ["-y", "@echomem/mcp@latest"],
       "env": {
         "ECHO_API_TOKEN": "ec_YOUR_API_KEY_HERE",
         "ECHO_API_BASE_URL": "https://echo-mem-chrome.vercel.app"
       }
     }
  }
}

3. Restart Windsurf.

Add to Claude Desktop

claude.ai integrations must be configured via the Claude Desktop app.

1. Open your Claude Desktop setting file:
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Update your mcpServers object to include EchoMem, adding ECHO_API_TOKEN to the env object:

{
  "mcpServers": {
     "echomem": {
       "command": "node",
       "args": ["/absolute/path/to/EchoMem-Chrome/packages/mcp-server/dist/index.js"],
       "env": {
         "ECHO_API_TOKEN": "your_generated_ec_key..."
       }
     }
  }
}

3. Restart Claude Desktop.

Using via CLI (testing)

ECHO_API_TOKEN="your_token" ECHO_API_BASE_URL="http://localhost:3000" npm run start

Available Tools

• search_memories: Retrieve ranked personal memories for a query. Defaults to memory-only output and skips EchoMem answer generation; set includeAnswer: true for the legacy synthesized recall.
• save_conversation: Ingest and structure a conversation directly into your EchoMem timeline.
• get_memories_by_time_range: Retrieve memories between explicit start/end timestamps.
• search_memories_by_keywords: Retrieve memories by matching the keys field.
• search_others_memories: Search other users' public memories through MemoryFeed public search.
• delete_memory: Delete a single personal memory through a two-step confirmation flow. First call with memoryId only to preview the target and receive confirmationToken; after the user explicitly confirms, call again with confirmed: true and that exact token. This deletes the memory row only and preserves raw source_of_truth conversation records.
• echomem_update_status: Check the installed bridge against the latest published npm version. Works without login, uses cached background checks in normal operation, and returns the update command to show the user when a newer bridge exists.
• echo_context_health: Return the local Codex/Claude context-health score as markdown. Works without login and uploads no transcript content.

Legacy aliases are preserved for compatibility:

• search_memories_by_description_semantic -> search_memories
• search_memories_by_time_range -> get_memories_by_time_range

Contract reference:

• docs/PUBLIC_API_CONTRACT_V1.md
• docs/MCP_COMPAT_MATRIX.md