@echomem/mcp 1.4.7 → 1.4.8

package/dist/setup.js

@@ -129,6 +129,51 @@ export function writeCodexConfig(configPath, entry) {
     fs.appendFileSync(configPath, sep + block + "\n");
     return "wrote";
 }
+/**
+ * Write the EchoMem guidance block into the agent's GLOBAL memory file (~/.codex/AGENTS.md,
+ * ~/.claude/CLAUDE.md) so the agent treats EchoMem as its core memory tool without the tool
+ * descriptions having to over-explain "when to call me". Marker-fenced + idempotent: only our
+ * block is ever replaced; the user's own content is never touched. Project-level files are
+ * deliberately NOT written — those belong to the user.
+ */
+const AGENTS_MD_BEGIN = "<!-- echomem:begin -->";
+const AGENTS_MD_END = "<!-- echomem:end -->";
+function echomemGuidanceBlock() {
+    return [
+        AGENTS_MD_BEGIN,
+        "## Memory (EchoMem)",
+        "EchoMem is your long-term memory across all coding sessions and tools.",
+        "- Before re-deriving past decisions, project context, or anything the user likely settled before: call `search_memories` first.",
+        "- When meaningful work wraps up (a decision, a fix, a milestone) or the user asks to remember something: call `save_conversation`.",
+        "- If the user pastes a session carryover/checkpoint: it may reference `get_checkpoint_by_context` — use it to pull the checkpoint/decision trail when you need more than the snapshot.",
+        "- If the user asks to show, reopen, restart, or bring back the EchoMem HUD (the context-health overlay), run the shell command `echomem-hud app --client auto`.",
+        "- If the user wants the HUD to come back after a computer restart, run the shell command `echomem-hud autostart on --client auto`.",
+        AGENTS_MD_END,
+    ].join("\n");
+}
+export function writeAgentsMemoryGuidance(filePath) {
+    let content = "";
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        /* fresh file */
+    }
+    const block = echomemGuidanceBlock();
+    const start = content.indexOf(AGENTS_MD_BEGIN);
+    const end = content.indexOf(AGENTS_MD_END);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    if (start >= 0 && end > start) {
+        const current = content.slice(start, end + AGENTS_MD_END.length);
+        if (current === block)
+            return "exists";
+        fs.writeFileSync(filePath, content.slice(0, start) + block + content.slice(end + AGENTS_MD_END.length));
+        return "updated";
+    }
+    const sep = content ? (content.endsWith("\n") ? "\n" : "\n\n") : "";
+    fs.appendFileSync(filePath, sep + block + "\n");
+    return "wrote";
+}
 /** Merge the EchoMem entry into a JSON client's `mcpServers` map without clobbering siblings. */
 export function writeJsonClientConfig(configPath, entry) {
     let config = {};
@@ -275,8 +320,8 @@ export function resolveServerEntryVersion(entry) {
     }
     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;
+        // 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;
@@ -408,11 +453,54 @@ function openBrowser(url) {
         /* headless — caller prints the URL */
     }
 }
