@echomem/mcp 1.0.0

package/dist/setup.js

@@ -0,0 +1,383 @@
+/**
+ * `echomem-mcp setup | login | unlock | status | logout` — onboarding for the local bridge (spec §8).
+ *
+ * Design goals from the spec:
+ *   - One command → one browser approval → one reload.
+ *   - Both secrets (API token + encryption key) ride a single browser flow and land in the local
+ *     keystore — never in the client's MCP config, never in the agent's chat context.
+ *   - Re-unlock after the key's TTL is one step, not a re-setup.
+ *
+ * The browser flow posts `{ token, key? }` to a localhost callback this process opens. The
+ * "connect device" web page that drives it is the one piece that lives in the web app (not here);
+ * until it ships, the same flow is fully usable via the manual flags (`--token`, `--key`,
+ * `--passphrase`), which is also the documented headless/SSH path (spec §8).
+ */
+import http from "node:http";
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import axios from "axios";
+import { KeyStore } from "./keystore.js";
+import { fetchEncryptionConfig, deriveAndVerifyKey, verifyKeyB64 } from "./encryption.js";
+// The connect-device page lives on the main site (WebPageReactVersion → yeahecho.com), where the
+// user already has a session. It calls the EchoMem API cross-origin. Override with ECHO_WEB_URL.
+const WEB_URL = (process.env.ECHO_WEB_URL || "https://yeahecho.com").replace(/\/$/, "");
+const API_BASE_URL = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
+function home(...p) {
+    return path.join(os.homedir(), ...p);
+}
+/** Known clients and where their MCP server map lives. */
+export function knownClients() {
+    const appSupport = process.platform === "darwin"
+        ? home("Library", "Application Support")
+        : process.env.APPDATA || home(".config");
+    return [
+        { id: "cursor", label: "Cursor", kind: "json", configPath: home(".cursor", "mcp.json") },
+        { id: "windsurf", label: "Windsurf", kind: "json", configPath: home(".codeium", "windsurf", "mcp_config.json") },
+        { id: "claude-desktop", label: "Claude Desktop", kind: "json", configPath: path.join(appSupport, "Claude", "claude_desktop_config.json") },
+        { id: "claude-code", label: "Claude Code", kind: "snippet", note: "run: claude mcp add-json echomem '<entry>'  (or add to .mcp.json)" },
+        { id: "codex", label: "Codex", kind: "snippet", note: "add to ~/.codex/config.toml under [mcp_servers.echomem]" },
+    ];
+}
+/** A client is "present" if its config dir already exists (JSON) — a cheap heuristic for detection. */
+export function detectClients() {
+    return knownClients().filter((c) => {
+        if (c.kind !== "json")
+            return false;
+        return fs.existsSync(path.dirname(c.configPath));
+    });
+}
+/**
+ * The MCP server entry written into a client config. Deliberately carries NO secret — the bridge
+ * reads the token + key from the keystore at `~/.echomem/credentials.json`. `dev` points the client
+ * at a local checkout instead of the (unpublished) npm package.
+ */
+export function buildServerEntry(opts = {}) {
+    if (opts.devEntryPath) {
+        return { command: "node", args: [opts.devEntryPath] };
+    }
+    return { command: "npx", args: ["-y", "@echomem/mcp"] };
+}
+/** Merge the EchoMem entry into a JSON client's `mcpServers` map without clobbering siblings. */
+export function writeJsonClientConfig(configPath, entry) {
+    let config = {};
+    try {
+        config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    }
+    catch {
+        /* fresh config */
+    }
+    config.mcpServers = config.mcpServers || {};
+    config.mcpServers.echomem = entry;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+}
+// ---------------------------------------------------------------------------
+// Browser + localhost callback
+// ---------------------------------------------------------------------------
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+        spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
+    }
+    catch {
+        /* headless — caller prints the URL */
+    }
+}
+/**
+ * Start a localhost callback server. Resolves immediately with the bound `port` and a `wait` promise
+ * that settles when the connect-device page delivers `{ token, key? }` — by POSTing JSON to
+ * `/callback` or hitting `/callback?token=…&key=…`. Splitting port-acquisition from the token-wait
+ * lets the caller build the callback URL before the user approves.
+ */
+export function startCallbackServer(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 180_000;
+    const expectedNonce = opts.nonce;
+    return new Promise((resolveOuter, rejectOuter) => {
+        let settle;
+        let fail;
+        const wait = new Promise((res, rej) => {
+            settle = res;
+            fail = rej;
+        });
+        const server = http.createServer((req, res) => {
+            res.setHeader("Access-Control-Allow-Origin", "*");
+            res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+            res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+            // Let the HTTPS connect-device page reach this localhost server (Chrome Private Network Access).
+            res.setHeader("Access-Control-Allow-Private-Network", "true");
+            if (req.method === "OPTIONS")
+                return void res.writeHead(204).end();
+            const url = new URL(req.url || "/", "http://127.0.0.1");
+            if (!url.pathname.startsWith("/callback"))
+                return void res.writeHead(404).end();
+            const finish = (token, key, nonce) => {
+                // Nonce gates the callback: only the page we opened (which carries the nonce) can post here.
+                if (expectedNonce && nonce !== expectedNonce)
+                    return void res.writeHead(403, { "Content-Type": "text/plain" }).end("bad nonce");
+                if (!token)
+                    return void res.writeHead(400, { "Content-Type": "text/plain" }).end("missing token");
+                res.writeHead(200, { "Content-Type": "text/html" }).end("<html><body style='font-family:system-ui;padding:3rem;text-align:center'><h2>✅ EchoMem connected</h2><p>You can close this tab and return to your editor.</p></body></html>");
+                clearTimeout(timer);
+                server.close();
+                settle({ token, key });
+            };
+            if (req.method === "GET") {
+                finish(url.searchParams.get("token") || undefined, url.searchParams.get("key") || undefined, url.searchParams.get("nonce") || undefined);
+            }
+            else {
+                let body = "";
+                req.on("data", (c) => (body += c));
+                req.on("end", () => {
+                    try {
+                        const parsed = JSON.parse(body || "{}");
+                        finish(parsed.token, parsed.key, parsed.nonce);
+                    }
+                    catch {
+                        res.writeHead(400).end("bad json");
+                    }
+                });
+            }
+        });
+        const timer = setTimeout(() => {
+            server.close();
+            fail(new Error("timed out waiting for browser approval"));
+        }, timeoutMs);
+        server.on("error", (e) => rejectOuter(e));
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            resolveOuter({
+                port,
+                wait,
+                close: () => {
+                    clearTimeout(timer);
+                    server.close();
+                },
+            });
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Key/token provisioning
+// ---------------------------------------------------------------------------
+function authedAxios(token) {
+    return axios.create({
+        baseURL: API_BASE_URL,
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+    });
+}
+/**
+ * Verify supplied secrets and persist them. Given a token (required), and EITHER a base64 key or a
+ * passphrase (optional — only for encrypted accounts), this verifies the key against the server's
+ * verification token before caching. Returns a human-readable status.
+ */
+export async function verifyAndStore(input) {
+    const store = new KeyStore();
+    store.saveToken(input.token);
+    const config = await fetchEncryptionConfig(authedAxios(input.token));
+    if (!config.enabled) {
+        return input.key || input.passphrase
+            ? "Token saved. (Account is not encrypted — the supplied key was ignored.)"
+            : "Token saved. Account is not encrypted; you're ready.";
+    }
+    // Encrypted account — provision and VERIFY the key before caching.
+    let keyB64 = null;
+    if (input.passphrase) {
+        keyB64 = await deriveAndVerifyKey(input.passphrase, config);
+        if (!keyB64)
+            return "❌ Passphrase did not match this account's encryption. Nothing saved for the key.";
+    }
+    else if (input.key) {
+        keyB64 = (await verifyKeyB64(input.key, config)) ? input.key : null;
+        if (!keyB64)
+            return "❌ Supplied key failed verification against the account. Nothing saved for the key.";
+    }
+    else {
+        return "Token saved, but this account is ENCRYPTED. Re-run with --passphrase to unlock the vault.";
+    }
+    store.saveKey(keyB64);
+    return "✅ Token + encryption key verified and saved. Reload your MCP client.";
+}
+function prompt(question, { silent = false } = {}) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    return new Promise((resolve) => {
+        if (silent) {
+            const out = process.stdout;
+            rl._writeToOutput = () => out.write("");
+        }
+        rl.question(question, (answer) => {
+            rl.close();
+            if (silent)
+                process.stdout.write("\n");
+            resolve(answer.trim());
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+function parseFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next && !next.startsWith("--")) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+    }
+    return flags;
+}
+async function cmdSetup(flags) {
+    const entry = buildServerEntry({ devEntryPath: typeof flags.dev === "string" ? flags.dev : undefined });
+    const requested = typeof flags.client === "string" ? flags.client : undefined;
+    const targets = (requested ? knownClients().filter((c) => c.id === requested) : detectClients());
+    if (targets.length === 0) {
+        console.log("No JSON-config client auto-detected. Add this MCP server entry manually:\n");
+        console.log(JSON.stringify({ echomem: entry }, null, 2));
+        console.log("\n(Or re-run with --client cursor|windsurf|claude-desktop.)");
+    }
+    else {
+        for (const c of targets) {
+            if (c.kind === "json") {
+                writeJsonClientConfig(c.configPath, entry);
+                console.log(`✅ Wrote EchoMem MCP entry to ${c.label}: ${c.configPath}`);
+            }
+            else {
+                console.log(`ℹ️  ${c.label}: ${c.note}\n   entry: ${JSON.stringify(entry)}`);
+            }
+        }
+    }
+    console.log("");
+    await cmdLogin(flags);
+}
+async function cmdLogin(flags) {
+    // Manual path (also the headless path): secrets supplied as flags.
+    if (typeof flags.token === "string") {
+        const msg = await verifyAndStore({
+            token: flags.token,
+            key: typeof flags.key === "string" ? flags.key : undefined,
+            passphrase: typeof flags.passphrase === "string" ? flags.passphrase : undefined,
+        });
+        console.log(msg);
+        return;
+    }
+    // Browser path: open the connect-device page pointed at our localhost callback. The nonce gates
+    // the callback so only the page we opened can deliver the token+key.
+    console.log("Opening your browser to approve this device…");
+    const nonce = randomUUID();
+    const { port, wait, close } = await startCallbackServer({ nonce });
+    const callbackUrl = `http://127.0.0.1:${port}/callback`;
+    const connectUrl = `${WEB_URL}/connect-device?callback=${encodeURIComponent(callbackUrl)}&nonce=${nonce}`;
+    openBrowser(connectUrl);
+    console.log(`If it didn't open, visit:\n  ${connectUrl}\n`);
+    try {
+        const { token, key } = await wait;
+        const msg = await verifyAndStore({ token, key });
+        console.log(msg);
+    }
+    catch (e) {
+        close();
+        console.error(`❌ ${e?.message || e}. You can instead run: echomem-mcp login --token ec_… [--passphrase <vault pass>]`);
+        process.exitCode = 1;
+    }
+}
+async function cmdUnlock(flags) {
+    const store = new KeyStore();
+    const token = store.getToken();
+    if (!token) {
+        console.error("Not logged in. Run `echomem-mcp login` first.");
+        process.exitCode = 1;
+        return;
+    }
+    const config = await fetchEncryptionConfig(authedAxios(token));
+    if (!config.enabled) {
+        console.log("This account is not encrypted — nothing to unlock.");
+        return;
+    }
+    let passphrase = typeof flags.passphrase === "string" ? flags.passphrase : undefined;
+    const key = typeof flags.key === "string" ? flags.key : undefined;
+    if (!passphrase && !key) {
+        passphrase = await prompt("Vault passphrase: ", { silent: true });
+    }
+    const keyB64 = passphrase ? await deriveAndVerifyKey(passphrase, config) : key && (await verifyKeyB64(key, config)) ? key : null;
+    if (!keyB64) {
+        console.error("❌ Passphrase/key did not match. Vault stays locked.");
+        process.exitCode = 1;
+        return;
+    }
+    store.saveKey(keyB64);
+    console.log("✅ Vault unlocked. Reload your MCP client (or start a new session).");
+}
+async function cmdStatus() {
+    const store = new KeyStore();
+    const token = store.getToken();
+    console.log(`Credentials file: ${store.path()}`);
+    console.log(`API token: ${token ? "present" : "MISSING — run `echomem-mcp login`"}`);
+    console.log(`Encryption key: ${store.getKey() ? "present" : store.isKeyExpired() ? "EXPIRED — run `echomem-mcp unlock`" : "not set"}`);
+    const detected = detectClients();
+    console.log(`Detected clients: ${detected.length ? detected.map((c) => c.label).join(", ") : "none auto-detected"}`);
+}
+function cmdLogout() {
+    const store = new KeyStore();
+    try {
+        fs.rmSync(store.path());
+        console.log(`Removed ${store.path()}.`);
+    }
+    catch {
+        console.log("No stored credentials to remove.");
+    }
+}
+const HELP = `EchoMem MCP — local memory bridge
+
+Usage:
+  echomem-mcp                       Run the MCP server (stdio; default — used by your editor)
+  echomem-mcp setup [--client X]    Detect editor, write its MCP config, then log in
+  echomem-mcp login                 Approve this device in the browser (or --token/--passphrase)
+  echomem-mcp unlock                Re-derive the encryption key after its TTL (or --passphrase)
+  echomem-mcp status                Show token/key/clients
+  echomem-mcp logout                Remove stored credentials
+
+Manual / headless:
+  echomem-mcp login --token ec_xxx [--passphrase <vault pass> | --key <base64>]
+  echomem-mcp setup --dev /abs/path/dist/index.js   # point clients at a local checkout
+`;
+/** Returns true if argv was a recognized subcommand (and was handled). */
+export async function runCli(argv) {
+    const cmd = argv[0];
+    const flags = parseFlags(argv.slice(1));
+    switch (cmd) {
+        case "setup":
+            await cmdSetup(flags);
+            return true;
+        case "login":
+            await cmdLogin(flags);
+            return true;
+        case "unlock":
+            await cmdUnlock(flags);
+            return true;
+        case "status":
+            await cmdStatus();
+            return true;
+        case "logout":
+            cmdLogout();
+            return true;
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(HELP);
+            return true;
+        default:
+            return false;
+    }
+}

package/dist/v1-contract.js

@@ -0,0 +1,151 @@
+import { z } from "zod";
+export const canonicalToolNames = {
+    search: "search_memories",
+    save: "save_conversation",
+    timeRange: "get_memories_by_time_range",
+    keywords: "search_memories_by_keywords",
+    others: "search_others_memories",
+};
+export const legacyAliasToCanonical = {
+    search_memories_by_description_semantic: canonicalToolNames.search,
+    search_memories_by_time_range: canonicalToolNames.timeRange,
+};
+export function resolveCanonicalToolName(toolName) {
+    return legacyAliasToCanonical[toolName] ?? toolName;
+}
+export const searchMemoriesSchema = z.object({
+    query: z.string().optional(),
+    k: z.number().optional(),
+    limit: z.number().optional(),
+    threshold: z.number().optional().default(0.1),
+    timeFrameDays: z.number().optional(),
+});
+export const saveConversationSchema = z.object({
+    conversation: z.string().optional(),
+    title: z.string().optional(),
+    url: z.string().optional(),
+    source: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    messages: z
+        .array(z.object({
+        role: z.string(),
+        content: z.string(),
+    }))
+        .optional(),
+});
+export const timeRangeSchema = z.object({
+    startDate: z.string(),
+    endDate: z.string(),
+    limit: z.number().optional().default(50),
+});
+export const keywordsSchema = z.object({
+    keywords: z.array(z.string()),
+    limit: z.number().optional().default(10),
+});
+export const othersSchema = z.object({
+    query: z.string(),
+});
+export function listToolSpecs() {
+    const currentTime = new Date().toISOString();
+    return [
+        {
+            name: canonicalToolNames.search,
+            description: `Recall the user's prior decisions, preferences, constraints, and context from EchoMem — their long-term memory spanning ALL their AI tools (Claude.ai, ChatGPT, other agents), not just this session. CALL THIS AT THE START of any non-trivial task, before planning or writing code, to avoid re-deriving things the user already decided. Also call it whenever the user refers to past work ("what did we decide", "like before", "the usual"). Returns ranked memories with provenance. Current time: ${currentTime}.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string" },
+                    limit: { type: "number", default: 10 },
+                    threshold: { type: "number", default: 0.1 },
+                    timeFrameDays: { type: "number" },
+                },
+            },
+        },
+        {
+            name: "search_memories_by_description_semantic",
+            description: "Legacy alias for search_memories.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string" },
+                    limit: { type: "number", default: 10 },
+                    threshold: { type: "number", default: 0.1 },
+                    timeFrameDays: { type: "number" },
+                },
+            },
+        },
+        {
+            name: canonicalToolNames.save,
+            description: "Save conversation into EchoMem for future retrieval.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    conversation: { type: "string" },
+                    title: { type: "string" },
+                    url: { type: "string" },
+                    source: { type: "string" },
+                    tags: { type: "array", items: { type: "string" } },
+                    messages: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                role: { type: "string" },
+                                content: { type: "string" },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        {
+            name: canonicalToolNames.timeRange,
+            description: `Retrieve memories within a specific date range. Current time: ${currentTime}.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    startDate: { type: "string" },
+                    endDate: { type: "string" },
+                    limit: { type: "number", default: 50 },
+                },
+                required: ["startDate", "endDate"],
+            },
+        },
+        {
+            name: canonicalToolNames.keywords,
+            description: "Search memories based on keywords in keys field.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    keywords: { type: "array", items: { type: "string" } },
+                    limit: { type: "number", default: 10 },
+                },
+                required: ["keywords"],
+            },
+        },
+        {
+            name: canonicalToolNames.others,
+            description: "Search other users' public memories.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string" },
+                },
+                required: ["query"],
+            },
+        },
+        {
+            name: "search_memories_by_time_range",
+            description: "Legacy alias for get_memories_by_time_range.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    startDate: { type: "string" },
+                    endDate: { type: "string" },
+                    limit: { type: "number", default: 50 },
+                },
+                required: ["startDate", "endDate"],
+            },
+        },
+    ];
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@echomem/mcp",
+  "version": "1.0.0",
+  "description": "EchoMem Cloud-First MCP Server",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "echomem-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "smoke": "node smoke.mjs",
+    "test": "npm run build && node test/crypto.test.mjs && node test/integration.test.mjs && node test/no-restart.test.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "zod": "^3.22.4",
+    "axios": "^1.6.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "tsx": "^4.7.1",
+    "@types/node": "^20.11.0"
+  }
+}

package/templates/echomem-recall.md

@@ -0,0 +1,17 @@
+<!-- echomem:recall-rule v1 — installed by `npx @echomem/mcp setup` into the client's
+     project rules (CLAUDE.md / .cursor/rules / AGENTS.md). This is the second half of the
+     nudged-triggering design (spec §9): the tool description nudges, this rule reinforces. -->
+
+## EchoMem memory
+
+This project has EchoMem connected — the user's long-term memory across all their AI tools.
+
+- **At the start of any non-trivial task**, call `search_memories` first to recall the user's
+  prior decisions, preferences, and constraints before planning or writing code. Don't re-derive
+  things they've already decided.
+- Call it again whenever the user refers to past work ("what did we decide", "like before",
+  "the usual", "our convention").
+- Treat recalled memories as authoritative context, but **cite them** (they carry provenance —
+  date + source) so the user can verify.
+- To persist a new decision/constraint/resolved-bug, use `save_conversation` **only when the user
+  explicitly asks** ("remember this"). Never auto-save the transcript.