@echomem/mcp 1.4.41 → 1.4.43

package/dist/index.js

@@ -613,6 +613,8 @@ function toolEventName(canonicalName, status) {
 class EchoMemApiClient {
     store;
     axios;
+    activeToken;
+    accountGeneration = 0;
     boundSourceSession = null;
     requestSourceSession = new AsyncLocalStorage();
     sourceSessionsByCanonicalKey = new Map();
@@ -623,6 +625,7 @@ class EchoMemApiClient {
     deleteConfirmations = new Map();
     constructor(store) {
         this.store = store;
+        this.activeToken = store.getToken();
         this.axios = axios.create({
             baseURL: ECHO_API_BASE_URL.replace(/\/$/, ""),
             headers: {
@@ -632,7 +635,7 @@ class EchoMemApiClient {
         // Read the token fresh on EVERY request (not baked in at construction) so a `login` that runs
         // after the editor already launched the bridge is picked up on the next call — no restart.
         this.axios.interceptors.request.use((config) => {
-            const token = this.store.getToken();
+            const token = this.synchronizeAccountContext();
             if (token)
                 config.headers.set("Authorization", `Bearer ${token}`);
             const sourceSession = this.getBoundSourceSession();
@@ -642,21 +645,46 @@ class EchoMemApiClient {
             return config;
         });
     }
+    /**
+     * Account-scoped state must move atomically with the credential file. The token is intentionally
+     * read fresh, but encryption, identity, source-session, and confirmation caches belong to the
+     * token that populated them and cannot survive an in-process account switch.
+     */
+    synchronizeAccountContext() {
+        const token = this.store.getToken();
+        if (token === this.activeToken)
+            return token;
+        this.activeToken = token;
+        this.accountGeneration += 1;
+        this.encConfigPromise = null;
+        this.whoamiCache = null;
+        this.boundSourceSession = null;
+        this.sourceSessionsByCanonicalKey.clear();
+        this.deleteConfirmations.clear();
+        return token;
+    }
+    /** Lets the MCP server invalidate its account-scoped tool-description caches too. */
+    refreshAccountContext() {
+        this.synchronizeAccountContext();
+        return this.accountGeneration;
+    }
     /** Whether a usable API token currently exists (read fresh from the keystore each call). */
     hasToken() {
-        return !!this.store.getToken();
+        return !!this.synchronizeAccountContext();
     }
     /** The per-process session id — the join key telemetry shares with grouped saves. */
     getSessionId() {
         return this.sessionId;
     }
     getBoundSourceSession() {
+        this.synchronizeAccountContext();
         return this.requestSourceSession.getStore() ?? this.boundSourceSession;
     }
     async withSourceSession(sourceSession, operation) {
         return sourceSession ? this.requestSourceSession.run(sourceSession, operation) : operation();
     }
     async bindSourceSession(verified, persistForBridge = true) {
+        this.synchronizeAccountContext();
         const cached = this.sourceSessionsByCanonicalKey.get(verified.canonicalKey);
         if (cached) {
             if (persistForBridge)
@@ -739,16 +767,23 @@ class EchoMemApiClient {
             return undefined;
         }
     }
-    /** Encryption config for the account, fetched once and cached. Failures are not cached. */
+    /** Encryption config for the current account, cached only for the lifetime of its token. */
     async getEncryptionConfig() {
+        const generation = this.refreshAccountContext();
         if (!this.encConfigPromise) {
-            this.encConfigPromise = fetchEncryptionConfig(this.axios).catch((error) => {
-                this.encConfigPromise = null; // allow retry next call
+            const request = fetchEncryptionConfig(this.axios).catch((error) => {
+                if (this.encConfigPromise === request)
+                    this.encConfigPromise = null; // allow retry next call
                 console.error(`[encryption] config fetch failed: ${describeError(error)} — refusing memory access`);
                 throw new EncryptionStatusUnavailableError("EchoMem could not verify the account encryption state");
             });
+            this.encConfigPromise = request;
         }
-        return this.encConfigPromise;
+        const request = this.encConfigPromise;
+        const config = await request;
+        if (this.refreshAccountContext() !== generation)
+            return this.getEncryptionConfig();
+        return config;
     }
     /**
      * Resolve the encryption state for a read/write. For encrypted accounts this REQUIRES a usable
@@ -756,13 +791,19 @@ class EchoMemApiClient {
      * handing the model ciphertext. For unencrypted accounts it returns `{ enabled: false }`.
      */
     async encState() {
+        const generation = this.refreshAccountContext();
         const cfg = await this.getEncryptionConfig();
+        if (this.refreshAccountContext() !== generation)
+            return this.encState();
         if (!cfg.enabled)
             return { enabled: false };
         const key = this.store.getKey();
         if (!key)
             throw new LockedError("EchoMem vault locked");
-        if (!(await verifyKeyB64(key, cfg))) {
+        const isValid = await verifyKeyB64(key, cfg);
+        if (this.refreshAccountContext() !== generation)
+            return this.encState();
+        if (!isValid) {
             // A file-backed stale key can be removed safely; environment-provided
             // keys remain under the caller's control and are ignored until corrected.
             if (!process.env.ECHO_ENCRYPTION_KEY)
@@ -779,16 +820,23 @@ class EchoMemApiClient {
         }
     }
     async whoami() {
+        const generation = this.refreshAccountContext();
         if (!this.whoamiCache) {
-            this.whoamiCache = this.axios
+            const request = this.axios
                 .get("/api/openclaw/v1/whoami", { timeout: 6000 })
                 .then((response) => response.data)
                 .catch((error) => {
-                this.whoamiCache = null; // don't pin a token-less failure; retry once a token exists
+                if (this.whoamiCache === request)
+                    this.whoamiCache = null;
                 throw error;
             });
+            this.whoamiCache = request;
         }
-        return this.whoamiCache;
+        const request = this.whoamiCache;
+        const identity = await request;
+        if (this.refreshAccountContext() !== generation)
+            return this.whoami();
+        return identity;
     }
     async fetchMemoryById(id, enc) {
         try {
@@ -1096,6 +1144,8 @@ class EchoMemApiClient {
                 kPerUser: parsed.kPerUser,
                 similarityThreshold: parsed.similarityThreshold,
                 timeFrameDays: parsed.timeFrameDays,
+                workspaceId: parsed.workspaceId ?? parsed.groupId,
+                scope: parsed.scope,
                 requestId: this.sessionId,
                 source: "mcp_friend_public_memory_search",
             });
@@ -1108,7 +1158,14 @@ class EchoMemApiClient {
     async getPublicMemory(args) {
         const parsed = publicMemorySchema.parse(args ?? {});
         try {
-            const response = await this.axios.get(`/api/extension/social/public-memories/${encodeURIComponent(parsed.memoryId)}?requestId=${encodeURIComponent(this.sessionId)}&source=mcp_friend_public_memory_fetch`);
+            const workspaceId = parsed.workspaceId ?? parsed.groupId;
+            const query = new URLSearchParams({
+                requestId: this.sessionId,
+                source: "mcp_friend_public_memory_fetch",
+            });
+            if (workspaceId)
+                query.set("workspaceId", workspaceId);
+            const response = await this.axios.get(`/api/extension/social/public-memories/${encodeURIComponent(parsed.memoryId)}?${query.toString()}`);
             return response.data;
         }
         catch (error) {
@@ -1131,9 +1188,13 @@ class EchoMemApiClient {
         }
     }
     async getGroupContext(args) {
-        groupContextSchema.parse(args ?? {});
+        const parsed = groupContextSchema.parse(args ?? {});
         try {
-            const response = await this.axios.get("/api/extension/social/groups/current");
+            const workspaceId = parsed.workspaceId ?? parsed.groupId;
+            const path = workspaceId
+                ? `/api/extension/social/groups/current?workspaceId=${encodeURIComponent(workspaceId)}`
+                : "/api/extension/social/groups/current";
+            const response = await this.axios.get(path);
             return response.data;
         }
         catch (error) {
@@ -1197,6 +1258,7 @@ class EchoMemApiClient {
         const enc = await this.encState();
         try {
             const response = await this.axios.post(`/api/extension/social/groups/current/memories/${encodeURIComponent(parsed.memoryId)}/publish`, {
+                workspaceId: parsed.workspaceId ?? parsed.groupId,
                 acknowledgedFlaggedMemoryIds: parsed.acknowledgedFlaggedMemoryIds,
             }, {
                 headers: enc.enabled && enc.key ? { "X-Encryption-Key": enc.key } : undefined,
@@ -1212,6 +1274,7 @@ class EchoMemApiClient {
         const enc = await this.encState();
         try {
             const response = await this.axios.post("/api/extension/social/groups/current/memories/publish-batch", {
+                workspaceId: parsed.workspaceId ?? parsed.groupId,
                 memoryIds: parsed.memoryIds,
                 contextId: parsed.contextId,
                 selectionReason: parsed.selectionReason,
@@ -1240,6 +1303,7 @@ function capWait(pending) {
 class EchoMemMCPServer {
     server;
     client;
+    accountGeneration = 0;
     mapCache = null;
     groupMapCache = null;
     events;
@@ -1312,8 +1376,19 @@ class EchoMemMCPServer {
             platform_source: hostPlatform,
         };
     }
+    refreshAccountContext() {
+        const generation = this.client.refreshAccountContext();
+        if (generation === this.accountGeneration)
+            return;
+        this.accountGeneration = generation;
+        this.mapCache = null;
+        this.groupMapCache = null;
+        this.mapInjected = false;
+        this.groupMapInjected = false;
+    }
     setupToolHandlers() {
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            this.refreshAccountContext();
             const clientVersion = this.server.getClientVersion();
             this.mcpClientName = clientVersion?.name ?? this.mcpClientName;
             this.mcpClientVersion = clientVersion?.version ?? this.mcpClientVersion;
@@ -1345,6 +1420,7 @@ class EchoMemMCPServer {
             return { tools: listToolSpecs({ map, groupMap, updateNotice }) };
         });
         this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+            this.refreshAccountContext();
             const resolvedCanonicalName = resolveCanonicalToolName(request.params.name);
             const recallRoute = routePersonalRecallInvocation(resolvedCanonicalName, request.params.arguments);
             const canonicalName = recallRoute.canonicalName;
@@ -1995,6 +2071,28 @@ Details: ${m.details || "N/A"}`)
     async handleOthers(args) {
         const parsed = othersSchema.parse(args ?? {});
         const payload = await this.client.searchOthersMemories(args);
+        if (payload?.requiresWorkspaceSelection === true) {
+            const availableWorkspaces = Array.isArray(payload?.availableWorkspaces)
+                ? payload.availableWorkspaces.filter(isRecord)
+                : [];
+            const choices = availableWorkspaces
+                .map((workspace) => `${readString(workspace, "name") ?? "Unnamed workspace"} (${readString(workspace, "id") ?? "unknown id"})`)
+                .join(", ");
+            return {
+                content: [{
+                        type: "text",
+                        text: `You belong to ${availableWorkspaces.length} workspaces: ${choices}. Ask the user which workspace's teammates to search, then call search_others_memories again with workspaceId set to one of those ids. (To search a specific friend instead, pass that person as target.)`,
+                    }],
+            };
+        }
+        if (payload?.groupScopeUnavailable === true) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "You are not in a company workspace, so there are no teammates to search. To search friends instead, call search_others_memories again with scope \"friends\", or pass a specific person as target.",
+                    }],
+            };
+        }
         const memories = payload?.memories ?? [];
         const authenticatedViewer = isRecord(payload?.authenticatedViewer)
             ? payload.authenticatedViewer
@@ -2216,6 +2314,20 @@ Details: ${m.details || "N/A"}`;
     async handleGroupContext(args) {
         groupContextSchema.parse(args ?? {});
         const payload = await this.client.getGroupContext(args);
+        if (payload?.requiresWorkspaceSelection === true) {
+            const availableWorkspaces = Array.isArray(payload?.availableWorkspaces)
+                ? payload.availableWorkspaces.filter(isRecord)
+                : [];
+            const choices = availableWorkspaces
+                .map((workspace) => `${readString(workspace, "name") ?? "Unnamed workspace"} (${readString(workspace, "id") ?? "unknown id"})`)
+                .join(", ");
+            return {
+                content: [{
+                        type: "text",
+                        text: `You belong to ${availableWorkspaces.length} workspaces: ${choices}. Ask the user which workspace to show context for, then call get_group_context again with workspaceId set to one of those ids.`,
+                    }],
+            };
+        }
         const group = isRecord(payload?.group) ? payload.group : null;
         const participants = Array.isArray(payload?.participants)
             ? payload.participants.filter(isRecord)

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

@@ -1090,6 +1090,41 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
       function paidRecallPlan(plan) {
         return ["pro", "power", "team", "enterprise"].indexOf(String(plan || "").toLowerCase()) >= 0;
       }
+      var planQuotaCatalog = null;
+      var planQuotaCatalogLastFetchedAt = 0;
+      function quotaLimitsForPlan(plan) {
+        var normalized = String(plan || "free").toLowerCase();
+        if (normalized === "team") normalized = "pro";
+        if (normalized === "enterprise") normalized = "power";
+        var limits = planQuotaCatalog && planQuotaCatalog[normalized];
+        if (!limits || typeof limits !== "object") return null;
+        if (
+          typeof limits.historicalConversationLimit !== "number" ||
+          typeof limits.memoryProcessingInputTokensWeeklyLimit !== "number" ||
+          typeof limits.memorySearchWeeklyLimit !== "number"
+        ) return null;
+        return limits;
+      }
+      function quotaNumber(value) {
+        return number(Math.max(0, Math.floor(value)));
+      }
+      function quotaTokens(value) {
+        var normalized = Math.max(0, Math.floor(value));
+        if (normalized > 0 && normalized % 1000000 === 0) return String(normalized / 1000000) + "M";
+        return normalized > 0 && normalized % 1000 === 0 ? String(normalized / 1000) + "K" : quotaNumber(normalized);
+      }
+      async function refreshPlanQuotaCatalog() {
+        if (Date.now() - planQuotaCatalogLastFetchedAt < 60000) return;
+        try {
+          var response = await fetch("https://echo-mem-chrome.vercel.app/api/public/plan-quotas", { cache: "no-store" });
+          var payload = response.ok ? await response.json() : null;
+          if (!payload || !payload.plans || typeof payload.plans !== "object") return;
+          planQuotaCatalog = payload.plans;
+          planQuotaCatalogLastFetchedAt = Date.now();
+        } catch (_) {
+          // Generic labels remain visible until the managed catalog is available.
+        }
+      }
       function setupPlanPrice(plan) {
         return plan === "power" ? "$100" : "$20";
       }
@@ -1151,7 +1186,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
         var statusLabel = canceled ? "Canceled" : (state === "trialing" ? "Trial active" : "Active");
         var lifecycle = paidPlanLifecycleText(plan);
         var quota = billingStatus && billingStatus.historicalConversationQuota;
-        var limit = quota && typeof quota.limit === "number" ? quota.limit : (plan === "power" ? 2000 : 500);
+        var limit = quota && typeof quota.limit === "number" ? quota.limit : null;
         var moneyFact = canceled
           ? "No future charge"
           : (state === "trialing" ? setupPlanPrice(plan) + "/month after trial" : setupPlanPrice(plan) + "/month");
@@ -1160,7 +1195,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
           '<section class="billingCommitment' + (canceled ? ' is-canceled' : '') + '" aria-label="Current plan commitment">' +
             '<div class="billingCommitmentIdentity"><span>' + esc(statusLabel) + '</span><strong>' + esc(planLabel) + '</strong></div>' +
             '<div class="billingCommitmentFacts">' +
-              '<span><b>' + esc(number(limit)) + '</b> coding-session imports</span>' +
+              '<span><b>' + esc(limit === null ? "Plan import allowance" : quotaNumber(limit)) + '</b>' + (limit === null ? "" : " coding-session imports") + '</span>' +
               '<span><b>' + esc(moneyFact) + '</b></span>' +
             '</div>' +
             '<p>' + esc(lifecycle || "Your paid plan is active.") + '</p>' +
@@ -1171,6 +1206,14 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
       }
       function setupPlanDefinition(plan) {
         var trialAvailable = !billingStatus || billingStatus.trialAvailable !== false;
+        var limits = quotaLimitsForPlan(plan);
+        var features = limits
+          ? [
+              quotaNumber(limits.historicalConversationLimit) + " past chats",
+              quotaTokens(limits.memoryProcessingInputTokensWeeklyLimit) + " new-chat tokens / week",
+              quotaNumber(limits.memorySearchWeeklyLimit) + " memory recalls / week"
+            ]
+          : ["Past-chat imports", "Weekly new-chat processing", "Weekly memory recalls"];
         if (plan === "power") return {
           id: "power",
           name: "Power",
@@ -1180,11 +1223,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
           cadence: trialAvailable ? "per month · 14-day trial" : "per month · billed immediately",
           sticker: "/hud-assets/echo-pricing-power-sticker.png",
           stickerAlt: "Power Echo arrives with a gold key and a crew of notebook helpers.",
-          features: [
-            "2,000 past chats",
-            "agent-heavy memory",
-            "2,000 memory recalls / week"
-          ]
+          features: features
         };
         if (plan === "pro") return {
           id: "pro",
@@ -1196,11 +1235,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
           sticker: "/hud-assets/echo-pricing-pro-sticker.png",
           stickerAlt: "Pro Echo organizes tabbed notebooks and a daily refresh control.",
           popular: true,
-          features: [
-            "500 past chats",
-            "daily memory updates",
-            "500 memory recalls / week"
-          ]
+          features: features
         };
         return {
           id: "free",
@@ -1211,7 +1246,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
           cadence: "free forever · no card needed",
           sticker: "/hud-assets/echo-pricing-free-sticker.png",
           stickerAlt: "Original Echo hugs one simple memory card.",
-          features: ["100 coding sessions", "a few new sessions / week", "100 memory recalls / week"]
+          features: features
         };
       }
       function renderPlanHabitat() {
@@ -1333,7 +1368,11 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
         if (setupPlanChoice === "free") {
           if (readySettings) readySettings.classList.remove("is-plan-open", "is-checkout-pending");
           if (planGateDecision) planGateDecision.classList.remove("is-checkout-pending");
-          slot.innerHTML = '<div class="setupPlanConfirmed"><span class="setupPlanConfirmedIcon" aria-hidden="true">' + setupIcon("check") + '</span><span class="setupPlanConfirmedCopy"><strong>Original Echo</strong><span>100 coding sessions and 100 memory recalls each week.</span></span><button type="button" class="textButton" id="changeSetupPlan">Change</button></div>';
+          var freeLimits = quotaLimitsForPlan("free");
+          var freePlanCopy = freeLimits
+            ? quotaNumber(freeLimits.historicalConversationLimit) + " coding sessions and " + quotaNumber(freeLimits.memorySearchWeeklyLimit) + " memory recalls each week."
+            : "Your managed import and weekly memory allowances are ready.";
+          slot.innerHTML = '<div class="setupPlanConfirmed"><span class="setupPlanConfirmedIcon" aria-hidden="true">' + setupIcon("check") + '</span><span class="setupPlanConfirmedCopy"><strong>Original Echo</strong><span>' + esc(freePlanCopy) + '</span></span><button type="button" class="textButton" id="changeSetupPlan">Change</button></div>';
           renderBillingCommitment("");
           var changeBtn = document.getElementById("changeSetupPlan");
           if (changeBtn) changeBtn.onclick = function () {
@@ -1434,6 +1473,7 @@ export const SETUP_PAGE_CLIENT_EXTRACTION = String.raw `      /* ---------- dash
           var nextBillingStatus = await getJson("/billing-status");
           if (billingEpoch !== accountStateEpoch || !connected) return;
           billingStatus = nextBillingStatus;
+          await refreshPlanQuotaCatalog();
           billingLastCheckedAt = Date.now();
           billingCheckMessage = "";
           if (readyStage === "sessions" && setupPlanConfirmed()) {

package/dist/setup.js

@@ -309,12 +309,51 @@ export function codexTomlBlock(entry) {
     const args = (Array.isArray(entry.args) ? entry.args : []).map((a) => JSON.stringify(String(a))).join(", ");
     return `[mcp_servers.echomem]\ncommand = ${command}\nargs = [${args}]\n`;
 }
-/**
- * Write/merge the EchoMem entry straight into Codex's config.toml — no `codex` CLI needed. Idempotent.
- * If an `[mcp_servers.echomem]` block already exists it is REPLACED (so re-running `setup` upgrades a
- * stale `npx -y` entry to the direct path); identical entries are left untouched.
- */
-export function writeCodexConfig(configPath, entry) {
+function objectRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function validDesktopManagedEntry(value) {
+    const entry = objectRecord(value);
+    const environment = objectRecord(entry?.env);
+    if (!entry || environment?.ECHO_DESKTOP_MANAGED !== "1")
+        return false;
+    const command = entry.command;
+    const args = Array.isArray(entry.args) ? entry.args : [];
+    return typeof command === "string"
+        && fs.existsSync(command)
+        && typeof args[0] === "string"
+        && fs.existsSync(args[0]);
+}
+function codexEntryFromBlock(lines, start, end) {
+    let command;
+    let args = [];
+    let desktopManaged = false;
+    for (const line of lines.slice(start + 1, end)) {
+        const commandMatch = line.match(/^\s*command\s*=\s*(.+?)\s*$/);
+        const argsMatch = line.match(/^\s*args\s*=\s*(.+?)\s*$/);
+        try {
+            if (commandMatch)
+                command = JSON.parse(commandMatch[1]);
+            if (argsMatch)
+                args = JSON.parse(argsMatch[1]);
+        }
+        catch {
+            return undefined;
+        }
+        if (/ECHO_DESKTOP_MANAGED\s*=\s*["']1["']/.test(line))
+            desktopManaged = true;
+    }
+    if (typeof command !== "string")
+        return undefined;
+    return {
+        command,
+        args: Array.isArray(args) ? args : [],
+        ...(desktopManaged ? { env: { ECHO_DESKTOP_MANAGED: "1" } } : {}),
+    };
+}
+export function writeCodexConfig(configPath, entry, options = {}) {
     let content = "";
     try {
         content = fs.readFileSync(configPath, "utf8");
@@ -331,6 +370,9 @@ export function writeCodexConfig(configPath, entry) {
         let end = start + 1;
         while (end < lines.length && !/^\s*\[/.test(lines[end]))
             end++;
+        if (!options.forceHeadless && validDesktopManagedEntry(codexEntryFromBlock(lines, start, end))) {
+            return "desktop-managed";
+        }
         if (lines.slice(start, end).join("\n").trimEnd() === block)
             return "exists"; // already correct
         const next = [...lines.slice(0, start), ...block.split("\n"), ...lines.slice(end)];
@@ -403,7 +445,7 @@ export function writeAgentsMemoryGuidance(filePath) {
     return "wrote";
 }
 /** Merge the EchoMem entry into a JSON client's `mcpServers` map without clobbering siblings. */
-export function writeJsonClientConfig(configPath, entry) {
+export function writeJsonClientConfig(configPath, entry, options = {}) {
     let config = {};
     try {
         config = JSON.parse(fs.readFileSync(configPath, "utf8"));
@@ -412,17 +454,74 @@ export function writeJsonClientConfig(configPath, entry) {
         /* fresh config */
     }
     config.mcpServers = config.mcpServers || {};
+    if (!options.forceHeadless && validDesktopManagedEntry(config.mcpServers.echomem)) {
+        return "desktop-managed";
+    }
     config.mcpServers.echomem = entry;
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    return "wrote";
+}
+function readClaudeCodeConfigFile(configPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function echoMemEntryFromServers(value) {
+    return objectRecord(objectRecord(value)?.echomem);
+}
+function claudeEntriesMatch(actual, expected) {
+    if (!actual || actual.command !== expected.command)
+        return false;
+    const actualArgs = Array.isArray(actual.args) ? actual.args : [];
+    const expectedArgs = Array.isArray(expected.args) ? expected.args : [];
+    if (actualArgs.length !== expectedArgs.length || actualArgs.some((value, index) => value !== expectedArgs[index])) {
+        return false;
+    }
+    const expectedEnv = expected.env;
+    if (!expectedEnv || typeof expectedEnv !== "object" || Array.isArray(expectedEnv))
+        return true;
+    const actualEnv = actual.env;
+    if (!actualEnv || typeof actualEnv !== "object" || Array.isArray(actualEnv))
+        return false;
+    return Object.entries(expectedEnv).every(([key, value]) => actualEnv[key] === value);
+}
+function claudeCodeLocalEchoMemProjects(configPath) {
+    const projects = readClaudeCodeConfigFile(configPath).projects;
+    if (!projects || typeof projects !== "object" || Array.isArray(projects))
+        return [];
+    return Object.entries(projects)
+        .filter(([, value]) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return false;
+        return Boolean(echoMemEntryFromServers(value.mcpServers));
+    })
+        .map(([projectPath]) => projectPath)
+        .sort();
 }
-export function writeClaudeCodeConfig(entry) {
-    // EchoMem is a memory server that should load in EVERY Claude Code project, so it belongs at
-    // `user` scope (~/.claude.json, all projects) rather than `local` scope (the current project only).
-    const addArguments = ["mcp", "add-json", "-s", "user", "echomem", JSON.stringify(entry)];
-    const removeFromScope = (scope) => {
+export function writeClaudeCodeConfig(entry, options = {}) {
+    // EchoMem belongs at user scope so every Claude Code project resolves the same durable runtime.
+    // Older CLI versions wrote local/project entries, which take precedence over user scope and can
+    // keep launching a deleted npm cache or stale runtime. Migrate those only after user scope is safe.
+    const configPath = options.configPath ?? home(".claude.json");
+    const emptyResult = () => ({
+        state: "unavailable",
+        removedLocalProjects: [],
+        skippedLocalProjects: [],
+        failedLocalProjects: [],
+        restoredPreviousUserEntry: false,
+        preservedDesktopManaged: false,
+    });
+    const runClaude = (args, cwd) => {
         try {
-            execFileSync("claude", ["mcp", "remove", "echomem", "-s", scope], {
+            execFileSync("claude", args, {
+                cwd,
                 encoding: "utf8",
                 stdio: ["ignore", "pipe", "pipe"],
                 timeout: 10000,
@@ -433,39 +532,65 @@ export function writeClaudeCodeConfig(entry) {
             return false;
         }
     };
-    // Older builds installed EchoMem at `local` scope. Left in place it would shadow the user-scoped
-    // entry and keep launching the stale command, so drop it first. Best-effort: `local` is per-project,
-    // so this only clears the directory setup runs from — a no-op (ignored) when nothing is there.
-    removeFromScope("local");
-    try {
-        execFileSync("claude", addArguments, {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "pipe"],
-            timeout: 10000,
-        });
-        return "wrote";
-    }
-    catch (error) {
-        const stderr = error.stderr;
-        const detail = Buffer.isBuffer(stderr) ? stderr.toString("utf8") : String(stderr ?? "");
-        if (!detail.includes("already exists"))
-            return "unavailable";
-    }
-    // Claude Code's CLI will not replace a same-name server. Once the replacement entry is fully
-    // constructed, remove only EchoMem and immediately re-add it; sibling MCP servers remain.
-    try {
-        if (!removeFromScope("user"))
-            return "unavailable";
-        execFileSync("claude", addArguments, {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "pipe"],
-            timeout: 10000,
-        });
-        return "wrote";
+    const addUser = (value) => runClaude([
+        "mcp", "add-json", "-s", "user", "echomem", JSON.stringify(value),
+    ]);
+    const removeUser = () => runClaude(["mcp", "remove", "echomem", "-s", "user"]);
+    const before = readClaudeCodeConfigFile(configPath);
+    const previousUserEntry = echoMemEntryFromServers(before.mcpServers);
+    const preservedDesktopManaged = !options.forceHeadless
+        && validDesktopManagedEntry(previousUserEntry);
+    const desiredUserEntry = preservedDesktopManaged ? previousUserEntry : entry;
+    let restoredPreviousUserEntry = false;
+    // Avoid interrupting active/new sessions when the correct global entry is already installed.
+    if (!claudeEntriesMatch(previousUserEntry, desiredUserEntry)) {
+        if (previousUserEntry && !removeUser())
+            return emptyResult();
+        if (!addUser(desiredUserEntry)) {
+            if (previousUserEntry)
+                restoredPreviousUserEntry = addUser(previousUserEntry);
+            return { ...emptyResult(), restoredPreviousUserEntry };
+        }
     }
-    catch {
-        return "unavailable";
+    const installedUserEntry = echoMemEntryFromServers(readClaudeCodeConfigFile(configPath).mcpServers);
+    if (!claudeEntriesMatch(installedUserEntry, desiredUserEntry)) {
+        return { ...emptyResult(), restoredPreviousUserEntry, preservedDesktopManaged };
+    }
+    const removedLocalProjects = [];
+    const skippedLocalProjects = [];
+    const failedLocalProjects = [];
+    for (const projectPath of claudeCodeLocalEchoMemProjects(configPath)) {
+        // A deleted directory cannot currently shadow user scope. Do not recreate it or hand-edit
+        // ~/.claude.json, which also contains Claude account/session state.
+        if (!fs.existsSync(projectPath)) {
+            skippedLocalProjects.push(projectPath);
+            continue;
+        }
+        let projectCwd = projectPath;
+        try {
+            projectCwd = fs.realpathSync(projectPath);
+        }
+        catch {
+            /* The existence check above already established the safe fallback path. */
+        }
+        if (runClaude(["mcp", "remove", "echomem", "-s", "local"], projectCwd)) {
+            removedLocalProjects.push(projectPath);
+        }
+        else {
+            failedLocalProjects.push(projectPath);
+        }
     }
+    const remainingActiveProjects = claudeCodeLocalEchoMemProjects(configPath)
+        .filter((projectPath) => fs.existsSync(projectPath));
+    const unresolved = [...new Set([...failedLocalProjects, ...remainingActiveProjects])].sort();
+    return {
+        state: unresolved.length > 0 ? "needs-repair" : "wrote",
+        removedLocalProjects,
+        skippedLocalProjects,
+        failedLocalProjects: unresolved,
+        restoredPreviousUserEntry,
+        preservedDesktopManaged,
+    };
 }
 function readJsonClientEntry(configPath) {
     try {
@@ -2668,6 +2793,9 @@ async function cmdSetup(flags) {
     const entry = buildServerEntry({ devEntryPath: typeof flags.dev === "string" ? flags.dev : undefined });
     const requested = typeof flags.client === "string" ? flags.client : undefined;
     const targets = selectSetupTargets(requested, Boolean(flags.all));
+    // --dev is already an explicit request to replace the managed runtime with a checkout.
+    const forceHeadless = flags["force-headless"] === true || typeof flags.dev === "string";
+    const configurationFailures = [];
     if (targets.length === 0) {
         console.log("No client auto-detected. Add this MCP server entry manually:\n");
         console.log(JSON.stringify({ echomem: entry }, null, 2));
@@ -2676,27 +2804,57 @@ async function cmdSetup(flags) {
     else {
         for (const c of targets) {
             if (c.kind === "json") {
-                writeJsonClientConfig(c.configPath, entry);
-                console.log(`✅ Wrote EchoMem MCP entry to ${c.label}: ${c.configPath}`);
+                const result = writeJsonClientConfig(c.configPath, entry, { forceHeadless });
+                if (result === "desktop-managed") {
+                    console.log(`✅ Kept the valid Echo Desktop-managed EchoMem entry for ${c.label}: ${c.configPath}`);
+                }
+                else {
+                    console.log(`✅ Wrote EchoMem MCP entry to ${c.label}: ${c.configPath}`);
+                }
             }
             else if (c.kind === "command") {
-                const result = writeCodexConfig(c.configPath, entry);
+                const result = writeCodexConfig(c.configPath, entry, { forceHeadless });
                 if (result === "wrote")
                     console.log(`✅ Wrote EchoMem MCP entry to ${c.label}: ${c.configPath} — start a new Codex session to load it.`);
+                else if (result === "desktop-managed")
+                    console.log(`✅ Kept the valid Echo Desktop-managed EchoMem entry for ${c.label}: ${c.configPath}`);
                 else
                     console.log(`✅ ${c.label} already has the EchoMem MCP entry: ${c.configPath}`);
             }
             else {
-                const result = c.id === "claude-code" ? writeClaudeCodeConfig(entry) : "unavailable";
-                if (result === "wrote") {
-                    console.log(`✅ Wrote EchoMem MCP entry to ${c.label} via \`claude mcp add-json\` — start a new Claude Code session to load it.`);
+                const result = c.id === "claude-code"
+                    ? writeClaudeCodeConfig(entry, { forceHeadless })
+                    : "unavailable";
+                if (result !== "unavailable" && result.state === "wrote") {
+                    if (result.preservedDesktopManaged) {
+                        console.log(`✅ Kept the valid Echo Desktop-managed EchoMem user entry for ${c.label}.`);
+                    }
+                    else {
+                        console.log(`✅ Wrote EchoMem MCP entry to ${c.label} via \`claude mcp add-json\` — start a new Claude Code session to load it.`);
+                    }
+                    if (result.removedLocalProjects.length > 0) {
+                        console.log(`✅ Removed ${result.removedLocalProjects.length} stale Claude Code project-local EchoMem ${result.removedLocalProjects.length === 1 ? "entry" : "entries"}.`);
+                    }
+                    if (result.skippedLocalProjects.length > 0) {
+                        console.log(`ℹ️  Ignored ${result.skippedLocalProjects.length} EchoMem local ${result.skippedLocalProjects.length === 1 ? "entry" : "entries"} for deleted project directories; they cannot shadow the user entry.`);
+                    }
                 }
                 else {
-                    console.log(`ℹ️  ${c.label}: ${c.note}\n   entry: ${JSON.stringify(entry)}`);
+                    const failedProjects = result === "unavailable" ? [] : result.failedLocalProjects;
+                    configurationFailures.push(failedProjects.length > 0
+                        ? `${c.label} still has project-local EchoMem overrides in: ${failedProjects.join(", ")}`
+                        : `${c.label} user-scoped EchoMem entry could not be verified`);
                 }
             }
         }
     }
+    if (configurationFailures.length > 0) {
+        throw new Error([
+            "EchoMem MCP configuration is incomplete; onboarding was stopped before login/import.",
+            ...configurationFailures.map((failure) => `- ${failure}`),
+            `Retry with: ${MCP_UPDATE_COMMAND} --client claude-code`,
+        ].join("\n"));
+    }
     if (!flags["no-agents-md"]) {
         writeMemoryGuidanceForTargets(targets);
     }
@@ -3788,6 +3946,7 @@ Usage:
   echomem-mcp                       Run the MCP server (stdio; default — used by your editor)
   echomem-mcp setup [--client X]    Detect editor, write its MCP config, then connect this device
   echomem-mcp setup --skip-login    Write MCP config without opening login/browser
+  echomem-mcp setup --force-headless  Explicitly replace valid Echo Desktop-managed entries
   echomem-mcp setup --no-codex-skills  Skip installing the bundled EchoMem Codex skills
   echomem-mcp update --all          Install this bridge durably + repoint detected clients; no login/browser
   echomem-mcp update --client X     Repoint one MCP client; no login/browser

package/dist/v1-contract.js

@@ -165,6 +165,42 @@ const triggerMetadataSchema = {
     triggerMessage: z.string().optional(),
     triggerMessageRole: z.string().optional(),
 };
+// Canonical workspace selector for tools that act inside a company workspace.
+// `workspaceId` is the current name; `groupId` is the legacy alias kept working
+// so existing prompts keep functioning. Handlers normalize with
+// normalizeWorkspaceId (workspaceId ?? groupId). Required only when the user
+// belongs to more than one workspace; a single-workspace user may omit it.
+const WORKSPACE_SELECTOR_DESCRIPTION = "Workspace to act in. Required when the user belongs to more than one workspace; omit it when they have a single workspace. If omitted with multiple workspaces, the tool returns the available workspaces so you can ask the user which to use.";
+const workspaceSelectorSchema = {
+    workspaceId: z.string().uuid().optional().describe(WORKSPACE_SELECTOR_DESCRIPTION),
+    groupId: z.string().uuid().optional().describe("Legacy alias for workspaceId."),
+};
+// The advertised JSON-Schema counterpart of workspaceSelectorSchema. Tool
+// inputSchemas are hand-written, so the selector must be injected into every
+// workspace-scoped tool's properties or clients never learn they can pass it.
+const workspaceSelectorProperties = {
+    workspaceId: { type: "string", description: WORKSPACE_SELECTOR_DESCRIPTION },
+    groupId: { type: "string", description: "Legacy alias for workspaceId." },
+};
+const WORKSPACE_SCOPED_TOOL_NAMES = new Set([
+    canonicalToolNames.others,
+    canonicalToolNames.publicMemory,
+    canonicalToolNames.groupContext,
+    canonicalToolNames.createGroupInvite,
+    canonicalToolNames.prepareGroupPublication,
+    canonicalToolNames.updateGroupProfile,
+    canonicalToolNames.publishToGroup,
+    canonicalToolNames.publishBatchToGroup,
+]);
+function injectWorkspaceSelector(specs) {
+    for (const spec of specs) {
+        if (!WORKSPACE_SCOPED_TOOL_NAMES.has(spec.name))
+            continue;
+        const existing = spec.inputSchema.properties ?? {};
+        spec.inputSchema.properties = { ...workspaceSelectorProperties, ...existing };
+    }
+    return specs;
+}
 export const searchMemoriesSchema = z.object({
     ...triggerMetadataSchema,
     query: z.string().trim().min(1).optional(),
@@ -235,6 +271,8 @@ export const sendFriendRequestSchema = z.object({
 });
 export const othersSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
+    scope: z.enum(["group", "friends"]).optional(),
     query: z.string().trim().optional().default(""),
     limit: z.number().int().min(1).max(50).optional().default(10),
     target: z.string().optional(),
@@ -249,6 +287,7 @@ export const othersSchema = z.object({
 });
 export const publicMemorySchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
     memoryId: z.string().min(1),
 });
 export const recordMemoryCitationsSchema = z.object({
@@ -258,6 +297,7 @@ export const recordMemoryCitationsSchema = z.object({
 });
 export const groupContextSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
 });
 export const getGroupSessionSharingSchema = z.object({
     ...triggerMetadataSchema,
@@ -282,6 +322,7 @@ export const createGroupSchema = z.object({
 });
 export const createGroupInviteSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
     expiresInDays: z.number().int().min(1).max(30).optional(),
     maxUses: z.number().int().min(1).max(100).optional(),
 });
@@ -294,6 +335,7 @@ export const joinGroupSchema = z.object({
 });
 export const prepareGroupPublicationSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
     scope: z.enum(["bootstrap", "since_last_scan", "context", "time_range"]).default("since_last_scan"),
     contextId: z.string().min(1).optional(),
     startAt: z.string().optional(),
@@ -310,6 +352,7 @@ export const flagPublicationAttentionSchema = z.object({
 });
 export const updateGroupProfileSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
     displayName: z.string().min(1).max(120).optional(),
     title: z.string().min(1).max(160),
     responsibilitySummary: z.string().min(1).max(1000),
@@ -325,11 +368,13 @@ export const completeGroupPublicationSchema = z.object({
 });
 export const publishToGroupSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
     memoryId: z.string().min(1),
     acknowledgedFlaggedMemoryIds: z.array(z.string().min(1)).max(1).optional(),
 });
 export const publishBatchToGroupSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
     memoryIds: z.array(z.string().min(1)).min(1).max(50),
     contextId: z.string().min(1).optional(),
     selectionReason: z.string().max(500).optional(),
@@ -573,10 +618,15 @@ export function listToolSpecs(opts = {}) {
         {
             name: canonicalToolNames.others,
             title: "Search teammates' and friends' memories",
-            description: `PEER-MEMORY SEARCH for public memories owned by accepted friends or company-group members—not the user's own memories. Pass query for a topic; omit it only when intentionally browsing peer memories, and optionally use target to scope a person. Do not use this tool for the user's private memories or the EchoMem user directory. EchoMem identifies the caller from the EchoMem credential and has already excluded only that authenticated user's own memories. Present every returned owner; never filter again using a Claude account, host profile, git identity, or inference. For onboarding and division-of-work questions, call get_group_context first. Returned memories are recorded in memory_views for the owners. ${memoryCitationInstruction}${groupMapSection}`,
+            description: `PEER-MEMORY SEARCH for public memories owned by accepted friends or company-group members—not the user's own memories. Pass query for a topic. Set scope to pick the audience — 'group' (only workspace teammates) or 'friends' (only friends) — or target for one person; scope defaults to teammates. Do not use this tool for the user's private memories or the EchoMem user directory. EchoMem identifies the caller from the EchoMem credential and has already excluded only that authenticated user's own memories. Present every returned owner; never filter again using a Claude account, host profile, git identity, or inference. For onboarding and division-of-work questions, call get_group_context first. Returned memories are recorded in memory_views for the owners. ${memoryCitationInstruction}${groupMapSection}`,
             inputSchema: {
                 type: "object",
                 properties: {
+                    scope: {
+                        type: "string",
+                        enum: ["group", "friends"],
+                        description: "Audience to search. 'group' = only the named workspace's teammates (you'll be asked which if the user is in several and names none). 'friends' = only accepted friends. For one specific person, omit scope and pass target instead. Omitting scope defaults to the group/teammates audience.",
+                    },
                     query: {
                         type: "string",
                         description: "Optional peer-memory topic. Omit only for an intentional broad browse; never send this field as conversation.",
@@ -584,7 +634,7 @@ export function listToolSpecs(opts = {}) {
                     limit: { type: "integer", minimum: 1, maximum: 50, default: 10 },
                     target: {
                         type: "string",
-                        description: "Accessible friend or group-member user id or exact display name. Prefer this for @Name asks.",
+                        description: "Accessible friend or group-member user id or exact display name. Prefer this for @Name asks or a single specific person.",
                     },
                     ownerUserId: {
                         type: "string",
@@ -1021,5 +1071,5 @@ export function listToolSpecs(opts = {}) {
             },
         },
     ];
-    return tools.map(decorateLocalToolSpec);
+    return injectWorkspaceSelector(tools).map(decorateLocalToolSpec);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.41",
+  "version": "1.4.43",
   "description": "EchoMem MCP bridge: cloud-first memory tools and the Agent Doctor workspace forensics report (cost ledger + 3D repo city)",
   "main": "dist/index.js",
   "type": "module",
@@ -33,7 +33,7 @@
     "test:ui": "npm run build && node test/setup-ui.test.mjs",
     "test:onboarding-resilience": "npm run build && node test/onboarding-resilience.test.mjs",
     "test:billing-ui": "npm run build && node test/setup-ui.test.mjs billing",
-    "test": "npm run build && node test/source-session.test.mjs && node test/source-session-hook.test.mjs && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/onboarding-resilience.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/headless-runtime.test.mjs && node test/claude-code-config.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/save-checkpoint-hook.test.mjs",
+    "test": "npm run build && node test/source-session.test.mjs && node test/source-session-hook.test.mjs && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/onboarding-resilience.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/workspace-selector.test.mjs && node test/group-map.test.mjs && node test/update-check.test.mjs && node test/headless-runtime.test.mjs && node test/claude-code-config.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/save-checkpoint-hook.test.mjs",
     "prepack": "npm run build && node scripts/bundle-city.mjs"
   },
   "dependencies": {