@echomem/mcp 1.2.0 → 1.3.1

package/dist/setup.js

@@ -22,9 +22,13 @@ import readline from "node:readline";
 import axios from "axios";
 import { KeyStore } from "./keystore.js";
 import { fetchEncryptionConfig, deriveAndVerifyKey, verifyKeyB64 } from "./encryption.js";
-import { runReport, buildReportText } from "./report.js";
-// The connect-device page lives on the main site (WebPageReactVersion → yeahecho.com), where the
-// user already has a session. It calls the EchoMem API cross-origin. Override with ECHO_WEB_URL.
+import { collect, runReport, buildReportText, buildStatsPayload } from "./report.js";
+import { cmdMigrate, discoverMigratableSessions, estimateMigrationEta, startMigration } from "./migrate.js";
+import { syncCodexUsage } from "./codex-sync.js";
+import { renderSetupPage } from "./setup-page.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.
 const WEB_URL = (process.env.ECHO_WEB_URL || "https://yeahecho.com").replace(/\/$/, "");
 const API_BASE_URL = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
 function home(...p) {
@@ -62,7 +66,24 @@ export function buildServerEntry(opts = {}) {
     if (opts.devEntryPath) {
         return { command: "node", args: [opts.devEntryPath] };
     }
-    return { command: "npx", args: ["-y", "@echomem/mcp"] };
+    // Spawn the ALREADY-INSTALLED bridge directly (this node + this script's real path) instead of
+    // `npx -y @echomem/mcp`. `npx -y` re-resolves and, on a cache miss, NETWORK-fetches from the npm
+    // registry on EVERY client start — on a slow/flaky network that delays the MCP handshake past the
+    // client's timeout, so the agent hangs ("connection timed out after 30000ms") and Codex can SIGTERM.
+    // Using process.execPath (the running node) + the realpath'd entry also dodges the GUI-PATH trap:
+    // GUI/IDE-launched clients don't inherit nvm's PATH, so a bare `npx`/`echomem-mcp` may not resolve.
+    // Trade-off: the node path is version-specific under nvm — re-run `setup` after a Node upgrade.
+    try {
+        const entry = fs.realpathSync(process.argv[1] || "");
+        if (entry && fs.existsSync(entry)) {
+            return { command: process.execPath, args: [entry] };
+        }
+    }
+    catch {
+        /* couldn't resolve a local install — fall through to npx */
+    }
+    // Fallback (unresolved local install): at least drop `-y` so npx doesn't auto-INSTALL on every start.
+    return { command: "npx", args: ["@echomem/mcp"] };
 }
 /** The TOML block EchoMem adds to ~/.codex/config.toml. No secret — the bridge reads the keystore. */
 export function codexTomlBlock(entry) {
@@ -70,8 +91,12 @@ export function codexTomlBlock(entry) {
     const args = (Array.isArray(entry.args) ? entry.args : []).map((a) => JSON.stringify(String(a))).join(", ");
     return `[mcp_servers.echomem]\ncommand = ${command}\nargs = [${args}]\n`;
 }
-/** Write/merge the EchoMem entry straight into Codex's config.toml — no `codex` CLI needed. Idempotent. */
-function writeCodexConfig(configPath, entry) {
+/**
+ * Write/merge the EchoMem entry straight into Codex's config.toml — no `codex` CLI needed. Idempotent.
+ * If an `[mcp_servers.echomem]` block already exists it is REPLACED (so re-running `setup` upgrades a
+ * stale `npx -y` entry to the direct path); identical entries are left untouched.
+ */
+export function writeCodexConfig(configPath, entry) {
     let content = "";
     try {
         content = fs.readFileSync(configPath, "utf8");
@@ -79,11 +104,23 @@ function writeCodexConfig(configPath, entry) {
     catch {
         /* fresh config */
     }
-    if (/^\s*\[mcp_servers\.echomem\]/m.test(content))
-        return "exists";
+    const block = codexTomlBlock(entry).trimEnd();
+    const lines = content.split("\n");
+    const start = lines.findIndex((l) => /^\s*\[mcp_servers\.echomem\]\s*$/.test(l));
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    if (start >= 0) {
+        // The block runs from its header to the next top-level [section] (or EOF).
+        let end = start + 1;
+        while (end < lines.length && !/^\s*\[/.test(lines[end]))
+            end++;
+        if (lines.slice(start, end).join("\n").trimEnd() === block)
+            return "exists"; // already correct
+        const next = [...lines.slice(0, start), ...block.split("\n"), ...lines.slice(end)];
+        fs.writeFileSync(configPath, next.join("\n").replace(/\n{3,}/g, "\n\n").replace(/^\n+/, ""));
+        return "wrote"; // replaced a stale entry → caller tells the user to restart Codex
+    }
     const sep = content ? (content.endsWith("\n") ? "\n" : "\n\n") : "";
-    fs.appendFileSync(configPath, sep + codexTomlBlock(entry));
+    fs.appendFileSync(configPath, sep + block + "\n");
     return "wrote";
 }
 /** Merge the EchoMem entry into a JSON client's `mcpServers` map without clobbering siblings. */
@@ -112,23 +149,132 @@ function openBrowser(url) {
         /* headless — caller prints the URL */
     }
 }
+function deferred() {
+    let done = false;
+    let resolveInner;
+    let rejectInner;
+    const promise = new Promise((resolve, reject) => {
+        resolveInner = resolve;
+        rejectInner = reject;
+    });
+    return {
+        promise,
+        resolve: (value) => {
+            if (done)
+                return;
+            done = true;
+            resolveInner(value);
+        },
+        reject: (reason) => {
+            if (done)
+                return;
+            done = true;
+            rejectInner(reason);
+        },
+        settled: () => done,
+    };
+}
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = "";
+        req.on("data", (chunk) => {
+            body += chunk.toString();
+        });
+        req.on("end", () => {
+            try {
+                const parsed = JSON.parse(body || "{}");
+                resolve(isObjectRecord(parsed) ? parsed : {});
+            }
+            catch {
+                reject(new Error("bad json"));
+            }
+        });
+        req.on("error", (e) => reject(e instanceof Error ? e : new Error(String(e))));
+    });
+}
+function withTimeout(promise, ms, code, onTimeout) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            onTimeout?.();
+            const e = new Error(code);
+            e.code = code;
+            reject(e);
+        }, ms);
+        timer.unref?.();
+    });
+    return Promise.race([promise, timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+export function respondMigrate(res, body, status = 200) {
+    if (res.writableEnded)
+        return;
+    res.writeHead(status, { "Content-Type": "application/json" }).end(JSON.stringify(body));
+}
 /**
- * Start a localhost callback server. Resolves immediately with the bound `port` and a `wait` promise
- * that settles when the connect-device page delivers `{ token, key? }` — by POSTing JSON to
- * `/callback` or hitting `/callback?token=…&key=…`. Splitting port-acquisition from the token-wait
- * lets the caller build the callback URL before the user approves.
+ * Start the persistent localhost bridge used by the connect-device page. It accepts the token,
+ * serves local Wrapped stats, and holds the /migrate response until cmdLogin has created a cloud
+ * import session.
  */
 export function startCallbackServer(opts = {}) {
-    const timeoutMs = opts.timeoutMs ?? 180_000;
+    const timeoutMs = opts.timeoutMs ?? 300_000;
     const expectedNonce = opts.nonce;
     return new Promise((resolveOuter, rejectOuter) => {
-        let settle;
-        let fail;
-        const wait = new Promise((res, rej) => {
-            settle = res;
-            fail = rej;
-        });
-        const server = http.createServer((req, res) => {
+        const onToken = deferred();
+        const decision = deferred();
+        const migrateRequest = deferred();
+        let stats = null;
+        let authUrl = "";
+        let connected = false;
+        let progress = { status: "idle", total: 0, completed: 0, running: 0, queued: 0, failed: 0, extracted: 0 };
+        let migrateStarted = false;
+        let timer;
+        let closed = false;
+        let server;
+        const checkNonce = (nonce) => !expectedNonce || nonce === expectedNonce;
+        const text = (res, status, body = "") => res.writeHead(status, { "Content-Type": "text/plain" }).end(body);
+        const json = (res, status, body) => res.writeHead(status, { "Content-Type": "application/json" }).end(JSON.stringify(body));
+        const close = () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+            if (closed)
+                return;
+            closed = true;
+            server.close();
+        };
+        const armTimeout = () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                if (!onToken.settled()) {
+                    onToken.reject(new Error("timed out waiting for browser approval"));
+                }
+                else if (!decision.settled()) {
+                    decision.resolve("timeout");
+                }
+                close();
+            }, timeoutMs);
+        };
+        const handleCallback = (res, token, key, nonce) => {
+            if (!checkNonce(nonce))
+                return void text(res, 403, "bad nonce");
+            if (!token)
+                return void text(res, 400, "missing token");
+            connected = true;
+            res.writeHead(200, { "Content-Type": "text/html" }).end(`<!doctype html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=/setup?nonce=${encodeURIComponent(nonce || "")}&connected=1"></head><body style="font-family:system-ui;padding:3rem;text-align:center"><h2>EchoMem connected</h2><p>Returning to the local dashboard...</p><p><a href="/setup?nonce=${encodeURIComponent(nonce || "")}&connected=1">Continue</a></p></body></html>`);
+            onToken.resolve({ token, key });
+            armTimeout();
+        };
+        server = http.createServer((req, res) => {
             res.setHeader("Access-Control-Allow-Origin", "*");
             res.setHeader("Access-Control-Allow-Headers", "Content-Type");
             res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
@@ -137,51 +283,118 @@ export function startCallbackServer(opts = {}) {
             if (req.method === "OPTIONS")
                 return void res.writeHead(204).end();
             const url = new URL(req.url || "/", "http://127.0.0.1");
-            if (!url.pathname.startsWith("/callback"))
-                return void res.writeHead(404).end();
-            const finish = (token, key, nonce) => {
-                // Nonce gates the callback: only the page we opened (which carries the nonce) can post here.
-                if (expectedNonce && nonce !== expectedNonce)
-                    return void res.writeHead(403, { "Content-Type": "text/plain" }).end("bad nonce");
-                if (!token)
-                    return void res.writeHead(400, { "Content-Type": "text/plain" }).end("missing token");
-                res.writeHead(200, { "Content-Type": "text/html" }).end("<html><body style='font-family:system-ui;padding:3rem;text-align:center'><h2>✅ EchoMem connected</h2><p>You can close this tab and return to your editor.</p></body></html>");
-                clearTimeout(timer);
-                server.close();
-                settle({ token, key });
-            };
-            if (req.method === "GET") {
-                finish(url.searchParams.get("token") || undefined, url.searchParams.get("key") || undefined, url.searchParams.get("nonce") || undefined);
-            }
-            else {
-                let body = "";
-                req.on("data", (c) => (body += c));
-                req.on("end", () => {
+            const route = url.pathname;
+            const run = async () => {
+                if (route === "/setup" && req.method === "GET") {
+                    res.writeHead(200, {
+                        "Content-Type": "text/html; charset=utf-8",
+                        "Cache-Control": "no-store",
+                    }).end(renderSetupPage());
+                    return;
+                }
+                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, localOnly: true });
+                    return;
+                }
+                if (route === "/callback" && req.method === "GET") {
+                    handleCallback(res, url.searchParams.get("token") || undefined, url.searchParams.get("key") || undefined, url.searchParams.get("nonce") || undefined);
+                    return;
+                }
+                if (route === "/callback" && req.method === "POST") {
+                    let body;
                     try {
-                        const parsed = JSON.parse(body || "{}");
-                        finish(parsed.token, parsed.key, parsed.nonce);
+                        body = await readJsonBody(req);
                     }
                     catch {
-                        res.writeHead(400).end("bad json");
+                        text(res, 400, "bad json");
+                        return;
                     }
-                });
-            }
+                    handleCallback(res, asString(body.token), asString(body.key), asString(body.nonce));
+                    return;
+                }
+                if (route === "/stats" && req.method === "GET") {
+                    if (!checkNonce(url.searchParams.get("nonce") || undefined))
+                        return void text(res, 403, "bad nonce");
+                    const payload = opts.getStats ? opts.getStats() : stats;
+                    if (payload == null)
+                        return void res.writeHead(202).end();
+                    json(res, 200, payload);
+                    return;
+                }
+                if (route === "/progress" && req.method === "GET") {
+                    if (!checkNonce(url.searchParams.get("nonce") || undefined))
+                        return void text(res, 403, "bad nonce");
+                    json(res, 200, progress);
+                    return;
+                }
+                if (route === "/migrate" && 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");
+                    if (migrateStarted)
+                        return void json(res, 409, { error: "MIGRATE_IN_PROGRESS" });
+                    migrateStarted = true;
+                    const safety = setTimeout(() => {
+                        respondMigrate(res, { error: "IMPORT_START_TIMEOUT" }, 504);
+                    }, 30_000);
+                    safety.unref?.();
+                    migrateRequest.resolve({ res });
+                    decision.resolve("migrate");
+                    return;
+                }
+                if (route === "/skip" && 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");
+                    json(res, 200, { ok: true });
+                    decision.resolve("skip");
+                    close();
+                    return;
+                }
+                res.writeHead(404).end();
+            };
+            run().catch((e) => {
+                if (!res.writableEnded)
+                    text(res, 500, e instanceof Error ? e.message : String(e));
+            });
         });
-        const timer = setTimeout(() => {
-            server.close();
-            fail(new Error("timed out waiting for browser approval"));
-        }, timeoutMs);
+        armTimeout();
         server.on("error", (e) => rejectOuter(e));
         server.listen(0, "127.0.0.1", () => {
             const addr = server.address();
             const port = typeof addr === "object" && addr ? addr.port : 0;
             resolveOuter({
                 port,
-                wait,
-                close: () => {
-                    clearTimeout(timer);
-                    server.close();
+                onToken: onToken.promise,
+                wait: onToken.promise,
+                decision: decision.promise,
+                migrateRequest: migrateRequest.promise,
+                setAuthUrl: (url) => {
+                    authUrl = url;
+                },
+                setStats: (s) => {
+                    stats = s;
+                },
+                setProgress: (p) => {
+                    progress = p;
                 },
+                close,
             });
         });
     });
