@echomem/mcp 1.4.28 → 1.4.29

package/dist/index.js

@@ -12,7 +12,7 @@ import { contextHealthMarkdown, recomposeCapsuleMarkdown } from "./hud/api.js";
 import { createHash, randomUUID } from "node:crypto";
 import { fetchEncryptionConfig, decryptMemoryFields, verifyKeyB64, } from "./encryption.js";
 import { runCli } from "./setup.js";
-import { MCP_PACKAGE_VERSION, MCP_SERVER_INSTRUCTIONS } from "./package-metadata.js";
+import { MCP_PACKAGE_VERSION, MCP_SERVER_INSTRUCTIONS, MEMORY_CITATION_INSTRUCTION, } from "./package-metadata.js";
 import { clearBillingAlert, writeBillingAlert } from "./billing-alert.js";
 import { checkLatestUpdateStatus, formatUpdateNotice, formatUpdateStatusText, startBackgroundUpdateCheck, } from "./update-check.js";
 const ECHO_API_BASE_URL = process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app";
@@ -32,6 +32,9 @@ function memoryMarkdownLink(url, keys, description) {
         .replace(/\]/g, "\\]");
     return `[${label}](${url})`;
 }
+function withMemoryCitationInstruction(text) {
+    return `${text}\n\n${MEMORY_CITATION_INSTRUCTION}`;
+}
 /** Thrown when no API token is present yet — the model gets a "run login" nudge, not a hard error. */
 class NoTokenError extends Error {
 }
@@ -1446,7 +1449,12 @@ class EchoMemMCPServer {
                 ].filter(Boolean).join("\n");
             })
                 .join("\n\n");
-            return { content: [{ type: "text", text: `Retrieved ${memories.length} memories:\n\n${formattedResults}` }] };
+            return {
+                content: [{
+                        type: "text",
+                        text: withMemoryCitationInstruction(`Retrieved ${memories.length} memories:\n\n${formattedResults}`),
+                    }],
+            };
         }
         // Fallback: untuned / time-range shape.
         const { success, memories, error } = result;
@@ -1463,7 +1471,12 @@ Category: ${m.category} | Object: ${m.object} | Emotion: ${m.emotion}
 Description: ${m.description}
 Details: ${m.details || "N/A"}`)
             .join("\n\n");
-        return { content: [{ type: "text", text: `Found ${memories.length} relevant memories:\n\n${formattedResults}` }] };
+        return {
+            content: [{
+                    type: "text",
+                    text: withMemoryCitationInstruction(`Found ${memories.length} relevant memories:\n\n${formattedResults}`),
+                }],
+        };
     }
     async handleSave(args, rec) {
         const sourceFallback = this.getMcpClientAnalytics().platform_source;
@@ -1565,7 +1578,7 @@ Details: ${m.details || "N/A"}`)
             content: [
                 {
                     type: "text",
-                    text: `Found ${memories.length} memories between ${parsed.startDate} and ${parsed.endDate}:\n\n${formattedResults}`,
+                    text: withMemoryCitationInstruction(`Found ${memories.length} memories between ${parsed.startDate} and ${parsed.endDate}:\n\n${formattedResults}`),
                 },
             ],
         };
@@ -1591,7 +1604,7 @@ Details: ${m.details || "N/A"}`)
             content: [
                 {
                     type: "text",
-                    text: `Recalled ${memories.length} memories from context ${parsed.contextId} (deterministic full batch):\n\n${formattedResults}`,
+                    text: withMemoryCitationInstruction(`Recalled ${memories.length} memories from context ${parsed.contextId} (deterministic full batch):\n\n${formattedResults}`),
                 },
             ],
         };
@@ -1636,7 +1649,10 @@ Details: ${m.details || "N/A"}`)
                 const desc = readString(memory, "description") ?? "";
                 const details = compactOneLine(readString(memory, "details"), 260);
                 const id = readString(memory, "id");
-                lines.push(`- ${title}${id ? ` (${id})` : ""}: ${desc}${details ? ` — ${details}` : ""}`);
+                const linkedTitle = id
+                    ? memoryMarkdownLink(personalMemoryWebUrl(id), title, desc)
+                    : title;
+                lines.push(`- ${linkedTitle}${id ? ` (${id})` : ""}: ${desc}${details ? ` — ${details}` : ""}`);
             }
             lines.push("");
         }
@@ -1645,7 +1661,7 @@ Details: ${m.details || "N/A"}`)
             content: [
                 {
                     type: "text",
-                    text: lines.join("\n"),
+                    text: withMemoryCitationInstruction(lines.join("\n")),
                 },
             ],
         };
@@ -1672,7 +1688,7 @@ Details: ${m.details || "N/A"}`)
             content: [
                 {
                     type: "text",
-                    text: `Found ${memories.length} memories matching keywords:\n\n${formattedResults}`,
+                    text: withMemoryCitationInstruction(`Found ${memories.length} memories matching keywords:\n\n${formattedResults}`),
                 },
             ],
         };
