@echomem/mcp 1.4.33 → 1.4.34

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, recordMemoryCitationsSchema, 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, requestGroupSessionSharingSchema, 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";
@@ -1013,7 +1013,12 @@ class EchoMemApiClient {
     async recordMemoryCitations(args) {
         const parsed = recordMemoryCitationsSchema.parse(args ?? {});
         try {
-            const response = await this.axios.post("/api/extension/social/memory-citations", { ...parsed, sessionKey: this.sessionId });
+            const response = await this.axios.post("/api/extension/social/memory-citations", 
+            // A citation receipt belongs to one planned answer, not to the lifetime of the MCP stdio
+            // process. Deriving the legacy API's sessionKey from the required per-answer receipt keeps
+            // retries idempotent while avoiding the same process-vs-conversation coupling that broke
+            // group sharing in long-lived Claude hosts.
+            { ...parsed, sessionKey: `answer:${parsed.receiptId}` });
             return response.data;
         }
         catch (error) {
@@ -1320,6 +1325,8 @@ class EchoMemMCPServer {
                         return await this.handleGroupContext(request.params.arguments);
                     case canonicalToolNames.getGroupSessionSharing:
                         return await this.handleGetGroupSessionSharing(request.params.arguments);
+                    case canonicalToolNames.requestGroupSessionSharing:
+                        return await this.handleRequestGroupSessionSharing(request.params.arguments);
                     case canonicalToolNames.setGroupSessionSharing:
                         return await this.handleSetGroupSessionSharing(request.params.arguments);
                     case canonicalToolNames.createGroup:
@@ -1607,7 +1614,7 @@ Details: ${m.details || "N/A"}`)
                     syncedGroupNames.length
                         ? `Saved privately first and synced to approved groups: ${syncedGroupNames.join(", ")}.`
                         : "Saved to your private memory.",
-                    `This user has multiple groups: ${availableGroups.map((group) => `${readString(group, "name") ?? "Unnamed group"} (${readString(group, "id") ?? "unknown id"})`).join(", ")}. Call get_group_session_sharing with this conversation scope and one groupId at a time; obtain a separate explicit Yes/No decision for each group.`,
+                    `This user has multiple groups: ${availableGroups.map((group) => `${readString(group, "name") ?? "Unnamed group"} (${readString(group, "id") ?? "unknown id"})`).join(", ")}. Call request_group_session_sharing with this conversation scope and one groupId at a time so supported hosts render a separate sharing choice for each group.`,
                     failedSyncs.length
                         ? `${failedSyncs.length} approved group sync(s) failed; private memories were preserved.`
                         : "",
@@ -1616,7 +1623,7 @@ Details: ${m.details || "N/A"}`)
                         : "",
                 ].filter(Boolean).join(" ")
                 : sharing?.decision === null || sharing?.decision === undefined
-                    ? `Saved to your private memory. Ask: “Share memories saved from this conversation with ${readString(sharingGroup, "name") ?? "your current group"}?” Silence leaves the state unset, so ask again at a later qualifying checkpoint until the user explicitly answers Yes or No; do not repeat the prompt in the same response.`
+                    ? `Saved to your private memory. Call request_group_session_sharing with this conversation scope${readString(sharingGroup, "id") ? ` and groupId ${readString(sharingGroup, "id")}` : ""} so a supported host can show the sharing choice for ${readString(sharingGroup, "name") ?? "your current group"}. If the client cannot render it, relay that tool's fallback question. Decline, cancel, or silence leaves the state unset.`
                     : sharing.decision === "private"
                         ? "Saved to your private memory."
                         : syncedGroupNames.length
@@ -1646,7 +1653,7 @@ Details: ${m.details || "N/A"}`)
             `Successfully ingested conversation. Extracted ${memoriesExtracted} memory distinct events.`,
             receipt,
             typeof groupSharingScopeId === "string" && groupSharingScopeId
-                ? `Conversation sharing scope: ${groupSharingScopeId}\nReuse this exact groupSharingScopeId only for get_group_session_sharing, set_group_session_sharing, and save_conversation calls in this conversation. Never reuse it in another conversation or save it as memory.`
+                ? `Conversation sharing scope: ${groupSharingScopeId}\nReuse this exact groupSharingScopeId only for get_group_session_sharing, request_group_session_sharing, set_group_session_sharing, and save_conversation calls in this conversation. Never reuse it in another conversation or save it as memory.`
                 : "",
             typeof memoriesDiscarded === "number" && memoriesDiscarded > 0
                 ? `${memoriesDiscarded} additional memories were not stored because your active-memory limit was reached.`
@@ -2090,7 +2097,7 @@ Details: ${m.details || "N/A"}`;
             return {
                 content: [{
                         type: "text",
-                        text: `${scopeText}\n\nThis user belongs to multiple groups: ${choices}. Reuse this same conversation scope and call get_group_session_sharing once per groupId. Ask for a separate explicit Yes/No sharing decision for each selected group.`,
+                        text: `${scopeText}\n\nThis user belongs to multiple groups: ${choices}. Reuse this same conversation scope and call request_group_session_sharing once per groupId so supported hosts render a separate sharing choice for each group.`,
                     }],
             };
         }
@@ -2100,7 +2107,7 @@ Details: ${m.details || "N/A"}`;
             return {
                 content: [{
                         type: "text",
-                        text: `${scopeText}\n\nNo sharing decision exists for this conversation. Ask: “Share memories saved from this conversation with ${readString(group, "name") ?? "your group"}?” Silence is not a No: leave the state unset and ask again at a later qualifying checkpoint until the user explicitly answers Yes or No, without repeating the prompt in the same response. Then call set_group_session_sharing with that explicit answer and the scope above; an explicit No stops later prompts for this conversation.`,
+                        text: `${scopeText}\n\nNo sharing decision exists for this conversation. Call request_group_session_sharing with the scope above${readString(group, "id") ? ` and groupId ${readString(group, "id")}` : ""}. Supported hosts will show a native Share with team / Keep private choice. If the client cannot render it, relay that tool's fallback question. Decline, cancel, or silence is not a No and leaves the state unset.`,
                     }],
             };
         }
