@echomem/mcp 1.4.34 → 1.4.36

package/README.md

@@ -37,38 +37,26 @@ legacy EchoMem-synthesized recall answer.
 
 ## Quick start (recommended)
 
-```bash
-# One command, everything: download the bridge + HUD, configure every coding agent you have
-# installed (Codex, Claude Code, Claude Desktop, Cursor, Windsurf…), log in, and launch the HUD.
-npm i -g @echomem/mcp@latest && echomem-mcp init
-```
+Install Echo Desktop, sign in once, then open **Connect MCP** and choose **Connect Echo**. The app
+ships and installs the MCP runtime, configures the detected Codex and Claude hosts, mirrors the same
+device credential used by the desktop app, and verifies the MCP handshake. No terminal login is
+required.
+
+The standalone HUD has been retired; Echo Desktop is the persistent setup and status surface. The
+bridge still reads local agent logs for on-demand context-health tools, but it no longer publishes or
+auto-launches an Electron overlay.
 
-A global install (not `npx`) is recommended because it wires each editor to a **stable** path: a bare
-`npx` run resolves the bridge into a throwaway `_npx/<hash>` cache dir that npm later garbage-collects,
-which would break the MCP server after the fact (`setup` now refuses to pin such a path and falls back
-to the global install, but installing globally avoids the issue entirely). The context HUD's
-launch-at-login also runs from the installed path. `init` is the flagship one-liner — it wraps `setup --all --with-hud`: it writes each
-installed agent's MCP config (with **no secret** in it — credentials live in
-`~/.echomem/credentials.json`, mode 0600), adds the EchoMem memory guidance to their global
-`AGENTS.md` / `CLAUDE.md`, installs first-party `echomem-search`, `echomem-save`,
-`echomem-forget`, and `echomem-login` skills for Codex, opens the browser to approve the device
-(and unlock the vault for encrypted accounts), then launches the context HUD. EchoMem updates only
-its own skill folders; other memory-provider skills are detected and reported but never modified.
-Reload your editors and you're done.
-
-Prefer to keep it minimal? `echomem-mcp setup` configures only the auto-detected editor and skips the
-HUD; the granular commands below still work.
+For headless systems and development, the granular CLI commands remain available:
 
 | Command | What it does |
 |---|---|
-| `npm i -g @echomem/mcp@latest && echomem-mcp init` | **Everything in one command** — all installed agents + HUD + login |
+| `npm i -g @echomem/mcp@latest && echomem-mcp init` | Legacy/headless setup for installed agents + login |
 | `npm i -g @echomem/mcp@latest && echomem-mcp setup` | Install the CLI globally and configure just the detected editor |
 | `npx -y @echomem/mcp@latest setup` | One-off setup without keeping a global CLI command |
 | `echomem-mcp setup [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex]` | Write client config + log in |
 | `echomem-mcp setup --skip-login [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex]` | Write client config without opening the browser or changing credentials |
 | `npx -y @echomem/mcp@latest update --all` | One-shot update: install the latest bridge durably and repoint detected client configs, with no browser login |
 | `npx -y @echomem/mcp@latest update --client codex` | Update one client only |
-| `echomem-mcp setup --with-hud [--client codex]` | Write client config + log in + launch the EchoMem context HUD |
 | `echomem-mcp login` | Approve device in browser (or use `--token` / `--passphrase`) |
 | `echomem-mcp unlock` | Privately unlock the vault on this trusted device |
 | `echomem-mcp lock` | Remove the local vault key while keeping the device login |
@@ -82,29 +70,8 @@ checks npm for a newer published bridge using a cached, non-blocking check. Agen
 `npx -y @echomem/mcp@latest update --all` if the user agrees. The bridge does not auto-update on
 every MCP startup.
 