@@ -1729,7 +1745,7 @@ Details: ${m.details || "N/A"}`;
             content: [
                 {
                     type: "text",
-                    text: `Found ${memories.length} others' public memories${metadata ? ` (${metadata})` : ""}:\n\n${formattedResults}`,
+                    text: withMemoryCitationInstruction(`Found ${memories.length} others' public memories${metadata ? ` (${metadata})` : ""}:\n\n${formattedResults}`),
                 },
             ],
         };
@@ -1857,7 +1873,7 @@ Details: ${m.details || "N/A"}`;
                 : "",
         ].filter(Boolean).join("\n");
         return {
-            content: [{ type: "text", text }],
+            content: [{ type: "text", text: withMemoryCitationInstruction(text) }],
         };
     }
     async handleGroupContext(args) {

package/dist/package-metadata.js

@@ -23,6 +23,7 @@ export const MCP_PACKAGE_DESCRIPTION = stringOrFallback(packageJson.description,
 export const MCP_PACKAGE_LABEL = `${MCP_PACKAGE_NAME}@${MCP_PACKAGE_VERSION}`;
 export const MCP_UPDATE_COMMAND = `npx -y ${MCP_PACKAGE_NAME}@latest update`;
 export const MCP_UPDATE_ALL_COMMAND = `${MCP_UPDATE_COMMAND} --all`;
+export const MEMORY_CITATION_INSTRUCTION = 'If the 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. Use each memory key as the Markdown label and 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.';
 export const MCP_SERVER_INSTRUCTIONS = [
     `${MCP_PACKAGE_DESCRIPTION} (${MCP_PACKAGE_LABEL}).`,
     `If the user or local config expects a newer EchoMem MCP version than ${MCP_PACKAGE_VERSION}, update once with \`${MCP_UPDATE_ALL_COMMAND}\` and start a new MCP session.`,
@@ -34,6 +35,7 @@ export const MCP_SERVER_INSTRUCTIONS = [
     "After joining or when profile fields are missing, use candidate memory evidence to propose a title and responsibility summary. Ask the user to confirm that proposal together with the publication preview, then call update_group_profile and complete_group_publication.",
     "Use one canonical https://echoknows.com/memory/<memory-id> link for private, group, and friend evidence. Label it with the memory key; the site resolves the authorized representation.",
     "Each search result is one memory: preserve its Memory ID and canonical echoknows.com link when citing it.",
+    MEMORY_CITATION_INSTRUCTION,
     "During a publication preview, if an unflagged candidate appears sensitive, proactively ask whether the user wants to mark its exact ID for publication attention first. Explain that marking does not publish or change encryption; it means the agent will call it out and ask for detailed confirmation whenever a later publication includes it. Never auto-flag inferred sensitivity. For sensitive-topic flags, search and preview exact owned memories before confirmed flag_memories_for_publication_attention. Separate already-flagged candidates, state that nothing has been published yet, and offer to exclude them, review them separately, or first search for and mark similar sensitive owned memories.",
     "Never save an inferred group profile. Manual prepared publication requires explicit preview confirmation; flagged memories still require separate exact-memory confirmation. Never store or log an echo_grp_ invite code.",
 ].join(" ");

package/dist/setup-page/client-core.js

@@ -302,14 +302,13 @@ export const SETUP_PAGE_CLIENT_CORE = String.raw `      var params = new URLSear
         setExtractMode(false);
         setReadyMode(true);
         setHead("EchoMem connected", "Done");
-        app.className = "notice";
+        app.className = "localAuthCompleteStage";
         app.innerHTML =
-          '<section class="localAuthCard localAuthComplete">' +
-            '<div class="localAuthLead">' +
-              '<img src="/hud-assets/echo-face-cutout.png" alt="" />' +
-              '<h2 class="siteHeadline">You\'re signed in.</h2>' +
-              '<p>Return to Terminal, or run <code>echomem-mcp init</code> to start onboarding.</p>' +
-            '</div>' +
+          '<section class="localAuthComplete" aria-labelledby="localAuthCompleteTitle">' +
+            '<img src="/hud-assets/echo-face-cutout.png" alt="" />' +
+            '<h2 id="localAuthCompleteTitle">You\'re signed in.</h2>' +
+            '<p>Return to Terminal.</p>' +
+            '<p class="localAuthCompleteNext">Run <code>echomem-mcp init</code> when you\'re ready to start onboarding.</p>' +
           '</section>';
       }
       async function finishLocalLogin() {

package/dist/setup-page/client-extraction.js

@@ -1315,9 +1315,13 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
           renderSessionSelection(true);
           return;
         }
-        var pendingPaidPlan = setupPlanChoice === "power" || billingActivationPendingPlan === "power"
+        var pendingPaidPlan = billingActivationPendingPlan === "power"
           ? "power"
-          : (setupPlanChoice === "pro" || billingActivationPendingPlan === "pro" ? "pro" : "");
+          : (billingActivationPendingPlan === "pro"
+            ? "pro"
+            : (pendingCheckoutSessionId && (setupPlanChoice === "pro" || setupPlanChoice === "power")
+              ? setupPlanChoice
+              : ""));
         if (pendingPaidPlan) {
           renderBillingCommitment("");
           if (readySettings) {
@@ -1478,6 +1482,10 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
           }
           document.title = "Finish checkout — Echo setup is waiting";
           renderSetupPlan(true);
+        } else {
+          // A selected plan is not proof that Stripe created a Checkout session.
+          // Avoid restoring a phantom pending state after a failed request or popup.
+          rememberSetupPlanChoice("");
         }
       }
       async function openHostedPlanOptions() {

package/dist/setup-page/styles-mvp.js

@@ -285,6 +285,56 @@ export const SETUP_PAGE_STYLES_MVP = String.raw `
     .localAuthWelcomeStage.localAuthPassphraseStage .localAuthWelcome {
       margin: clamp(24px, 5vh, 48px) auto 0;
     }
