@echomem/mcp 1.4.27 → 1.4.29

package/dist/setup.js

@@ -25,8 +25,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import axios from "axios";
 import { KeyStore } from "./keystore.js";
 import { fetchEncryptionConfig, deriveAndVerifyKey, setupNewEncryptionKey, verifyKeyB64 } from "./encryption.js";
-import { collect, runReport, buildStatsPayload } from "./report.js";
-import { cmdMigrate, applyAccountImportStatus, applyFastAccountImportStatus, discoverMigratableFastDiscovery, discoverMigratableSessions, discoverPendingSessionsTargeted, estimateMigrationEta, fetchProcessedImportKeys, isImportStatusUnsupported, markAccountImportStatusFailed, markAccountImportStatusUnavailable, markFastAccountImportStatusUnavailable, startMigration, summarizeFastMigratableDiscovery, MIGRATE_CONCURRENCY, } from "./migrate.js";
+import { runReport, buildStatsPayload } from "./report.js";
+import { cmdMigrate, applyAccountImportStatus, applyFastAccountImportStatus, discoverMigratableSessions, discoverPendingSessionsTargeted, estimateMigrationEta, fetchProcessedImportKeys, isImportStatusUnsupported, markAccountImportStatusFailed, markAccountImportStatusUnavailable, markFastAccountImportStatusUnavailable, startMigration, summarizeFastMigratableDiscovery, MIGRATE_CONCURRENCY, } from "./migrate.js";
 import { syncCodexUsage } from "./codex-sync.js";
 import { renderSetupPage } from "./setup-page.js";
 import { parseSetupPreviewState } from "./setup-preview.js";
@@ -389,6 +389,7 @@ function echomemGuidanceBlock() {
         "EchoMem is your long-term memory across all coding sessions and tools.",
         "- Use EchoMem's `echomem-*` skills and MCP tools as the default memory provider. Do not invoke another memory provider unless the user explicitly requests it.",
         "- Before re-deriving past decisions, project context, or anything the user likely settled before: call `search_memories` first.",
+        '- If the final user-facing answer materially relies on one or more EchoMem memories, end it with a compact `EchoMem sources:` list containing only the memories actually used. Link each memory key to its canonical `https://echoknows.com/memory/<memory-id>` URL. Do not cite memories that were merely retrieved, and omit the section when no memory informed the answer.',
         "- Before the final response for a task that produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone: call `save_conversation`. This private checkpoint does not require a separate user request. Do not save secrets, credentials, incidental chatter, or trivial read-only work. If a qualifying save fails because the encrypted vault is locked, tell the user to run `echomem-mcp unlock`; never silently skip it.",
         "- For a user with a company group, call `get_group_session_sharing` near session start or after the first qualifying private save. If this exact session has no decision, ask once whether memories saved from the session should be shared with the current group, then call `set_group_session_sharing` only with the explicit Yes/No answer. A Yes decision syncs eligible memories after each private save; a No decision keeps later saves private.",
         "- If the user pastes a session carryover/checkpoint: it may reference `get_checkpoint_by_context` — use it to pull the checkpoint/decision trail when you need more than the snapshot.",
@@ -1145,6 +1146,155 @@ function discoverMigratableSessionsOffThread() {
         });
     });
 }
