@echomem/mcp 1.4.1 → 1.4.3

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";
@@ -29,6 +29,8 @@ import { cmdMigrate, applyAccountImportStatus, applyFastAccountImportStatus, dis
 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_NAME, MCP_PACKAGE_VERSION, MCP_UPDATE_COMMAND } from "./package-metadata.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.
@@ -140,6 +142,283 @@ 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) {
+        if (!candidate.includes(MCP_PACKAGE_NAME) && !candidate.includes(`${path.sep}echomem-mcp`))
+            continue;
+        const resolved = packageVersionFromPath(candidate);
+        if (resolved)
+            return resolved;
+    }
+    return {};
+}
+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;
+}
+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 readLatestPublishedVersion() {
+    try {
+        const raw = execFileSync("npm", ["view", MCP_PACKAGE_NAME, "version", "--silent"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 3500,
+        }).trim();
+        return /^\d+\.\d+\.\d+/.test(raw) ? raw : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+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
 // ---------------------------------------------------------------------------
@@ -786,12 +1065,66 @@ 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)}`);
+                }
             }
         }
     }
     console.log("");
-    await cmdLogin(flags);
+    if (flags["skip-login"] || flags["no-login"]) {
+        console.log(`Skipped login; existing EchoMem credentials are unchanged. Current bridge: ${MCP_PACKAGE_LABEL}`);
+    }
+    else {
+        await cmdLogin(flags);
+    }
+    if (flags["with-hud"])
+        await cmdSetupHud(flags);
+}
+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}.`);
+}
+async function cmdSetupHud(flags) {
+    const client = parseHudClient(flags["hud-client"] || "auto");
+    const hudCli = resolveHudCliPath();
+    console.log("");
+    console.log(`✅ EchoMem HUD available: ${process.execPath} ${hudCli}`);
+    if (flags["install-hud-hooks"]) {
+        const paths = installHooks(client === "claude-desktop" ? "auto" : client);
+        console.log(`✅ Installed EchoMem HUD hook support:\n${paths.map((p) => `   - ${p}`).join("\n")}`);
+        console.log("   Codex users: run /hooks in a new Codex session to review and trust changed hooks.");
+    }
+    else {
+        console.log("ℹ️  HUD hooks not installed. Add --install-hud-hooks if you want lifecycle wakeups.");
+    }
+    if (!flags["no-launch-hud"]) {
+        try {
+            spawn(process.execPath, [hudCli, "app", "--client", client], { stdio: "ignore", detached: true }).unref();
+            console.log("✅ Launched EchoMem HUD app.");
+        }
+        catch {
+            console.log(`ℹ️  Could not auto-launch HUD. Run: echomem-hud app --client ${client}`);
+        }
+    }
+    else {
+        console.log(`Run the HUD later with: echomem-hud app --client ${client}`);
+    }
+}
+function resolveHudCliPath() {
+    const entry = fs.realpathSync(process.argv[1] || "");
+    const base = path.dirname(entry);
+    const candidate = path.join(base, "hud", "cli.js");
+    return fs.existsSync(candidate) ? candidate : path.join(base, "hud", "cli.ts");
+}
+function parseHudClient(value) {
+    return value === "codex" || value === "claude-code" || value === "claude-desktop" || value === "both" || value === "auto"
+        ? value
+        : "auto";
 }
 async function cmdLogin(flags) {
     // Manual path (also the headless path): secrets supplied as flags.
@@ -1331,14 +1664,48 @@ 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 latest = flags["no-network"] ? undefined : readLatestPublishedVersion();
+    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_COMMAND}`);
+        }
+    }
     console.log(`Credentials file: ${store.path()}`);
     console.log(`API token: ${token ? "present" : "MISSING — run `echomem-mcp login`"}`);
+    if (token) {
+        // Best-effort: resolve who this token belongs to so `status` shows the logged-in account.
+        // whoami already exists in production, so this works even against a local API checkout.
+        try {
+            const { data } = await withTimeout(authedAxios(token).get("/api/openclaw/v1/whoami"), 6000, "WHOAMI_TIMEOUT");
+            const email = typeof data?.email === "string" ? data.email : "";
+            const userId = typeof data?.user_id === "string" ? data.user_id : "";
+            if (email)
+                console.log(`Logged in as: ${email}${userId ? ` (${userId})` : ""}`);
+            else if (userId)
+                console.log(`Logged in as: ${userId}`);
+            else
+                console.log("Logged in as: (token valid; account identity unavailable)");
+        }
+        catch (error) {
+            console.log(`Logged in as: (could not verify — ${formatVerificationError(error)})`);
+        }
+    }
     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();
@@ -1355,9 +1722,13 @@ 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 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 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
@@ -1371,8 +1742,12 @@ 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
   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
+
+Current bridge version: ${MCP_PACKAGE_VERSION}
 `;
 /** Returns true if argv was a recognized subcommand (and was handled). */
 export async function runCli(argv) {
@@ -1382,6 +1757,9 @@ export async function runCli(argv) {
         case "setup":
             await cmdSetup(flags);
             return true;
+        case "update":
+            await cmdUpdate(flags);
+            return true;
         case "login":
             await cmdLogin(flags);
             return true;
@@ -1389,7 +1767,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/v1-contract.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { withMcpVersion } from "./package-metadata.js";
 export const canonicalToolNames = {
     search: "search_memories",
     save: "save_conversation",
@@ -6,7 +7,10 @@ export const canonicalToolNames = {
     keywords: "search_memories_by_keywords",
     others: "search_others_memories",
     report: "echomem_usage_report",
+    contextHealth: "echo_context_health",
+    recompose: "echo_recompose",
     delete: "delete_memory",
+    getByContext: "get_memories_by_context",
 };
 export const legacyAliasToCanonical = {
     search_memories_by_description_semantic: canonicalToolNames.search,
@@ -35,6 +39,7 @@ export const saveConversationSchema = z.object({
     url: z.string().optional(),
     source: z.string().optional(),
     tags: z.array(z.string()).optional(),
+    passthrough: z.boolean().optional(),
     messages: z
         .array(z.object({
         role: z.string(),
@@ -62,6 +67,11 @@ export const deleteMemorySchema = z.object({
     confirmed: z.boolean().optional().default(false),
     confirmationToken: z.string().optional(),
 });
+export const getByContextSchema = z.object({
+    ...triggerMetadataSchema,
+    contextId: z.string().min(1),
+    limit: z.number().optional().default(50),
+});
 export function listToolSpecs(opts = {}) {
     const currentTime = new Date().toISOString();
     const map = opts.map?.trim();
@@ -71,7 +81,7 @@ export function listToolSpecs(opts = {}) {
     return [
         {
             name: canonicalToolNames.search,
-            description: `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}.`),
             inputSchema: {
                 type: "object",
                 properties: {
@@ -117,7 +127,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.save,
-            description: "Save conversation into EchoMem for future retrieval.",
+            description: "Save conversation into EchoMem for future retrieval. Set passthrough=true to store the text verbatim as a session capsule (no LLM extraction, no embeddings) — use this for warm-up capsules that a fresh session will reload via get_memories_by_context.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -126,6 +136,10 @@ export function listToolSpecs(opts = {}) {
                     url: { type: "string" },
                     source: { type: "string" },
                     tags: { type: "array", items: { type: "string" } },
+                    passthrough: {
+                        type: "boolean",
+                        description: "When true, store the conversation text verbatim as a session capsule — no LLM extraction, no embeddings. Use for warm-up capsules.",
+                    },
                     messages: {
                         type: "array",
                         items: {
@@ -218,11 +232,56 @@ export function listToolSpecs(opts = {}) {
                 required: ["memoryId"],
             },
         },
+        {
+            name: canonicalToolNames.getByContext,
+            description: withMcpVersion(`Deterministically re-fetch the exact batch of memories saved under one contextId — no semantic search, no ranking, just that session's saved capsule. save_conversation returns a contextId; pass it here to pull back precisely those memories, e.g. to warm up a fresh session with what a prior session saved, or to verify the saved facts are still present. Current time: ${currentTime}.`),
+            inputSchema: {
+                type: "object",
+                properties: {
+                    contextId: { type: "string", description: "The contextId returned by save_conversation." },
+                    limit: { type: "number", default: 50 },
+                    triggerMessage: {
+                        type: "string",
+                        description: "Optional: the user's message that caused this lookup. EchoMem stores only a redacted analytics preview and hash.",
+                    },
+                    triggerMessageRole: { type: "string", default: "user" },
+                },
+                required: ["contextId"],
+            },
+        },
         {
             name: canonicalToolNames.report,
             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.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.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    client: {
+                        type: "string",
+                        enum: ["codex", "claude-code", "claude-desktop", "auto"],
+                        default: "auto",
+                    },
+                },
+            },
+        },
+        {
+            name: canonicalToolNames.recompose,
+            description: "Capture a clean-start capsule of the CURRENT local Codex/Claude session — its goal, the files in play, the most recent instruction, and where things stand — so the user can start a fresh session without re-paying orientation or letting the window auto-compact. Use when echo_context_health shows heavy/dirty context (high saturation or pollution), when the agent starts drifting or repeating, or when the user asks how to clean up or start fresh. Returns inspectable markdown to show the user; this is a clean recompose, not a provider compaction. Reads local agent logs only and needs no login.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    client: {
+                        type: "string",
+                        enum: ["codex", "claude-code", "claude-desktop", "auto"],
+                        default: "auto",
+                    },
+                },
+            },
+        },
         {
             name: "search_memories_by_time_range",
             description: "Legacy alias for get_memories_by_time_range.",

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "EchoMem Cloud-First MCP Server",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
-    "echomem-mcp": "./dist/index.js"
+    "mcp": "./dist/index.js",
+    "echomem-mcp": "./dist/index.js",
+    "echomem-hud": "./dist/hud/cli.js"
   },
   "files": [
     "dist",
+    "assets",
     "templates",
     "README.md"
   ],
@@ -17,17 +20,18 @@
     "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 && node test/report.test.mjs && node test/tools.test.mjs && node test/delete.test.mjs && node test/migrate.test.mjs",
+    "test": "npm run build && node test/crypto.test.mjs && node test/integration.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/tools.test.mjs && node test/delete.test.mjs && node test/migrate.test.mjs && node test/hud.test.mjs",
     "prepack": "npm run build && node scripts/bundle-city.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.1",
-    "zod": "^3.22.4",
-    "axios": "^1.6.8"
+    "axios": "^1.6.8",
+    "electron": "41.7.1",
+    "zod": "^3.22.4"
   },
   "devDependencies": {
-    "typescript": "^5.3.3",
-    "tsx": "^4.7.1",
-    "@types/node": "^20.11.0"
+    "@types/node": "^20.11.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.3.3"
   }
 }