@@ -2116,13 +2123,23 @@ Details: ${m.details || "N/A"}`;
                 }],
         };
     }
-    async handleSetGroupSessionSharing(args) {
-        const parsed = setGroupSessionSharingSchema.parse(args ?? {});
-        const payload = await this.client.setGroupSessionSharing(parsed);
-        const sync = isRecord(payload?.sync) ? payload.sync : null;
+    sharingScopeText(groupSharingScopeId) {
+        return groupSharingScopeId
+            ? `Conversation sharing scope: ${groupSharingScopeId}\nReuse this exact groupSharingScopeId only in this conversation for later get/request/set/save calls. Never persist it as memory.`
+            : "";
+    }
+    sharingFallbackText(scopeText, groupName) {
+        return [
+            scopeText,
+            `This client cannot show EchoMem's sharing choice UI. Ask: “Share eligible memories saved from this conversation with ${groupName}?” Only an explicit Yes or No may be passed to set_group_session_sharing. Decline, cancel, or silence leaves the state unset.`,
+        ].filter(Boolean).join("\n\n");
+    }
+    formatGroupSessionSharingUpdate(share, payload, scopeText = "") {
+        const data = isRecord(payload) ? payload : {};
+        const sync = isRecord(data.sync) ? data.sync : null;
         const protectedIds = Array.isArray(sync?.protectedMemoryIds) ? sync.protectedMemoryIds : [];
-        const group = isRecord(payload?.group) ? payload.group : {};
-        const receipt = parsed.share
+        const group = isRecord(data.group) ? data.group : {};
+        const receipt = share
             ? sync?.synced === false
                 ? "Conversation sharing is enabled, but the initial group sync failed. Private memories were preserved; retry before claiming publication."
                 : `Conversation sharing is enabled for ${readString(group, "name") ?? "the current group"}. Existing eligible memories in this scope were synced and later saves carrying the same scope will sync automatically.`
@@ -2130,10 +2147,127 @@ Details: ${m.details || "N/A"}`;
         return {
             content: [{
                     type: "text",
-                    text: `${receipt}${protectedIds.length ? ` ${protectedIds.length} flagged ${protectedIds.length === 1 ? "memory was" : "memories were"} protected and kept private.` : ""}`,
+                    text: [
+                        scopeText,
+                        `${receipt}${protectedIds.length ? ` ${protectedIds.length} flagged ${protectedIds.length === 1 ? "memory was" : "memories were"} protected and kept private.` : ""}`,
+                    ].filter(Boolean).join("\n\n"),
                 }],
         };
     }
+    async handleRequestGroupSessionSharing(args) {
+        const parsed = requestGroupSessionSharingSchema.parse(args ?? {});
+        const payload = await this.client.getGroupSessionSharing(parsed);
+        const groupSharingScopeId = readString(payload ?? {}, "groupSharingScopeId");
+        const scopeText = this.sharingScopeText(groupSharingScopeId);
+        if (!groupSharingScopeId) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "EchoMem could not establish a conversation sharing scope, so no decision was recorded and the checkpoint remains private. Retry request_group_session_sharing before offering team sharing.",
+                    }],
+            };
+        }
+        if (payload?.hasGroup !== true) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "No company group is configured for this user. Saves remain private; do not ask about conversation sharing.",
+                    }],
+            };
+        }
+        if (payload?.requiresGroupSelection === true) {
+            const availableGroups = Array.isArray(payload?.availableGroups)
+                ? payload.availableGroups.filter(isRecord)
+                : [];
+            const choices = availableGroups
+                .map((group) => `${readString(group, "name") ?? "Unnamed group"} (${readString(group, "id") ?? "unknown id"})`)
+                .join(", ");
+            return {
+                content: [{
+                        type: "text",
+                        text: `${scopeText}\n\nChoose one group and call request_group_session_sharing again with the same scope and its groupId: ${choices}. Each group has an independent decision.`,
+                    }],
+            };
+        }
+        const group = isRecord(payload?.group) ? payload.group : {};
+        const groupName = readString(group, "name") ?? "your group";
+        const existingDecision = typeof payload?.decision === "string" ? payload.decision : null;
+        if (existingDecision === "share" || existingDecision === "private") {
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            scopeText,
+                            existingDecision === "share"
+                                ? `This conversation is already approved for ${groupName}. Eligible memories sync automatically; flagged memories stay private.`
+                                : `This conversation is already private for ${groupName}. No sharing prompt was shown.`,
+                        ].filter(Boolean).join("\n\n"),
+                    }],
+            };
+        }
+        const formElicitation = this.server.getClientCapabilities()?.elicitation?.form;
+        if (!formElicitation) {
+            return {
+                content: [{ type: "text", text: this.sharingFallbackText(scopeText, groupName) }],
+            };
+        }
+        let elicitation;
+        try {
+            elicitation = await this.server.elicitInput({
+                mode: "form",
+                message: `EchoMem saved this checkpoint privately. Choose whether eligible memories from this conversation should also be shared with ${groupName}. Flagged memories always remain private.`,
+                requestedSchema: {
+                    type: "object",
+                    properties: {
+                        sharingDecision: {
+                            type: "string",
+                            title: "Team sharing",
+                            description: `Choose whether eligible conversation memories may be shared with ${groupName}.`,
+                            oneOf: [
+                                { const: "share", title: "Share with team" },
+                                { const: "private", title: "Keep private" },
+                            ],
+                        },
+                    },
+                    required: ["sharingDecision"],
+                },
+            });
+        }
+        catch {
+            return {
+                content: [{ type: "text", text: this.sharingFallbackText(scopeText, groupName) }],
+            };
+        }
+        if (elicitation.action !== "accept") {
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            scopeText,
+                            `No sharing decision was recorded for ${groupName}. The checkpoint remains private. Ask again at a later qualifying checkpoint; never interpret decline or cancel as No.`,
+                        ].filter(Boolean).join("\n\n"),
+                    }],
+            };
+        }
+        const sharingDecision = readString(elicitation.content ?? {}, "sharingDecision");
+        if (sharingDecision !== "share" && sharingDecision !== "private") {
+            return {
+                content: [{ type: "text", text: this.sharingFallbackText(scopeText, groupName) }],
+            };
+        }
+        const updatePayload = await this.client.setGroupSessionSharing({
+            ...parsed,
+            groupSharingScopeId,
+            share: sharingDecision === "share",
+            confirmed: true,
+        });
+        return this.formatGroupSessionSharingUpdate(sharingDecision === "share", updatePayload, scopeText);
+    }
+    async handleSetGroupSessionSharing(args) {
+        const parsed = setGroupSessionSharingSchema.parse(args ?? {});
+        const payload = await this.client.setGroupSessionSharing(parsed);
+        return this.formatGroupSessionSharingUpdate(parsed.share, payload);
+    }
     async handlePublishToGroup(args) {
         const parsed = publishToGroupSchema.parse(args ?? {});
         const payload = await this.client.publishMemoryToGroup(args);
@@ -2182,8 +2316,8 @@ Details: ${m.details || "N/A"}`;
             content: [{
                     type: "text",
                     text: payload?.alreadyMember
-                        ? `You are already a member of ${payload?.group?.name ?? "this group"}. No memories were published. Use prepare_group_publication to review memories and propose any missing title or responsibility fields, then call get_group_session_sharing and, if unset, ask again at later qualifying checkpoints until the user explicitly answers Yes or No.`
-                        : `Joined ${payload?.group?.name ?? "the company group"}. No memories were published. Next use prepare_group_publication to review candidates, infer a proposed title and responsibility summary, and ask the user to confirm that profile together with the publication preview. Also call get_group_session_sharing without a scope to mint one for this conversation; if unset, ask whether memories saved from this conversation should be shared and ask again at a later qualifying checkpoint after silence until an explicit Yes or No.`,
+                        ? `You are already a member of ${payload?.group?.name ?? "this group"}. No memories were published. Use prepare_group_publication to review memories and propose any missing title or responsibility fields, then call request_group_session_sharing so supported hosts render the native sharing choice. Decline or cancel stays unset for a later checkpoint.`
+                        : `Joined ${payload?.group?.name ?? "the company group"}. No memories were published. Next use prepare_group_publication to review candidates, infer a proposed title and responsibility summary, and ask the user to confirm that profile together with the publication preview. Also call request_group_session_sharing without a scope so supported hosts show the native team-sharing choice. Decline or cancel leaves consent unset for a later checkpoint.`,
                 }],
         };
     }

