@echomem/mcp 1.1.0 → 1.3.0

package/README.md

@@ -6,11 +6,11 @@ This package implements a stateless, cloud-first [Model Context Protocol (MCP)](
 
 This MCP Server bridges local tools and your EchoMem Cloud API entirely via authenticated REST `fetch()` calls. 
 
-- `search_memories`: Connects to `POST /api/extension/memories/search`
+- `search_memories`: Calls the deep-search candidate phase, resolves the retrieved memory rows, and returns those memories only by default
 - `save_conversation`: Connects to `POST /api/extension/memories/ingest`
 - `get_memories_by_time_range`: Connects to `POST /api/extension/memories/time-range`
 - `search_memories_by_keywords`: Connects to `POST /api/extension/memories/keywords`
-- `search_others_memories`: Connects to MemoryFeed search after resolving the authenticated Echo user id
+- `search_others_memories`: Connects to MemoryFeed public search without sending the authenticated Echo user id
 
 No direct access to the `IndexedDB` or local files is required.
 
@@ -27,7 +27,9 @@ For **zero-knowledge accounts**, the key never leaves your machine. The bridge h
 - **locked state:** if the key is absent or past its TTL (7 days, matching the extension), tools
   return a `🔒 locked` nudge to run `echomem-mcp unlock` — **ciphertext is never handed to the model**.
 
-Unencrypted accounts are unaffected and use the tuned two-phase retriever as before.
+Unencrypted accounts are unaffected. `search_memories` returns retrieved memories by default so
+your MCP client does the final answer generation; pass `includeAnswer: true` only if you need the
+legacy EchoMem-synthesized recall answer.
 
 ## Quick start (recommended)
 
@@ -142,11 +144,11 @@ ECHO_API_TOKEN="your_token" ECHO_API_BASE_URL="http://localhost:3000" npm run st
 
 ## Available Tools
 
-* **`search_memories`**: Perform semantic searches against your personal memory vault using cloud embeddings.
+* **`search_memories`**: Retrieve ranked personal memories for a query. Defaults to memory-only output and skips EchoMem answer generation; set `includeAnswer: true` for the legacy synthesized recall.
 * **`save_conversation`**: Ingest and structure a conversation directly into your EchoMem timeline.
 * **`get_memories_by_time_range`**: Retrieve memories between explicit start/end timestamps.
 * **`search_memories_by_keywords`**: Retrieve memories by matching the `keys` field.
-* **`search_others_memories`**: Search other users' public memories through MemoryFeed.
+* **`search_others_memories`**: Search other users' public memories through MemoryFeed public search.
 
 Legacy aliases are preserved for compatibility:
 

package/dist/index.js

@@ -88,6 +88,46 @@ function classifyError(error) {
         return "invalid_args";
     return "api_error";
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(record, key) {
+    const value = record[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function readNumber(record, key) {
+    const value = record[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function normalizeRetrievalCandidate(value, fallbackRank) {
+    if (!isRecord(value))
+        return null;
+    const id = readString(value, "memory_id") ?? readString(value, "id");
+    if (!id)
+        return null;
+    return {
+        id,
+        bucket: readString(value, "bucket") ?? "primary",
+        rank: readNumber(value, "rank") ?? fallbackRank,
+        score: readNumber(value, "retrieval_similarity_score")
+            ?? readNumber(value, "similarity_score")
+            ?? readNumber(value, "similarity"),
+        key: readString(value, "key") ?? readString(value, "keys"),
+        time: readString(value, "time"),
+        isPublic: typeof value.is_public === "boolean" ? value.is_public : undefined,
+    };
+}
+function withinTimeFrame(memory, candidate, timeFrameDays) {
+    if (!timeFrameDays)
+        return true;
+    const timestamp = readString(memory, "time") ?? readString(memory, "created_at") ?? candidate.time;
+    if (!timestamp)
+        return true;
+    const ms = Date.parse(timestamp);
+    if (!Number.isFinite(ms))
+        return true;
+    return ms >= Date.now() - timeFrameDays * 24 * 60 * 60 * 1000;
+}
 class EchoMemApiClient {
     store;
     axios;
@@ -190,6 +230,89 @@ class EchoMemApiClient {
         const idx = desc.indexOf("Content:");
         return (idx >= 0 ? desc.slice(idx + "Content:".length) : desc).trim();
     }
+    async fetchMemoryById(id, enc) {
+        try {
+            const response = await this.axios.get(`/api/extension/memories/${encodeURIComponent(id)}`, {
+                timeout: 10_000,
+            });
+            const row = isRecord(response.data) ? response.data : {};
+            return enc.enabled ? await decryptMemoryFields(row, enc.key) : row;
+        }
+        catch (error) {
+            if (axios.isAxiosError(error) && error.response?.status === 404) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async searchMemoriesRaw(query, opts, enc, retrievalOnly = false) {
+        const response = await this.axios.post("/api/extension/memories/search", {
+            query,
+            k: opts.limit,
+            similarityThreshold: opts.threshold,
+            timeFrameDays: opts.timeFrameDays,
+        });
+        const data = enc.enabled ? await this.decryptResult(response.data, enc.key) : response.data;
+        return retrievalOnly && isRecord(data)
+            ? { ...data, retrievalOnly: true, tuned: false }
+            : data;
+    }
+    async searchMemoriesRetrieved(query, opts, enc) {
+        const response = await this.axios.post("/api/extension/memories/deep-search/candidates", {
+            query,
+            userTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
+        });
+        const data = response.data ?? {};
+        if (data.success === false) {
+            throw new Error(`deep-search candidates proxy error: ${data.error || "unknown"}`);
+        }
+        const rawCandidates = Array.isArray(data.personalCandidates) ? data.personalCandidates : [];
+        const candidates = rawCandidates
+            .map((candidate, index) => normalizeRetrievalCandidate(candidate, index))
+            .filter((candidate) => candidate !== null);
+        const primaryIds = new Set(candidates.filter((c) => c.bucket === "primary").map((c) => c.id));
+        const seen = new Set();
+        const dedupedCandidates = candidates.filter((candidate) => {
+            if (candidate.bucket === "inference" && primaryIds.has(candidate.id))
+                return false;
+            if (candidate.score !== undefined && candidate.score < opts.threshold)
+                return false;
+            if (seen.has(candidate.id))
+                return false;
+            seen.add(candidate.id);
+            return true;
+        });
+        const memories = [];
+        for (const candidate of dedupedCandidates) {
+            const row = await this.fetchMemoryById(candidate.id, enc);
+            if (!row || !withinTimeFrame(row, candidate, opts.timeFrameDays))
+                continue;
+            const key = readString(row, "key") ?? readString(row, "keys") ?? candidate.key ?? "";
+            const memory = {
+                ...row,
+                id: readString(row, "id") ?? candidate.id,
+                key,
+                keys: readString(row, "keys") ?? key,
+                retrieval_bucket: candidate.bucket,
+                retrieval_rank: candidate.rank,
+                is_public: typeof row.is_public === "boolean" ? row.is_public : candidate.isPublic,
+            };
+            if (candidate.score !== undefined) {
+                memory.similarity = candidate.score;
+                memory.similarity_score = candidate.score;
+                memory.retrieval_similarity_score = candidate.score;
+            }
+            memories.push(memory);
+            if (memories.length >= opts.limit)
+                break;
+        }
+        return {
+            success: true,
+            tuned: true,
+            retrievalOnly: true,
+            memories,
+        };
+    }
     // Tuned recall. Routes through echo-mem-chrome's AUTHENTICATED deep-search proxy
     // (the same route the Chrome extension uses): it verifies our ec_ token, derives
     // user_id server-side, and forwards to dg-web's two-phase retriever. The bridge
@@ -233,29 +356,26 @@ class EchoMemApiClient {
             });
             return enc.enabled ? await this.decryptResult(response.data, enc.key) : response.data;
         }
+        const searchOpts = { limit, threshold, timeFrameDays: parsed.timeFrameDays };
+        if (!parsed.includeAnswer) {
+            try {
+                return await this.searchMemoriesRetrieved(query, searchOpts, enc);
+            }
+            catch {
+                return await this.searchMemoriesRaw(query, searchOpts, enc, true);
+            }
+        }
         // Encrypted account: the server can't synthesize over plaintext it doesn't hold, so use the raw
         // retriever (returns ciphertext) and decrypt locally — zero-knowledge preserved end-to-end.
         if (enc.enabled) {
-            const response = await this.axios.post("/api/extension/memories/search", {
-                query,
-                k: limit,
-                similarityThreshold: threshold,
-                timeFrameDays: parsed.timeFrameDays,
-            });
-            return await this.decryptResult(response.data, enc.key);
+            return await this.searchMemoriesRaw(query, searchOpts, enc);
         }
         // Unencrypted: prefer the tuned two-phase retriever; degrade gracefully to the untuned path.
         try {
             return await this.searchMemoriesTuned(query);
         }
         catch {
-            const response = await this.axios.post("/api/extension/memories/search", {
-                query,
-                k: limit,
-                similarityThreshold: threshold,
-                timeFrameDays: parsed.timeFrameDays,
-            });
-            return response.data;
+            return await this.searchMemoriesRaw(query, searchOpts, enc);
         }
     }
     /** Decrypt the model-visible fields on a `{ memories: [...] }` response locally. */
@@ -313,9 +433,7 @@ class EchoMemApiClient {
     async searchOthersMemories(args) {
         const parsed = othersSchema.parse(args);
         try {
-            const whoami = await this.whoami();
-            const response = await axios.post(`${MEMORY_FEED_API_URL.replace(/\/$/, "")}/api/search`, {
-                userId: whoami.user_id,
+            const response = await axios.post(`${MEMORY_FEED_API_URL.replace(/\/$/, "")}/api/search/public`, {
                 query: parsed.query,
                 excludedMemoryIds: [],
             }, {
@@ -459,6 +577,47 @@ class EchoMemMCPServer {
             rec.results_chars = mems.reduce((n, m) => n + String(m?.description ?? "").length, 0);
             rec.memory_keys = mems.map((m) => String(m?.key ?? m?.keys ?? "").trim()).filter(Boolean).slice(0, 40);
         }
+        // Default MCP recall path: return only retrieved memories. The calling agent does the answer
+        // generation, so we avoid spending an extra EchoMem model call and avoid double synthesis.
+        if (result?.retrievalOnly) {
+            const memories = Array.isArray(result.memories) ? result.memories.filter(isRecord) : [];
+            if (!memories.length) {
+                return { content: [{ type: "text", text: "No relevant memories found." }] };
+            }
+            const formattedResults = memories
+                .map((m, idx) => {
+                const key = readString(m, "key") ?? readString(m, "keys") ?? "Saved memory";
+                const score = readNumber(m, "similarity")
+                    ?? readNumber(m, "similarity_score")
+                    ?? readNumber(m, "retrieval_similarity_score");
+                const meta = [
+                    readString(m, "time") ? `Time: ${readString(m, "time")}` : "",
+                    readString(m, "location") ? `Location: ${readString(m, "location")}` : "",
+                    readString(m, "category") ? `Category: ${readString(m, "category")}` : "",
+                    readString(m, "object") ? `Object: ${readString(m, "object")}` : "",
+                    readString(m, "emotion") ? `Emotion: ${readString(m, "emotion")}` : "",
+                    readString(m, "retrieval_bucket") ? `Bucket: ${readString(m, "retrieval_bucket")}` : "",
+                ].filter(Boolean).join(" | ");
+                const description = typeof m.description === "string"
+                    ? m.description
+                    : m.description == null
+                        ? ""
+                        : String(m.description);
+                const details = typeof m.details === "string"
+                    ? m.details.trim()
+                    : m.details == null
+                        ? ""
+                        : String(m.details).trim();
+                return [
+                    `[${idx + 1}] ${key}${typeof score === "number" ? ` (score ${score.toFixed(3)})` : ""}`,
+                    meta,
+                    `Description: ${description}`,
+                    details ? `Details: ${details}` : "",
+                ].filter(Boolean).join("\n");
+            })
+                .join("\n\n");
+            return { content: [{ type: "text", text: `Retrieved ${memories.length} memories:\n\n${formattedResults}` }] };
+        }
         // Tuned two-phase path: synthesized brief + ranked source memories.
         if (result?.tuned) {
             const { answer, memories } = result;

package/dist/migrate.js

@@ -0,0 +1,438 @@
+/**
+ * `echomem-mcp migrate` — one-shot bulk back-fill of the user's EXISTING local coding-agent history
+ * (Codex + Claude Code) into their Echo cloud. The onboarding "see it instantly know my work" moment.
+ *
+ * Why this lives in the bridge (client-side): the session logs exist ONLY on the user's machine
+ * (~/.codex/sessions, ~/.claude/projects). The bridge discovers each session, assembles it into a
+ * `## `-turn transcript, and feeds it to the EXISTING durable import queue (the same one the extension
+ * uses): POST /api/extension/import-sessions creates one import_jobs row per session, then the bridge
+ * POSTs each transcript to /api/extension/import-jobs/{id}/run. The web dashboard polls
+ * GET /import-sessions/{id} for live progress — the bridge owns local-file access, the server owns the
+ * queue + status. (Headless CLI also works; it just shows progress in the terminal.)
+ *
+ * Idempotency: the queue dedups by (platform, conversationId) → source_hash (a repeat run hits a
+ * non-fatal DUPLICATE_SOURCE), and a local ledger (~/.echomem/migrate-ledger.json) skips done+unchanged
+ * files WITHOUT a round-trip. Turns are joined with a SINGLE "\n" so the transcript stays byte-stable
+ * across runs (guarded by test/migrate.test.mjs). The run is sequential (throttled < 30/min to the /run
+ * limit) and stops cleanly if the encrypted vault's key expires mid-run.
+ * NOTE: client-pull — the queue advances only while the bridge runs; there is no server-side worker.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import readline from "node:readline";
+import axios from "axios";
+import { KeyStore, echoConfigDir } from "./keystore.js";
+import { fetchEncryptionConfig } from "./encryption.js";
+import { walk, eachLine } from "./report.js";
+const API_BASE = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
+const RATE_MAX = 28; // stay under the import-jobs /run limit of 30 / 60s
+const RATE_WINDOW_MS = 60_000;
+// ---------------------------------------------------------------------------
+// Assemblers — reconstruct a `## `-turn transcript from a raw session log.
+// ---------------------------------------------------------------------------
+const sha16 = (s) => crypto.createHash("sha256").update(s).digest("hex").slice(0, 16);
+const turn = (role, ts, body) => `## ${role}${ts ? " — " + ts : ""}\n${body}`;
+const firstLine = (s) => (s.split("\n").find((l) => l.trim()) || "").trim().slice(0, 120);
+const truncate = (s, n) => (s.length > n ? s.slice(0, n) + "…" : s);
+/** Strip Codex's synthetic scaffolding blocks from a user message; "" if nothing real remains. */
+function cleanCodexUser(msg) {
+    let s = String(msg || "");
+    s = s.replace(/<(environment_context|user_instructions|permissions|app-context)>[\s\S]*?<\/\1>/g, "");
+    return s.trim();
+}
+/** Codex rollout-*.jsonl → one session. session_meta is TOP-LEVEL `o.type`; turns are payload events. */
+export function assembleCodex(file) {
+    let sessionId = null;
+    let cwd = null;
+    let firstTs = null;
+    let title = "";
+    const turns = [];
+    eachLine(file, (o) => {
+        if (o && o.type === "session_meta") {
+            sessionId = (o.payload && typeof o.payload.id === "string" && o.payload.id) || sessionId;
+            cwd = (o.payload && typeof o.payload.cwd === "string" && o.payload.cwd) || cwd;
+            return;
+        }
+        const p = o && typeof o.payload === "object" && o.payload ? o.payload : o;
+        if (!p || typeof p !== "object")
+            return;
+        const ts = typeof o.timestamp === "string" ? o.timestamp : "";
+        if (p.type === "user_message" && typeof p.message === "string") {
+            const body = cleanCodexUser(p.message);
+            if (!body)
+                return;
+            turns.push(turn("User", ts, body));
+            if (!firstTs)
+                firstTs = ts;
+            if (!title)
+                title = firstLine(body);
+        }
+        else if (p.type === "agent_message" && typeof p.message === "string") {
+            const body = p.message.trim();
+            if (!body)
+                return;
+            turns.push(turn("Assistant", ts, body));
+            if (!firstTs)
+                firstTs = ts;
+        }
+    });
+    if (!turns.length)
+        return null;
+    const stat = statSafe(file);
+    return {
+        filePath: file,
+        source: "codex",
+        conversationKey: `codex:${sessionId || sha16(file)}`,
+        cwd: normalizeCwd(cwd),
+        firstTs,
+        title: title || "Codex session",
+        rawData: turns.join("\n"),
+        turnCount: turns.length,
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+    };
+}
+/** Claude Code <uuid>.jsonl → one session. Only user/assistant lines are turns; thinking is dropped. */
+export function assembleClaude(file) {
+    let sessionId = null;
+    let cwd = null;
+    let firstTs = null;
+    let title = "";
+    const turns = [];
+    eachLine(file, (o) => {
+        if (!cwd && typeof o.cwd === "string")
+            cwd = o.cwd;
+        if (!sessionId && typeof o.sessionId === "string")
+            sessionId = o.sessionId;
+        const ts = typeof o.timestamp === "string" ? o.timestamp : "";
+        if (o.type === "user") {
+            const c = o.message && o.message.content;
+            let body = "";
+            if (typeof c === "string")
+                body = c.trim();
+            else if (Array.isArray(c)) {
+                // tool_result-only carriers are NOT real user prompts → skip; keep any genuine text blocks.
+                body = c.filter((b) => b && b.type === "text" && b.text).map((b) => b.text).join("\n").trim();
+            }
+            if (!body)
+                return;
+            turns.push(turn("User", ts, body));
+            if (!firstTs)
+                firstTs = ts;
+            if (!title)
+                title = firstLine(body);
+        }
+        else if (o.type === "assistant") {
+            const c = o.message && o.message.content;
+            let body = "";
+            if (Array.isArray(c)) {
+                const parts = [];
+                for (const b of c) {
+                    if (b && b.type === "text" && b.text)
+                        parts.push(b.text);
+                    else if (b && b.type === "tool_use")
+                        parts.push(`[tool: ${b.name || "?"} ${truncate(JSON.stringify(b.input || {}), 120)}]`);
+                    // thinking blocks dropped (bulk of tokens, low memory value)
+                }
+                body = parts.join("\n").trim();
+            }
+            else if (typeof c === "string") {
+                body = c.trim();
+            }
+            if (!body)
+                return; // thinking-only turn → no header
+            turns.push(turn("Assistant", ts, body));
+            if (!firstTs)
+                firstTs = ts;
+        }
+        // queue-operation / attachment / ai-title / last-prompt / mode / summary / unknown → ignored
+    });
+    if (!turns.length)
+        return null;
+    const stat = statSafe(file);
+    return {
+        filePath: file,
+        source: "claude-code",
+        conversationKey: `claude:${sessionId || sha16(file)}`,
+        cwd: normalizeCwd(cwd),
+        firstTs,
+        title: title || "Claude Code session",
+        rawData: turns.join("\n"),
+        turnCount: turns.length,
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+    };
+}
+function statSafe(file) {
+    try {
+        const s = fs.statSync(file);
+        return { size: s.size, mtimeMs: Math.round(s.mtimeMs) };
+    }
+    catch {
+        return { size: 0, mtimeMs: 0 };
+    }
+}
+/** Strip agent/git worktree wrappers so worktree sessions group under their real project root. */
+export function normalizeCwd(cwd) {
+    if (!cwd)
+        return null;
+    const m = cwd.match(/worktrees\/[^/]+\/(.+)$/);
+    return m ? m[1] : cwd;
+}
+/** Discover every local session, newest first (by first-turn timestamp). */
+export function discoverSessions() {
+    const out = [];
+    const codexRoot = path.join(os.homedir(), ".codex", "sessions");
+    for (const f of walk(codexRoot, (p) => /rollout-.*\.jsonl$/.test(p), () => false)) {
+        const s = assembleCodex(f);
+        if (s)
+            out.push(s);
+    }
+    const claudeRoot = path.join(os.homedir(), ".claude", "projects");
+    for (const f of walk(claudeRoot, (p) => p.endsWith(".jsonl"), (name) => name === "subagents" || name === "workflows")) {
+        const s = assembleClaude(f);
+        if (s)
+            out.push(s);
+    }
+    out.sort((a, b) => String(b.firstTs || "").localeCompare(String(a.firstTs || "")));
+    return out;
+}
+function ledgerPath() {
+    return path.join(echoConfigDir(), "migrate-ledger.json");
+}
+function loadLedger() {
+    try {
+        return JSON.parse(fs.readFileSync(ledgerPath(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function saveLedger(l) {
+    try {
+        fs.mkdirSync(echoConfigDir(), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(ledgerPath(), JSON.stringify(l, null, 2));
+    }
+    catch {
+        /* best effort */
+    }
+}
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+const color = (enabled) => {
+    const w = (code) => (s) => (enabled ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+    return { bold: w("1"), dim: w("2"), red: w("31"), green: w("32"), cyan: w("36"), yellow: w("33") };
+};
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function promptYesNo(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(!/^n/i.test(a.trim())); }));
+}
+export async function cmdMigrate(flags) {
+    const c = color(process.stdout.isTTY === true && !process.env.NO_COLOR && flags["no-color"] !== true);
+    const store = new KeyStore();
+    // Discover + filter (pure local — discovery and --dry-run need no login).
+    let sessions = discoverSessions();
+    const since = typeof flags.since === "string" ? flags.since : undefined;
+    if (since)
+        sessions = sessions.filter((s) => (s.firstTs || "").slice(0, 10) >= since);
+    const limit = typeof flags.limit === "string" ? parseInt(flags.limit, 10) : undefined;
+    if (limit && limit > 0)
+        sessions = sessions.slice(0, limit);
+    if (!sessions.length) {
+        console.log("No local Codex/Claude Code sessions found to migrate.");
+        return;
+    }
+    const ledger = loadLedger();
+    const isNew = (s) => {
+        const e = ledger[s.conversationKey];
+        return !e || e.size !== s.size; // unseen, or the file grew/changed since last migrate
+    };
+    const pending = sessions.filter(isNew);
+    const codexN = sessions.filter((s) => s.source === "codex").length;
+    const claudeN = sessions.length - codexN;
+    console.log("");
+    console.log(c.bold(c.cyan("EchoMem migration")) + c.dim(`  (${API_BASE})`));
+    console.log(`Found ${c.bold(String(sessions.length))} sessions (${codexN} Codex + ${claudeN} Claude Code) · ${c.bold(String(pending.length))} new/changed to import` +
+        (sessions.length - pending.length ? c.dim(`, ${sessions.length - pending.length} already migrated`) : ""));
+    if (flags["dry-run"] === true) {
+        console.log(c.dim("\n--dry-run: discovered + assembled only, nothing sent.\n"));
+        for (const s of pending.slice(0, 50)) {
+            console.log(`  ${s.source === "codex" ? "codex " : "claude"} ${(s.firstTs || "").slice(0, 10)}  ${s.turnCount} turns  ${c.dim(truncate(s.title, 60))}`);
+        }
+        if (pending.length > 50)
+            console.log(c.dim(`  … and ${pending.length - 50} more`));
+        return;
+    }
+    if (!pending.length) {
+        console.log(c.green("\n✓ Everything is already migrated — nothing to do.\n"));
+        return;
+    }
+    // --- Below here we actually send → require a token + (if encrypted) an unlocked key. ---
+    const token = store.getToken();
+    if (!token) {
+        console.error("Not logged in. Run `echomem-mcp login` first, then re-run migrate.");
+        process.exitCode = 1;
+        return;
+    }
+    const client = axios.create({
+        baseURL: API_BASE,
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+    });
+    let encKey;
+    try {
+        const cfg = await fetchEncryptionConfig(client);
+        if (cfg.enabled) {
+            encKey = store.getKey();
+            if (!encKey) {
+                console.error(store.isKeyExpired()
+                    ? "Vault key expired. Run `echomem-mcp unlock`, then re-run migrate."
+                    : "This account is ENCRYPTED but the vault is locked. Run `echomem-mcp unlock`, then re-run migrate.");
+                process.exitCode = 1;
+                return;
+            }
+        }
+    }
+    catch {
+        /* config fetch failed → proceed as unencrypted (server enforces 422 if it's actually encrypted) */
+    }
+    // Consent: one keypress (skipped with --yes or when non-interactive).
+    if (flags.yes !== true && process.stdin.isTTY) {
+        const ok = await promptYesNo(`Import ${pending.length} session(s) into your EchoMem memory? [Y/n] `);
+        if (!ok) {
+            console.log("Aborted. Nothing was sent.");
+            return;
+        }
+    }
+    const userTz = Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    const bareId = (s) => s.conversationKey.slice(s.conversationKey.indexOf(":") + 1);
+    const mapKey = (platform, conv) => `${platform}:${conv}`;
+    // 1) Create the import session — descriptors only, NO transcript. The server fans this out to one
+    //    import_jobs row per session, which is what the web dashboard polls (GET /import-sessions/{id}).
+    let toImport = pending;
+    let session;
+    try {
+        session = await createImportSession(client, toImport, bareId, userTz);
+    }
+    catch (e) {
+        // Plan caps the batch → import the newest N and tell the user to re-run for the rest.
+        const max = Number(e?.response?.data?.maxConversations);
+        if (e?.response?.status === 422 && e?.response?.data?.error === "IMPORT_LIMIT_EXCEEDED" && max > 0) {
+            console.log(c.yellow(`Your plan imports up to ${max} at a time — importing the newest ${max}; re-run migrate for older sessions.`));
+            toImport = pending.slice(0, max);
+            session = await createImportSession(client, toImport, bareId, userTz);
+        }
+        else {
+            console.error(c.red(`Could not start the import: ${e?.response?.data?.message || e?.response?.data?.error || e?.message || e}`));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const byConv = new Map(toImport.map((s) => [mapKey(s.source, bareId(s)), s]));
+    console.log(c.dim(`Import session ${session.id} — ${session.jobs.length} jobs queued (the web dashboard can watch this live).`));
+    // 2) Drive each job: the queue lives server-side, but only THIS machine can read the logs, so the
+    //    bridge streams each transcript to /import-jobs/{id}/run. The web just polls. Throttle < 30/min.
+    const reqTimes = [];
+    const throttle = async () => {
+        for (;;) {
+            const now = Date.now();
+            while (reqTimes.length && now - reqTimes[0] > RATE_WINDOW_MS)
+                reqTimes.shift();
+            if (reqTimes.length < RATE_MAX) {
+                reqTimes.push(Date.now());
+                return;
+            }
+            await sleep(RATE_WINDOW_MS - (now - reqTimes[0]) + 100);
+        }
+    };
+    let migrated = 0, extracted = 0, failed = 0, i = 0;
+    for (const job of session.jobs) {
+        const s = byConv.get(mapKey(job.platform, job.conversation_id));
+        if (!s)
+            continue;
+        i++;
+        const tag = `${c.dim(`[${i}/${session.jobs.length}]`)} ${s.source === "codex" ? "codex " : "claude"} ${(s.firstTs || "").slice(0, 10)}`;
+        try {
+            await throttle();
+            const r = await runImportJob(client, job.id, s, userTz, encKey);
+            extracted += r.memories;
+            migrated++;
+            ledger[s.conversationKey] = { size: s.size, mtimeMs: s.mtimeMs, status: "done", memories: r.memories };
+            saveLedger(ledger);
+            const note = r.alreadyDone || r.duplicate ? c.dim("already imported") : c.green(`+${r.memories} ${r.memories === 1 ? "memory" : "memories"}`);
+            console.log(`${tag}  ${note}  ${c.dim(truncate(s.title, 48))}`);
+        }
+        catch (e) {
+            const status = e?.response?.status;
+            const errCode = e?.response?.data?.error;
+            // Vault key expired mid-run (TTL crossed) → stop cleanly; the rest is resumable on re-run.
+            if (status === 422 && errCode === "ENCRYPTION_KEY_REQUIRED") {
+                console.error(c.yellow(`\n⚠ Vault locked mid-run. Run \`echomem-mcp unlock\` and re-run migrate to resume (${migrated} done so far).`));
+                process.exitCode = 1;
+                break;
+            }
+            failed++;
+            console.log(`${tag}  ${c.red("✗ failed")} ${c.dim(truncate(String(e?.response?.data?.message || errCode || e?.message || e), 60))}`);
+        }
+    }
+    console.log("");
+    console.log(c.bold("Done.") + `  ${c.green(String(migrated) + " imported")} · ${c.bold(String(extracted))} memories` +
+        (failed ? ` · ${c.red(String(failed) + " failed")}` : "") + ".");
+    if (extracted > 0) {
+        console.log(c.dim("Now ask your agent about a past project — it can recall it from memory.\n"));
+    }
+}
+/** Create an import session (lightweight descriptors only — NO transcript). Returns the session id + jobs. */
+async function createImportSession(client, sessions, bareId, userTz) {
+    const items = sessions.map((s) => ({
+        conversationId: bareId(s),
+        platform: s.source, // free-text label; also half of the (session, platform, conversation) key
+        title: s.title,
+        sourceDate: s.firstTs,
+        userTz,
+    }));
+    const res = await client.post("/api/extension/import-sessions", { items });
+    const data = res.data || {};
+    return { id: String(data.session?.id || ""), jobs: Array.isArray(data.jobs) ? data.jobs : [] };
+}
+/** Run one queued job: stream its transcript to the server, which extracts it. One retry on 429/5xx. */
+async function runImportJob(client, jobId, s, userTz, encKey) {
+    const body = {
+        rawData: s.rawData,
+        source: s.source, // NOT containing "mcp" (avoids the route's MCP title truncation)
+        title: s.title,
+        sourceDate: s.firstTs, // back-fill memories on the session's real date
+        userTz,
+        sessionType: "coding", // routes to the coding-checkpoint extraction prompt (ignored if unsupported)
+    };
+    const cfg = encKey ? { headers: { "X-Encryption-Key": encKey } } : undefined;
+    for (let attempt = 0;; attempt++) {
+        try {
+            const res = await client.post(`/api/extension/import-jobs/${jobId}/run`, body, cfg);
+            const data = res.data || {};
+            if (data.claimed === false) {
+                // Already completed on a prior run → idempotent, not an error; otherwise it didn't start.
+                if (data.job?.status === "completed")
+                    return { memories: Number(data.job?.saved_memory_count) || 0, alreadyDone: true, duplicate: false };
+                throw new Error(data.message || "job did not start");
+            }
+            const result = data.result || {};
+            return { memories: Number(result.memoriesExtracted) || 0, alreadyDone: false, duplicate: !!result.duplicate };
+        }
+        catch (e) {
+            const status = e?.response?.status;
+            if (status === 422 && e?.response?.data?.error === "ENCRYPTION_KEY_REQUIRED")
+                throw e; // not retryable
+            if (status === 409)
+                throw e; // claim conflict — don't hammer a job another worker holds
+            const retryable = status === 429 || (status >= 500 && status < 600) || e?.code === "ECONNABORTED" || !status;
+            if (!retryable || attempt >= 2)
+                throw e;
+            const retryAfter = Number(e?.response?.headers?.["retry-after"]) || Number(e?.response?.data?.retryAfterSeconds);
+            await sleep((status === 429 && retryAfter > 0 ? retryAfter : Math.pow(2, attempt) * 2) * 1000);
+        }
+    }
+}

package/dist/report.js

@@ -110,7 +110,7 @@ function classifyClaudeTool(name) {
  * readFileSync().split()) avoids both loading a multi-hundred-MB session into one string and the
  * V8 ~512 MB max-string cliff that would silently drop a large session. Never throws.
  */
-function eachLine(file, fn) {
+export function eachLine(file, fn) {
     let fd;
     try {
         fd = fs.openSync(file, "r");
@@ -256,7 +256,7 @@ export function parseClaude(file) {
         toolsEcho: echo,
     };
 }
-function walk(dir, match, skipDir, out = []) {
+export function walk(dir, match, skipDir, out = []) {
     let entries;
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });

package/dist/setup.js

@@ -23,6 +23,7 @@ import axios from "axios";
 import { KeyStore } from "./keystore.js";
 import { fetchEncryptionConfig, deriveAndVerifyKey, verifyKeyB64 } from "./encryption.js";
 import { runReport, buildReportText } from "./report.js";
+import { cmdMigrate } from "./migrate.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.
 const WEB_URL = (process.env.ECHO_WEB_URL || "https://yeahecho.com").replace(/\/$/, "");
@@ -387,6 +388,7 @@ 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
 
 Manual / headless:
   echomem-mcp login --token ec_xxx [--passphrase <vault pass> | --key <base64>]
@@ -415,6 +417,9 @@ export async function runCli(argv) {
         case "report":
             await runReport(flags);
             return true;
+        case "migrate":
+            await cmdMigrate(flags);
+            return true;
         case "help":
         case "--help":
         case "-h":

package/dist/v1-contract.js

@@ -20,6 +20,7 @@ export const searchMemoriesSchema = z.object({
     limit: z.number().optional(),
     threshold: z.number().optional().default(0.1),
     timeFrameDays: z.number().optional(),
+    includeAnswer: z.boolean().optional().default(false),
 });
 export const saveConversationSchema = z.object({
     conversation: z.string().optional(),
@@ -55,7 +56,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). Returns ranked memories with provenance. Current time: ${currentTime}.`,
+            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}.`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -63,6 +64,11 @@ export function listToolSpecs(opts = {}) {
                     limit: { type: "number", default: 10 },
                     threshold: { type: "number", default: 0.1 },
                     timeFrameDays: { type: "number" },
+                    includeAnswer: {
+                        type: "boolean",
+                        default: false,
+                        description: "Default false: return only retrieved memories and skip answer generation. Set true for the legacy synthesized recall answer.",
+                    },
                 },
             },
         },
@@ -76,6 +82,11 @@ export function listToolSpecs(opts = {}) {
                     limit: { type: "number", default: 10 },
                     threshold: { type: "number", default: 0.1 },
                     timeFrameDays: { type: "number" },
+                    includeAnswer: {
+                        type: "boolean",
+                        default: false,
+                        description: "Default false: return only retrieved memories and skip answer generation. Set true for the legacy synthesized recall answer.",
+                    },
                 },
             },
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "EchoMem Cloud-First MCP Server",
   "main": "dist/index.js",
   "type": "module",
@@ -17,7 +17,7 @@
     "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",
+    "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/migrate.test.mjs",
     "prepack": "npm run build"
   },
   "dependencies": {