@echomem/mcp 1.4.28 → 1.4.30

package/dist/index.js

@@ -4,7 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
 import { ZodError } from "zod";
-import { canonicalToolNames, completeGroupPublicationSchema, createGroupInviteSchema, createGroupSchema, deleteMemorySchema, flagPublicationAttentionSchema, getGroupSessionSharingSchema, getByContextSchema, groupContextSchema, joinGroupSchema, keywordsSchema, listFriendsSchema, listToolSpecs, othersSchema, publishBatchToGroupSchema, publishToGroupSchema, prepareGroupPublicationSchema, publicMemorySchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, searchUsersSchema, sendFriendRequestSchema, timeRangeSchema, updateGroupProfileSchema, setGroupSessionSharingSchema, } from "./v1-contract.js";
+import { canonicalToolNames, completeGroupPublicationSchema, createGroupInviteSchema, createGroupSchema, deleteMemorySchema, flagPublicationAttentionSchema, getGroupSessionSharingSchema, getByContextSchema, groupContextSchema, joinGroupSchema, keywordsSchema, listFriendsSchema, listToolSpecs, othersSchema, publishBatchToGroupSchema, publishToGroupSchema, prepareGroupPublicationSchema, publicMemorySchema, recordMemoryCitationsSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, searchUsersSchema, sendFriendRequestSchema, timeRangeSchema, updateGroupProfileSchema, setGroupSessionSharingSchema, } from "./v1-contract.js";
 import { KeyStore } from "./keystore.js";
 import { EventLogger, hashText } from "./events.js";
 import { buildReportText } from "./report.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 {
 }
@@ -510,6 +513,16 @@ function inputAnalyticsForTool(canonicalName, args) {
                 memory_id_hash: memoryId ? hashText(memoryId) : undefined,
             };
         }