+function openClaudeDesktop() {
+    if (process.platform !== "darwin") {
+        return { ok: false, message: "Could not auto-open Claude on this system. The prompt is copied - open Claude Desktop and paste it." };
+    }
+    const installedPath = firstExisting([
+        "/Applications/Claude.app",
+        path.join(os.homedir(), "Applications", "Claude.app"),
+    ]);
+    const attempts = [
+        ["-b", "com.anthropic.claudefordesktop"],
+        ["-a", "Claude"],
+        ...(installedPath ? [[installedPath]] : []),
+    ];
+    const failures = [];
+    for (const args of attempts) {
+        try {
+            execFileSync("open", args, { stdio: "pipe" });
+            return { ok: true, message: "Opened Claude Desktop. The prompt is copied - paste it into Claude." };
+        }
+        catch (error) {
+            failures.push(`${args.join(" ")}: ${commandFailureMessage(error)}`);
+        }
+    }
+    return {
+        ok: false,
+        message: installedPath
+            ? "Could not auto-open Claude Desktop. The prompt is copied - open Claude Desktop and paste it."
+            : "Claude Desktop was not found by macOS. The prompt is copied - open Claude manually and paste it.",
+        detail: failures.join(" | "),
+    };
+}
+function commandFailureMessage(error) {
+    const maybe = error;
+    if (Buffer.isBuffer(maybe.stderr)) {
+        const stderr = maybe.stderr.toString("utf8").trim();
+        if (stderr)
+            return stderr;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
 function migratableFromDiscovery(disc) {
     const eta = estimateMigrationEta(disc.pending, disc.skippedActive);
+    const pendingCodex = disc.pendingCodex ?? disc.pending.filter((s) => s.source === "codex").length;
     return {
         pending: disc.pending.length,
         pendingTotal: disc.pendingTotal,
+        pendingCodex,
+        pendingClaudeCode: disc.pendingClaudeCode ?? disc.pending.length - pendingCodex,
         alreadyMigrated: disc.alreadyMigrated,
         skippedActive: disc.skippedActive,
         limited: disc.limited,
@@ -438,6 +526,8 @@ function migratableFromFastSummary(summary) {
     return {
         pending: summary.pending,
         pendingTotal: summary.pendingTotal,
+        pendingCodex: summary.pendingCodex,
+        pendingClaudeCode: summary.pendingClaudeCode,
         alreadyMigrated: summary.alreadyMigrated,
         skippedActive: summary.skippedActive,
         eta: summary.eta,
@@ -557,6 +647,107 @@ function serveRepoCityAsset(reqPath, res) {
     fs.createReadStream(filePath).pipe(res);
     return true;
 }
+function hudAssetsRoot() {
+    return fileURLToPath(new URL("../assets/hud/", import.meta.url));
+}
+function serveHudAsset(reqPath, res) {
+    const root = hudAssetsRoot();
+    const rel = decodeURIComponent(reqPath.slice("/hud-assets/".length));
+    const filePath = path.resolve(root, rel);
+    const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+    if (!filePath.startsWith(rootWithSep)) {
+        res.writeHead(403).end("forbidden");
+        return true;
+    }
+    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+        res.writeHead(404).end("not found");
+        return true;
+    }
+    res.writeHead(200, {
+        "Content-Type": CITY_ASSET_TYPES[path.extname(filePath)] || "application/octet-stream",
+        "Cache-Control": "no-store",
+    });
+    fs.createReadStream(filePath).pipe(res);
+    return true;
+}
+function firstExisting(paths) {
+    for (const candidate of paths) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+function appResourcesPath(appName) {
+    const app = firstExisting([
+        `/Applications/${appName}.app`,
+        path.join(os.homedir(), "Applications", `${appName}.app`),
+    ]);
+    return app ? path.join(app, "Contents", "Resources") : null;
+}
+function agentIconSource(id) {
+    const resources = appResourcesPath(id === "codex" ? "Codex" : "Claude");
+    if (!resources)
+        return null;
+    if (id === "codex") {
+        return firstExisting([
+            path.join(resources, "icon.png"),
+            path.join(resources, "icon-codex-dark-color.png"),
+            path.join(resources, "icon-codex-light.png"),
+            path.join(resources, "icon.icns"),
+            path.join(resources, "app.icns"),
+            path.join(resources, "electron.icns"),
+        ]);
+    }
+    return firstExisting([
+        path.join(resources, "icon.png"),
+        path.join(resources, "app.png"),
+        path.join(resources, "icon.icns"),
+        path.join(resources, "electron.icns"),
+    ]);
+}
+function convertedAgentIconPath(id, sourcePath) {
+    if (path.extname(sourcePath).toLowerCase() === ".png")
+        return sourcePath;
+    if (process.platform !== "darwin" || path.extname(sourcePath).toLowerCase() !== ".icns")
+        return null;
+    const stat = fs.statSync(sourcePath);
+    const cacheDir = path.join(os.homedir(), ".echomem", "cache", "agent-icons");
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const out = path.join(cacheDir, `${id}-${Math.round(stat.mtimeMs)}-${stat.size}.png`);
+    if (fs.existsSync(out))
+        return out;
+    try {
+        execFileSync("sips", ["-s", "format", "png", sourcePath, "--out", out], { stdio: "ignore" });
+        return fs.existsSync(out) ? out : null;
+    }
+    catch {
+        try {
+            fs.rmSync(out, { force: true });
+        }
+        catch { }
+        return null;
+    }
+}
+function serveAgentIcon(reqPath, res) {
+    const raw = decodeURIComponent(reqPath.slice("/agent-icons/".length)).replace(/\.png$/i, "");
+    const id = raw === "codex" || raw === "claude-desktop" ? raw : null;
+    if (!id) {
+        res.writeHead(404).end("not found");
+        return true;
+    }
+    const source = agentIconSource(id);
+    const filePath = source ? convertedAgentIconPath(id, source) : null;
+    if (!filePath) {
+        res.writeHead(404).end("not found");
+        return true;
+    }
+    res.writeHead(200, {
+        "Content-Type": "image/png",
+        "Cache-Control": "no-store",
+    });
+    fs.createReadStream(filePath).pipe(res);
+    return true;
+}
 function discoverMigratableSessionsOffThread() {
     const migrateUrl = new URL("./migrate.js", import.meta.url).href;
     const code = `
@@ -739,6 +930,14 @@ export function startCallbackServer(opts = {}) {
                     serveRepoCityAsset(route, res);
                     return;
                 }
+                if (route.startsWith("/hud-assets/") && req.method === "GET") {
+                    serveHudAsset(route, res);
+                    return;
+                }
+                if (route.startsWith("/agent-icons/") && req.method === "GET") {
+                    serveAgentIcon(route, res);
+                    return;
+                }
                 if (route === "/setup" && req.method === "GET") {
                     res.writeHead(200, {
                         "Content-Type": "text/html; charset=utf-8",
@@ -749,7 +948,25 @@ export function startCallbackServer(opts = {}) {
                 if (route === "/config" && req.method === "GET") {
                     if (!checkNonce(url.searchParams.get("nonce") || undefined))
                         return void text(res, 403, "bad nonce");
-                    json(res, 200, { connected, authUrl, switchAccountUrl: switchAccountUrl || authUrl, localOnly: true });
+                    json(res, 200, { connected, authUrl, switchAccountUrl: switchAccountUrl || authUrl, localOnly: true, workspacePath: process.cwd() });
+                    return;
+                }
+                if (route === "/launch-agent" && req.method === "POST") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        text(res, 400, "bad json");
+                        return;
+                    }
+                    if (!checkNonce(asString(body.nonce)))
+                        return void text(res, 403, "bad nonce");
+                    const agent = asString(body.agent);
+                    if (agent !== "claude-desktop")
+                        return void json(res, 400, { ok: false, message: "Unsupported agent." });
+                    const result = openClaudeDesktop();
+                    json(res, result.ok ? 200 : 501, result);
                     return;
                 }
                 if (route === "/callback" && req.method === "GET") {
@@ -1052,9 +1269,14 @@ async function cmdSetup(flags) {
             }
         }
     }
+    if (!flags["no-agents-md"]) {
+        writeMemoryGuidanceForTargets(targets);
+    }
     console.log("");
     if (flags["skip-login"] || flags["no-login"]) {
-        console.log(`Skipped login; existing EchoMem credentials are unchanged. Current bridge: ${MCP_PACKAGE_LABEL}`);
+        // init drives login itself right after, so the "skipped" note would be misleading there.
+        if (!flags["init-quiet"])
+            console.log(`Skipped login; existing EchoMem credentials are unchanged. Current bridge: ${MCP_PACKAGE_LABEL}`);
     }
     else {
         await cmdLogin(flags);
@@ -1062,6 +1284,63 @@ async function cmdSetup(flags) {
     if (flags["with-hud"])
         await cmdSetupHud(flags);
 }
+/**
+ * `echomem-mcp init` — the one-command install. Configures EVERY coding agent installed on this
+ * machine (Codex + Claude Code + Claude Desktop, not just auto-detected ones), writes the AGENTS.md
+ * memory guidance, logs in via the browser, and launches the context HUD — the whole product in a
+ * single command. `setup`/`update` remain the granular primitives; init just picks the "do everything"
+ * defaults and frames the result.
+ */
+async function cmdInit(flags) {
+    console.log("Setting up EchoMem — shared memory for all your coding agents, plus the live context HUD.\n");
+    // 1. Configure every installed agent + write AGENTS.md. Hold login + HUD so we control ordering.
+    await cmdSetup({ ...flags, all: true, "skip-login": true, "with-hud": false, "init-quiet": true });
+    // 2. Bring the HUD up NOW (non-blocking) so everything is already running while onboarding proceeds.
+    if (!flags["no-hud"])
+        await cmdSetupHud(flags);
+    // 3. Start onboarding — opens the browser dashboard (scan → connect → extraction) and waits there.
+    console.log("");
+    if (!flags["skip-login"] && !flags["no-login"])
+        await cmdLogin(flags);
+    console.log("");
+    console.log("🎉 EchoMem is ready.");
+    console.log("   • MCP memory is configured for every coding agent installed on this machine.");
+    if (!flags["no-hud"]) {
+        console.log('   • The context HUD is running (top-right). Right-click it → "Open at login" to keep it,');
+        console.log('     or just tell your agent "open the EchoMem HUD" anytime (it runs: echomem-hud app).');
+    }
+    else {
+        console.log('   • Start the context HUD anytime with: echomem-hud app');
+    }
+    console.log('   • Try it now: ask your agent — "search my EchoMem for what I\'ve been working on and recap it."');
+}
+/**
+ * For each configured client, add the EchoMem guidance block to its GLOBAL memory file so the
+ * agent knows to lean on EchoMem for recall/save. Global only (~/.codex/AGENTS.md,
+ * ~/.claude/CLAUDE.md) — project files are the user's. Skip with --no-agents-md.
+ */
+function writeMemoryGuidanceForTargets(targets) {
+    const files = new Map(); // path → label
+    for (const t of targets) {
+        if (t.id === "codex")
+            files.set(home(".codex", "AGENTS.md"), "Codex");
+        if (t.id === "claude-code" || t.id === "claude-desktop")
+            files.set(home(".claude", "CLAUDE.md"), "Claude");
+    }
+    for (const [file, label] of files) {
+        try {
+            const result = writeAgentsMemoryGuidance(file);
+            if (result === "wrote")
+                console.log(`✅ Added EchoMem memory guidance to ${label}'s global memory file: ${file}`);
+            else if (result === "updated")
+                console.log(`✅ Refreshed EchoMem memory guidance in ${file}`);
+            // "exists" → silent; nothing changed.
+        }
+        catch (error) {
+            console.log(`ℹ️  Could not write memory guidance to ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
 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}.`);
@@ -1544,49 +1823,79 @@ async function cmdLogin(flags) {
                 return;
             }
             updateProgress({ status: "starting", running: 0, queued: exact.pending.length, latest: "Creating import session." });
-            const controller = new AbortController();
-            const h = await withTimeout(startMigration({
-                pending: exact.pending,
-                signal: controller.signal,
-                onProgress: (ev) => {
-                    let latestRepo;
-                    if (ev.error) {
-                        progressFailed += 1;
-                    }
-                    else {
-                        progressDone += 1;
-                        progressExtracted += ev.memories ?? 0;
-                        latestRepo = repoLabel(ev.session.cwd); // building this completed conversation belongs to
-                    }
-                    updateProgress({
-                        latest: `${ev.session.source} ${(ev.session.firstTs || "").slice(0, 10)}${ev.error ? ` failed: ${ev.error}` : ""}`,
-                        ...(latestRepo ? { latestRepo } : {}),
-                    });
-                },
-            }), 30_000, "IMPORT_START_TIMEOUT", () => controller.abort());
-            activeSessionId = h.sessionId;
-            activeJobCount = h.jobCount;
-            updateProgress({ status: "running", sessionId: h.sessionId, jobCount: h.jobCount, total: h.jobCount, capped: h.capped, latest: "Import session created." });
-            sendMigrate({ sessionId: h.sessionId, jobCount: h.jobCount, ...(h.capped ? { capped: h.capped } : {}) });
+            // Plan caps limit how many conversations one import session accepts (IMPORT_LIMIT_EXCEEDED →
+            // startMigration slices to the cap). Instead of making the user re-run setup per batch (3000
+            // sessions used to mean 3 clicks), loop batches automatically until everything pending is done.
+            const onBatchProgress = (ev) => {
+                let latestRepo;
+                if (ev.error) {
+                    progressFailed += 1;
+                }
+                else {
+                    progressDone += 1;
+                    progressExtracted += ev.memories ?? 0;
+                    latestRepo = repoLabel(ev.session.cwd); // building this completed conversation belongs to
+                }
+                updateProgress({
+                    latest: `${ev.session.source} ${(ev.session.firstTs || "").slice(0, 10)}${ev.error ? ` failed: ${ev.error}` : ""}`,
+                    ...(latestRepo ? { latestRepo } : {}),
+                });
+            };
+            let remaining = exact.pending;
+            let stoppedReason;
+            let planLimitNote;
+            let batchIndex = 0;
             console.log("Migrating your history… keep this terminal open until it completes.");
-            console.log(`Migration metrics: ${h.metricsFile}`);
-            const r = await h.done;
+            for (;;) {
+                batchIndex += 1;
+                let h;
+                try {
+                    const controller = new AbortController();
+                    h = await withTimeout(startMigration({ pending: remaining, signal: controller.signal, onProgress: onBatchProgress }), 30_000, "IMPORT_START_TIMEOUT", () => controller.abort());
+                }
+                catch (batchError) {
+                    if (batchIndex === 1)
+                        throw batchError; // first batch failing = the whole import failed
+                    // A later batch could not start (e.g. plan headroom exhausted). Finish gracefully with a note.
+                    planLimitNote = `Imported ${progressDone} so far — the rest hit your plan's import limit. Re-run extraction later for the remaining ${remaining.length}.`;
+                    break;
+                }
+                activeSessionId = h.sessionId;
+                if (batchIndex === 1) {
+                    updateProgress({ status: "running", sessionId: h.sessionId, jobCount: activeJobCount, total: activeJobCount, latest: "Import session created." });
+                    sendMigrate({ sessionId: h.sessionId, jobCount: activeJobCount });
+                }
+                else {
+                    updateProgress({ latest: `Continuing automatically — batch ${batchIndex} (${remaining.length} left).` });
+                }
+                console.log(`Migration metrics (batch ${batchIndex}): ${h.metricsFile}`);
+                const r = await h.done;
+                if (r.stoppedReason) {
+                    stoppedReason = r.stoppedReason;
+                    break;
+                }
+                // startMigration sliced to the cap ⇒ more remain: continue with the next batch automatically.
+                if (h.capped && remaining.length > h.jobCount) {
+                    remaining = remaining.slice(h.jobCount);
+                    continue;
+                }
+                break;
+            }
             srv.setProgress({
-                status: r.failed || r.stoppedReason ? "failed" : "completed",
-                sessionId: h.sessionId,
-                jobCount: h.jobCount,
-                capped: h.capped,
-                total: h.jobCount,
-                completed: r.migrated,
+                status: stoppedReason ? "failed" : "completed",
+                sessionId: activeSessionId || undefined,
+                jobCount: activeJobCount,
+                total: activeJobCount,
+                completed: progressDone,
                 running: 0,
                 queued: 0,
-                failed: r.failed,
-                extracted: r.extracted,
-                latest: r.stoppedReason ? `Stopped: ${r.stoppedReason}` : "Import complete.",
-                ...(r.stoppedReason ? { error: r.stoppedReason } : {}),
+                failed: progressFailed,
+                extracted: progressExtracted,
+                latest: stoppedReason ? `Stopped: ${stoppedReason}` : planLimitNote || "Import complete.",
+                ...(stoppedReason ? { error: stoppedReason } : {}),
             });
-            console.log(`Import finished: ${r.migrated} imported, ${r.extracted} memories, ${r.failed} failed.`);
-            if (r.stoppedReason || r.failed)
+            console.log(`Import finished: ${progressDone} imported, ${progressExtracted} memories, ${progressFailed} failed.`);
+            if (stoppedReason || progressFailed)
                 process.exitCode = 1;
             await new Promise((resolve) => setTimeout(resolve, 2000));
             srv.close();
@@ -1713,6 +2022,7 @@ function cmdLogout() {
 const HELP = `EchoMem MCP — local memory bridge
 
 Usage:
+  echomem-mcp init                  One command: configure every installed agent + HUD + log in
   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
@@ -1749,6 +2059,9 @@ export async function runCli(argv) {
     const cmd = argv[0];
     const flags = parseFlags(argv.slice(1));
     switch (cmd) {
+        case "init":
+            await cmdInit(flags);
+            return true;
         case "setup":
             await cmdSetup(flags);
             return true;

package/dist/v1-contract.js

@@ -16,6 +16,7 @@ export const canonicalToolNames = {
     recompose: "echo_recompose",
     delete: "delete_memory",
     getByContext: "get_memories_by_context",
+    checkpointByContext: "get_checkpoint_by_context",
 };
 export const legacyAliasToCanonical = {
     search_memories_by_description_semantic: canonicalToolNames.search,
@@ -114,7 +115,7 @@ export function listToolSpecs(opts = {}) {
     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}.${updateSection}`),
+            description: withMcpVersion(`Recall the user's prior decisions, preferences, and project context from EchoMem — their long-term memory across ALL their AI tools, not just this session. Use it instead of re-deriving or re-asking what the user already settled.${mapSection}\nReturns the ranked memories; set includeAnswer=true only if you need the legacy synthesized answer. Current time: ${currentTime}.${updateSection}`),
             inputSchema: {
                 type: "object",
                 properties: {
@@ -160,7 +161,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.save,
-            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.",
+            description: "Save this conversation into EchoMem as long-term memory (durable memories are extracted automatically). passthrough=true stores the text verbatim as a session capsule instead — reload it later via get_memories_by_context.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -383,6 +384,23 @@ export function listToolSpecs(opts = {}) {
                 required: ["contextId"],
             },
         },
+        {
+            name: canonicalToolNames.checkpointByContext,
+            description: withMcpVersion(`Rebuild a clean-context checkpoint / decision log from one EchoMem contextId. Use this when the user or EchoMem HUD gives you a contextId for a renewed coding session and you need the session handoff, not a raw memory dump. It deterministically fetches that context and formats it as orientation state: decisions, carryover, constraints, and checkpoints. Current time: ${currentTime}.`),
+            inputSchema: {
+                type: "object",
+                properties: {
+                    contextId: { type: "string", description: "The EchoMem contextId shown by the HUD or returned by save_conversation / Renew session." },
+                    limit: { type: "number", default: 100 },
+                    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.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.7",
+  "version": "1.4.8",
   "description": "EchoMem Cloud-First MCP Server",
   "main": "dist/index.js",
   "type": "module",
@@ -20,7 +20,8 @@
     "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/update-check.test.mjs && node test/delete.test.mjs && node test/migrate.test.mjs && node test/hud.test.mjs",
+    "preview:extraction": "npm run build && node scripts/preview-extraction.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/update-check.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/hud.test.mjs",
     "prepack": "npm run build && node scripts/bundle-city.mjs"
   },
   "dependencies": {