+    body.readyMode #app.localAuthCompleteStage {
+      min-height: calc(100vh - clamp(56px, 10vw, 128px));
+      display: grid;
+      place-items: center;
+    }
+    .localAuthComplete {
+      width: min(680px, 100%);
+      display: grid;
+      justify-items: center;
+      gap: 14px;
+      margin: 0 auto;
+      padding: clamp(24px, 5vw, 48px) 0;
+      color: var(--echo-ink-text);
+      text-align: center;
+    }
+    .localAuthComplete > img {
+      width: 76px;
+      height: 76px;
+      object-fit: contain;
+      filter: drop-shadow(0 12px 20px rgba(26,58,143,0.18));
+    }
+    .localAuthComplete h2 {
+      max-width: 100%;
+      margin: 4px 0 0;
+      color: var(--echo-ink-text);
+      font-family: var(--echo-font-brand);
+      font-size: clamp(42px, 6vw, 64px);
+      font-weight: 800;
+      letter-spacing: -0.055em;
+      line-height: 0.98;
+      white-space: nowrap;
+    }
+    .localAuthComplete p {
+      margin: 0;
+      color: var(--echo-ink-mute);
+      font-size: clamp(17px, 2.2vw, 22px);
+      line-height: 1.45;
+    }
+    .localAuthComplete .localAuthCompleteNext {
+      max-width: 460px;
+      margin-top: 2px;
+      color: var(--echo-ink-faint);
+      font-size: 14px;
+    }
+    .localAuthComplete code {
+      color: var(--echo-ink-primary);
+    }
+    @media (max-width: 560px) {
+      .localAuthComplete h2 { white-space: normal; }
+    }
     .localAuthWelcome {
       width: min(440px, 100%);
       gap: 14px;

package/dist/setup-preview.js

@@ -21,7 +21,9 @@ export const SETUP_PREVIEW_STATES = [
     "auth-login",
     "auth-login-pro",
     "auth-otp",
+    "auth-complete",
     "checkout-pro-selected",
+    "checkout-pro-stale",
     "auth-unlock",
     "auth-setup",
     "extract-run",
@@ -252,6 +254,7 @@ function extractionPreviewBootstrap(options) {
         connected = true;
         billingStatus = ${JSON.stringify(billingStatus)};
         setupPlanChoice = ${JSON.stringify(options.selectFree ? "free" : options.selectedPlanChoice || "")};
+        pendingCheckoutSessionId = ${JSON.stringify(options.checkoutPending ? "cs_test_preview_pending_123" : "")};
         stats = {
           sessions: { total: ${candidateCount}, codex: ${Math.ceil(candidateCount * 0.68)}, claudeCode: ${Math.floor(candidateCount * 0.32)} },
           migratable: {
@@ -400,7 +403,15 @@ export function renderSetupPreviewBootstrap(state) {
         return `${watermark}
         localAuthEmail = "preview@example.com";
         renderLocalOtp("Verification code sent. Check your email inbox.");`;
+    if (state === "auth-complete")
+        return `${watermark}
+        renderLocalLoginComplete();`;
     if (state === "checkout-pro-selected")
+        return `${watermark}${extractionPreviewBootstrap({
+            plan: "free", paid: false, trialAvailable: true, trialUsed: false,
+            quotaLimit: 100, quotaRemaining: 100, selectedPlanChoice: "pro", checkoutPending: true,
+        })}`;
+    if (state === "checkout-pro-stale")
         return `${watermark}${extractionPreviewBootstrap({
             plan: "free", paid: false, trialAvailable: true, trialUsed: false,
             quotaLimit: 100, quotaRemaining: 100, selectedPlanChoice: "pro",

package/dist/setup.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.",

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.28",
+  "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.