@echomem/mcp 1.4.0 → 1.4.2

package/dist/index.js

@@ -4,13 +4,15 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
 import { ZodError } from "zod";
-import { canonicalToolNames, deleteMemorySchema, keywordsSchema, listToolSpecs, othersSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, timeRangeSchema, } from "./v1-contract.js";
+import { canonicalToolNames, deleteMemorySchema, getByContextSchema, keywordsSchema, listToolSpecs, othersSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, timeRangeSchema, } from "./v1-contract.js";
 import { KeyStore } from "./keystore.js";
 import { EventLogger, hashText } from "./events.js";
 import { buildReportText } from "./report.js";
+import { contextHealthMarkdown, recomposeCapsuleMarkdown } from "./hud/api.js";
 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";
 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. */
@@ -690,6 +692,7 @@ class EchoMemApiClient {
             title: parsed.title,
             // Stable per-session id so multiple saves in this coding session group under one context.
             conversationKey: this.sessionId,
+            passthrough: parsed.passthrough || false,
             triggerMessage: parsed.triggerMessage ||
                 lastUserMessageFromMessages(parsed.messages) ||
                 lastUserMessageFromConversationText(parsed.conversation),
@@ -751,6 +754,15 @@ class EchoMemApiClient {
         });
         return enc.enabled ? await this.decryptResult(response.data, enc.key) : response.data;
     }
+    async getMemoriesByContext(args) {
+        const parsed = getByContextSchema.parse(args);
+        const enc = await this.encState();
+        const response = await this.axios.post("/api/extension/memories/by-context", {
+            contextId: parsed.contextId,
+            limit: parsed.limit,
+        });
+        return enc.enabled ? await this.decryptResult(response.data, enc.key) : response.data;
+    }
     async searchMemoriesByKeywords(args) {
         const parsed = keywordsSchema.parse(args);
         const enc = await this.encState();
@@ -778,7 +790,7 @@ class EchoMemApiClient {
         }
     }
 }