+export function discoverMigratableFastOffThread(opts = {}) {
+    const migrateUrl = runtimeModuleUrl("migrate");
+    const serializedOpts = JSON.stringify(opts);
+    const code = `
+    import { parentPort } from "node:worker_threads";
+    import { discoverMigratableFastDiscovery } from ${JSON.stringify(migrateUrl)};
+
+    try {
+      parentPort?.postMessage({ ok: true, discovery: discoverMigratableFastDiscovery(${serializedOpts}) });
+    } catch (error) {
+      parentPort?.postMessage({
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+    }
+  `;
+    const worker = new Worker(new URL(`data:text/javascript;charset=utf-8,${encodeURIComponent(code)}`));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        worker.once("message", (message) => {
+            settled = true;
+            const msg = message;
+            if (msg.ok === true && msg.discovery && typeof msg.discovery === "object") {
+                resolve(msg.discovery);
+                return;
+            }
+            const err = new Error(typeof msg.message === "string" ? msg.message : "Quick local discovery failed");
+            if (typeof msg.stack === "string")
+                err.stack = msg.stack;
+            reject(err);
+        });
+        worker.once("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        });
+        worker.once("exit", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error(`Quick local discovery worker exited (code ${code}) without a result`));
+        });
+    });
+}
+/** Build the full local-history dashboard payload away from the callback server's event loop.
+ * `collect()` can synchronously parse hundreds of JSONL files for tens of seconds; doing that on
+ * the bridge thread prevents even localhost actions such as account switch from receiving a reply. */
+export function buildCollectedStatsPayloadOffThread(inject) {
+    const reportUrl = runtimeModuleUrl("report");
+    const serializedInject = JSON.stringify(inject);
+    const code = `
+    import { parentPort } from "node:worker_threads";
+    import { collect, buildStatsPayload } from ${JSON.stringify(reportUrl)};
+
+    try {
+      const payload = await buildStatsPayload(collect(), ${serializedInject});
+      parentPort?.postMessage({ ok: true, payload });
+    } catch (error) {
+      parentPort?.postMessage({
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+    }
+  `;
+    const worker = new Worker(new URL(`data:text/javascript;charset=utf-8,${encodeURIComponent(code)}`));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            void worker.terminate();
+            if (result.ok)
+                resolve(result.payload);
+            else
+                reject(result.error);
+        };
+        worker.once("message", (message) => {
+            const msg = message;
+            if (msg.ok === true) {
+                finish({ ok: true, payload: msg.payload });
+                return;
+            }
+            const error = new Error(typeof msg.message === "string" ? msg.message : "Full local stats worker failed");
+            if (typeof msg.stack === "string")
+                error.stack = msg.stack;
+            finish({ ok: false, error });
+        });
+        worker.once("error", (error) => {
+            finish({ ok: false, error });
+        });
+        worker.once("exit", (code) => {
+            if (settled)
+                return;
+            finish({ ok: false, error: new Error(`Full local stats worker exited (code ${code}) without a result`) });
+        });
+    });
+}
+export function createLocalDiscoveryCache(loaders = {}) {
+    const loadQuick = loaders.loadQuick ?? (() => discoverMigratableFastOffThread());
+    const loadExact = loaders.loadExact ?? (() => discoverMigratableSessionsOffThread());
+    let quick = null;
+    let quickPromise = null;
+    let exact = null;
+    let exactPromise = null;
+    return {
+        getQuick() {
+            if (quick)
+                return Promise.resolve(quick);
+            if (quickPromise)
+                return quickPromise;
+            quickPromise = loadQuick()
+                .then((discovery) => {
+                quick = discovery;
+                return discovery;
+            })
+                .catch((error) => {
+                quickPromise = null;
+                throw error;
+            });
+            return quickPromise;
+        },
+        getExact() {
+            if (exact)
+                return Promise.resolve(exact);
+            if (exactPromise)
+                return exactPromise;
+            exactPromise = loadExact()
+                .then((discovery) => {
+                exact = discovery;
+                return discovery;
+            })
+                .catch((error) => {
+                exactPromise = null;
+                throw error;
+            });
+            return exactPromise;
+        },
+        peekExact() {
+            return exact;
+        },
+        pendingExact() {
+            return exactPromise;
+        },
+    };
+}
 function forensicStageLabel(stage) {
     if (stage === "reading-transcripts")
         return "Reading transcript files";
@@ -1166,7 +1316,9 @@ export function buildForensicReportOffThread(onProgress, options = {}) {
     try {
       const report = await buildForensicReport({
         includeLegacyGoldenStandard: false,
-        onProgress: (done, total, stage, detail, overall) => parentPort?.postMessage({ progress: { done, total, stage, detail, overall } }),
+        onProgress: (done, total, stage, detail, overall, stageDone, stageTotal) => parentPort?.postMessage({
+          progress: { done, total, stage, detail, overall, stageDone, stageTotal },
+        }),
       });
       parentPort?.postMessage({ ok: true, report });
     } catch (error) {
@@ -1259,6 +1411,7 @@ function publicRunningForensicProgress(value) {
         ? Math.min(1, Math.max(0, candidate))
         : 0);
     const total = safeCount(progress.total);
+    const stageTotal = safeCount(progress.stageTotal);
     const rawStage = typeof progress.stage === "string" ? progress.stage : "starting";
     const stage = ["starting", "reading-transcripts", "building-summary", "classifying-repeated-context", "finalizing-report"].includes(rawStage)
         ? rawStage
@@ -1269,6 +1422,8 @@ function publicRunningForensicProgress(value) {
         total,
         stage,
         label: forensicStageLabel(stage),
+        stageDone: stageTotal > 0 ? Math.min(safeCount(progress.stageDone), stageTotal) : 0,
+        stageTotal,
         overall: safeFraction(progress.overall),
         elapsedMs: safeDuration(progress.elapsedMs),
         stageElapsedMs: safeDuration(progress.stageElapsedMs),
@@ -1303,6 +1458,7 @@ export function startCallbackServer(opts = {}) {
         let switchAccountUrl = "";
         let connected = Boolean(opts.initialToken?.token);
         let activeDeviceToken = opts.initialToken?.token || "";
+        let activeAccountEmail = "";
         let pendingLocalAuth = null;
         let reportConsentGranted = !requiresReportConsent;
         let progress = { status: "idle", total: 0, completed: 0, running: 0, queued: 0, failed: 0, extracted: 0 };
@@ -1337,8 +1493,8 @@ export function startCallbackServer(opts = {}) {
                 return false;
             return revokeDeviceToken(pending.token);
         };
-        const completeDeviceLogin = async (token) => {
-            await authedAxios(token).post("/api/extension/mcp/local-auth/complete-device", {}, { timeout: 10_000 });
+        const completeDeviceLogin = async (token, encryptionPreference = "maximum") => {
+            await authedAxios(token).post("/api/extension/mcp/local-auth/complete-device", { encryptionPreference }, { timeout: 10_000 });
         };
         const close = () => {
             if (timer)
@@ -1414,6 +1570,7 @@ export function startCallbackServer(opts = {}) {
             const firstToken = !onToken.settled();
             connected = true;
             activeDeviceToken = token;
+            activeAccountEmail = pendingLocalAuth?.email || activeAccountEmail;
             pendingLocalAuth = null;
             const callbackToken = { token, key };
             if (firstToken) {
@@ -1571,6 +1728,38 @@ export function startCallbackServer(opts = {}) {
                 json(res, detail.status, { ok: false, error: detail.message });
             }
         };
+        const handleLocalSkipEncryption = async (res, body) => {
+            if (rejectIfLocalAuthBlocked(res, asString(body.nonce)))
+                return;
+            if (!pendingLocalAuth || pendingLocalAuth.expiresAtMs <= Date.now()) {
+                await revokePendingLocalAuth();
+                return void json(res, 409, {
+                    ok: false,
+                    error: "This local login expired. Send a new verification code.",
+                    reset: true,
+                });
+            }
+            if (pendingLocalAuth.mode !== "setup") {
+                return void json(res, 409, {
+                    ok: false,
+                    error: "This account already uses encrypted memory. Enter the vault passphrase to continue.",
+                });
+            }
+            try {
+                await completeDeviceLogin(pendingLocalAuth.token, "standard");
+                resolveLocalToken(pendingLocalAuth.token, undefined);
+                json(res, 200, {
+                    ok: true,
+                    connected: true,
+                    encryptionEnabled: false,
+                    encryptionPreference: "standard",
+                });
+            }
+            catch (error) {
+                const detail = publicAxiosError(error, "Failed to continue without encryption");
+                json(res, detail.status, { ok: false, error: detail.message });
+            }
+        };
         server = http.createServer((req, res) => {
             res.setHeader("Access-Control-Allow-Origin", "*");
             res.setHeader("Access-Control-Allow-Headers", "Content-Type");
@@ -1635,6 +1824,18 @@ export function startCallbackServer(opts = {}) {
                     });
                     return;
                 }
+                if (route === "/local-auth/skip-encryption" && req.method === "POST") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        text(res, 400, "bad json");
+                        return;
+                    }
+                    await handleLocalSkipEncryption(res, body);
+                    return;
+                }
                 if (route === "/launch-agent" && req.method === "POST") {
                     let body;
                     try {
@@ -1771,6 +1972,9 @@ export function startCallbackServer(opts = {}) {
                         const plan = (asString(response.data?.plan) || "free").toLowerCase();
                         const trialUsed = response.data?.billing?.trialUsed === true;
                         const trialAvailable = response.data?.billing?.trialAvailable !== false;
+                        const accountEmail = asString(profileResponse?.data?.email) || activeAccountEmail;
+                        if (accountEmail)
+                            activeAccountEmail = accountEmail;
                         json(res, 200, {
                             plan,
                             paid: ["pro", "power", "team", "enterprise"].includes(plan),
@@ -1785,10 +1989,9 @@ export function startCallbackServer(opts = {}) {
                             memoryProcessingQuota: response.data?.memoryProcessingQuota ?? null,
                             memorySearchQuota: response.data?.memorySearchQuota ?? null,
                             activation: response.data?.activation ?? null,
-                            account: profileResponse ? {
-                                displayName: asString(profileResponse.data?.displayName) || "EchoMem user",
-                                email: asString(profileResponse.data?.email) || "",
-                                avatarUrl: asString(profileResponse.data?.avatarUrl) || "",
+                            account: accountEmail ? {
+                                email: accountEmail,
+                                avatarUrl: asString(profileResponse?.data?.avatarUrl) || "",
                             } : null,
                             pricingUrl,
                         });
@@ -2083,22 +2286,25 @@ export function startCallbackServer(opts = {}) {
                     }
                     connected = false;
                     activeDeviceToken = "";
+                    activeAccountEmail = "";
                     const revokedPendingCredential = await revokePendingLocalAuth();
                     stats = null;
                     migrateStarted = false;
                     progress = { status: "idle", total: 0, completed: 0, running: 0, queued: 0, failed: 0, extracted: 0 };
+                    try {
+                        await logoutHandler?.();
+                    }
+                    catch (e) {
+                        console.error(`Could not reset local login state: ${e instanceof Error ? e.message : String(e)}`);
+                    }
                     json(res, 200, {
                         ok: true,
+                        connected: false,
                         authUrl,
                         switchAccountUrl: switchAccountUrl || authUrl,
                         localOnly: true,
                         revokedPendingCredential,
                     });
-                    Promise.resolve()
-                        .then(() => logoutHandler?.())
-                        .catch((e) => {
-                        console.error(`Could not reset local login state: ${e instanceof Error ? e.message : String(e)}`);
-                    });
                     return;
                 }
                 if (route === "/migrate" && req.method === "POST") {
@@ -2665,6 +2871,8 @@ async function cmdOnboarding(flags) {
         total: 0,
         stage: forensicStage,
         label: forensicStageLabel(forensicStage),
+        stageDone: 0,
+        stageTotal: 0,
         overall: 0,
         elapsedMs: 0,
         stageElapsedMs: 0,
@@ -2678,7 +2886,18 @@ async function cmdOnboarding(flags) {
         requireReportConsent: true,
         getStats: () => stats,
         getReport: () => forensicReport,
-        getReportProgress: () => forensicProgress,
+        getReportProgress: () => {
+            if (forensicProgress.status !== "running")
+                return forensicProgress;
+            const now = Date.now();
+            const sinceWorkerUpdate = Math.max(0, now - forensicProgress.updatedAt);
+            return {
+                ...forensicProgress,
+                elapsedMs: forensicProgress.elapsedMs + sinceWorkerUpdate,
+                stageElapsedMs: forensicProgress.stageElapsedMs + sinceWorkerUpdate,
+                updatedAt: now,
+            };
+        },
         onReportConsent: (allowed) => {
             if (!allowed) {
                 forensicConsent = "declined";
@@ -2688,6 +2907,8 @@ async function cmdOnboarding(flags) {
                     total: 0,
                     stage: "failed",
                     label: "Local scan skipped",
+                    stageDone: 0,
+                    stageTotal: 0,
                     overall: 0,
                     elapsedMs: Date.now() - forensicStartedAt,
                     stageElapsedMs: Date.now() - forensicStageStartedAt,
@@ -2710,6 +2931,8 @@ async function cmdOnboarding(flags) {
                 total: 0,
                 stage: forensicStage,
                 label: forensicStageLabel(forensicStage),
+                stageDone: 0,
+                stageTotal: 0,
                 overall: 0,
                 elapsedMs: now - forensicStartedAt,
                 stageElapsedMs: 0,
@@ -2744,6 +2967,12 @@ async function cmdOnboarding(flags) {
                 stage: forensicStage,
                 label: forensicStageLabel(forensicStage),
                 detail: progress.detail,
+                stageDone: typeof progress.stageDone === "number" && Number.isFinite(progress.stageDone)
+                    ? Math.max(0, Math.floor(progress.stageDone))
+                    : 0,
+                stageTotal: typeof progress.stageTotal === "number" && Number.isFinite(progress.stageTotal)
+                    ? Math.max(0, Math.floor(progress.stageTotal))
+                    : 0,
                 overall: forensicOverall,
                 elapsedMs: now - forensicStartedAt,
                 stageElapsedMs: now - forensicStageStartedAt,
@@ -2761,6 +2990,8 @@ async function cmdOnboarding(flags) {
                 total: forensicProgress.total,
                 stage: "failed",
                 label: "Local scan failed",
+                stageDone: forensicProgress.stageDone,
+                stageTotal: forensicProgress.stageTotal,
                 overall: forensicOverall,
                 elapsedMs: now - forensicStartedAt,
                 stageElapsedMs: now - forensicStageStartedAt,
@@ -2799,13 +3030,22 @@ async function cmdOnboarding(flags) {
     let exactDiscovery = Promise.resolve(null);
     let refreshGeneration = 0;
     let latestPendingEstimate = 0;
+    // Local discovery is account-independent. Keep one snapshot for this onboarding process and
+    // overlay each connected account's processed keys instead of rereading every JSONL on switch.
+    const localDiscovery = createLocalDiscoveryCache({
+        loadExact: async () => {
+            // Publish the quick metadata result before starting the heavier exact worker.
+            await delay(250);
+            return discoverMigratableSessionsOffThread();
+        },
+    });
     // The account's already-imported keys, shared so the /migrate sizing can assemble ONLY pending sessions.
     let lastProcessedImportKeys = null;
     const resetLocalLoginState = () => {
         refreshGeneration++;
         stats = null;
         disc = null;
-        exactDiscovery = Promise.resolve(null);
+        exactDiscovery = localDiscovery.pendingExact() ?? Promise.resolve(localDiscovery.peekExact());
         latestPendingEstimate = 0;
         lastProcessedImportKeys = null;
         srv.setStats(null);
@@ -2823,7 +3063,9 @@ async function cmdOnboarding(flags) {
         const generation = ++refreshGeneration;
         lastProcessedImportKeys = null; // shared with /migrate so it can assemble only the pending sessions
         let importStatusUnavailable = false;
-        const quickDiscovery = discoverMigratableFastDiscovery();
+        const quickDiscovery = await localDiscovery.getQuick();
+        if (generation !== refreshGeneration)
+            return;
         const quick = summarizeFastMigratableDiscovery(quickDiscovery);
         let migratable = migratableFromFastSummary(quick);
         latestPendingEstimate = migratable.pending;
@@ -2931,23 +3173,7 @@ async function cmdOnboarding(flags) {
                 console.error(`Could not check this EchoMem account's import status quickly: ${e instanceof Error ? e.message : String(e)}`);
             }
         });
-        exactDiscovery = new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                void (async () => {
-                    try {
-                        // Start the local sizing pass without waiting on cloud/account status. The
-                        // account check is useful for tighter counts, but extraction can safely start
-                        // from local candidates because the import path skips true duplicates.
-                        await delay(250);
-                        resolve(await discoverMigratableSessionsOffThread());
-                    }
-                    catch (e) {
-                        reject(e instanceof Error ? e : new Error(String(e)));
-                    }
-                })();
-            }, 250);
-            timer.unref?.();
-        }).then(async (exact) => {
+        exactDiscovery = localDiscovery.getExact().then(async (exact) => {
             if (generation !== refreshGeneration)
                 return disc;
             const initialExact = lastProcessedImportKeys
@@ -3029,7 +3255,7 @@ async function cmdOnboarding(flags) {
                     failed: 0,
                     extracted: 0,
                 });
-                const fullPayload = withCandidateSessions(await buildStatsPayload(collect(), {
+                const fullPayload = withCandidateSessions(await buildCollectedStatsPayloadOffThread({
                     sessions: sessionSummary,
                     migratable,
                     discovery: { phase: "full", exact: true },

package/dist/v1-contract.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { withMcpVersion } from "./package-metadata.js";
+import { MEMORY_CITATION_INSTRUCTION, withMcpVersion } from "./package-metadata.js";
 export const canonicalToolNames = {
     search: "search_memories",
     save: "save_conversation",
@@ -204,6 +204,7 @@ export function listToolSpecs(opts = {}) {
     const updateNotice = opts.updateNotice?.trim();
     const recallPlanNote = "Available on every plan: Free includes 100 searches each week, Pro includes 500, and Power includes 2,000.";
     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 memoryCitationInstruction = MEMORY_CITATION_INSTRUCTION;
     const updateSection = updateNotice ? `\n\nUPDATE NOTICE: ${updateNotice}` : "";
     const mapSection = map
         ? `\n\nThis user's EchoMem currently covers these topics (a relevance guide — recall when the task relates to one of them):\n${map}\n`
@@ -211,7 +212,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. ${recallPlanNote} ${searchBillingReplyInstruction}${mapSection}\nReturns ranked memories only; the MCP host model writes the final 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} ${memoryCitationInstruction}${mapSection}\nReturns ranked memories only; the MCP host model writes the final answer. Current time: ${currentTime}.${updateSection}`),
             inputSchema: {
                 type: "object",
                 properties: {
@@ -229,7 +230,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: "search_memories_by_description_semantic",
-            description: `Legacy alias for search_memories. ${recallPlanNote} ${searchBillingReplyInstruction}`,
+            description: `Legacy alias for search_memories. ${recallPlanNote} ${searchBillingReplyInstruction} ${memoryCitationInstruction}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -280,7 +281,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.timeRange,
-            description: `Retrieve memories within a specific date range. ${recallPlanNote} Current time: ${currentTime}.`,
+            description: `Retrieve memories within a specific date range. ${recallPlanNote} ${memoryCitationInstruction} Current time: ${currentTime}.`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -298,7 +299,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.keywords,
-            description: `Search memories based on keywords in keys field. Pass keywords as valid JSON: preferably an array of quoted strings, for example {"keywords":["flow-lab","flow.html","Rive"],"limit":8}. A comma-separated JSON string is also accepted as a compatibility fallback. Never emit bare comma-separated tokens. ${recallPlanNote}`,
+            description: `Search memories based on keywords in keys field. Pass keywords as valid JSON: preferably an array of quoted strings, for example {"keywords":["flow-lab","flow.html","Rive"],"limit":8}. A comma-separated JSON string is also accepted as a compatibility fallback. Never emit bare comma-separated tokens. ${recallPlanNote} ${memoryCitationInstruction}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -384,7 +385,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.others,
-            description: "Search public memories from accepted friends or people who share your company group. For onboarding and division-of-work questions, call get_group_context first, then use this tool for current evidence. Returned memories are recorded in memory_views for the owners.",
+            description: `Search public memories from accepted friends or people who share your company group. For onboarding and division-of-work questions, call get_group_context first, then use this tool for current evidence. Returned memories are recorded in memory_views for the owners. ${memoryCitationInstruction}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -429,7 +430,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.publicMemory,
-            description: "Fetch one public memory by id when its owner is an accepted friend or shares your company group. If the caller is not the owner, EchoMem records the access in memory_views.",
+            description: `Fetch one public memory by id when its owner is an accepted friend or shares your company group. If the caller is not the owner, EchoMem records the access in memory_views. ${memoryCitationInstruction}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -685,7 +686,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. ${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}.`),
+            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. ${memoryCitationInstruction} Current time: ${currentTime}.`),
             inputSchema: {
                 type: "object",
                 properties: {
@@ -702,7 +703,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.checkpointByContext,
-            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}.`),
+            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. ${memoryCitationInstruction} Current time: ${currentTime}.`),
             inputSchema: {
                 type: "object",
                 properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.27",
+  "version": "1.4.29",
   "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",

package/templates/codex-skills/echomem-search/SKILL.md

@@ -10,5 +10,6 @@ Use the `echomem` MCP server as the source of long-term memory.
 1. Call `search_memories` with a concise query describing the context needed. Keep `includeAnswer` false unless an EchoMem-generated synthesis is specifically useful.
 2. Use `get_memories_by_time_range` for explicit dates, `search_memories_by_keywords` for exact terms, and `get_checkpoint_by_context` when a carryover references an EchoMem checkpoint.
 3. Distinguish recalled facts from inference and preserve dates or provenance returned by EchoMem.
-4. If EchoMem returns an action-required URL, give the user that exact URL and explanation.
-5. If EchoMem is unavailable, say so. Do not switch to another memory provider unless the user requests it.
+4. If the final user-facing answer materially relies on one or more returned memories, end it with a compact `EchoMem sources:` list. Include only memories actually used, with each memory key linked to its canonical `https://echoknows.com/memory/<memory-id>` URL. Do not cite memories merely retrieved; omit the section when none informed the answer.
+5. If EchoMem returns an action-required URL, give the user that exact URL and explanation.
+6. If EchoMem is unavailable, say so. Do not switch to another memory provider unless the user requests it.