-## EchoMem Context HUD
-
-The package also ships `echomem-hud`, a local context-health sidecar for Codex and Claude. It reads
-local agent logs, computes a tracked lower-bound "clean vs dirty" context score, and renders a small
-HUD without adding tokens to the agent conversation.
-
-```bash
-echomem-hud app                 # Electron floating HUD
-echomem-hud serve               # Browser fallback at http://127.0.0.1:17377
-echomem-hud summary --json      # Machine-readable current score
-echomem-hud status              # Show detected Codex/Claude sources
-```
-
-Supported local sources:
-- Codex: `~/.codex/sessions/**/rollout-*.jsonl`
-- Claude Code: `~/.claude/echo-ctx/*.json` first, then local transcripts when present
-- Claude desktop agent/Cowork: local agent-mode transcripts under Application Support
-
-The v1 metric counts `range_redundant` reads only and reports pollution as `tracked dead-weight ≥`
-because exact context composition and provider eviction are not observable.
-
-MCP fallback: agents can call `echo_context_health` to get the same score as markdown in-chat. This
-is on-demand; the passive HUD remains a separate local process.
+Agents can still call `echo_context_health` for an on-demand local context-health report. It reads
+the local Codex/Claude logs and does not require a separate process or desktop overlay.
 
 ## Agent Doctor — local workspace forensics (new in 1.4.9)
 

package/dist/codex-sync.js

@@ -132,7 +132,7 @@ function summarizeToolArgs(toolName, args) {
             tag_count: Array.isArray(args.tags) ? args.tags.length : undefined,
         };
     }