package/dist/package-metadata.js

@@ -27,19 +27,15 @@ export const MEMORY_CITATION_INSTRUCTION = 'If the user-facing answer materially
 export const SAVED_MEMORY_RECEIPT_INSTRUCTION = 'After save_conversation succeeds and returns one or more saved memory IDs, make the save visible in the final user-facing answer with a compact "EchoMem saved:" list containing every memory created by that call. Use each memory key as the Markdown label and its canonical https://echoknows.com/memory/<memory-id> URL. This save receipt is separate from "EchoMem sources:" and does not imply that the newly saved memories 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.`,
-    "Use echomem_update_status to check whether npm has a newer bridge; it is cached and non-blocking during normal tool listing.",
-    "Do not auto-update on every MCP startup; this bridge is intentionally stable between explicit updates.",
-    "Before the final response for work that produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone, call save_conversation. This is a private checkpoint and does not require a separate user request. Skip secrets, incidental chatter, and trivial read-only work. If an encrypted vault is locked, tell the user to run echomem-mcp unlock rather than silently skipping the checkpoint.",
-    "For a user with a company group, call get_group_session_sharing near conversation start or after a qualifying private save. On the first call in a conversation, omit groupSharingScopeId so EchoMem mints a fresh opaque scope. Reuse that exact scope only in this conversation for later get/set/save calls, and never persist it as memory. If multiple groups are returned, reuse the same scope and check one groupId at a time. Each group requires its own explicit Yes/No decision. Silence leaves that group's state unset; never infer an answer or repeat the prompt in the same response. Store only explicit answers with set_group_session_sharing, the same scope, and the selected groupId. Saves sync eligible memories to every approved group; a No keeps them private for that group. Flagged memories stay private.",
-    "For company-group sharing, use get_group_context for orientation; create_memory_group/create_group_invite/join_memory_group for membership; and prepare_group_publication as a no-publication preview.",
-    "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,
-    SAVED_MEMORY_RECEIPT_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.",
+    `If this bridge is stale, update once with \`${MCP_UPDATE_ALL_COMMAND}\` and start a new MCP session; never auto-update at startup.`,
+    "Before re-deriving prior decisions or preferences, use search_memories.",
+    "Before the final response for a durable decision, implementation, fix, commit, passing verification, release, or milestone, call save_conversation. Skip secrets and trivial work. If the encrypted vault is locked, tell the user to run echomem-mcp unlock.",
+    "After a successful save, show every memory created by that call in a compact EchoMem saved: list with canonical links; this is separate from \"EchoMem sources:\".",
+    "For company groups, call request_group_session_sharing near conversation start or after a qualifying save. It renders a native choice on clients with MCP elicitation and returns a text fallback otherwise. Omit groupSharingScopeId only on the first call, then reuse the returned scope only in this conversation. Each group needs an explicit choice; decline, cancel, or silence stays unset. Never infer consent. Flagged memories stay private.",
+    "EchoMem credential identity is authoritative over Claude profiles, host accounts, git identity, or inference. Use get_group_context before group-orientation answers and never re-filter owners returned by search_others_memories.",
+    "When a final answer materially uses teammate or friend memories, call record_memory_citations with only the exact used Memory IDs and a unique per-answer receiptId.",
+    "End memory-informed answers with a compact EchoMem sources: list. Use each memory key as the label and https://echoknows.com/memory/<memory-id> as its canonical link.",
+    "Group profiles, conversation sharing, publication, sensitive-memory flags, and deletion require explicit user confirmation. Never store or log an echo_grp_ invite code.",
 ].join(" ");
 export function withMcpVersion(description) {
     return `${description}\n\nEchoMem MCP bridge: ${MCP_PACKAGE_LABEL}. If this version is stale, update once with \`${MCP_UPDATE_ALL_COMMAND}\` (or add \`--client cursor|windsurf|claude-desktop|claude-code|codex\` for a single client), then start a new MCP session. Do not run updates repeatedly or on every startup.`;

package/dist/save-checkpoint-hook.js

@@ -7,8 +7,8 @@ const CHECKPOINT_REASON = [
     "Run EchoMem's private completion checkpoint before finishing this turn.",
     "Review the work that just completed. If it produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone, call `save_conversation` now with a concise structured summary of the outcome, reasoning, relevant files, and constraints.",
     "Do not save secrets or incidental chatter. If the work was not durable, do not call the tool and finish normally.",
-    "Private persistence happens first. For a user with a company group, call `get_group_session_sharing` near conversation start or after a qualifying private save.",
-    "On the first get_group_session_sharing call in a conversation, omit groupSharingScopeId so EchoMem mints a fresh opaque scope. Reuse that exact scope only in this conversation for later get/set/save calls, and never persist it as memory. If multiple groups are returned, reuse the same scope and check one groupId at a time. Each group needs its own explicit Yes/No decision. Silence leaves that group's state unset; do not infer an answer or repeat the prompt in the same response. A Yes decision syncs eligible memories from later saves carrying the same scope to that group; saves automatically sync to every approved group. A No decision keeps them private for that group.",
+    "Private persistence happens first. For a user with a company group, call `request_group_session_sharing` near conversation start or after a qualifying private save.",
+    "On the first request_group_session_sharing call in a conversation, omit groupSharingScopeId so EchoMem mints a fresh opaque scope. Reuse that exact scope only in this conversation for later get/request/set/save calls, and never persist it as memory. If multiple groups are returned, reuse the same scope and call once per groupId. Supported clients render a native Share with team / Keep private choice; if the tool returns a text fallback, relay its exact question and call set_group_session_sharing only after an explicit Yes/No. Decline, cancel, or silence leaves that group's state unset. A Share decision syncs eligible memories from later saves carrying the same scope to that group; saves automatically sync to every approved group. Keep private keeps them private for that group.",
     "Flagged memories are withheld from automatic conversation sync and remain private.",
     "If EchoMem reports that the encrypted vault is locked, tell the user to run `echomem-mcp unlock`; never silently skip a qualifying checkpoint.",
 ].join(" ");

package/dist/setup.js

@@ -218,13 +218,15 @@ export function knownClients() {
         { id: "codex", label: "Codex", kind: "command", detectDir: codexHome(), configPath: path.join(codexHome(), "config.toml"), note: "add to ~/.codex/config.toml under [mcp_servers.echomem]" },
     ];
 }