@@ -311,24 +524,193 @@ async function cmdLogin(flags) {
         console.log(msg);
         return;
     }
-    // Browser path: open the connect-device page pointed at our localhost callback. The nonce gates
-    // the callback so only the page we opened can deliver the token+key.
+    // Browser path: open a localhost dashboard. It briefly leaves for hosted auth, then returns here
+    // after the web page has delivered the token+key to the callback. The nonce gates every local route.
     console.log("Opening your browser to approve this device…");
     const nonce = randomUUID();
-    const { port, wait, close } = await startCallbackServer({ nonce });
-    const callbackUrl = `http://127.0.0.1:${port}/callback`;
-    const connectUrl = `${WEB_URL}/connect-device?callback=${encodeURIComponent(callbackUrl)}&nonce=${nonce}`;
-    openBrowser(connectUrl);
-    console.log(`If it didn't open, visit:\n  ${connectUrl}\n`);
+    let stats = null;
+    const srv = await startCallbackServer({ nonce, getStats: () => stats });
+    const callbackUrl = `http://127.0.0.1:${srv.port}/callback`;
+    const localSetupUrl = `http://127.0.0.1:${srv.port}/setup?nonce=${nonce}`;
+    const connectUrl = `${WEB_URL}/connect-device?callback=${encodeURIComponent(callbackUrl)}&nonce=${nonce}&return_to=${encodeURIComponent(localSetupUrl)}`;
+    srv.setAuthUrl(connectUrl);
+    openBrowser(localSetupUrl);
+    console.log(`If it didn't open, visit:\n  ${localSetupUrl}\n`);
+    let token;
+    let key;
     try {
-        const { token, key } = await wait;
-        const msg = await verifyAndStore({ token, key });
-        console.log(msg);
+        ({ token, key } = await srv.onToken);
     }
     catch (e) {
-        close();
+        srv.close();
         console.error(`❌ ${e?.message || e}. You can instead run: echomem-mcp login --token ec_… [--passphrase <vault pass>]`);
         process.exitCode = 1;
+        return;
+    }
+    console.log(await verifyAndStore({ token, key }));
+    const disc = discoverMigratableSessions();
+    const eta = estimateMigrationEta(disc.pending, disc.skippedActive);
+    const migratable = {
+        pending: disc.pending.length,
+        alreadyMigrated: disc.alreadyMigrated,
+        skippedActive: disc.skippedActive,
+        eta,
+        buckets: eta.buckets,
+        totalChars: eta.totalChars,
+        approxInputTokens: eta.approxInputTokens,
+        estimatedSeconds: eta.estimatedSeconds,
+        estimatedLabel: eta.estimatedLabel,
+    };
+    const sessionSummary = {
+        total: disc.sessions.length,
+        codex: disc.codexCount,
+        claudeCode: disc.claudeCount,
+    };
+    stats = await buildStatsPayload([], {
+        partial: true,
+        skipMemoryCount: true,
+        sessions: sessionSummary,
+        migratable,
+    });
+    srv.setStats(stats);
+    const fullStatsTimer = setTimeout(() => {
+        void buildStatsPayload(collect(), {
+            sessions: sessionSummary,
+            migratable,
+        }).then((payload) => {
+            stats = payload;
+            srv.setStats(payload);
+        }).catch(() => {
+            /* best effort — the fast local counts are already available */
+        });
+    }, 1500);
+    fullStatsTimer.unref?.();
+    srv.setProgress({
+        status: "idle",
+        total: disc.pending.length,
+        completed: 0,
+        running: 0,
+        queued: disc.pending.length,
+        failed: 0,
+        extracted: 0,
+    });
+    const choice = await srv.decision;
+    if (choice === "migrate") {
+        const { res } = await srv.migrateRequest;
+        let activeSessionId = "";
+        let activeJobCount = disc.pending.length;
+        let progressDone = 0;
+        let progressFailed = 0;
+        let progressExtracted = 0;
+        const updateProgress = (patch) => {
+            srv.setProgress({
+                status: "running",
+                sessionId: activeSessionId || undefined,
+                jobCount: activeJobCount,
+                total: activeJobCount,
+                completed: progressDone,
+                running: progressDone + progressFailed < activeJobCount ? 1 : 0,
+                queued: Math.max(0, activeJobCount - progressDone - progressFailed - 1),
+                failed: progressFailed,
+                extracted: progressExtracted,
+                ...patch,
+            });
+        };
+        try {
+            if (disc.pending.length === 0) {
+                srv.setProgress({
+                    status: "completed",
+                    total: 0,
+                    completed: 0,
+                    running: 0,
+                    queued: 0,
+                    failed: 0,
+                    extracted: 0,
+                    latest: "No unprocessed local conversations found.",
+                });
+                respondMigrate(res, { error: "NO_PENDING_SESSIONS" }, 409);
+                srv.close();
+                console.log("Setup complete — no unprocessed local conversations to extract.");
+                return;
+            }
+            updateProgress({ status: "starting", running: 0, queued: disc.pending.length, latest: "Creating import session." });
+            const controller = new AbortController();
+            const h = await withTimeout(startMigration({
+                pending: disc.pending,
+                signal: controller.signal,
+                onProgress: (ev) => {
+                    if (ev.error) {
+                        progressFailed += 1;
+                    }
+                    else {
+                        progressDone += 1;
+                        progressExtracted += ev.memories ?? 0;
+                    }
+                    updateProgress({
+                        latest: `${ev.session.source} ${(ev.session.firstTs || "").slice(0, 10)}${ev.error ? ` failed: ${ev.error}` : ""}`,
+                    });
+                },
+            }), 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." });
+            respondMigrate(res, { sessionId: h.sessionId, jobCount: h.jobCount, ...(h.capped ? { capped: h.capped } : {}) });
+            console.log("Migrating your history… keep this terminal open until it completes.");
+            console.log(`Migration metrics: ${h.metricsFile}`);
+            const r = await h.done;
+            srv.setProgress({
+                status: r.failed || r.stoppedReason ? "failed" : "completed",
+                sessionId: h.sessionId,
+                jobCount: h.jobCount,
+                capped: h.capped,
+                total: h.jobCount,
+                completed: r.migrated,
+                running: 0,
+                queued: 0,
+                failed: r.failed,
+                extracted: r.extracted,
+                latest: r.stoppedReason ? `Stopped: ${r.stoppedReason}` : "Import complete.",
+                ...(r.stoppedReason ? { error: r.stoppedReason } : {}),
+            });
+            console.log(`Import finished: ${r.migrated} imported, ${r.extracted} memories, ${r.failed} failed.`);
+            if (r.stoppedReason || r.failed)
+                process.exitCode = 1;
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+            srv.close();
+        }
+        catch (e) {
+            srv.setProgress({
+                status: "failed",
+                sessionId: activeSessionId || undefined,
+                jobCount: activeJobCount,
+                total: activeJobCount,
+                completed: progressDone,
+                running: 0,
+                queued: Math.max(0, activeJobCount - progressDone - progressFailed),
+                failed: progressFailed || 1,
+                extracted: progressExtracted,
+                error: String(e?.message || e),
+            });
+            if (e?.code === "NOT_LOGGED_IN")
+                respondMigrate(res, { error: "NOT_LOGGED_IN" }, 401);
+            else if (e?.code === "FORBIDDEN_SCOPE")
+                respondMigrate(res, { error: "FORBIDDEN_SCOPE" }, 403);
+            else if (e?.code === "VAULT_LOCKED")
+                respondMigrate(res, { error: "VAULT_LOCKED" }, 409);
+            else if (e?.code === "NO_PENDING_SESSIONS")
+                respondMigrate(res, { error: "NO_PENDING_SESSIONS" }, 409);
+            else if (e?.code === "IMPORT_START_TIMEOUT")
+                respondMigrate(res, { error: "IMPORT_START_TIMEOUT" }, 504);
+            else
+                respondMigrate(res, { error: "IMPORT_START_FAILED", message: String(e?.message || e) }, 500);
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+            srv.close();
+            process.exitCode = 1;
+        }
+    }
+    else {
+        console.log("Setup complete — run `echomem-mcp migrate` later to back-fill your history.");
+        srv.close();
     }
 }
 async function cmdUnlock(flags) {
@@ -387,10 +769,19 @@ Usage:
   echomem-mcp status                Show token/key/clients
   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
+  echomem-mcp migrate --estimate    Estimate migration size/time metadata without uploading transcripts
+  echomem-mcp migrate --max-chars N Import only sessions up to N assembled text chars
+  echomem-mcp migrate --min-chars N Import only sessions at least N assembled text chars
+  echomem-mcp migrate --largest --limit 1  Sample the largest pending session first
+  echomem-mcp migrate --include-active  Include sessions modified in the last 5 minutes
+  echomem-mcp migrate --metrics-file PATH  Write local per-session timing metadata JSONL
+  echomem-mcp sync-usage            Sync safe Codex JSONL usage summaries to EchoMem/Amplitude
 
 Manual / headless:
   echomem-mcp login --token ec_xxx [--passphrase <vault pass> | --key <base64>]
   echomem-mcp setup --dev /abs/path/dist/index.js   # point clients at a local checkout
+  echomem-mcp sync-usage --days 7 --limit 50 --dry-run
 `;
 /** Returns true if argv was a recognized subcommand (and was handled). */
 export async function runCli(argv) {
@@ -415,6 +806,12 @@ export async function runCli(argv) {
         case "report":
             await runReport(flags);
             return true;
+        case "migrate":
+            await cmdMigrate(flags);
+            return true;
+        case "sync-usage":
+            await syncCodexUsage(argv.slice(1));
+            return true;
         case "help":
         case "--help":
         case "-h":