@echomem/mcp 1.4.29 → 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";
@@ -513,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 {
@@ -610,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) {
@@ -983,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 {
@@ -1076,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({
@@ -1133,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);
@@ -1168,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).
@@ -1251,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:
@@ -1876,6 +1935,28 @@ Details: ${m.details || "N/A"}`;
             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,7 +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 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.`,

package/dist/v1-contract.js

@@ -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,6 +207,7 @@ 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\".";
@@ -209,6 +216,11 @@ export function listToolSpecs(opts = {}) {
     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,
@@ -385,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. ${memoryCitationInstruction}`,
+            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: {
@@ -447,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: {

package/package.json

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