+        case canonicalToolNames.recordCitations: {
+            const memoryIds = Array.isArray(a.memoryIds)
+                ? a.memoryIds.filter((id) => typeof id === "string")
+                : [];
+            const receiptId = readString(a, "receiptId");
+            return {
+                memory_count: memoryIds.length,
+                receipt_id_hash: receiptId ? hashText(receiptId) : undefined,
+            };
+        }
         case canonicalToolNames.flagPublicationAttention: {
             const memoryIds = Array.isArray(a.memoryIds) ? a.memoryIds.filter((id) => typeof id === "string") : [];
             return {
@@ -607,6 +620,21 @@ class EchoMemApiClient {
             return undefined;
         }
     }
+    /**
+     * Compact "who covers what" guide for the user's company group, used to decorate the group tool
+     * descriptions. Group publication snapshots are plaintext by design, so this works even when the
+     * local vault is locked — unlike `fetchMemoryMap`, it never needs a decryption key.
+     */
+    async fetchGroupMemoryMap() {
+        try {
+            const response = await this.axios.get("/api/extension/social/groups/current", { timeout: 6000 });
+            const map = typeof response.data?.map === "string" ? response.data.map.trim() : "";
+            return map || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /** Encryption config for the account, fetched once and cached. Failures are not cached. */
     async getEncryptionConfig() {
         if (!this.encConfigPromise) {
@@ -980,6 +1008,16 @@ class EchoMemApiClient {
             throw new Error(`get_public_memory failed against ${ECHO_API_BASE_URL}: ${describeError(error)}`);
         }
     }
+    async recordMemoryCitations(args) {
+        const parsed = recordMemoryCitationsSchema.parse(args ?? {});
+        try {
+            const response = await this.axios.post("/api/extension/social/memory-citations", { ...parsed, sessionKey: this.sessionId });
+            return response.data;
+        }
+        catch (error) {
+            throw new Error(`record_memory_citations failed against ${ECHO_API_BASE_URL}: ${describeError(error)}`);
+        }
+    }
     async getGroupContext(args) {
         groupContextSchema.parse(args ?? {});
         try {
@@ -1073,15 +1111,28 @@ class EchoMemApiClient {
     }
 }
 const SERVER_VERSION = MCP_PACKAGE_VERSION;
+/** Tool-description decoration must never delay the MCP handshake; give up and decorate next listing. */
+const MAP_WAIT_MS = 2500;
+function capWait(pending) {
+    if (!pending)
+        return Promise.resolve(undefined);
+    return Promise.race([
+        pending,
+        new Promise((resolve) => setTimeout(() => resolve(undefined), MAP_WAIT_MS)),
+    ]);
+}
 class EchoMemMCPServer {
     server;
     client;
     mapCache = null;
+    groupMapCache = null;
     events;
     mcpClientName;
     mcpClientVersion;
     /** Whether the most recent ListTools response carried the memory map (per-session recall signal). */
     mapInjected = false;
+    /** Whether the most recent ListTools response carried the group memory map. */
+    groupMapInjected = false;
     updateStatus;
     constructor(store) {
         this.server = new Server({
@@ -1130,15 +1181,23 @@ class EchoMemMCPServer {
                 this.mapCache.then((m) => { if (!m)
                     this.mapCache = null; }).catch(() => { this.mapCache = null; });
             }
+            if (this.client.hasToken() && !this.groupMapCache) {
+                this.groupMapCache = this.client.fetchGroupMemoryMap();
+                this.groupMapCache.then((m) => { if (!m)
+                    this.groupMapCache = null; }).catch(() => { this.groupMapCache = null; });
+            }
             // NEVER block tool-listing on the network. A flaky/unreachable API would otherwise hang the MCP
-            // handshake and freeze the whole agent ("connection timed out after 30000ms"). The map is
-            // best-effort: cap the wait, and it'll be injected on the next listing once it resolves.
-            const map = this.mapCache
-                ? await Promise.race([this.mapCache, new Promise((r) => setTimeout(() => r(undefined), 2500))])
-                : undefined;
+            // handshake and freeze the whole agent ("connection timed out after 30000ms"). The maps are
+            // best-effort: cap the wait, and they'll be injected on the next listing once they resolve.
+            // Both races share one wall-clock budget because they run concurrently.
+            const [map, groupMap] = await Promise.all([
+                capWait(this.mapCache),
+                capWait(this.groupMapCache),
+            ]);
             this.mapInjected = !!map;
+            this.groupMapInjected = !!groupMap;
             const updateNotice = formatUpdateNotice(this.updateStatus);
-            return { tools: listToolSpecs({ map, updateNotice }) };
+            return { tools: listToolSpecs({ map, groupMap, updateNotice }) };
         });
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const canonicalName = resolveCanonicalToolName(request.params.name);
@@ -1165,6 +1224,7 @@ class EchoMemMCPServer {
                 type: "tool_call",
                 tool: canonicalName,
                 map_injected: this.mapInjected,
+                group_map_injected: this.groupMapInjected,
             };
             try {
                 // The usage report is a local, $0 audit — works with no login (value before signup).
@@ -1248,6 +1308,8 @@ class EchoMemMCPServer {
                         return await this.handleOthers(request.params.arguments);
                     case canonicalToolNames.publicMemory:
                         return await this.handlePublicMemory(request.params.arguments);
+                    case canonicalToolNames.recordCitations:
+                        return await this.handleRecordMemoryCitations(request.params.arguments);
                     case canonicalToolNames.groupContext:
                         return await this.handleGroupContext(request.params.arguments);
                     case canonicalToolNames.getGroupSessionSharing:
@@ -1446,7 +1508,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 +1530,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 +1637,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 +1663,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 +1708,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 +1720,7 @@ Details: ${m.details || "N/A"}`)
             content: [
                 {
                     type: "text",
-                    text: lines.join("\n"),
+                    text: withMemoryCitationInstruction(lines.join("\n")),
                 },
             ],
         };
@@ -1672,7 +1747,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 +1804,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,9 +1932,31 @@ Details: ${m.details || "N/A"}`;
                 : "",
         ].filter(Boolean).join("\n");
         return {
-            content: [{ type: "text", text }],
+            content: [{ type: "text", text: withMemoryCitationInstruction(text) }],
         };
     }
+    async handleRecordMemoryCitations(args) {
+        const parsed = recordMemoryCitationsSchema.parse(args ?? {});
+        const payload = await this.client.recordMemoryCitations(parsed);
+        const acceptedMemoryIds = Array.isArray(payload?.acceptedMemoryIds)
+            ? payload.acceptedMemoryIds.filter((id) => typeof id === "string")
+            : [];
+        const rejectedMemoryIds = Array.isArray(payload?.rejectedMemoryIds)
+            ? payload.rejectedMemoryIds.filter((id) => typeof id === "string")
+            : [];
+        const insertedCount = typeof payload?.insertedCount === "number" ? payload.insertedCount : 0;
+        const duplicateCount = typeof payload?.duplicateCount === "number" ? payload.duplicateCount : 0;
+        const text = [
+            `Citation receipt accepted for ${acceptedMemoryIds.length} ${acceptedMemoryIds.length === 1 ? "memory" : "memories"}.`,
+            `New citations recorded: ${insertedCount}.`,
+            duplicateCount ? `Idempotent duplicates skipped: ${duplicateCount}.` : "",
+            rejectedMemoryIds.length
+                ? `Rejected inaccessible or self-owned Memory IDs: ${rejectedMemoryIds.join(", ")}. Do not describe these as helped.`
+                : "",
+            "Now send the final answer with an EchoMem sources list containing the same accepted memories actually used.",
+        ].filter(Boolean).join("\n");
+        return { content: [{ type: "text", text }] };
+    }
     async handleGroupContext(args) {
         groupContextSchema.parse(args ?? {});
         const payload = await this.client.getGroupContext(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. For memories owned by teammates or accepted friends, call record_memory_citations immediately before the final answer with those exact Memory IDs. Do not cite memories that were merely retrieved. Use each memory key as the Markdown label and its canonical https://echoknows.com/memory/<memory-id> URL. Omit the sources section and citation receipt 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",
@@ -10,6 +10,7 @@ export const canonicalToolNames = {
     sendFriendRequest: "send_friend_request",
     others: "search_others_memories",
     publicMemory: "get_public_memory",
+    recordCitations: "record_memory_citations",
     groupContext: "get_group_context",
     getGroupSessionSharing: "get_group_session_sharing",
     setGroupSessionSharing: "set_group_session_sharing",
@@ -114,6 +115,11 @@ export const publicMemorySchema = z.object({
     ...triggerMetadataSchema,
     memoryId: z.string().min(1),
 });
+export const recordMemoryCitationsSchema = z.object({
+    ...triggerMetadataSchema,
+    memoryIds: z.array(z.string().uuid()).min(1).max(20),
+    receiptId: z.string().min(1).max(200),
+});
 export const groupContextSchema = z.object({
     ...triggerMetadataSchema,
 });
@@ -201,17 +207,24 @@ export const getByContextSchema = z.object({
 export function listToolSpecs(opts = {}) {
     const currentTime = new Date().toISOString();
     const map = opts.map?.trim();
+    const groupMap = opts.groupMap?.trim();
     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`
         : "";
+    // Same device as the personal map, aimed at the group surface: the agent judges whether teammates
+    // have covered the topic before searching, instead of never calling the group tools at all.
+    const groupMapSection = groupMap
+        ? `\n\nThis user's company group currently shares work in these areas (a relevance guide — search the group when the task relates to one of these people or topics):\n${groupMap}\n`
+        : "";
     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 +242,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 +293,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 +311,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 +397,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}${groupMapSection}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -429,7 +442,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: {
@@ -446,9 +459,37 @@ export function listToolSpecs(opts = {}) {
                 required: ["memoryId"],
             },
         },
+        {
+            name: canonicalToolNames.recordCitations,
+            description: "Call this tool immediately before the final answer when it materially uses memories owned by teammates or accepted friends. Include only the exact Memory IDs actually used. Do not cite memories that were merely retrieved. Create one opaque receiptId for the planned final answer and reuse it exactly if this tool call is retried. Do not include answer text, prompts, or secrets in receiptId.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    memoryIds: {
+                        type: "array",
+                        minItems: 1,
+                        maxItems: 20,
+                        items: { type: "string", format: "uuid" },
+                        description: "Exact IDs of teammate/friend memories materially used in the final answer.",
+                    },
+                    receiptId: {
+                        type: "string",
+                        minLength: 1,
+                        maxLength: 200,
+                        description: "Opaque per-answer idempotency key. Reuse the same value on retry; never include answer content.",
+                    },
+                    triggerMessage: {
+                        type: "string",
+                        description: "Optional user message that caused the answer. EchoMem stores only redacted analytics metadata.",
+                    },
+                    triggerMessageRole: { type: "string", default: "user" },
+                },
+                required: ["memoryIds", "receiptId"],
+            },
+        },
         {
             name: canonicalToolNames.groupContext,
-            description: "Get your current company group, its participant directory, declared titles and responsibilities, and published-memory coverage. Use this before answering who works on what or suggesting where a new group member could contribute. Treat declared profile fields as facts and memory-derived work as evidence or inference. Session sharing is separate; call get_group_session_sharing instead of inferring it.",
+            description: `Get your current company group, its participant directory, declared titles and responsibilities, and published-memory coverage. Use this before answering who works on what or suggesting where a new group member could contribute. Treat declared profile fields as facts and memory-derived work as evidence or inference. Session sharing is separate; call get_group_session_sharing instead of inferring it.${groupMapSection}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -685,7 +726,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 +743,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.30",
   "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",
@@ -27,7 +27,7 @@
     "test:registry-ui": "npm run build && node test/registry-ui.test.mjs",
     "test:ui": "npm run build && node test/setup-ui.test.mjs",
     "test:billing-ui": "npm run build && node test/setup-ui.test.mjs billing",
-    "test": "npm run build && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/local-auth.test.mjs && node test/retrieval-only.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/forensics.test.mjs && node test/canonical-golden.test.mjs && node test/tools.test.mjs && node test/update-check.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/restart-recovery.test.mjs && node test/hud.test.mjs && node test/save-checkpoint-hook.test.mjs",
+    "test": "npm run build && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/local-auth.test.mjs && node test/retrieval-only.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/forensics.test.mjs && node test/canonical-golden.test.mjs && node test/tools.test.mjs && node test/group-map.test.mjs && node test/update-check.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/restart-recovery.test.mjs && node test/hud.test.mjs && node test/save-checkpoint-hook.test.mjs",
     "prepack": "npm run build && node scripts/bundle-city.mjs"
   },
   "dependencies": {

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.