-    if (toolName === "get_memories_by_time_range" || toolName === "search_memories_by_time_range") {
+    if (toolName === "get_memories_by_time_range") {
         return {
             has_start_date: !!asString(args.startDate),
             has_end_date: !!asString(args.endDate),

package/dist/context-analysis/claude-native-canonical.js

@@ -7,6 +7,14 @@ import { walk } from "../report.js";
 import { isStrongPositiveFeedback, } from "./workspace-report.js";
 const OUTPUT_TOKEN_CAP = 12_000;
 const IMAGE_TOKENS = 4_000;
+// Request-by-request retained-context scoring grows faster than the raw JSONL. Keep onboarding
+// predictable by analyzing a deterministic head/middle/tail sample from oversized sessions. The
+// source transcript is untouched and remains available to the separate import pipeline.
+const CLAUDE_MAX_TURNS_PER_SESSION = 1_000;
+const CLAUDE_HEAD_TURNS = 200;
+const CLAUDE_TAIL_TURNS = 500;
+const CLAUDE_MIDDLE_WINDOWS = 3;
+const CLAUDE_MIDDLE_WINDOW_TURNS = 100;
 const PROBLEM_META = {
     P01: { label: "Outdated Images & Screenshots", bucket: "dead", category: "Runtime Bug", confidence: "high" },
     P02: { label: "Ignored User Instructions", bucket: "refind", category: "Model Behavior", confidence: "medium" },
@@ -350,26 +358,31 @@ function resultItem(args) {
 }
 function scoreClaudeNativeSession(parsed) {
     classifyItems(parsed.items);
-    const requestRows = [];
+    const terminalRequestByTurn = new Map();
     for (const request of parsed.requests) {
         const rawBuckets = { keep_oh: 0, keep_prod: 0, opt_dup: 0, opt_refind: 0, opt_dead: 0 };
         const buckets = { duplicate: 0, refind: 0, dead: 0, unattributed: 0 };
         const problemStats = new Map();
-        const occurrences = [];
-        const priorItems = parsed.items
-            .filter((item) => item.requestSeq < request.seq)
-            .flatMap((item) => {
+        // Episode rendering only needs totals by episode/problem/bucket. Aggregating here avoids
+        // retaining one occurrence for every prior item on every request (quadratic heap growth).
+        const occurrenceMap = new Map();
+        const priorItems = [];
+        let usefulItemTokens = 0;
+        let wasteItemTokens = 0;
+        for (const item of parsed.items) {
+            if (item.requestSeq >= request.seq)
+                continue;
             const classification = classForRequest(item, request);
-            return classification ? [{ item, classification }] : [];
-        });
+            if (!classification)
+                continue;
+            priorItems.push({ item, classification });
+            if (classification.kind === "useful")
+                usefulItemTokens += item.tokens;
+            else
+                wasteItemTokens += item.tokens;
+        }
         const overhead = Math.min(request.inputTokens, parsed.overheadTokens);
         const productBudget = Math.max(0, request.inputTokens - overhead);
-        const usefulItemTokens = priorItems
-            .filter(({ classification }) => classification.kind === "useful")
-            .reduce((sum, { item }) => sum + item.tokens, 0);
-        const wasteItemTokens = priorItems
-            .filter(({ classification }) => classification.kind === "waste")
-            .reduce((sum, { item }) => sum + item.tokens, 0);
         const totalObserved = usefulItemTokens + wasteItemTokens;
         const scale = totalObserved > productBudget && totalObserved > 0 ? productBudget / totalObserved : 1;
         const keepProd = usefulItemTokens * scale;
@@ -413,7 +426,7 @@ function scoreClaudeNativeSession(parsed) {
                 });
             }
             problemStats.set(classification.problemId, stat);
-            occurrences.push({
+            recordNativeOccurrence(occurrenceMap, {
                 episode: request.episode,
                 problemId: classification.problemId,
                 bucket: classification.bucket,
@@ -437,7 +450,7 @@ function scoreClaudeNativeSession(parsed) {
             problemStats,
             buckets,
             rawBuckets,
-            occurrences,
+            occurrences: occurrenceMap,
             requestUsefulTokens: rawUseful,
             requestWasteTokens: rawResidue,
         });
@@ -466,7 +479,7 @@ function scoreClaudeNativeSession(parsed) {
                     turnWasteTokens: Math.round(rawResidue),
                 }];
         }
-        requestRows.push({
+        terminalRequestByTurn.set(request.turn, {
             request,
             officialInputTokens: request.inputTokens,
             usefulTokens: rawUseful,
@@ -477,10 +490,11 @@ function scoreClaudeNativeSession(parsed) {
             buckets,
             rawBuckets,
             problems: problemStats,
-            occurrences,
+            occurrences: [...occurrenceMap.values()],
         });
     }
-    const selectedRows = selectTerminalRequestPerTurn(requestRows);
+    const selectedRows = [...terminalRequestByTurn.values()]
+        .sort((left, right) => left.request.turn - right.request.turn || left.request.seq - right.request.seq);
     const selected = mergeRequestAccountingRows(selectedRows);
     const zeroBuckets = { duplicate: 0, refind: 0, dead: 0, unattributed: 0 };
     const zeroRawBuckets = { keep_oh: 0, keep_prod: 0, opt_dup: 0, opt_refind: 0, opt_dead: 0 };
@@ -537,7 +551,7 @@ function allocateResidualToProblemSignals(args) {
             });
         }
         args.problemStats.set(problemId, stat);
-        args.occurrences.push({
+        recordNativeOccurrence(args.occurrences, {
             episode: args.request.episode,
             problemId,
             bucket,
@@ -548,15 +562,15 @@ function allocateResidualToProblemSignals(args) {
     }
     return allocated;
 }
-function selectTerminalRequestPerTurn(rows) {
-    const byTurn = new Map();
-    for (const row of rows) {
-        const current = byTurn.get(row.request.turn);
-        if (!current || row.request.seq > current.request.seq) {
-            byTurn.set(row.request.turn, row);
-        }
+function recordNativeOccurrence(occurrences, occurrence) {
+    const key = `${occurrence.episode}:${occurrence.problemId}:${occurrence.bucket}`;
+    const existing = occurrences.get(key);
+    if (existing) {
+        existing.tokens += occurrence.tokens;
+        existing.turn = Math.max(existing.turn, occurrence.turn);
+        return;
     }
-    return [...byTurn.values()].sort((left, right) => left.request.turn - right.request.turn || left.request.seq - right.request.seq);
+    occurrences.set(key, { ...occurrence });
 }
 function mergeRequestAccountingRows(rows) {
     const buckets = { duplicate: 0, refind: 0, dead: 0, unattributed: 0 };
@@ -1023,7 +1037,52 @@ function internalBucket(bucket) {
     return "opt_dead";
 }
 function readRows(file) {
+    const totalTurns = countClaudeNativeTurns(file);
+    const ranges = claudeTurnSampleRanges(totalTurns);
     const rows = [];
+    let turn = 0;
+    forEachJsonRow(file, (row) => {
+        if (stringValue(row.type) === "user" && !isClaudeToolResultUser(row))
+            turn += 1;
+        if (turn === 0 || turnInClaudeRanges(turn, ranges))
+            rows.push(row);
+    });
+    return rows;
+}
+function countClaudeNativeTurns(file) {
+    let turns = 0;
+    forEachJsonRow(file, (row) => {
+        if (stringValue(row.type) === "user" && !isClaudeToolResultUser(row))
+            turns += 1;
+    });
+    return turns;
+}
+export function claudeTurnSampleRanges(totalTurns) {
+    if (totalTurns <= CLAUDE_MAX_TURNS_PER_SESSION)
+        return totalTurns > 0 ? [[1, totalTurns]] : [];
+    const tailStart = totalTurns - CLAUDE_TAIL_TURNS + 1;
+    const ranges = [
+        [1, CLAUDE_HEAD_TURNS],
+        [tailStart, totalTurns],
+    ];
+    const middleStart = CLAUDE_HEAD_TURNS + 1;
+    const middleEnd = tailStart - 1;
+    const middleSpan = Math.max(0, middleEnd - middleStart + 1);
+    for (let index = 0; index < CLAUDE_MIDDLE_WINDOWS; index += 1) {
+        const segmentStart = middleStart + Math.floor((middleSpan * index) / CLAUDE_MIDDLE_WINDOWS);
+        const segmentEnd = middleStart + Math.floor((middleSpan * (index + 1)) / CLAUDE_MIDDLE_WINDOWS) - 1;
+        const segmentTurns = Math.max(0, segmentEnd - segmentStart + 1);
+        const windowTurns = Math.min(CLAUDE_MIDDLE_WINDOW_TURNS, segmentTurns);
+        const start = segmentStart + Math.floor((segmentTurns - windowTurns) / 2);
+        if (windowTurns > 0)
+            ranges.push([start, start + windowTurns - 1]);
+    }
+    return ranges.sort((left, right) => left[0] - right[0]);
+}
+function turnInClaudeRanges(turn, ranges) {
+    return ranges.some(([start, end]) => turn >= start && turn <= end);
+}
+function forEachJsonRow(file, visit) {
     const fd = fs.openSync(file, "r");
     const decoder = new StringDecoder("utf8");
     const buffer = Buffer.allocUnsafe(1 << 20);
@@ -1034,7 +1093,7 @@ function readRows(file) {
         try {
             const parsed = JSON.parse(line);
             if (isRecord(parsed))
-                rows.push(parsed);
+                visit(parsed);
         }
         catch {
             // Claude Code may leave an active final JSONL line partial.
@@ -1064,7 +1123,6 @@ function readRows(file) {
     finally {
         fs.closeSync(fd);
     }
-    return rows;
 }
 function isClaudeToolResultUser(record) {
     const content = recordValue(record.message).content;

package/dist/forensics.js

@@ -1158,9 +1158,9 @@ function invalidSetupReport(code, message) {
 /**
  * Fail-closed boundary between the local scanner and setup UI.
  *
- * The setup page must never infer that a fixture, partial scan, or internally inconsistent token
- * ledger is the user's report. This validator checks the provenance and the cross-ledger identities
- * the UI relies on before any absolute token number is rendered.
+ * The setup page must never infer that a fixture, unreconciled scan, or internally inconsistent
+ * token ledger is the user's report. This validator checks provenance and the cross-ledger
+ * identities the UI relies on before any absolute token number is rendered.
  */
 export function validateForensicReportForSetup(value) {
     const report = recordValue(value);
@@ -1268,6 +1268,7 @@ export function validateForensicReportForSetup(value) {
         return invalidSetupReport("REPORT_COST_INVALID", "Per-workspace costs do not reconcile with total spend.");
     }
     const diagnostics = canonical.diagnostics === undefined ? null : recordValue(canonical.diagnostics);
+    let skippedCanonicalSessions = 0;
     if (canonical.diagnostics !== undefined && !diagnostics) {
         return invalidSetupReport("REPORT_MALFORMED", "Canonical scan diagnostics are malformed.");
     }
@@ -1277,12 +1278,15 @@ export function validateForensicReportForSetup(value) {
         if (skippedSessions === null || !Array.isArray(errors)) {
             return invalidSetupReport("REPORT_MALFORMED", "Canonical scan diagnostics are malformed.");
         }
-        if (skippedSessions > 0 || errors.length > 0) {
-            return invalidSetupReport("REPORT_PARTIAL", "Some local sessions could not be analyzed; no partial report was shown.");
+        if (skippedSessions !== errors.length) {
+            return invalidSetupReport("REPORT_MALFORMED", "Canonical scan diagnostics do not reconcile.");
         }
+        skippedCanonicalSessions = skippedSessions;
     }
-    if (sessionCount !== canonicalSessionCount) {
-        return invalidSetupReport("REPORT_COHORT_MISMATCH", "Provider and canonical ledgers cover different session cohorts.");
+    if (canonicalSessionCount > sessionCount ||
+        canonicalSessionCount + skippedCanonicalSessions !== sessionCount ||
+        (sessionCount > 0 && canonicalSessionCount === 0)) {
+        return invalidSetupReport("REPORT_COHORT_MISMATCH", "Canonical analysis did not retain a usable local-session cohort.");
     }
     if (canonicalUseful + canonicalWaste !== canonicalInput) {
         return invalidSetupReport("REPORT_CANONICAL_INVALID", "Canonical useful and waste totals do not reconcile.");
@@ -1517,8 +1521,7 @@ export async function buildForensicReport(opts) {
     }
     if (report.canonicalGoldenStandard &&
         !("error" in report.canonicalGoldenStandard) &&
-        (report.canonicalGoldenStandard.diagnostics?.skippedSessions ?? 0) === 0 &&
-        report.scale.sessionCount === report.canonicalGoldenStandard.summary.sessionsAnalyzed) {
+        report.canonicalGoldenStandard.summary.sessionsAnalyzed > 0) {
         const projection = projectCanonicalWasteToBilledInput(Number(report.scale.totalInputTokens || 0), report.canonicalGoldenStandard.summary);
         if (projection)
             report.billedWasteProjection = projection;

package/dist/index.js

@@ -18,6 +18,13 @@ import { checkLatestUpdateStatus, formatUpdateNotice, formatUpdateStatusText, st
 const ECHO_API_BASE_URL = process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app";
 const ECHO_PRICING_URL = process.env.ECHO_PRICING_URL || "https://echoknows.com/account";
 const ECHO_MEMORY_WEB_URL = (process.env.ECHO_MEMORY_WEB_URL || "https://echoknows.com/memory").replace(/\/$/, "");
+const DESKTOP_MANAGED = process.env.ECHO_DESKTOP_MANAGED === "1";
+const CONNECT_DEVICE_INSTRUCTION = DESKTOP_MANAGED
+    ? "Open Echo Desktop, sign in, and choose Connect MCP, then retry this action."
+    : "Run `echomem-mcp login` in a terminal to reconnect this device, then retry this action.";
+const UNLOCK_VAULT_INSTRUCTION = DESKTOP_MANAGED
+    ? "Open Echo Desktop and unlock the vault there. Keep the passphrase out of chat."
+    : "Open Terminal and run `echomem-mcp unlock` yourself. Do not have the agent run this interactive command and do not send your passphrase in chat.";
 function memoryWebUrl(memoryId) {
     return `${ECHO_MEMORY_WEB_URL}/${encodeURIComponent(memoryId)}`;
 }
@@ -156,7 +163,7 @@ function formatReconnectRequiredResult(error) {
         return null;
     return [
         "🔌 EchoMem's saved login is no longer accepted (Unauthorized, HTTP 401).",
-        "Action required from the user: run `echomem-mcp login` in a terminal to reconnect this device, then retry this action.",
+        `Action required from the user: ${CONNECT_DEVICE_INSTRUCTION}`,
         "No editor restart is needed. Keep all credentials out of chat.",
     ].join("\n");
 }
@@ -185,6 +192,56 @@ function readNumber(record, key) {
     const value = record[key];
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
+function normalizeQueryAlias(args) {
+    if (!isRecord(args) || !("conversation" in args))
+        return args;
+    const query = readString(args, "query") ?? readString(args, "conversation");
+    const { conversation: _ignored, ...rest } = args;
+    return query ? { ...rest, query } : rest;
+}
+const PERSONAL_RECALL_TOOL_NAMES = new Set([
+    canonicalToolNames.search,
+    canonicalToolNames.timeRange,
+    canonicalToolNames.keywords,
+]);
+function hasKeywordInput(args) {
+    const value = args.keywords;
+    if (Array.isArray(value)) {
+        return value.some((item) => typeof item === "string" && item.trim().length > 0);
+    }
+    return typeof value === "string" && value.trim().length > 0;
+}
+function routePersonalRecallInvocation(canonicalName, args) {
+    if (!PERSONAL_RECALL_TOOL_NAMES.has(canonicalName)) {
+        return { canonicalName, args };
+    }
+    const normalizedArgs = normalizeQueryAlias(args);
+    if (!isRecord(normalizedArgs)) {
+        return { canonicalName, args: normalizedArgs };
+    }
+    const hasSemanticInput = Boolean(readString(normalizedArgs, "query")
+        || readNumber(normalizedArgs, "timeFrameDays") !== undefined);
+    const hasKeywords = hasKeywordInput(normalizedArgs);
+    const hasDateRangeInput = Boolean(readString(normalizedArgs, "startDate") || readString(normalizedArgs, "endDate"));
+    const intentCount = Number(hasSemanticInput) + Number(hasKeywords) + Number(hasDateRangeInput);
+    if (intentCount > 1) {
+        return {
+            canonicalName,
+            args: normalizedArgs,
+            error: "Ambiguous memory search arguments. Use exactly one input shape: {query, optional timeFrameDays} for topic search, {keywords} for exact-key search, or {startDate, endDate} for a date range.",
+        };
+    }
+    if (hasSemanticInput) {
+        return { canonicalName: canonicalToolNames.search, args: normalizedArgs };
+    }
+    if (hasKeywords) {
+        return { canonicalName: canonicalToolNames.keywords, args: normalizedArgs };
+    }
+    if (hasDateRangeInput) {
+        return { canonicalName: canonicalToolNames.timeRange, args: normalizedArgs };
+    }
+    return { canonicalName, args: normalizedArgs };
+}
 function errorCodeFrom(value) {
     if (!isRecord(value))
         return undefined;
@@ -776,12 +833,12 @@ class EchoMemApiClient {
         };
     }
     async searchMemories(args, trace) {
-        const parsed = searchMemoriesSchema.parse(args ?? {});
+        const parsed = searchMemoriesSchema.parse(normalizeQueryAlias(args) ?? {});
         const query = parsed.query?.trim();
         const limit = parsed.limit ?? parsed.k ?? 10;
         const threshold = parsed.threshold ?? 0.1;
         if (!query && !parsed.timeFrameDays) {
-            throw new McpError(ErrorCode.InvalidParams, "Provide query, or provide timeFrameDays for chronological fetch.");
+            throw new McpError(ErrorCode.InvalidParams, "search_memories requires a non-empty query. For example: {\"query\":\"research article hero image\",\"timeFrameDays\":14}. For an explicit date range, call get_memories_by_time_range with both startDate and endDate.");
         }
         const enc = await this.encState(); // throws LockedError for an encrypted account without a key
         if (!query) {
@@ -1157,9 +1214,11 @@ class EchoMemMCPServer {
         });
         this.client = new EchoMemApiClient(store);
         this.events = new EventLogger({ session_id: this.client.getSessionId(), app_version: SERVER_VERSION });
-        startBackgroundUpdateCheck((status) => {
-            this.updateStatus = status;
-        });
+        if (!DESKTOP_MANAGED) {
+            startBackgroundUpdateCheck((status) => {
+                this.updateStatus = status;
+            });
+        }
         this.setupToolHandlers();
         this.server.onerror = (error) => console.error("[MCP Error]", error);
         process.on("SIGINT", async () => {
@@ -1207,11 +1266,16 @@ class EchoMemMCPServer {
             ]);
             this.mapInjected = !!map;
             this.groupMapInjected = !!groupMap;
-            const updateNotice = formatUpdateNotice(this.updateStatus);
+            const updateNotice = DESKTOP_MANAGED ? undefined : formatUpdateNotice(this.updateStatus);
             return { tools: listToolSpecs({ map, groupMap, updateNotice }) };
         });
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
-            const canonicalName = resolveCanonicalToolName(request.params.name);
+            const resolvedCanonicalName = resolveCanonicalToolName(request.params.name);
+            const recallRoute = routePersonalRecallInvocation(resolvedCanonicalName, request.params.arguments);
+            const canonicalName = recallRoute.canonicalName;
+            const toolArgs = canonicalName === canonicalToolNames.others
+                ? normalizeQueryAlias(recallRoute.args)
+                : recallRoute.args;
             const clientVersion = this.server.getClientVersion();
             this.mcpClientName = clientVersion?.name ?? this.mcpClientName;
             this.mcpClientVersion = clientVersion?.version ?? this.mcpClientVersion;
@@ -1226,8 +1290,8 @@ class EchoMemMCPServer {
                 conversation_id: this.client.getSessionId(),
                 tool_name: request.params.name,
                 canonical_tool_name: canonicalName,
-                ...triggerAnalyticsForTool(canonicalName, request.params.arguments),
-                ...inputAnalyticsForTool(canonicalName, request.params.arguments),
+                ...triggerAnalyticsForTool(canonicalName, toolArgs),
+                ...inputAnalyticsForTool(canonicalName, toolArgs),
             };
             const analyticsCallId = randomUUID();
             // One event per call. Handlers enrich `rec` with tool-specific detail; we finalize + log in `finally`.
@@ -1238,11 +1302,22 @@ class EchoMemMCPServer {
                 group_map_injected: this.groupMapInjected,
             };
             try {
+                if (recallRoute.error) {
+                    throw new McpError(ErrorCode.InvalidParams, recallRoute.error);
+                }
                 // The usage report is a local, $0 audit — works with no login (value before signup).
                 if (canonicalName === canonicalToolNames.report) {
                     return { content: [{ type: "text", text: await buildReportText(false) }] };
                 }
                 if (canonicalName === canonicalToolNames.updateStatus) {
+                    if (DESKTOP_MANAGED) {
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: `Echo Desktop manages this MCP runtime (${MCP_PACKAGE_VERSION}). Install app updates from Echo Desktop, then start a new agent session.`,
+                                }],
+                        };
+                    }
                     const force = isRecord(request.params.arguments) && request.params.arguments.force === true;
                     const status = await checkLatestUpdateStatus({ force });
                     this.updateStatus = status;
@@ -1298,17 +1373,17 @@ class EchoMemMCPServer {
                 }
                 switch (canonicalName) {
                     case canonicalToolNames.search:
-                        return await this.handleSearch(request.params.arguments, rec);
+                        return await this.handleSearch(toolArgs, rec);
                     case canonicalToolNames.save:
                         return await this.handleSave(request.params.arguments, rec);
                     case canonicalToolNames.timeRange:
-                        return await this.handleTimeRange(request.params.arguments);
+                        return await this.handleTimeRange(toolArgs);
                     case canonicalToolNames.getByContext:
                         return await this.handleGetByContext(request.params.arguments);
                     case canonicalToolNames.checkpointByContext:
                         return await this.handleGetCheckpointByContext(request.params.arguments);
                     case canonicalToolNames.keywords:
-                        return await this.handleKeywords(request.params.arguments);
+                        return await this.handleKeywords(toolArgs);
                     case canonicalToolNames.friends:
                         return await this.handleFriends(request.params.arguments);
                     case canonicalToolNames.searchUsers:
@@ -1316,7 +1391,7 @@ class EchoMemMCPServer {
                     case canonicalToolNames.sendFriendRequest:
                         return await this.handleSendFriendRequest(request.params.arguments);
                     case canonicalToolNames.others:
-                        return await this.handleOthers(request.params.arguments);
+                        return await this.handleOthers(toolArgs);
                     case canonicalToolNames.publicMemory:
                         return await this.handlePublicMemory(request.params.arguments);
                     case canonicalToolNames.recordCitations:
@@ -1361,7 +1436,7 @@ class EchoMemMCPServer {
                         content: [
                             {
                                 type: "text",
-                                text: "🔌 EchoMem isn't connected yet. Run `echomem-mcp login` in a terminal to connect this device, then retry — no editor restart needed.",
+                                text: `🔌 EchoMem isn't connected yet. ${CONNECT_DEVICE_INSTRUCTION} No editor restart is needed.`,
                             },
                         ],
                     };
@@ -1375,8 +1450,10 @@ class EchoMemMCPServer {
                                 text: [
                                     "🔒 EchoMem vault is locked.",
                                     "This encrypted account has no usable local decryption key. Once unlocked, this trusted device stays unlocked until you explicitly lock it or log out.",
-                                    "Action required from the user: open Terminal and run `echomem-mcp unlock` yourself. Do not have the agent run this interactive command and do not send your passphrase in chat.",
-                                    "At `Vault passphrase (typing is hidden):`, type the passphrase and press Return. No characters will appear while you type; that is expected.",
+                                    `Action required from the user: ${UNLOCK_VAULT_INSTRUCTION}`,
+                                    ...(DESKTOP_MANAGED ? [] : [
+                                        "At `Vault passphrase (typing is hidden):`, type the passphrase and press Return. No characters will appear while you type; that is expected.",
+                                    ]),
                                     "After the success message, retry this EchoMem action in the current session — no editor restart is needed.",
                                 ].join("\n"),
                             },

package/dist/package-metadata.js

@@ -21,15 +21,22 @@ export const MCP_PACKAGE_NAME = stringOrFallback(packageJson.name, FALLBACK_PACK
 export const MCP_PACKAGE_VERSION = stringOrFallback(packageJson.version, FALLBACK_PACKAGE.version);
 export const MCP_PACKAGE_DESCRIPTION = stringOrFallback(packageJson.description, FALLBACK_PACKAGE.description);
 export const MCP_PACKAGE_LABEL = `${MCP_PACKAGE_NAME}@${MCP_PACKAGE_VERSION}`;
+export const MCP_DESKTOP_MANAGED = process.env.ECHO_DESKTOP_MANAGED === "1";
 export const MCP_UPDATE_COMMAND = `npx -y ${MCP_PACKAGE_NAME}@latest update`;
 export const MCP_UPDATE_ALL_COMMAND = `${MCP_UPDATE_COMMAND} --all`;
+export const MCP_VAULT_UNLOCK_INSTRUCTION = MCP_DESKTOP_MANAGED
+    ? "open Echo Desktop and unlock the vault there"
+    : "run `echomem-mcp unlock` locally";
+const MCP_UPDATE_INSTRUCTION = MCP_DESKTOP_MANAGED
+    ? "Echo Desktop manages this MCP runtime; install an Echo Desktop update when one is offered"
+    : `update once with \`${MCP_UPDATE_ALL_COMMAND}\``;
 export const MEMORY_CITATION_INSTRUCTION = 'If the user-facing answer materially relies on one or more EchoMem memories, end it with a compact "EchoMem sources:" list containing only the memories actually used. For memories owned by teammates or accepted friends, call record_memory_citations immediately before the final answer with those exact Memory IDs. Do not cite memories that were merely retrieved. Use each memory key as the Markdown label and its canonical https://echoknows.com/memory/<memory-id> URL. Omit the sources section and citation receipt when no memory informed the answer.';
 export const 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 this bridge is stale, update once with \`${MCP_UPDATE_ALL_COMMAND}\` and start a new MCP session; never auto-update at startup.`,
+    `If this bridge is stale, ${MCP_UPDATE_INSTRUCTION} 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.",
+    `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 ${MCP_VAULT_UNLOCK_INSTRUCTION}.`,
     "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.",
@@ -38,5 +45,5 @@ export const MCP_SERVER_INSTRUCTIONS = [
     "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.`;
+    return `${description}\n\nEchoMem MCP bridge: ${MCP_PACKAGE_LABEL}. If this version is stale, ${MCP_UPDATE_INSTRUCTION}, then start a new MCP session. Do not run updates repeatedly or on every startup.`;
 }

package/dist/save-checkpoint-hook.js

@@ -10,7 +10,7 @@ const CHECKPOINT_REASON = [
     "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.",
+    "If EchoMem reports that the encrypted vault is locked, tell the user to open Echo Desktop and unlock the vault there; on a headless system, use `echomem-mcp unlock`. Never silently skip a qualifying checkpoint.",
 ].join(" ");
 function currentTurnSlice(transcript) {
     const lines = transcript.split(/\r?\n/);