@echomem/mcp 1.4.18 → 1.4.19

package/dist/setup-preview.js

@@ -1,4 +1,6 @@
 export const SETUP_PREVIEW_STATES = [
+    "consent",
+    "consent-required",
     "report",
     "extract-counting",
     "extract-ready",
@@ -200,6 +202,15 @@ function previewWatermarkScript() {
 }
 export function renderSetupPreviewBootstrap(state) {
     const watermark = previewWatermarkScript();
+    if (state === "consent") {
+        return `${watermark}
+        renderLocalScanConsent();`;
+    }
+    if (state === "consent-required") {
+        return `${watermark}
+        renderLocalScanConsent();
+        setConsentStatus("Local history access is required to continue setup. Nothing will be scanned or uploaded unless you allow it.", "required");`;
+    }
     if (state === "report") {
         const reportJson = JSON.stringify(previewReport);
         return `${watermark}
@@ -214,6 +225,17 @@ export function renderSetupPreviewBootstrap(state) {
     }
     if (state === "extract-ready") {
         return `${watermark}
+        connected = true;
+        billingStatus = {
+          plan: "free", paid: false, trialAvailable: true,
+          pricingUrl: "https://echoknows.com/pricing?source=mcp_onboarding",
+          account: {
+            displayName: "Erik Hein",
+            email: "erik@example.com",
+            avatarUrl: "/hud-assets/echo-face-cutout.png"
+          },
+          historicalConversationQuota: { used: 72, limit: 100, remaining: 28 }
+        };
         stats = {
           sessions: { total: 136, codex: 82, claudeCode: 54 },
           migratable: {
@@ -221,6 +243,19 @@ export function renderSetupPreviewBootstrap(state) {
             alreadyMigrated: 108, skippedActive: 0,
             eta: { estimatedLabel: "under 2 minutes" }, estimatedLabel: "under 2 minutes"
           },
+          candidateSessions: Array.from({ length: 28 }, function (_, index) {
+            var codex = index < 19;
+            return {
+              key: (codex ? "codex:" : "claude-code:") + "preview-" + index,
+              source: codex ? "codex" : "claude-code",
+              title: ["Plan the onboarding flow", "Repair memory extraction", "Review pricing limits", "Polish the EchoMem HUD"][index % 4] + " · " + (index + 1),
+              project: ["EchoMem Chrome", "MCP Server", "Memory Platform"][index % 3],
+              date: new Date(Date.UTC(2026, 6, 18 - (index % 12))).toISOString(),
+              characters: 42000 + index * 2700,
+              approxInputTokens: 10500 + index * 675,
+              turns: 18 + index
+            };
+          }),
           discovery: { phase: "account", exact: false }
         };
         renderDashboard();`;
@@ -237,6 +272,20 @@ export function renderSetupPreviewBootstrap(state) {
     }
     if (state === "extract-done") {
         return `${watermark}
+        stats = {
+          candidateSessions: [
+            { key: "codex:done-1", project: "EchoMem Chrome", title: "Polish the onboarding flow" },
+            { key: "codex:done-2", project: "EchoMem Chrome", title: "Repair memory extraction" },
+            { key: "claude-code:done-3", project: "MCP Server", title: "Review recall limits" },
+            { key: "codex:done-4", project: "Memory Platform", title: "Plan the next release" }
+          ]
+        };
+        selectedSessionKeys = {
+          "codex:done-1": true,
+          "codex:done-2": true,
+          "claude-code:done-3": true,
+          "codex:done-4": true
+        };
         renderProgress({ status: "completed", total: 28, completed: 28, extracted: 128, failed: 0 });`;
     }
     if (state === "extract-ending")

package/dist/setup.js

@@ -629,6 +629,24 @@ function commandFailureMessage(error) {
     }
     return error instanceof Error ? error.message : String(error);
 }
+function candidateSessionsFromDiscovery(disc) {
+    return disc.pending.map((session) => ({
+        key: session.conversationKey,
+        source: session.source,
+        title: session.title || "Untitled coding session",
+        project: repoLabel(session.cwd) || "No project detected",
+        date: session.firstTs,
+        characters: session.rawData.length,
+        approxInputTokens: Math.ceil(session.rawData.length / 4),
+        turns: session.turnCount,
+    }));
+}
+function withCandidateSessions(payload, disc) {
+    const base = payload && typeof payload === "object" && !Array.isArray(payload)
+        ? payload
+        : {};
+    return { ...base, candidateSessions: candidateSessionsFromDiscovery(disc) };
+}
 function migratableFromDiscovery(disc) {
     const eta = estimateMigrationEta(disc.pending, disc.skippedActive);
     const pendingCodex = disc.pendingCodex ?? disc.pending.filter((s) => s.source === "codex").length;
@@ -709,6 +727,16 @@ function isObjectRecord(value) {
 function asString(value) {
     return typeof value === "string" && value ? value : undefined;
 }
+function asConversationKeys(value) {
+    if (!Array.isArray(value))
+        return null;
+    const keys = value
+        .slice(0, 5000)
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => /^(codex|claude-code):[^\s]{1,180}$/.test(item));
+    return Array.from(new Set(keys));
+}
 function readJsonBody(req) {
     return new Promise((resolve, reject) => {
         let body = "";
@@ -1084,6 +1112,7 @@ export function startCallbackServer(opts = {}) {
         let authUrl = "";
         let switchAccountUrl = "";
         let connected = false;
+        let reportConsentGranted = opts.requireReportConsent !== true;
         let progress = { status: "idle", total: 0, completed: 0, running: 0, queued: 0, failed: 0, extracted: 0 };
         let migrateStarted = false;
         let tokenRefreshHandler = null;
@@ -1129,6 +1158,12 @@ export function startCallbackServer(opts = {}) {
         const handleCallback = (res, token, key, nonce) => {
             if (!checkNonce(nonce))
                 return void text(res, 403, "bad nonce");
+            if (opts.requireReportConsent === true && !reportConsentGranted) {
+                return void json(res, 403, {
+                    error: "LOCAL_HISTORY_CONSENT_REQUIRED",
+                    message: "Allow local history access in the setup page before connecting EchoMem.",
+                });
+            }
             if (!token)
                 return void text(res, 400, "missing token");
             console.log(`[${new Date().toISOString()}] Browser approval callback received.`);
@@ -1191,7 +1226,15 @@ 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, workspacePath: process.cwd() });
+                    json(res, 200, {
+                        connected,
+                        authUrl,
+                        switchAccountUrl: switchAccountUrl || authUrl,
+                        localOnly: true,
+                        workspacePath: process.cwd(),
+                        consentRequired: opts.requireReportConsent === true,
+                        consentGranted: reportConsentGranted,
+                    });
                     return;
                 }
                 if (route === "/launch-agent" && req.method === "POST") {
@@ -1246,6 +1289,12 @@ export function startCallbackServer(opts = {}) {
                 if (route === "/stats" && req.method === "GET") {
                     if (!checkNonce(url.searchParams.get("nonce") || undefined))
                         return void text(res, 403, "bad nonce");
+                    if (opts.requireReportConsent === true && !reportConsentGranted) {
+                        return void json(res, 403, {
+                            error: "LOCAL_HISTORY_CONSENT_REQUIRED",
+                            message: "Allow local history access before continuing setup.",
+                        });
+                    }
                     const payload = opts.getStats ? opts.getStats() : stats;
                     if (payload == null)
                         return void res.writeHead(202).end();
@@ -1255,6 +1304,12 @@ export function startCallbackServer(opts = {}) {
                 if (route === "/billing-status" && req.method === "GET") {
                     if (!checkNonce(url.searchParams.get("nonce") || undefined))
                         return void text(res, 403, "bad nonce");
+                    if (opts.requireReportConsent === true && !reportConsentGranted) {
+                        return void json(res, 403, {
+                            error: "LOCAL_HISTORY_CONSENT_REQUIRED",
+                            message: "Allow local history access before continuing setup.",
+                        });
+                    }
                     const token = new KeyStore().getToken();
                     const pricingUrl = `${PRICING_URL}?source=mcp_onboarding`;
                     if (!token) {
@@ -1262,7 +1317,11 @@ export function startCallbackServer(opts = {}) {
                         return;
                     }
                     try {
-                        const response = await authedAxios(token).get("/api/extension/account/bootstrap", { timeout: 6000 });
+                        const client = authedAxios(token);
+                        const [response, profileResponse] = await Promise.all([
+                            client.get("/api/extension/account/bootstrap", { timeout: 6000 }),
+                            client.get("/api/extension/account/profile-summary", { timeout: 6000 }).catch(() => null),
+                        ]);
                         const plan = (asString(response.data?.plan) || "free").toLowerCase();
                         const trialUsed = response.data?.billing?.trialUsed === true;
                         const trialAvailable = response.data?.billing?.trialAvailable !== false;
@@ -1271,6 +1330,14 @@ export function startCallbackServer(opts = {}) {
                             paid: ["pro", "power", "team", "enterprise"].includes(plan),
                             trialAvailable,
                             trialUsed,
+                            historicalConversationQuota: response.data?.historicalConversationQuota ?? null,
+                            memoryProcessingQuota: response.data?.memoryProcessingQuota ?? null,
+                            memorySearchQuota: response.data?.memorySearchQuota ?? null,
+                            account: profileResponse ? {
+                                displayName: asString(profileResponse.data?.displayName) || "EchoMem user",
+                                email: asString(profileResponse.data?.email) || "",
+                                avatarUrl: asString(profileResponse.data?.avatarUrl) || "",
+                            } : null,
                             pricingUrl,
                         });
                     }
@@ -1284,6 +1351,12 @@ export function startCallbackServer(opts = {}) {
                     res.setHeader("Cache-Control", "no-store");
                     if (!checkNonce(url.searchParams.get("nonce") || undefined))
                         return void text(res, 403, "bad nonce");
+                    if (opts.requireReportConsent === true && !reportConsentGranted) {
+                        return void json(res, 403, {
+                            error: "LOCAL_HISTORY_CONSENT_REQUIRED",
+                            message: "Allow local history access before starting the local scan.",
+                        });
+                    }
                     let payload;
                     try {
                         payload = opts.getReport ? opts.getReport() : null;
@@ -1379,6 +1452,12 @@ export function startCallbackServer(opts = {}) {
                 if (route === "/progress" && req.method === "GET") {
                     if (!checkNonce(url.searchParams.get("nonce") || undefined))
                         return void text(res, 403, "bad nonce");
+                    if (opts.requireReportConsent === true && !reportConsentGranted) {
+                        return void json(res, 403, {
+                            error: "LOCAL_HISTORY_CONSENT_REQUIRED",
+                            message: "Allow local history access before continuing setup.",
+                        });
+                    }
                     json(res, 200, progress);
                     return;
                 }
@@ -1394,6 +1473,7 @@ export function startCallbackServer(opts = {}) {
                     if (!checkNonce(asString(body.nonce)))
                         return void text(res, 403, "bad nonce");
                     const allowed = body.allowed === true;
+                    reportConsentGranted = allowed;
                     opts.onReportConsent?.(allowed);
                     json(res, 200, { ok: true, allowed });
                     return;
@@ -1442,6 +1522,12 @@ export function startCallbackServer(opts = {}) {
                     }
                     if (!checkNonce(asString(body.nonce)))
                         return void text(res, 403, "bad nonce");
+                    if (opts.requireReportConsent === true && !reportConsentGranted) {
+                        return void json(res, 403, {
+                            error: "LOCAL_HISTORY_CONSENT_REQUIRED",
+                            message: "Allow local history access before starting extraction.",
+                        });
+                    }
                     if (migrateStarted)
                         return void json(res, 409, { error: "MIGRATE_IN_PROGRESS" });
                     migrateStarted = true;
@@ -1449,7 +1535,7 @@ export function startCallbackServer(opts = {}) {
                         respondMigrate(res, { error: "IMPORT_START_TIMEOUT" }, 504);
                     }, 30_000);
                     safety.unref?.();
-                    migrateRequest.resolve({ res });
+                    migrateRequest.resolve({ res, conversationKeys: asConversationKeys(body.conversationKeys) });
                     decision.resolve("migrate");
                     return;
                 }
@@ -1863,6 +1949,7 @@ async function cmdLogin(flags) {
     const srv = await startCallbackServer({
         port: devPortRaw,
         nonce,
+        requireReportConsent: true,
         getStats: () => stats,
         getReport: () => forensicReport,
         getReportProgress: () => forensicProgress,
@@ -1886,6 +1973,19 @@ async function cmdLogin(flags) {
                 return;
             }
             forensicConsent = "allowed";
+            const now = Date.now();
+            forensicStage = "starting";
+            forensicStageStartedAt = now;
+            forensicProgress = {
+                status: "running",
+                scanned: 0,
+                total: 0,
+                stage: forensicStage,
+                label: forensicStageLabel(forensicStage),
+                elapsedMs: now - forensicStartedAt,
+                stageElapsedMs: 0,
+                updatedAt: now,
+            };
             startForensicScan();
         },
     });
@@ -2125,13 +2225,13 @@ async function cmdLogin(flags) {
             migratable = migratableFromDiscovery(initialExact);
             latestPendingEstimate = migratable.pending;
             sessionSummary = sessionsFromDiscovery(initialExact);
-            const partialPayload = await buildStatsPayload([], {
+            const partialPayload = withCandidateSessions(await buildStatsPayload([], {
                 partial: true,
                 skipMemoryCount: true,
                 sessions: sessionSummary,
                 migratable,
                 discovery: { phase: "exact", exact: true },
-            });
+            }), initialExact);
             if (generation !== refreshGeneration)
                 return disc;
             stats = partialPayload;
@@ -2175,13 +2275,13 @@ async function cmdLogin(flags) {
                 migratable = migratableFromDiscovery(reconciled);
                 latestPendingEstimate = migratable.pending;
                 sessionSummary = sessionsFromDiscovery(reconciled);
-                const reconciledPayload = await buildStatsPayload([], {
+                const reconciledPayload = withCandidateSessions(await buildStatsPayload([], {
                     partial: true,
                     skipMemoryCount: true,
                     sessions: sessionSummary,
                     migratable,
                     discovery: { phase: "exact", exact: true },
-                });
+                }), reconciled);
                 if (generation !== refreshGeneration)
                     return;
                 stats = reconciledPayload;
@@ -2195,11 +2295,11 @@ async function cmdLogin(flags) {
                     failed: 0,
                     extracted: 0,
                 });
-                const fullPayload = await buildStatsPayload(collect(), {
+                const fullPayload = withCandidateSessions(await buildStatsPayload(collect(), {
                     sessions: sessionSummary,
                     migratable,
                     discovery: { phase: "full", exact: true },
-                });
+                }), reconciled);
                 if (generation !== refreshGeneration)
                     return;
                 stats = fullPayload;
@@ -2220,18 +2320,42 @@ async function cmdLogin(flags) {
         await refreshLocalStatsForToken(nextToken);
     });
     await refreshLocalStatsForToken(token);
-    // A pause is deliberately transient. Completed conversations remain recorded in the normal
-    // import ledger; unfinished conversations are rediscovered and offered again by the next init.
+    // Ending is deliberately transient. Completed conversations remain recorded in the normal
+    // import ledger; unfinished conversations are canceled and rediscovered by the next init.
     let pauseRequested = false;
     let pauseCompletion = null;
+    let activeMigrationCleanup = null;
+    let activeMigrationCleanupPromise = null;
+    const cancelActiveMigration = async () => {
+        if (!activeMigrationCleanup)
+            return false;
+        if (!activeMigrationCleanupPromise) {
+            const cleanup = activeMigrationCleanup();
+            activeMigrationCleanupPromise = cleanup;
+            cleanup.catch(() => {
+                // A transient backend failure must remain retryable from the restored extraction page.
+                if (activeMigrationCleanupPromise === cleanup)
+                    activeMigrationCleanupPromise = null;
+            });
+        }
+        await activeMigrationCleanupPromise;
+        return true;
+    };
     srv.setMigrationPauseHandler(async () => {
         pauseRequested = true;
+        // Cancel the backend session first. This immediately releases every queued reservation and
+        // prevents another job from being claimed while already-running requests finish safely.
+        const canceledBeforePause = await cancelActiveMigration();
         if (pauseCompletion)
             await pauseCompletion;
+        // If End for now raced with import-session creation, the cleanup handle becomes available only
+        // after the local worker loop observes pauseRequested. Cancel it before acknowledging the UI.
+        if (!canceledBeforePause)
+            await cancelActiveMigration();
     });
     const choice = await srv.decision;
     if (choice === "migrate") {
-        const { res } = await srv.migrateRequest;
+        const { res, conversationKeys } = await srv.migrateRequest;
         let migrateResponded = false;
         const sendMigrate = (body, status = 200) => {
             if (migrateResponded)
@@ -2311,7 +2435,11 @@ async function cmdLogin(flags) {
             process.exitCode = 1;
             return true;
         }
-        activeJobCount = exact.pending.length;
+        const requestedKeys = conversationKeys ? new Set(conversationKeys) : null;
+        const selectedPending = requestedKeys
+            ? exact.pending.filter((session) => requestedKeys.has(session.conversationKey))
+            : exact.pending;
+        activeJobCount = selectedPending.length;
         const updateProgress = (patch) => {
             srv.setProgress({
                 status: "running",
@@ -2327,7 +2455,7 @@ async function cmdLogin(flags) {
             });
         };
         try {
-            if (exact.pending.length === 0) {
+            if (selectedPending.length === 0) {
                 srv.setProgress({
                     status: "completed",
                     total: 0,
@@ -2343,7 +2471,7 @@ async function cmdLogin(flags) {
                 console.log("Setup complete — no unprocessed local conversations to extract.");
                 return true;
             }
-            updateProgress({ status: "starting", running: 0, queued: exact.pending.length, latest: "Creating import session." });
+            updateProgress({ status: "starting", running: 0, queued: selectedPending.length, latest: "Creating import session." });
             // 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.
@@ -2362,7 +2490,7 @@ async function cmdLogin(flags) {
                     ...(latestRepo ? { latestRepo } : {}),
                 });
             };
-            let remaining = exact.pending;
+            let remaining = selectedPending;
             let stoppedReason;
             let planLimitNote;
             let batchIndex = 0;
@@ -2383,10 +2511,12 @@ async function cmdLogin(flags) {
                     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}.`;
+                    planLimitNote = `Imported ${progressDone}. Upgrade your plan to import the remaining ${remaining.length} conversations.`;
                     break;
                 }
                 activeSessionId = h.sessionId;
+                activeMigrationCleanup = h.cancelQueued;
+                activeMigrationCleanupPromise = null;
                 if (batchIndex === 1) {
                     updateProgress({ status: "running", sessionId: h.sessionId, jobCount: activeJobCount, total: activeJobCount, latest: "Import session created." });
                     sendMigrate({ sessionId: h.sessionId, jobCount: activeJobCount });
@@ -2404,10 +2534,12 @@ async function cmdLogin(flags) {
                     stoppedReason = r.stoppedReason;
                     break;
                 }
-                // startMigration sliced to the cap ⇒ more remain: continue with the next batch automatically.
+                // A historical allowance is lifetime, not a per-batch cap. Stop cleanly
+                // after the allowed slice instead of attempting another session.
                 if (h.capped && remaining.length > h.jobCount) {
-                    remaining = remaining.slice(h.jobCount);
-                    continue;
+                    const left = remaining.length - h.jobCount;
+                    planLimitNote = `Import complete for this plan. Upgrade to import the remaining ${left} conversations.`;
+                    break;
                 }
                 break;
             }
@@ -2422,9 +2554,9 @@ async function cmdLogin(flags) {
                     queued: Math.max(0, activeJobCount - progressDone - progressFailed),
                     failed: progressFailed,
                     extracted: progressExtracted,
-                    latest: "Paused by user. Re-run setup to continue the remaining conversations.",
+                    latest: "Ended for now. Re-run setup to rebuild the remaining conversation list.",
                 });
-                console.log(`Import paused: ${progressDone} imported, ${progressExtracted} memories, ${progressFailed} failed.`);
+                console.log(`Import ended for now: ${progressDone} imported, ${progressExtracted} memories, ${progressFailed} failed.`);
                 completePause();
                 // /skip sends the browser acknowledgement and closes the localhost bridge after this
                 // safe pause boundary. Do not close it here first or the page can claim success early.
@@ -2461,7 +2593,7 @@ async function cmdLogin(flags) {
                     queued: Math.max(0, activeJobCount - progressDone - progressFailed),
                     failed: progressFailed,
                     extracted: progressExtracted,
-                    latest: "Paused by user. Re-run setup to continue the remaining conversations.",
+                    latest: "Ended for now. Re-run setup to rebuild the remaining conversation list.",
                 });
                 completePause();
                 return true;
@@ -2488,8 +2620,13 @@ async function cmdLogin(flags) {
                 sendMigrate({ error: "NO_PENDING_SESSIONS" }, 409);
             else if (e?.code === "IMPORT_START_TIMEOUT")
                 sendMigrate({ error: "IMPORT_START_TIMEOUT" }, 504);
-            else
-                sendMigrate({ error: "IMPORT_START_FAILED", message: String(e?.message || e) }, 500);
+            else {
+                const responseData = isObjectRecord(e?.response?.data) ? e.response.data : {};
+                const responseCode = asString(responseData.error) || "IMPORT_START_FAILED";
+                const responseMessage = asString(responseData.message) || String(e?.message || e);
+                const responseStatus = typeof e?.response?.status === "number" ? e.response.status : 500;
+                sendMigrate({ error: responseCode, message: responseMessage }, responseStatus);
+            }
             await new Promise((resolve) => setTimeout(resolve, 2000));
             srv.close();
             process.exitCode = 1;

package/dist/v1-contract.js

@@ -108,7 +108,7 @@ export function listToolSpecs(opts = {}) {
     const currentTime = new Date().toISOString();
     const map = opts.map?.trim();
     const updateNotice = opts.updateNotice?.trim();
-    const paidRecallNote = "Requires Echo Pro or Power; saving conversations and memory extraction remain included.";
+    const recallPlanNote = "Available on every plan: Free includes 10 searches each week, Pro includes 100, and Power includes 250.";
     const searchBillingReplyInstruction = "If search returns an ACTION REQUIRED subscription message, tell the user to start their trial or subscription and include the exact URL from that result verbatim. Do not respond only with \"connect\" or \"upgrade\".";
     const updateSection = updateNotice ? `\n\nUPDATE NOTICE: ${updateNotice}` : "";
     const mapSection = map
@@ -117,7 +117,7 @@ export function listToolSpecs(opts = {}) {
     return [
         {
             name: canonicalToolNames.search,
-            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. ${paidRecallNote} ${searchBillingReplyInstruction}${mapSection}\nReturns the ranked memories; set includeAnswer=true only if you need the legacy synthesized answer. 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. ${recallPlanNote} ${searchBillingReplyInstruction}${mapSection}\nReturns the ranked memories; set includeAnswer=true only if you need the legacy synthesized answer. Current time: ${currentTime}.${updateSection}`),
             inputSchema: {
                 type: "object",
                 properties: {
@@ -140,7 +140,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: "search_memories_by_description_semantic",
-            description: `Legacy alias for search_memories. ${paidRecallNote} ${searchBillingReplyInstruction}`,
+            description: `Legacy alias for search_memories. ${recallPlanNote} ${searchBillingReplyInstruction}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -163,7 +163,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.save,
-            description: "Save this conversation into EchoMem as long-term memory (durable memories are extracted automatically). Saving is included. passthrough=true stores the text verbatim as a session capsule; reloading/searching saved memories requires Echo Pro or Power.",
+            description: "Save this conversation into EchoMem as long-term memory (durable memories are extracted automatically). New extraction input uses the plan's weekly processing allowance; if the limit is reached, nothing is saved. passthrough=true stores the text verbatim as a session capsule.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -196,7 +196,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.timeRange,
-            description: `Retrieve memories within a specific date range. ${paidRecallNote} Current time: ${currentTime}.`,
+            description: `Retrieve memories within a specific date range. ${recallPlanNote} Current time: ${currentTime}.`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -214,7 +214,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.keywords,
-            description: `Search memories based on keywords in keys field. ${paidRecallNote}`,
+            description: `Search memories based on keywords in keys field. ${recallPlanNote}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -371,7 +371,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.getByContext,
-            description: withMcpVersion(`Deterministically re-fetch the exact batch of memories saved under one contextId — no semantic search, no ranking, just that session's saved capsule. ${paidRecallNote} save_conversation returns a contextId; pass it here to pull back precisely those memories, e.g. to warm up a fresh session with what a prior session saved, or to verify the saved facts are still present. Current time: ${currentTime}.`),
+            description: withMcpVersion(`Deterministically re-fetch the exact batch of memories saved under one contextId — no semantic search, no ranking, just that session's saved capsule. ${recallPlanNote} save_conversation returns a contextId; pass it here to pull back precisely those memories, e.g. to warm up a fresh session with what a prior session saved, or to verify the saved facts are still present. Current time: ${currentTime}.`),
             inputSchema: {
                 type: "object",
                 properties: {
@@ -388,7 +388,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.checkpointByContext,
-            description: withMcpVersion(`Rebuild a clean-context checkpoint / decision log from one EchoMem contextId. ${paidRecallNote} 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}.`),
+            description: withMcpVersion(`Rebuild a clean-context checkpoint / decision log from one EchoMem contextId. ${recallPlanNote} 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: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.18",
+  "version": "1.4.19",
   "description": "EchoMem MCP bridge: cloud-first memory tools, local context HUD, and the Agent Doctor workspace forensics report (cost ledger + 3D repo city)",
   "main": "dist/index.js",
   "type": "module",