@echomem/mcp 1.4.2 → 1.4.4

package/dist/index.js

@@ -13,6 +13,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { fetchEncryptionConfig, decryptMemoryFields } from "./encryption.js";
 import { runCli } from "./setup.js";
 import { MCP_PACKAGE_VERSION, MCP_SERVER_INSTRUCTIONS } from "./package-metadata.js";
+import { checkLatestUpdateStatus, formatUpdateNotice, formatUpdateStatusText, startBackgroundUpdateCheck, } from "./update-check.js";
 const ECHO_API_BASE_URL = process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app";
 const MEMORY_FEED_API_URL = process.env.MEMORY_FEED_API_URL || "https://memory-feed.vercel.app";
 /** Thrown when no API token is present yet — the model gets a "run login" nudge, not a hard error. */
@@ -800,6 +801,7 @@ class EchoMemMCPServer {
     mcpClientVersion;
     /** Whether the most recent ListTools response carried the memory map (per-session recall signal). */
     mapInjected = false;
+    updateStatus;
     constructor(store) {
         this.server = new Server({
             name: "echomem-mcp",
@@ -812,6 +814,9 @@ class EchoMemMCPServer {
         });
         this.client = new EchoMemApiClient(store);
         this.events = new EventLogger({ session_id: this.client.getSessionId(), app_version: SERVER_VERSION });
+        startBackgroundUpdateCheck((status) => {
+            this.updateStatus = status;
+        });
         this.setupToolHandlers();
         this.server.onerror = (error) => console.error("[MCP Error]", error);
         process.on("SIGINT", async () => {
@@ -851,7 +856,8 @@ class EchoMemMCPServer {
                 ? await Promise.race([this.mapCache, new Promise((r) => setTimeout(() => r(undefined), 2500))])
                 : undefined;
             this.mapInjected = !!map;
-            return { tools: listToolSpecs({ map }) };
+            const updateNotice = formatUpdateNotice(this.updateStatus);
+            return { tools: listToolSpecs({ map, updateNotice }) };
         });
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const canonicalName = resolveCanonicalToolName(request.params.name);
@@ -883,6 +889,12 @@ class EchoMemMCPServer {
                 if (canonicalName === canonicalToolNames.report) {
                     return { content: [{ type: "text", text: await buildReportText(false) }] };
                 }
+                if (canonicalName === canonicalToolNames.updateStatus) {
+                    const force = isRecord(request.params.arguments) && request.params.arguments.force === true;
+                    const status = await checkLatestUpdateStatus({ force });
+                    this.updateStatus = status;
+                    return { content: [{ type: "text", text: formatUpdateStatusText(status) }] };
+                }
                 if (canonicalName === canonicalToolNames.contextHealth) {
                     const client = isRecord(request.params.arguments) && typeof request.params.arguments.client === "string"
                         ? request.params.arguments.client
@@ -994,6 +1006,7 @@ class EchoMemMCPServer {
                 rec.latency_ms = Date.now() - t0;
                 this.events.record(rec);
                 if (canonicalName !== canonicalToolNames.report &&
+                    canonicalName !== canonicalToolNames.updateStatus &&
                     canonicalName !== canonicalToolNames.contextHealth &&
                     canonicalName !== canonicalToolNames.recompose &&
                     canonicalName !== canonicalToolNames.save &&

package/dist/package-metadata.js

@@ -22,11 +22,13 @@ export const MCP_PACKAGE_VERSION = stringOrFallback(packageJson.version, FALLBAC
 export const MCP_PACKAGE_DESCRIPTION = stringOrFallback(packageJson.description, FALLBACK_PACKAGE.description);
 export const MCP_PACKAGE_LABEL = `${MCP_PACKAGE_NAME}@${MCP_PACKAGE_VERSION}`;
 export const MCP_UPDATE_COMMAND = `npx -y ${MCP_PACKAGE_NAME}@latest update`;
+export const MCP_UPDATE_ALL_COMMAND = `${MCP_UPDATE_COMMAND} --all`;
 export const MCP_SERVER_INSTRUCTIONS = [
     `${MCP_PACKAGE_DESCRIPTION} (${MCP_PACKAGE_LABEL}).`,
-    `If the user or local config expects a newer EchoMem MCP version than ${MCP_PACKAGE_VERSION}, update once with \`${MCP_UPDATE_COMMAND}\` and start a new MCP session.`,
+    `If the user or local config expects a newer EchoMem MCP version than ${MCP_PACKAGE_VERSION}, update once with \`${MCP_UPDATE_ALL_COMMAND}\` and start a new MCP session.`,
+    "Use echomem_update_status to check whether npm has a newer bridge; it is cached and non-blocking during normal tool listing.",
     "Do not auto-update on every MCP startup; this bridge is intentionally stable between explicit updates.",
 ].join(" ");
 export function withMcpVersion(description) {
-    return `${description}\n\nEchoMem MCP bridge: ${MCP_PACKAGE_LABEL}. If this version is stale, update once with \`${MCP_UPDATE_COMMAND}\` (add \`--client cursor|windsurf|claude-desktop|codex\` when needed), then start a new MCP session. Do not run updates repeatedly or on every startup.`;
+    return `${description}\n\nEchoMem MCP bridge: ${MCP_PACKAGE_LABEL}. If this version is stale, update once with \`${MCP_UPDATE_ALL_COMMAND}\` (or add \`--client cursor|windsurf|claude-desktop|claude-code|codex\` for a single client), then start a new MCP session. Do not run updates repeatedly or on every startup.`;
 }

package/dist/setup.js

@@ -14,7 +14,7 @@
  */
 import http from "node:http";
 import { randomUUID } from "node:crypto";
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { Worker } from "node:worker_threads";
 import fs from "node:fs";
 import os from "node:os";
@@ -30,7 +30,8 @@ import { syncCodexUsage } from "./codex-sync.js";
 import { renderSetupPage } from "./setup-page.js";
 import { repoLabel } from "./forensics.js";
 import { installHooks } from "./hud/hooks.js";
-import { MCP_PACKAGE_LABEL, MCP_PACKAGE_VERSION, MCP_UPDATE_COMMAND } from "./package-metadata.js";
+import { MCP_PACKAGE_LABEL, MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION, MCP_UPDATE_ALL_COMMAND, MCP_UPDATE_COMMAND } from "./package-metadata.js";
+import { checkLatestUpdateStatus, compareSemver, readCachedUpdateStatus } from "./update-check.js";
 // The hosted connect-device page is now only the account-auth/token courier. The dashboard itself is
 // served by this localhost bridge, where local logs and processed/unprocessed counts never leave the
 // device unless the user explicitly starts migration. Override the hosted auth origin with ECHO_WEB_URL.
@@ -142,6 +143,259 @@ export function writeJsonClientConfig(configPath, entry) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
 }
+export function writeClaudeCodeConfig(entry) {
+    try {
+        execFileSync("claude", ["mcp", "add-json", "echomem", JSON.stringify(entry)], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 10000,
+        });
+        return "wrote";
+    }
+    catch {
+        return "unavailable";
+    }
+}
+function readJsonClientEntry(configPath) {
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        const servers = config.mcpServers;
+        if (!servers || typeof servers !== "object" || Array.isArray(servers))
+            return null;
+        const entry = servers.echomem;
+        return entry && typeof entry === "object" && !Array.isArray(entry) ? entry : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readCodexEntry(configPath) {
+    let content = "";
+    try {
+        content = fs.readFileSync(configPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const lines = content.split("\n");
+    const start = lines.findIndex((line) => /^\s*\[mcp_servers\.echomem\]\s*$/.test(line));
+    if (start < 0)
+        return null;
+    let end = start + 1;
+    while (end < lines.length && !/^\s*\[/.test(lines[end]))
+        end++;
+    const block = lines.slice(start, end);
+    const command = parseTomlString(block.find((line) => /^\s*command\s*=/.test(line)));
+    const args = parseTomlStringArray(block.find((line) => /^\s*args\s*=/.test(line)));
+    return command ? { command, args } : null;
+}
+function parseTomlString(line) {
+    if (!line)
+        return undefined;
+    const match = line.match(/=\s*(".*")\s*$/);
+    if (!match)
+        return undefined;
+    try {
+        const value = JSON.parse(match[1]);
+        return typeof value === "string" ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseTomlStringArray(line) {
+    if (!line)
+        return [];
+    const match = line.match(/=\s*(\[.*\])\s*$/);
+    if (!match)
+        return [];
+    try {
+        const value = JSON.parse(match[1]);
+        return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+function entryArgs(entry) {
+    return Array.isArray(entry.args) ? entry.args.filter((arg) => typeof arg === "string") : [];
+}
+function entryCommand(entry) {
+    return typeof entry.command === "string" && entry.command.trim() ? entry.command.trim() : undefined;
+}
+function entryTarget(entry) {
+    const command = entryCommand(entry) ?? "(missing command)";
+    const args = entryArgs(entry);
+    return [command, ...args].join(" ");
+}
+function packageVersionFromPath(entryPath) {
+    let current = entryPath;
+    try {
+        current = fs.realpathSync(entryPath);
+    }
+    catch {
+        /* keep the original path; it may still be inside an existing package dir */
+    }
+    try {
+        if (fs.existsSync(current) && fs.statSync(current).isFile())
+            current = path.dirname(current);
+    }
+    catch {
+        current = path.dirname(current);
+    }
+    for (let i = 0; i < 12; i += 1) {
+        const packagePath = path.join(current, "package.json");
+        try {
+            const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+            if (pkg.name === MCP_PACKAGE_NAME && typeof pkg.version === "string") {
+                return { version: pkg.version, packagePath };
+            }
+        }
+        catch {
+            /* keep walking */
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+export function resolveServerEntryVersion(entry) {
+    const command = entryCommand(entry);
+    const args = entryArgs(entry);
+    const npxPackageArg = args.find((arg) => arg === MCP_PACKAGE_NAME || arg.startsWith(`${MCP_PACKAGE_NAME}@`));
+    if (command && path.basename(command).replace(/\.(cmd|exe)$/i, "") === "npx" && npxPackageArg) {
+        const suffix = npxPackageArg.slice(MCP_PACKAGE_NAME.length);
+        if (suffix === "@latest")
+            return { runtime: "latest" };
+        if (suffix.startsWith("@") && /^\d+\.\d+\.\d+/.test(suffix.slice(1)))
+            return { version: suffix.slice(1) };
+        return { runtime: "dynamic" };
+    }
+    const candidates = [...args, command].filter((value) => typeof value === "string");
+    for (const candidate of candidates) {
+        // Direct local/dev entries often look like ".../packages/mcp-server/dist/index.js";
+        // they do not contain the published package name, but walking upward still finds package.json.
+        const resolved = packageVersionFromPath(candidate);
+        if (resolved)
+            return resolved;
+    }
+    return {};
+}
+function versionState(version, desiredVersion) {
+    if (!version || !desiredVersion)
+        return "unknown";
+    const cmp = compareSemver(version, desiredVersion);
+    if (cmp < 0)
+        return "stale";
+    if (cmp > 0)
+        return "newer";
+    return "ok";
+}
+function inspectClientConfig(client, desiredVersion) {
+    if (client.kind === "snippet")
+        return inspectClaudeCodeConfig(client, desiredVersion);
+    if (client.kind === "json" && !fs.existsSync(path.dirname(client.configPath)))
+        return null;
+    if (client.kind === "command" && !fs.existsSync(client.detectDir))
+        return null;
+    const entry = client.kind === "json" ? readJsonClientEntry(client.configPath) : readCodexEntry(client.configPath);
+    if (!entry) {
+        return {
+            id: client.id,
+            label: client.label,
+            configured: false,
+            detail: `no EchoMem MCP entry in ${client.configPath}`,
+            state: "missing",
+            command: `${MCP_UPDATE_COMMAND} --client ${client.id}`,
+        };
+    }
+    const resolved = resolveServerEntryVersion(entry);
+    const state = resolved.runtime === "latest" ? "ok" : versionState(resolved.version, desiredVersion);
+    return {
+        id: client.id,
+        label: client.label,
+        configured: true,
+        detail: entryTarget(entry),
+        version: resolved.version,
+        packagePath: resolved.packagePath,
+        runtime: resolved.runtime,
+        state,
+        command: state === "stale" || state === "missing" ? `${MCP_UPDATE_COMMAND} --client ${client.id}` : undefined,
+    };
+}
+function inspectClaudeCodeConfig(client, desiredVersion) {
+    if (!fs.existsSync(home(".claude")))
+        return null;
+    try {
+        const output = execFileSync("claude", ["mcp", "list"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 3000,
+        });
+        const line = output.split("\n").find((item) => item.toLowerCase().includes("echomem"));
+        if (!line) {
+            return {
+                id: client.id,
+                label: client.label,
+                configured: false,
+                detail: "Claude Code reports no EchoMem MCP server",
+                state: "missing",
+                command: `${MCP_UPDATE_COMMAND} --client ${client.id}`,
+            };
+        }
+        const match = line.match(new RegExp(`${MCP_PACKAGE_NAME.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}@(\\d+\\.\\d+\\.\\d+)`));
+        const version = match?.[1];
+        return {
+            id: client.id,
+            label: client.label,
+            configured: true,
+            detail: line.trim(),
+            version,
+            state: versionState(version, desiredVersion),
+            command: version && versionState(version, desiredVersion) === "stale" ? `${MCP_UPDATE_COMMAND} --client ${client.id}` : undefined,
+        };
+    }
+    catch {
+        return {
+            id: client.id,
+            label: client.label,
+            configured: false,
+            detail: "Claude Code CLI not available for `claude mcp list`; add EchoMem from Claude Code manually",
+            state: "unknown",
+        };
+    }
+}
+function inspectClientConfigs(desiredVersion) {
+    return knownClients()
+        .map((client) => inspectClientConfig(client, desiredVersion))
+        .filter((report) => report !== null);
+}
+function formatClientConfigReport(report) {
+    const lines = [];
+    const status = report.state === "ok"
+        ? "ok"
+        : report.state === "stale"
+            ? "stale"
+            : report.state === "newer"
+                ? "newer than this status command"
+                : report.state === "missing"
+                    ? "missing"
+                    : "unknown";
+    const version = report.runtime === "latest"
+        ? "latest at launch"
+        : report.runtime === "dynamic"
+            ? "dynamic npm resolution"
+            : report.version
+                ? `${MCP_PACKAGE_NAME}@${report.version}`
+                : "version unknown";
+    lines.push(`  ${report.label}: ${report.configured ? "configured" : "not configured"} (${status}; ${version})`);
+    lines.push(`    ${report.detail}`);
+    if (report.command)
+        lines.push(`    Update: ${report.command}`);
+    return lines;
+}
 // ---------------------------------------------------------------------------
 // Browser + localhost callback
 // ---------------------------------------------------------------------------
@@ -768,11 +1022,11 @@ function parseFlags(argv) {
 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());
+    const targets = selectSetupTargets(requested, Boolean(flags.all));
     if (targets.length === 0) {
         console.log("No 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|codex.)");
+        console.log("\n(Or re-run with --client cursor|windsurf|claude-desktop|claude-code|codex, or --all.)");
     }
     else {
         for (const c of targets) {
@@ -788,7 +1042,13 @@ async function cmdSetup(flags) {
                     console.log(`✅ ${c.label} already has the EchoMem MCP entry: ${c.configPath}`);
             }
             else {
-                console.log(`ℹ️  ${c.label}: ${c.note}\n   entry: ${JSON.stringify(entry)}`);
+                const result = c.id === "claude-code" ? writeClaudeCodeConfig(entry) : "unavailable";
+                if (result === "wrote") {
+                    console.log(`✅ Wrote EchoMem MCP entry to ${c.label} via \`claude mcp add-json\` — start a new Claude Code session to load it.`);
+                }
+                else {
+                    console.log(`ℹ️  ${c.label}: ${c.note}\n   entry: ${JSON.stringify(entry)}`);
+                }
             }
         }
     }
@@ -806,6 +1066,18 @@ async function cmdUpdate(flags) {
     await cmdSetup({ ...flags, "skip-login": true });
     console.log(`Update config complete. Start a new MCP session to load ${MCP_PACKAGE_LABEL}.`);
 }
+function selectSetupTargets(requested, all) {
+    if (all || requested === "all") {
+        return knownClients().filter((client) => {
+            if (client.kind === "json")
+                return fs.existsSync(path.dirname(client.configPath));
+            if (client.kind === "command")
+                return fs.existsSync(client.detectDir);
+            return client.id === "claude-code" && fs.existsSync(home(".claude"));
+        });
+    }
+    return requested ? knownClients().filter((client) => client.id === requested) : detectClients();
+}
 async function cmdSetupHud(flags) {
     const client = parseHudClient(flags["hud-client"] || "auto");
     const hudCli = resolveHudCliPath();
@@ -1381,10 +1653,21 @@ async function cmdUnlock(flags) {
     store.saveKey(keyB64);
     console.log("✅ Vault unlocked. Reload your MCP client (or start a new session).");
 }
-async function cmdStatus() {
+async function cmdStatus(flags = {}) {
     const store = new KeyStore();
     const token = store.getToken();
     console.log(`EchoMem MCP: ${MCP_PACKAGE_LABEL}`);
+    const updateStatus = flags["no-network"] ? readCachedUpdateStatus() : await checkLatestUpdateStatus({ force: true });
+    const latest = updateStatus?.latestVersion;
+    if (latest) {
+        console.log(`Published latest: ${MCP_PACKAGE_NAME}@${latest}`);
+        if (compareSemver(MCP_PACKAGE_VERSION, latest) < 0) {
+            console.log(`This status command is older than latest. Update client configs with: ${MCP_UPDATE_ALL_COMMAND}`);
+        }
+    }
+    else if (updateStatus?.error) {
+        console.log(`Published latest: unavailable (${updateStatus.error})`);
+    }
     console.log(`Credentials file: ${store.path()}`);
     console.log(`API token: ${token ? "present" : "MISSING — run `echomem-mcp login`"}`);
     if (token) {
@@ -1408,6 +1691,14 @@ async function cmdStatus() {
     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"}`);
+    const reports = inspectClientConfigs(latest ?? MCP_PACKAGE_VERSION);
+    if (reports.length) {
+        console.log("Client MCP configs:");
+        for (const report of reports) {
+            for (const line of formatClientConfigReport(report))
+                console.log(line);
+        }
+    }
 }
 function cmdLogout() {
     const store = new KeyStore();
@@ -1425,11 +1716,13 @@ 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 setup --skip-login    Write MCP config without opening login/browser
-  echomem-mcp update [--client X]   Repoint MCP config to this installed bridge; no login/browser
+  echomem-mcp update --all          Repoint detected clients to this installed bridge; no login/browser
+  echomem-mcp update --client X     Repoint one MCP client; no login/browser
   echomem-mcp setup --with-hud      Configure MCP, then launch the EchoMem context HUD
   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 doctor [--no-network] Diagnose configured client bridge versions
   echomem-mcp logout                Remove stored credentials
   echomem-mcp report [--json]       Your AI coding memory audit (local, no login, $0)
   echomem-mcp migrate [--since D]   Import your existing Codex/Claude history into your memory
@@ -1443,7 +1736,8 @@ Usage:
 
 Manual / headless:
   echomem-mcp login --token ec_xxx [--passphrase <vault pass> | --key <base64>]
-  ${MCP_UPDATE_COMMAND} --client codex   # one-shot latest update, no browser login
+  ${MCP_UPDATE_ALL_COMMAND}     # one-shot latest update for detected clients, no browser login
+  ${MCP_UPDATE_COMMAND} --client codex   # update one client only
   echomem-mcp setup --dev /abs/path/dist/index.js   # point clients at a local checkout
   echomem-mcp setup --with-hud --install-hud-hooks --client codex [--hud-client auto]
   echomem-mcp sync-usage --days 7 --limit 50 --dry-run
@@ -1468,7 +1762,10 @@ export async function runCli(argv) {
             await cmdUnlock(flags);
             return true;
         case "status":
-            await cmdStatus();
+            await cmdStatus(flags);
+            return true;
+        case "doctor":
+            await cmdStatus(flags);
             return true;
         case "logout":
             cmdLogout();

package/dist/update-check.js

@@ -0,0 +1,154 @@
+import fs from "node:fs";
+import path from "node:path";
+import { echoConfigDir } from "./keystore.js";
+import { MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION, MCP_UPDATE_ALL_COMMAND, } from "./package-metadata.js";
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const UPDATE_CHECK_TIMEOUT_MS = 3500;
+export function compareSemver(a, b) {
+    const av = a.split(/[.-]/).map((part) => Number(part));
+    const bv = b.split(/[.-]/).map((part) => Number(part));
+    for (let i = 0; i < Math.max(av.length, bv.length, 3); i += 1) {
+        const ai = Number.isFinite(av[i]) ? av[i] : 0;
+        const bi = Number.isFinite(bv[i]) ? bv[i] : 0;
+        if (ai !== bi)
+            return ai > bi ? 1 : -1;
+    }
+    return 0;
+}
+export function updateCheckCachePath() {
+    return path.join(echoConfigDir(), "mcp-update-check.json");
+}
+export function readCachedUpdateStatus(nowMs = Date.now()) {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(updateCheckCachePath(), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (raw.packageName !== MCP_PACKAGE_NAME)
+        return undefined;
+    if (typeof raw.latestVersion !== "string" || typeof raw.checkedAt !== "string")
+        return undefined;
+    const checkedMs = Date.parse(raw.checkedAt);
+    if (!Number.isFinite(checkedMs))
+        return undefined;
+    return {
+        packageName: MCP_PACKAGE_NAME,
+        currentVersion: MCP_PACKAGE_VERSION,
+        latestVersion: raw.latestVersion,
+        checkedAt: raw.checkedAt,
+        updateAvailable: compareSemver(MCP_PACKAGE_VERSION, raw.latestVersion) < 0,
+        source: "cache",
+        command: MCP_UPDATE_ALL_COMMAND,
+        error: nowMs - checkedMs > UPDATE_CHECK_INTERVAL_MS ? "cached result is older than 24h" : undefined,
+    };
+}
+export function isUpdateCheckFresh(status, nowMs = Date.now()) {
+    if (!status?.checkedAt)
+        return false;
+    const checkedMs = Date.parse(status.checkedAt);
+    return Number.isFinite(checkedMs) && nowMs - checkedMs <= UPDATE_CHECK_INTERVAL_MS;
+}
+export async function checkLatestUpdateStatus(opts = {}) {
+    const nowMs = opts.nowMs ?? Date.now();
+    const cached = readCachedUpdateStatus(nowMs);
+    if (process.env.ECHO_DISABLE_UPDATE_CHECK === "1") {
+        return cached ?? baseStatus("disabled");
+    }
+    if (!opts.force && cached && isUpdateCheckFresh(cached, nowMs))
+        return cached;
+    const registryUrl = opts.registryUrl
+        || process.env.ECHO_MCP_UPDATE_REGISTRY_URL
+        || `https://registry.npmjs.org/${encodeURIComponent(MCP_PACKAGE_NAME)}/latest`;
+    try {
+        const signal = AbortSignal.timeout(opts.timeoutMs ?? UPDATE_CHECK_TIMEOUT_MS);
+        const res = await fetch(registryUrl, {
+            headers: { accept: "application/json" },
+            signal,
+        });
+        if (!res.ok)
+            throw new Error(`npm registry HTTP ${res.status}`);
+        const data = await res.json();
+        const latestVersion = typeof data.version === "string" ? data.version.trim() : "";
+        if (!latestVersion)
+            throw new Error("npm registry response missing version");
+        const checkedAt = new Date(nowMs).toISOString();
+        const status = {
+            packageName: MCP_PACKAGE_NAME,
+            currentVersion: MCP_PACKAGE_VERSION,
+            latestVersion,
+            checkedAt,
+            updateAvailable: compareSemver(MCP_PACKAGE_VERSION, latestVersion) < 0,
+            source: "network",
+            command: MCP_UPDATE_ALL_COMMAND,
+        };
+        writeUpdateCache(status);
+        return status;
+    }
+    catch (error) {
+        return {
+            ...(cached ?? baseStatus("none")),
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export function startBackgroundUpdateCheck(onStatus) {
+    const cached = readCachedUpdateStatus();
+    if (cached)
+        onStatus(cached);
+    if (process.env.ECHO_DISABLE_UPDATE_CHECK === "1" || isUpdateCheckFresh(cached))
+        return cached;
+    void checkLatestUpdateStatus({ force: true }).then(onStatus).catch(() => {
+        /* Update checks are advisory; never affect MCP startup. */
+    });
+    return cached;
+}
+export function formatUpdateNotice(status) {
+    if (!status?.updateAvailable || !status.latestVersion)
+        return undefined;
+    return [
+        `EchoMem update available: installed ${status.currentVersion}, latest ${status.latestVersion}.`,
+        `Offer to update, then run \`${status.command}\` if the user agrees.`,
+        "After updating, start a new agent/MCP session.",
+    ].join(" ");
+}
+export function formatUpdateStatusText(status) {
+    const lines = [
+        `EchoMem MCP installed: ${status.packageName}@${status.currentVersion}`,
+        status.latestVersion ? `Latest published: ${status.packageName}@${status.latestVersion}` : "Latest published: unknown",
+        `Update available: ${status.updateAvailable ? "yes" : "no"}`,
+    ];
+    if (status.updateAvailable) {
+        lines.push(`Update command: ${status.command}`);
+        lines.push("After updating, start a new agent/MCP session.");
+    }
+    if (status.checkedAt)
+        lines.push(`Checked at: ${status.checkedAt} (${status.source})`);
+    else
+        lines.push(`Checked at: not checked (${status.source})`);
+    if (status.error)
+        lines.push(`Check note: ${status.error}`);
+    return lines.join("\n");
+}
+function baseStatus(source) {
+    return {
+        packageName: MCP_PACKAGE_NAME,
+        currentVersion: MCP_PACKAGE_VERSION,
+        updateAvailable: false,
+        source,
+        command: MCP_UPDATE_ALL_COMMAND,
+    };
+}
+function writeUpdateCache(status) {
+    if (!status.latestVersion || !status.checkedAt)
+        return;
+    const dir = echoConfigDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(updateCheckCachePath(), JSON.stringify({
+        packageName: status.packageName,
+        currentVersion: status.currentVersion,
+        latestVersion: status.latestVersion,
+        checkedAt: status.checkedAt,
+    }, null, 2), { mode: 0o600 });
+}

package/dist/v1-contract.js

@@ -7,6 +7,7 @@ export const canonicalToolNames = {
     keywords: "search_memories_by_keywords",
     others: "search_others_memories",
     report: "echomem_usage_report",
+    updateStatus: "echomem_update_status",
     contextHealth: "echo_context_health",
     recompose: "echo_recompose",
     delete: "delete_memory",
@@ -75,13 +76,15 @@ export const getByContextSchema = z.object({
 export function listToolSpecs(opts = {}) {
     const currentTime = new Date().toISOString();
     const map = opts.map?.trim();
+    const updateNotice = opts.updateNotice?.trim();
+    const updateSection = updateNotice ? `\n\nUPDATE NOTICE: ${updateNotice}` : "";
     const mapSection = map
         ? `\n\nThis user's EchoMem currently covers these topics (a relevance guide — recall when the task relates to one of them):\n${map}\n`
         : "";
     return [
         {
             name: canonicalToolNames.search,
-            description: withMcpVersion(`Recall the user's prior decisions, preferences, constraints, and project context from EchoMem — their long-term memory across ALL their AI tools (Claude.ai, ChatGPT, other agents), not just this session.${mapSection}\nCall this when the task plausibly relates to that remembered context — a topic above, or when the user refers to past work ("what did we decide", "like before", "the usual") — so you don't re-derive or re-ask what they already settled. Skip it for self-contained tasks with no link to their history (e.g. a generic algorithm question). By default this returns only the ranked memories retrieved for recall and skips EchoMem answer generation; set includeAnswer=true only when you explicitly need EchoMem's legacy synthesized recall. Current time: ${currentTime}.`),
+            description: withMcpVersion(`Recall the user's prior decisions, preferences, constraints, and project context from EchoMem — their long-term memory across ALL their AI tools (Claude.ai, ChatGPT, other agents), not just this session.${mapSection}\nCall this when the task plausibly relates to that remembered context — a topic above, or when the user refers to past work ("what did we decide", "like before", "the usual") — so you don't re-derive or re-ask what they already settled. Skip it for self-contained tasks with no link to their history (e.g. a generic algorithm question). By default this returns only the ranked memories retrieved for recall and skips EchoMem answer generation; set includeAnswer=true only when you explicitly need EchoMem's legacy synthesized recall. Current time: ${currentTime}.${updateSection}`),
             inputSchema: {
                 type: "object",
                 properties: {
@@ -254,6 +257,20 @@ export function listToolSpecs(opts = {}) {
             description: "Show the user a one-screen audit of THEIR OWN AI coding usage — computed locally from their Codex/Claude Code logs ($0, nothing uploaded): how many tokens their agents spent, how much was re-reading context, reads vs memory recalls, and what changes with EchoMem. Call this when the user asks about their usage, token spend, cost, how much they're wasting, or wants a summary of their agent activity — and you may offer it once right after EchoMem is first connected. Returns formatted text to show the user verbatim. Needs no login.",
             inputSchema: { type: "object", properties: {} },
         },
+        {
+            name: canonicalToolNames.updateStatus,
+            description: `Check whether this installed EchoMem MCP bridge is behind the latest published npm version. Works without login, uploads no user transcript, and normal background checks are cached so EchoMem does not hit npm on every startup. If it reports an update, tell the user and offer to run the returned update command; after updating, the user must start a new agent/MCP session.${updateSection}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    force: {
+                        type: "boolean",
+                        default: false,
+                        description: "When true, refresh npm latest now instead of using the cached check.",
+                    },
+                },
+            },
+        },
         {
             name: canonicalToolNames.contextHealth,
             description: "Show the current local Codex/Claude context-health score as markdown: clean percentage, tracked lower-bound dead-weight, redundant reads, source client, and token-count source. Use when the user asks about the context HUD, dirty context, context pollution, whether cleanup is worth it, or wants an in-chat fallback to the passive HUD. This reads local agent logs only and needs no login.",