-/** A client is "present" if its config dir already exists (JSON) — a cheap heuristic for detection. */
+/** A client is "present" if its config dir already exists — a cheap, side-effect-free heuristic. */
 export function detectClients() {
     return knownClients().filter((c) => {
         if (c.kind === "json")
             return fs.existsSync(path.dirname(c.configPath));
         if (c.kind === "command")
             return fs.existsSync(c.detectDir);
+        if (c.id === "claude-code")
+            return fs.existsSync(home(".claude"));
         return false;
     });
 }
@@ -392,7 +394,7 @@ function echomemGuidanceBlock() {
         '- 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.",
         '- After `save_conversation` succeeds and returns one or more saved memory IDs, make the save visible in the final user-facing answer with a compact `EchoMem saved:` list containing every memory created by that call. Link each memory key to its canonical `https://echoknows.com/memory/<memory-id>` URL. This save receipt is separate from `EchoMem sources:` and does not imply the newly saved memories informed the answer.',
-        "- For a user with a company group, call `get_group_session_sharing` near conversation start or after a qualifying private save. On the first call in a conversation, omit `groupSharingScopeId` so EchoMem mints a fresh opaque scope. Reuse that exact scope only in this conversation for later get/set/save calls, and never persist it as memory. If multiple groups are returned, reuse the same scope and check one `groupId` at a time. Each group requires its own explicit Yes/No decision. Silence leaves that group's state unset; never infer an answer or repeat the prompt in the same response. Store only explicit answers with `set_group_session_sharing`, the same scope, and the selected groupId. Saves sync eligible memories to every approved group; a No keeps them private for that group.",
+        "- For a user with a company group, call `request_group_session_sharing` near conversation start or after a qualifying private save. On the first call in a conversation, omit `groupSharingScopeId` so EchoMem mints a fresh opaque scope. Reuse that exact scope only in this conversation for later get/request/set/save calls, and never persist it as memory. If multiple groups are returned, reuse the same scope and call once per `groupId`. Supported clients render a native Share with team / Keep private choice. If the tool returns a text fallback, relay its exact question and call `set_group_session_sharing` only after an explicit Yes/No. Decline, cancel, or silence leaves that group's state unset; never infer an answer. Saves sync eligible memories to every approved group; a No keeps them private for that group.",
         "- 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.",
         "",
         "### Company group memory",

package/dist/v1-contract.js

@@ -13,6 +13,7 @@ export const canonicalToolNames = {
     recordCitations: "record_memory_citations",
     groupContext: "get_group_context",
     getGroupSessionSharing: "get_group_session_sharing",
+    requestGroupSessionSharing: "request_group_session_sharing",
     setGroupSessionSharing: "set_group_session_sharing",
     createGroup: "create_memory_group",
     createGroupInvite: "create_group_invite",
@@ -38,6 +39,127 @@ export const legacyAliasToCanonical = {
 export function resolveCanonicalToolName(toolName) {
     return legacyAliasToCanonical[toolName] ?? toolName;
 }
+export const TOOL_DESCRIPTION_BYTE_LIMIT = 2_000;
+const READ_ONLY_TOOL_NAMES = new Set([
+    canonicalToolNames.search,
+    "search_memories_by_description_semantic",
+    canonicalToolNames.timeRange,
+    "search_memories_by_time_range",
+    canonicalToolNames.keywords,
+    canonicalToolNames.friends,
+    canonicalToolNames.searchUsers,
+    canonicalToolNames.others,
+    canonicalToolNames.publicMemory,
+    canonicalToolNames.groupContext,
+    canonicalToolNames.getGroupSessionSharing,
+    canonicalToolNames.getByContext,
+    canonicalToolNames.checkpointByContext,
+    canonicalToolNames.report,
+    canonicalToolNames.updateStatus,
+    canonicalToolNames.contextHealth,
+    canonicalToolNames.recompose,
+]);
+const IDEMPOTENT_WRITE_TOOL_NAMES = new Set([
+    canonicalToolNames.recordCitations,
+    canonicalToolNames.requestGroupSessionSharing,
+    canonicalToolNames.setGroupSessionSharing,
+    canonicalToolNames.updateGroupProfile,
+    canonicalToolNames.completeGroupPublication,
+    canonicalToolNames.publishToGroup,
+    canonicalToolNames.publishBatchToGroup,
+]);
+const REQUIRES_USER_INTERACTION_TOOL_NAMES = new Set([
+    canonicalToolNames.requestGroupSessionSharing,
+    canonicalToolNames.setGroupSessionSharing,
+    canonicalToolNames.flagPublicationAttention,
+    canonicalToolNames.updateGroupProfile,
+    canonicalToolNames.completeGroupPublication,
+    canonicalToolNames.publishToGroup,
+    canonicalToolNames.publishBatchToGroup,
+    canonicalToolNames.delete,
+]);
+const ALWAYS_LOAD_TOOL_NAMES = new Set([
+    canonicalToolNames.search,
+    canonicalToolNames.save,
+]);
+const LOCAL_ONLY_TOOL_NAMES = new Set([
+    canonicalToolNames.report,
+    canonicalToolNames.contextHealth,
+    canonicalToolNames.recompose,
+]);
+function truncateToByteBudget(value, limit) {
+    if (Buffer.byteLength(value, "utf8") <= limit)
+        return value;
+    const ellipsis = "…";
+    const contentBudget = limit - Buffer.byteLength(ellipsis, "utf8");
+    if (contentBudget <= 0)
+        return "";
+    let low = 0;
+    let high = value.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (Buffer.byteLength(value.slice(0, middle), "utf8") <= contentBudget)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    const safeEnd = low > 0
+        && /[\uD800-\uDBFF]/.test(value.charAt(low - 1))
+        && /[\uDC00-\uDFFF]/.test(value.charAt(low))
+        ? low - 1
+        : low;
+    const candidate = value.slice(0, safeEnd);
+    const boundary = Math.max(candidate.lastIndexOf("\n"), candidate.lastIndexOf(" "));
+    const body = boundary >= Math.floor(candidate.length * 0.8) ? candidate.slice(0, boundary) : candidate;
+    return `${body.trimEnd()}${ellipsis}`;
+}
+function boundToolDescription(description) {
+    if (Buffer.byteLength(description, "utf8") <= TOOL_DESCRIPTION_BYTE_LIMIT)
+        return description;
+    const versionMarker = "\n\nEchoMem MCP bridge:";
+    const versionIndex = description.lastIndexOf(versionMarker);
+    if (versionIndex < 0) {
+        return truncateToByteBudget(description, TOOL_DESCRIPTION_BYTE_LIMIT);
+    }
+    const suffix = description.slice(versionIndex + 2);
+    const separator = "\n\n";
+    const bodyLimit = TOOL_DESCRIPTION_BYTE_LIMIT
+        - Buffer.byteLength(suffix, "utf8")
+        - Buffer.byteLength(separator, "utf8");
+    if (bodyLimit <= 0)
+        return truncateToByteBudget(suffix, TOOL_DESCRIPTION_BYTE_LIMIT);
+    return `${truncateToByteBudget(description.slice(0, versionIndex), bodyLimit)}${separator}${suffix}`;
+}
+function compactGroupRoster(groupMap) {
+    const labels = groupMap
+        .split("\n")
+        .map((line) => line.trim().replace(/^-\s*/, ""))
+        .filter(Boolean)
+        .map((line) => line.split(/\s+—\s+/u, 1)[0] ?? line)
+        .map((label) => truncateToByteBudget(label, 48));
+    return labels.length ? `Team roster: ${labels.join("; ")}.` : "";
+}
+function decorateLocalToolSpec(tool) {
+    const readOnly = READ_ONLY_TOOL_NAMES.has(tool.name);
+    const decorated = {
+        ...tool,
+        description: boundToolDescription(tool.description),
+        annotations: {
+            readOnlyHint: readOnly,
+            destructiveHint: tool.name === canonicalToolNames.delete,
+            idempotentHint: readOnly || IDEMPOTENT_WRITE_TOOL_NAMES.has(tool.name),
+            openWorldHint: !LOCAL_ONLY_TOOL_NAMES.has(tool.name),
+        },
+    };
+    const meta = {};
+    if (ALWAYS_LOAD_TOOL_NAMES.has(tool.name)) {
+        meta["anthropic/alwaysLoad"] = true;
+    }
+    if (REQUIRES_USER_INTERACTION_TOOL_NAMES.has(tool.name)) {
+        meta["anthropic/requiresUserInteraction"] = true;
+    }
+    return Object.keys(meta).length > 0 ? { ...decorated, _meta: meta } : decorated;
+}
 const triggerMetadataSchema = {
     triggerMessage: z.string().optional(),
     triggerMessageRole: z.string().optional(),
@@ -129,6 +251,7 @@ export const getGroupSessionSharingSchema = z.object({
     groupSharingScopeId: z.string().uuid().optional(),
     groupId: z.string().uuid().optional(),
 });
+export const requestGroupSessionSharingSchema = getGroupSessionSharingSchema;
 export const setGroupSessionSharingSchema = z.object({
     ...triggerMetadataSchema,
     groupSharingScopeId: z.string().uuid(),
@@ -224,9 +347,9 @@ export function listToolSpecs(opts = {}) {
     // 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`
+        ? `\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${compactGroupRoster(groupMap)}\n${groupMap}\n`
         : "";
-    return [
+    const tools = [
         {
             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} ${memoryCitationInstruction}${mapSection}\nReturns ranked memories only; the MCP host model writes the final answer. Current time: ${currentTime}.${updateSection}`),
@@ -265,7 +388,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.save,
-            description: `Save durable knowledge from this conversation into the user's private EchoMem (durable memories are extracted automatically). Call before the final response when work produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone; this private checkpoint does not require a separate user request. Omit secrets, incidental chatter, and trivial read-only work. If the encrypted vault is locked, tell the user to run \`echomem-mcp unlock\` and never silently skip a qualifying checkpoint. Private persistence happens first. For group sharing, reuse the exact groupSharingScopeId returned by get_group_session_sharing or an earlier save in this conversation. Never reuse it in another conversation or save it as memory. Each group has an independent decision under the same conversation scope; eligible memories sync automatically to every approved group, while flagged memories stay private. If a selected group has no decision yet, ask whether to share with that named group. Silence leaves it unset; never infer the answer. New extraction input uses the plan's weekly processing allowance; if the limit is reached, nothing is saved. passthrough=true stores the text verbatim as a session capsule. ${SAVED_MEMORY_RECEIPT_INSTRUCTION}`,
+            description: `Save durable knowledge from this conversation into the user's private EchoMem (durable memories are extracted automatically). Call before the final response when work produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone; this private checkpoint does not require a separate user request. Omit secrets, incidental chatter, and trivial read-only work. If the encrypted vault is locked, tell the user to run \`echomem-mcp unlock\` and never silently skip a qualifying checkpoint. Private persistence happens first. For group sharing, reuse the exact groupSharingScopeId returned by get_group_session_sharing, request_group_session_sharing, or an earlier save in this conversation. Never reuse it in another conversation or save it as memory. Each group has an independent decision under the same conversation scope; eligible memories sync automatically to every approved group, while flagged memories stay private. If a selected group has no decision yet, call request_group_session_sharing so supported hosts render a choice UI; its fallback tells you when a text Yes/No prompt is required. Silence leaves consent unset; never infer the answer. New extraction input uses the plan's weekly processing allowance; if the limit is reached, nothing is saved. passthrough=true stores the text verbatim as a session capsule. ${SAVED_MEMORY_RECEIPT_INSTRUCTION}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -513,7 +636,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.getGroupSessionSharing,
-            description: "Read the confirmed sharing decision for one group in this exact conversation. On the first call, omit groupSharingScopeId; EchoMem returns a new opaque scope. Reuse that scope only in this conversation. If the user belongs to multiple groups and groupId is omitted, EchoMem returns the available groups; call again with the same scope and one groupId at a time. Each group requires an independent explicit Yes/No decision. Silence leaves that group's state unset; never infer the answer.",
+            description: "Read the confirmed sharing decision for one group in this exact conversation. On the first call, omit groupSharingScopeId; EchoMem returns a new opaque scope. Reuse that scope only in this conversation. If the user belongs to multiple groups and groupId is omitted, EchoMem returns the available groups. If a decision is unset, call request_group_session_sharing with this scope and the selected groupId so supported hosts render a choice UI. Silence leaves that group's state unset; never infer the answer.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -532,6 +655,27 @@ export function listToolSpecs(opts = {}) {
                 },
             },
         },
+        {
+            name: canonicalToolNames.requestGroupSessionSharing,
+            description: "Check one group's sharing decision for this exact conversation and, only when it is unset, ask the user through the MCP client's native choice UI. Omit groupSharingScopeId only on the first call so EchoMem can mint a fresh scope; reuse the returned scope only in this conversation. When multiple groups are returned, call again with the same scope and one groupId at a time. An accepted Share choice backfills eligible private memories and syncs later saves; Keep private records No. Decline or cancel records nothing. If the client cannot render MCP elicitation, relay the returned fallback question and call set_group_session_sharing only after the user explicitly answers.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    groupSharingScopeId: {
+                        type: "string",
+                        format: "uuid",
+                        description: "Reuse the opaque scope returned in this conversation. Omit only on the first sharing check.",
+                    },
+                    groupId: {
+                        type: "string",
+                        format: "uuid",
+                        description: "Group to confirm. Required when the user belongs to multiple groups.",
+                    },
+                    triggerMessage: { type: "string" },
+                    triggerMessageRole: { type: "string", default: "user" },
+                },
+            },
+        },
         {
             name: canonicalToolNames.setGroupSessionSharing,
             description: "Store the user's explicit Yes/No sharing decision for one group in this exact conversation scope. Pass the exact groupSharingScopeId returned in this conversation and the selected groupId when the user belongs to multiple groups. EchoMem validates membership server-side. Decisions are independent per group: share=true backfills that group and later saves sync to every approved group; share=false keeps this conversation private for that group. Flagged memories remain private.",
@@ -574,7 +718,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.joinGroup,
-            description: "Join a company memory group using an invite code after the user explicitly asks to join. Joining never publishes memories. Next call prepare_group_publication, infer a proposed title and responsibility summary from the user's own candidate memories, and ask the user to confirm the profile together with the publication preview. Also call get_group_session_sharing without a scope to mint one for this conversation and, if unset, ask whether memories saved from this conversation should be shared. Silence stays unset and should be prompted again at a later qualifying checkpoint until an explicit Yes or No.",
+            description: "Join a company memory group using an invite code after the user explicitly asks to join. Joining never publishes memories. Next call prepare_group_publication, infer a proposed title and responsibility summary from the user's own candidate memories, and ask the user to confirm the profile together with the publication preview. Also call request_group_session_sharing without a scope so supported hosts render a native sharing choice. Decline or cancel stays unset and should be prompted again at a later qualifying checkpoint.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -841,4 +985,5 @@ export function listToolSpecs(opts = {}) {
             },
         },
     ];
+    return tools.map(decorateLocalToolSpec);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.33",
+  "version": "1.4.34",
   "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-save/SKILL.md

@@ -23,12 +23,12 @@ Use the `save_conversation` tool from the `echomem` MCP server.
    read-only work and incidental chatter.
 7. If the encrypted vault is locked, tell the user to run `echomem-mcp unlock`; never silently skip a
    qualifying checkpoint.
-8. For a user with a company group, call `get_group_session_sharing` near conversation start or after a
-   qualifying private save. On the first call in a conversation, omit `groupSharingScopeId` so EchoMem
-   mints a fresh opaque scope. Reuse that exact scope only in this conversation for later get/set/save
-   calls, and never persist it as memory. If multiple groups are returned, reuse the same scope and
-   check one `groupId` at a time. Each group requires its own explicit Yes/No decision. Silence leaves
-   that group's state unset; never infer an answer or repeat the prompt in the same response. Store only
-   explicit answers with `set_group_session_sharing`, the same scope, and the selected groupId. Saves
-   sync eligible memories to every approved group; a No keeps them private for that group; flagged
-   memories remain private.
+8. For a user with a company group, call `request_group_session_sharing` near conversation start or
+   after a qualifying private save. On the first call in a conversation, omit `groupSharingScopeId` so
+   EchoMem mints a fresh opaque scope. Reuse that exact scope only in this conversation for later
+   get/request/set/save calls, and never persist it as memory. If multiple groups are returned, reuse
+   the same scope and call once per `groupId`. Supported clients render a native Share with team / Keep
+   private choice. If the tool returns a text fallback, relay its exact question and call
+   `set_group_session_sharing` only after an explicit Yes/No. Decline, cancel, or silence leaves that
+   group's state unset; never infer an answer. Saves sync eligible memories to every approved group;
+   Keep private keeps them private for that group; flagged memories remain private.

package/templates/echomem-recall.md

@@ -23,12 +23,12 @@ This project has EchoMem connected — the user's long-term memory across all th
   created by that call. Link each memory key to its canonical
   `https://echoknows.com/memory/<memory-id>` URL. This save receipt is separate from
   `EchoMem sources:` and does not imply that the newly saved memories informed the answer.
-- For a user with a company group, call `get_group_session_sharing` near conversation start or after a
-  qualifying private save. On the first call in a conversation, omit `groupSharingScopeId` so EchoMem
-  mints a fresh opaque scope. Reuse that exact scope only in this conversation for later get/set/save
-  calls, and never persist it as memory. If multiple groups are returned, reuse the same scope and
-  check one `groupId` at a time. Each group requires its own explicit Yes/No decision. Silence leaves
-  that group's state unset; never infer an answer or repeat the prompt in the same response. Store only
-  explicit answers with `set_group_session_sharing`, the same scope, and the selected groupId. Saves
-  sync eligible memories to every approved group; a No keeps them private for that group; flagged
-  memories stay private.
+- For a user with a company group, call `request_group_session_sharing` near conversation start or
+  after a qualifying private save. On the first call in a conversation, omit `groupSharingScopeId` so
+  EchoMem mints a fresh opaque scope. Reuse that exact scope only in this conversation for later
+  get/request/set/save calls, and never persist it as memory. If multiple groups are returned, reuse
+  the same scope and call once per `groupId`. Supported clients render a native Share with team / Keep
+  private choice. If the tool returns a text fallback, relay its exact question and call
+  `set_group_session_sharing` only after an explicit Yes/No. Decline, cancel, or silence leaves that
+  group's state unset; never infer an answer. Saves sync eligible memories to every approved group;
+  Keep private keeps them private for that group; flagged memories stay private.