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 trusting a model-supplied identity; the hosted API resolves the caller from the EchoMem credential and the tool returns that authenticated viewer explicitly
• 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).
• trusted-device lifecycle: after a verified login/unlock, the MCP key remains available until the user runs echomem-mcp lock, logs out, or removes the local credentials. If the key is absent, tools tell the user to run echomem-mcp unlock in their own terminal. The passphrase prompt is visible while typed characters stay hidden, and the current agent session can retry immediately after 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

The standalone package installs and manages its own durable per-user MCP runtime. It configures detected Codex and Claude hosts, connects this device, imports selected local coding history, and keeps compatible runtime updates ready for the next agent session.

Prerequisite: Node.js 18 or newer. Run the command in the same environment as the agent you want to configure. Native Windows and WSL have separate home directories and client configs, so a WSL install does not configure native Windows apps.

macOS, Linux, or WSL:

npx -y @echomem/mcp@latest init

Windows PowerShell:

npx.cmd -y @echomem/mcp@latest init

The one-off npx command is the recommended install path; it stages a durable per-user runtime and does not require a global npm install. On Windows, use a new PowerShell window after installing Node if npx.cmd is not found.

| Command | What it does | |---|---| | npm i -g @echomem/mcp@latest && echomem-mcp init | Legacy/headless setup for installed agents + 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 | Bootstrap or repair the durable per-user runtime and repoint detected client configs, with no browser login | | npx -y @echomem/mcp@latest update --client codex | Update one client only | | echomem-mcp login | Approve device in browser (or use --token / --passphrase) | | echomem-mcp unlock | Privately unlock the vault on this trusted device | | echomem-mcp lock | Remove the local vault key while keeping the device login | | 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. Standalone installations stage compatible updates in the background under ~/.echomem/mcp-runtime and atomically activate them for the next MCP session; the current handshake never waits for npm. Agents can call echomem_update_status to inspect progress. ECHO_DISABLE_AUTO_UPDATE=1 disables automatic installation, and npx -y @echomem/mcp@latest update --all remains the bootstrap and repair command.

Agents can still call echo_context_health for an on-demand local context-health report. It reads the local Codex/Claude logs and does not require a separate process or desktop overlay.

Local conversation lifecycle hooks

For hook-capable Codex and Claude Code clients, MCP setup installs two local lifecycle hooks:

• SessionStart — source-session binding. The hook receives the host-owned session_id and transcript_path, verifies that they identify the same local JSONL, and idempotently binds the canonical codex:<id> or claude-code:<id> context through POST /api/extension/source-sessions/bind. On each MCP call, the bridge independently confirms the exact host-owned session metadata and attaches the returned context before saving, recalling, citing, sharing, or recording activity. No "latest session" lookup is used. bind_source_session remains available only for clients without startup hooks.
• Stop — private-save checkpoint. Before a completed turn exits, the hook reads only that turn's local transcript slice. If the turn appears durable and did not already call save_conversation, it blocks completion once and asks the Agent to create a concise private checkpoint. It never authors or uploads a checkpoint itself. Re-entry is guarded by stop_hook_active, so the second Stop is allowed after the Agent has checked or saved.

Both hook entries are merged idempotently into ~/.codex/hooks.json and ~/.claude/settings.json; unrelated user hooks and settings are preserved. Hooks fail open when their local input is missing so they cannot prevent a conversation from starting or finishing.

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 reports automatic installation state plus a fallback repair command.
• echo_context_health: Return the local Codex/Claude context-health score as markdown. Works without login and uploads no transcript content.

Contract reference:

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