-const SERVER_VERSION = "1.1.0";
+const SERVER_VERSION = MCP_PACKAGE_VERSION;
 class EchoMemMCPServer {
     server;
     client;
@@ -793,6 +805,7 @@ class EchoMemMCPServer {
             name: "echomem-mcp",
             version: SERVER_VERSION,
         }, {
+            instructions: MCP_SERVER_INSTRUCTIONS,
             capabilities: {
                 tools: {},
             },
@@ -870,6 +883,45 @@ class EchoMemMCPServer {
                 if (canonicalName === canonicalToolNames.report) {
                     return { content: [{ type: "text", text: await buildReportText(false) }] };
                 }
+                if (canonicalName === canonicalToolNames.contextHealth) {
+                    const client = isRecord(request.params.arguments) && typeof request.params.arguments.client === "string"
+                        ? request.params.arguments.client
+                        : "auto";
+                    const mode = client === "codex" || client === "claude-code" || client === "claude-desktop" || client === "auto"
+                        ? client
+                        : "auto";
+                    return { content: [{ type: "text", text: await contextHealthMarkdown(mode) }] };
+                }
+                if (canonicalName === canonicalToolNames.recompose) {
+                    const client = isRecord(request.params.arguments) && typeof request.params.arguments.client === "string"
+                        ? request.params.arguments.client
+                        : "auto";
+                    const mode = client === "codex" || client === "claude-code" || client === "claude-desktop" || client === "auto"
+                        ? client
+                        : "auto";
+                    const capsuleText = await recomposeCapsuleMarkdown(mode);
+                    // If logged in, persist the capsule via passthrough so it's retrievable by contextId.
+                    if (this.client.hasToken()) {
+                        try {
+                            const saveResult = await this.client.saveConversation({
+                                conversation: capsuleText,
+                                title: "Session capsule (recompose)",
+                                source: "mcp_recompose",
+                                passthrough: true,
+                            });
+                            const ctxId = saveResult?.contextId;
+                            const capId = saveResult?.capsuleId;
+                            const persistLine = ctxId
+                                ? `\n\n---\nCapsule persisted${capId ? ` (${capId})` : ""}. To reload in a fresh session:\nget_memories_by_context({ contextId: "${ctxId}" })`
+                                : "";
+                            return { content: [{ type: "text", text: capsuleText + persistLine }] };
+                        }
+                        catch {
+                            // Persistence is best-effort; return the capsule text regardless.
+                        }
+                    }
+                    return { content: [{ type: "text", text: capsuleText }] };
+                }
                 if (!this.client.hasToken())
                     throw new NoTokenError();
                 if (canonicalName !== canonicalToolNames.save) {
@@ -886,6 +938,8 @@ class EchoMemMCPServer {
                         return await this.handleSave(request.params.arguments, rec);
                     case canonicalToolNames.timeRange:
                         return await this.handleTimeRange(request.params.arguments);
+                    case canonicalToolNames.getByContext:
+                        return await this.handleGetByContext(request.params.arguments);
                     case canonicalToolNames.keywords:
                         return await this.handleKeywords(request.params.arguments);
                     case canonicalToolNames.others:
@@ -940,6 +994,8 @@ class EchoMemMCPServer {
                 rec.latency_ms = Date.now() - t0;
                 this.events.record(rec);
                 if (canonicalName !== canonicalToolNames.report &&
+                    canonicalName !== canonicalToolNames.contextHealth &&
+                    canonicalName !== canonicalToolNames.recompose &&
                     canonicalName !== canonicalToolNames.save &&
                     this.client.hasToken()) {
                     const finalAnalytics = {
@@ -1061,14 +1117,46 @@ Details: ${m.details || "N/A"}`)
             rec.conversation_chars = text.length;
             rec.save_source = typeof a?.source === "string" ? a.source : sourceFallback;
         }
-        const { success, memoriesExtracted, error } = await this.client.saveConversation(enrichedArgs);
+        const { success, memoriesExtracted, extractedMemories, contextId, capsuleId, passthrough: isPassthrough, error } = await this.client.saveConversation(enrichedArgs);
         if (!success)
             throw new Error(`EchoMem API Error: ${error}`);
         if (rec)
             rec.memories_extracted = typeof memoriesExtracted === "number" ? memoriesExtracted : undefined;
-        return {
-            content: [{ type: "text", text: `Successfully ingested conversation. Extracted ${memoriesExtracted} memory distinct events.` }],
-        };
+        // Passthrough saves store the capsule verbatim — no extraction, no embeddings.
+        if (isPassthrough) {
+            const text = [
+                `Session capsule saved (passthrough, no extraction).`,
+                typeof capsuleId === "string" && capsuleId ? `Capsule ID: ${capsuleId}` : "",
+                typeof contextId === "string" && contextId ? `Context: ${contextId}` : "",
+                "",
+                `To reload this capsule in a fresh session: get_memories_by_context({ contextId: "${contextId}" })`,
+            ].filter(Boolean).join("\n");
+            return { content: [{ type: "text", text }] };
+        }
+        // Surface WHAT was captured (not just the count) so the agent can verify the key facts survived
+        // extraction, and so it holds the ids to deterministically re-fetch this batch later (warm-up).
+        const saved = Array.isArray(extractedMemories) ? extractedMemories.filter(isRecord) : [];
+        const list = saved
+            .map((m, idx) => {
+            const keys = readString(m, "keys") ?? "(no key)";
+            const description = readString(m, "description") ?? "";
+            const details = readString(m, "details") ?? "";
+            const id = readString(m, "id");
+            return [
+                `[${idx + 1}] ${keys}${id ? ` · id ${id}` : ""}`,
+                description ? `Description: ${description}` : "",
+                details ? `Details: ${details}` : "",
+            ].filter(Boolean).join("\n");
+        })
+            .join("\n\n");
+        const text = [
+            `Successfully ingested conversation. Extracted ${memoriesExtracted} memory distinct events.`,
+            list,
+            saved.length
+                ? `Verify these captured the key facts. To re-fetch this exact batch later, search by the ids above${typeof contextId === "string" && contextId ? ` (context ${contextId})` : ""}.`
+                : "",
+        ].filter(Boolean).join("\n\n");
+        return { content: [{ type: "text", text }] };
     }
     async handleTimeRange(args) {
         const parsed = timeRangeSchema.parse(args);
@@ -1095,6 +1183,31 @@ Details: ${m.details || "N/A"}`)
             ],
         };
     }
+    async handleGetByContext(args) {
+        const parsed = getByContextSchema.parse(args);
+        const { success, memories, error } = await this.client.getMemoriesByContext(args);
+        if (!success)
+            throw new Error(`EchoMem API Error: ${error}`);
+        if (!memories?.length) {
+            return {
+                content: [{ type: "text", text: `No memories found for context ${parsed.contextId}.` }],
+            };
+        }
+        const formattedResults = memories
+            .map((m, idx) => `[${idx + 1}] ${m.keys || "Saved memory"}${m.id ? ` · id ${m.id}` : ""}
+Time: ${m.time} | Category: ${m.category} | Object: ${m.object} | Emotion: ${m.emotion}
+Description: ${m.description}
+Details: ${m.details || "N/A"}`)
+            .join("\n\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Recalled ${memories.length} memories from context ${parsed.contextId} (deterministic full batch):\n\n${formattedResults}`,
+                },
+            ],
+        };
+    }
     async handleKeywords(args) {
         const parsed = keywordsSchema.parse(args);
         const { success, memories, error } = await this.client.searchMemoriesByKeywords(args);

package/dist/package-metadata.js

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+const FALLBACK_PACKAGE = {
+    name: "@echomem/mcp",
+    version: "0.0.0",
+    description: "EchoMem Cloud-First MCP Server",
+};
+function loadPackageJson() {
+    try {
+        const packageUrl = new URL("../package.json", import.meta.url);
+        return JSON.parse(fs.readFileSync(packageUrl, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+const packageJson = loadPackageJson();
+function stringOrFallback(value, fallback) {
+    return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+export const MCP_PACKAGE_NAME = stringOrFallback(packageJson.name, FALLBACK_PACKAGE.name);
+export const MCP_PACKAGE_VERSION = stringOrFallback(packageJson.version, FALLBACK_PACKAGE.version);
+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_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.`,
+    "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.`;
+}

package/dist/report.js

@@ -623,7 +623,7 @@ function renderText(a, memCount, useColor) {
         L(c.green(`✓ You're connected — every new session now builds on your ${memCount} memories.`));
     }
     else {
-        L(c.green("→ Start now (no signup wall):  ") + c.bold("npx -y @echomem/mcp setup"));
+        L(c.green("→ Start now (no signup wall):  ") + c.bold("npm i -g @echomem/mcp@latest && echomem-mcp setup"));
         L(c.dim(`  ~1 minute. Your next coding session recalls instead of re-reading.`));
     }
     NL();

package/dist/setup-page.js

@@ -169,8 +169,7 @@ export function renderSetupPage() {
     .cityArrow {
       position: absolute;
       z-index: 5;
-      left: 50%;
-      transform: translateX(-50%);
+      right: clamp(22px, 3vw, 42px);
       bottom: clamp(22px, 3.5vh, 42px);
       width: 44px;
       height: 44px;

package/dist/setup.js

@@ -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_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.
@@ -791,7 +793,55 @@ async function cmdSetup(flags) {
         }
     }
     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.
@@ -1334,8 +1384,27 @@ async function cmdUnlock(flags) {
 async function cmdStatus() {
     const store = new KeyStore();
     const token = store.getToken();
+    console.log(`EchoMem MCP: ${MCP_PACKAGE_LABEL}`);
     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"}`);
@@ -1355,6 +1424,9 @@ 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
@@ -1371,8 +1443,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 +1458,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;

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.0",
+  "version": "1.4.2",
   "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"
   }
 }