@echomem/mcp 1.4.35 → 1.4.37

package/README.md

@@ -55,7 +55,7 @@ For headless systems and development, the granular CLI commands remain available
 | `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 --all` | Bootstrap or repair the durable per-user runtime and repoint detected client configs, with no browser login |
 | `npx -y @echomem/mcp@latest update --client codex` | Update one client only |
 | `echomem-mcp login` | Approve device in browser (or use `--token` / `--passphrase`) |
 | `echomem-mcp unlock` | Privately unlock the vault on this trusted device |
@@ -65,10 +65,11 @@ For headless systems and development, the granular CLI commands remain available
 | `echomem-mcp logout` | Remove stored credentials |
 
 The bridge reports its package version in MCP server instructions and in tool descriptions. It also
-checks npm for a newer published bridge using a cached, non-blocking check. Agents can call
-`echomem_update_status` to show the user whether an update exists and then run
-`npx -y @echomem/mcp@latest update --all` if the user agrees. The bridge does not auto-update on
-every MCP startup.
+checks npm for a newer published bridge using a cached, non-blocking check. Standalone installations
+stage compatible updates in the background under `~/.echomem/mcp-runtime` and atomically activate
+them for the next MCP session; the current handshake never waits for npm. Agents can call
+`echomem_update_status` to inspect progress. `ECHO_DISABLE_AUTO_UPDATE=1` disables automatic
+installation, and `npx -y @echomem/mcp@latest update --all` remains the bootstrap and repair command.
 
 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.
@@ -189,14 +190,9 @@ ECHO_API_TOKEN="your_token" ECHO_API_BASE_URL="http://localhost:3000" npm run st
 * **`search_memories_by_keywords`**: Retrieve memories by matching the `keys` field.
 * **`search_others_memories`**: Search other users' public memories through MemoryFeed public search.
 * **`delete_memory`**: Delete a single personal memory through a two-step confirmation flow. First call with `memoryId` only to preview the target and receive `confirmationToken`; after the user explicitly confirms, call again with `confirmed: true` and that exact token. This deletes the memory row only and preserves raw `source_of_truth` conversation records.
-* **`echomem_update_status`**: Check the installed bridge against the latest published npm version. Works without login, uses cached background checks in normal operation, and returns the update command to show the user when a newer bridge exists.
+* **`echomem_update_status`**: Check the installed bridge against the latest published npm version. Works without login, uses cached background checks in normal operation, and reports automatic installation state plus a fallback repair command.
 * **`echo_context_health`**: Return the local Codex/Claude context-health score as markdown. Works without login and uploads no transcript content.
 
-Legacy aliases are preserved for compatibility:
-
-* `search_memories_by_description_semantic` -> `search_memories`
-* `search_memories_by_time_range` -> `get_memories_by_time_range`
-
 Contract reference:
 
 * `docs/PUBLIC_API_CONTRACT_V1.md`

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/headless-runtime.js

@@ -0,0 +1,254 @@
+import { execFile, execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import { echoConfigDir } from "./keystore.js";
+import { MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION } from "./package-metadata.js";
+const execFileAsync = promisify(execFile);
+const RUNTIME_LAYOUT = 1;
+const UPDATE_LOCK_STALE_MS = 15 * 60 * 1000;
+export function headlessRuntimeRoot() {
+    return path.join(echoConfigDir(), "mcp-runtime");
+}
+function versionsRoot() {
+    return path.join(headlessRuntimeRoot(), "versions");
+}
+function activeRuntimePath() {
+    return path.join(headlessRuntimeRoot(), "active.json");
+}
+export function headlessLauncherPath() {
+    return path.join(headlessRuntimeRoot(), "launcher.mjs");
+}
+function packageEntryForPrefix(prefix) {
+    return path.join(prefix, "node_modules", ...MCP_PACKAGE_NAME.split("/"), "dist", "index.js");
+}
+function packageJsonForPrefix(prefix) {
+    return path.join(prefix, "node_modules", ...MCP_PACKAGE_NAME.split("/"), "package.json");
+}
+function safeVersion(value) {
+    const version = value.trim();
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+        throw new Error(`Invalid EchoMem MCP version: ${value}`);
+    }
+    return version;
+}
+function relativeEntryForVersion(version) {
+    return path.join("versions", version, "node_modules", ...MCP_PACKAGE_NAME.split("/"), "dist", "index.js");
+}
+function atomicWriteJson(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify(value, null, 2), { mode: 0o600 });
+    fs.renameSync(temporary, file);
+    try {
+        fs.chmodSync(file, 0o600);
+    }
+    catch {
+        /* Best effort on platforms without POSIX permissions. */
+    }
+}
+function ensureLauncher() {
+    const root = headlessRuntimeRoot();
+    const launcher = headlessLauncherPath();
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    const source = [
+        "#!/usr/bin/env node",
+        'import fs from "node:fs";',
+        'import path from "node:path";',
+        'import { fileURLToPath, pathToFileURL } from "node:url";',
+        "const root = path.dirname(fileURLToPath(import.meta.url));",
+        'const active = JSON.parse(fs.readFileSync(path.join(root, "active.json"), "utf8"));',
+        'if (active.layout !== 1 || typeof active.entry !== "string" || path.isAbsolute(active.entry) || active.entry.split(/[\\\\/]/).includes("..")) {',
+        '  throw new Error("EchoMem MCP runtime pointer is invalid; run `npx -y @echomem/mcp@latest update --all`.");',
+        "}",
+        "const entry = path.resolve(root, active.entry);",
+        'if (!fs.existsSync(entry)) throw new Error("EchoMem MCP runtime is missing; run `npx -y @echomem/mcp@latest update --all`.");',
+        "await import(pathToFileURL(entry).href);",
+        "",
+    ].join("\n");
+    let current = "";
+    try {
+        current = fs.readFileSync(launcher, "utf8");
+    }
+    catch {
+        /* Create it below. */
+    }
+    if (current !== source)
+        fs.writeFileSync(launcher, source, { mode: 0o700 });
+    try {
+        fs.chmodSync(launcher, 0o700);
+    }
+    catch {
+        /* Best effort on platforms without POSIX permissions. */
+    }
+    return launcher;
+}
+function readPackageVersion(prefix) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(packageJsonForPrefix(prefix), "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readHeadlessRuntimeInstallation() {
+    try {
+        const active = JSON.parse(fs.readFileSync(activeRuntimePath(), "utf8"));
+        if (active.layout !== RUNTIME_LAYOUT || typeof active.version !== "string" || typeof active.entry !== "string") {
+            return undefined;
+        }
+        if (path.isAbsolute(active.entry) || active.entry.split(/[\\/]/).includes(".."))
+            return undefined;
+        const entry = path.resolve(headlessRuntimeRoot(), active.entry);
+        const expectedRoot = `${path.resolve(headlessRuntimeRoot())}${path.sep}`;
+        if (!entry.startsWith(expectedRoot) || !fs.existsSync(entry))
+            return undefined;
+        const prefix = path.join(versionsRoot(), active.version);
+        if (readPackageVersion(prefix) !== active.version)
+            return undefined;
+        return { version: active.version, launcher: ensureLauncher(), entry };
+    }
+    catch {
+        return undefined;
+    }
+}
+function activateRuntime(prefix, version) {
+    const entry = packageEntryForPrefix(prefix);
+    if (!fs.existsSync(entry) || readPackageVersion(prefix) !== version) {
+        throw new Error(`${MCP_PACKAGE_NAME}@${version} did not install a valid MCP entry point`);
+    }
+    const launcher = ensureLauncher();
+    atomicWriteJson(activeRuntimePath(), {
+        layout: RUNTIME_LAYOUT,
+        version,
+        entry: relativeEntryForVersion(version),
+        activatedAt: new Date().toISOString(),
+    });
+    return { version, launcher, entry };
+}
+function resolveNpmInvocation() {
+    const candidates = [
+        process.env.npm_execpath,
+        path.resolve(path.dirname(process.execPath), "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+        path.resolve(path.dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js"),
+    ].filter((candidate) => Boolean(candidate));
+    for (const npmCli of candidates) {
+        try {
+            if (fs.existsSync(npmCli))
+                return { command: process.execPath, prefixArgs: [npmCli] };
+        }
+        catch {
+            /* Keep looking. */
+        }
+    }
+    return { command: process.platform === "win32" ? "npm.cmd" : "npm", prefixArgs: [] };
+}
+function npmInstallArguments(prefix, version) {
+    return [
+        "install",
+        "--ignore-scripts",
+        "--omit=dev",
+        "--no-audit",
+        "--no-fund",
+        "--no-package-lock",
+        "--prefix",
+        prefix,
+        `${MCP_PACKAGE_NAME}@${version}`,
+    ];
+}
+function prepareStaging(version) {
+    const destination = path.join(versionsRoot(), version);
+    fs.mkdirSync(versionsRoot(), { recursive: true, mode: 0o700 });
+    const staging = path.join(versionsRoot(), `.${version}-${process.pid}-${Date.now()}`);
+    fs.rmSync(staging, { recursive: true, force: true });
+    return { destination, staging };
+}
+function finishStaging(staging, destination, version) {
+    if (readPackageVersion(staging) !== version || !fs.existsSync(packageEntryForPrefix(staging))) {
+        throw new Error(`npm installed an invalid ${MCP_PACKAGE_NAME}@${version} runtime`);
+    }
+    if (fs.existsSync(destination))
+        fs.rmSync(destination, { recursive: true, force: true });
+    fs.renameSync(staging, destination);
+    return activateRuntime(destination, version);
+}
+export function installHeadlessRuntimeSync(targetVersion = MCP_PACKAGE_VERSION) {
+    const version = safeVersion(targetVersion);
+    const existing = readHeadlessRuntimeInstallation();
+    if (existing?.version === version)
+        return existing;
+    const destination = path.join(versionsRoot(), version);
+    if (readPackageVersion(destination) === version && fs.existsSync(packageEntryForPrefix(destination))) {
+        return activateRuntime(destination, version);
+    }
+    const { staging } = prepareStaging(version);
+    const npm = resolveNpmInvocation();
+    try {
+        execFileSync(npm.command, [...npm.prefixArgs, ...npmInstallArguments(staging, version)], {
+            stdio: "inherit",
+            windowsHide: true,
+        });
+        return finishStaging(staging, destination, version);
+    }
+    catch (error) {
+        fs.rmSync(staging, { recursive: true, force: true });
+        throw new Error(`Could not stage ${MCP_PACKAGE_NAME}@${version}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function acquireUpdateLock() {
+    const lock = path.join(headlessRuntimeRoot(), "update.lock");
+    fs.mkdirSync(headlessRuntimeRoot(), { recursive: true, mode: 0o700 });
+    try {
+        const descriptor = fs.openSync(lock, "wx", 0o600);
+        fs.writeFileSync(descriptor, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+        fs.closeSync(descriptor);
+    }
+    catch {
+        try {
+            const age = Date.now() - fs.statSync(lock).mtimeMs;
+            if (age <= UPDATE_LOCK_STALE_MS)
+                return undefined;
+            fs.rmSync(lock, { force: true });
+            return acquireUpdateLock();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return () => fs.rmSync(lock, { force: true });
+}
+export async function autoUpdateHeadlessRuntime(targetVersion) {
+    if (process.env.ECHO_DISABLE_AUTO_UPDATE === "1")
+        return { state: "disabled" };
+    let version;
+    try {
+        version = safeVersion(targetVersion);
+    }
+    catch (error) {
+        return { state: "failed", error: error instanceof Error ? error.message : String(error) };
+    }
+    if (readHeadlessRuntimeInstallation()?.version === version)
+        return { state: "already-installed" };
+    const releaseLock = acquireUpdateLock();
+    if (!releaseLock)
+        return { state: "busy" };
+    const { destination, staging } = prepareStaging(version);
+    const npm = resolveNpmInvocation();
+    try {
+        await execFileAsync(npm.command, [...npm.prefixArgs, ...npmInstallArguments(staging, version)], {
+            timeout: 120_000,
+            windowsHide: true,
+            maxBuffer: 1024 * 1024,
+        });
+        const installation = finishStaging(staging, destination, version);
+        return { state: "installed", installation };
+    }
+    catch (error) {
+        fs.rmSync(staging, { recursive: true, force: true });
+        return { state: "failed", error: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        releaseLock();
+    }
+}

package/dist/index.js

@@ -15,6 +15,7 @@ import { runCli } from "./setup.js";
 import { MCP_PACKAGE_VERSION, MCP_SERVER_INSTRUCTIONS, MEMORY_CITATION_INSTRUCTION, SAVED_MEMORY_RECEIPT_INSTRUCTION, } from "./package-metadata.js";
 import { clearBillingAlert, writeBillingAlert } from "./billing-alert.js";
 import { checkLatestUpdateStatus, formatUpdateNotice, formatUpdateStatusText, startBackgroundUpdateCheck, } from "./update-check.js";
+import { autoUpdateHeadlessRuntime } from "./headless-runtime.js";
 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(/\/$/, "");
@@ -192,6 +193,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;
@@ -783,12 +834,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) {
@@ -1166,7 +1217,7 @@ class EchoMemMCPServer {
         this.events = new EventLogger({ session_id: this.client.getSessionId(), app_version: SERVER_VERSION });
         if (!DESKTOP_MANAGED) {
             startBackgroundUpdateCheck((status) => {
-                this.updateStatus = status;
+                this.handleUpdateStatus(status);
             });
         }
         this.setupToolHandlers();
@@ -1176,6 +1227,33 @@ class EchoMemMCPServer {
             process.exit(0);
         });
     }
+    handleUpdateStatus(status) {
+        this.updateStatus = status;
+        if (!status.updateAvailable || !status.latestVersion)
+            return;
+        this.updateStatus = { ...status, autoUpdateState: "installing" };
+        void autoUpdateHeadlessRuntime(status.latestVersion).then((result) => {
+            if (result.state === "installed" || result.state === "already-installed") {
+                this.updateStatus = { ...status, autoUpdateState: "ready" };
+            }
+            else if (result.state === "busy") {
+                this.updateStatus = { ...status, autoUpdateState: "installing" };
+            }
+            else {
+                this.updateStatus = {
+                    ...status,
+                    autoUpdateState: "failed",
+                    error: result.state === "failed" ? result.error : "automatic updates are disabled",
+                };
+            }
+        }).catch((error) => {
+            this.updateStatus = {
+                ...status,
+                autoUpdateState: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        });
+    }
     getMcpClientAnalytics() {
         const hostPlatform = normalizeMcpHostPlatform(this.mcpClientName)
             ?? detectMcpHostFromEnv()
@@ -1220,7 +1298,12 @@ class EchoMemMCPServer {
             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;
@@ -1235,8 +1318,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`.
@@ -1247,6 +1330,9 @@ 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) }] };
@@ -1262,8 +1348,8 @@ class EchoMemMCPServer {
                     }
                     const force = isRecord(request.params.arguments) && request.params.arguments.force === true;
                     const status = await checkLatestUpdateStatus({ force });
-                    this.updateStatus = status;
-                    return { content: [{ type: "text", text: formatUpdateStatusText(status) }] };
+                    this.handleUpdateStatus(status);
+                    return { content: [{ type: "text", text: formatUpdateStatusText(this.updateStatus ?? status) }] };
                 }
                 if (canonicalName === canonicalToolNames.contextHealth) {
                     const client = isRecord(request.params.arguments) && typeof request.params.arguments.client === "string"
@@ -1315,17 +1401,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:
@@ -1333,7 +1419,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:
@@ -2257,6 +2343,14 @@ Details: ${m.details || "N/A"}`;
                 content: [{ type: "text", text: this.sharingFallbackText(scopeText, groupName) }],
             };
         }
+        if (elicitation.action === "cancel") {
+            return {
+                content: [{
+                        type: "text",
+                        text: this.sharingFallbackText(scopeText, groupName),
+                    }],
+            };
+        }
         if (elicitation.action !== "accept") {
             return {
                 content: [{

package/dist/package-metadata.js

@@ -28,13 +28,13 @@ 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}\``;
+    ? "Echo Desktop auto-installs compatible MCP updates"
+    : `updates auto-install in the background; on failure run \`${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, ${MCP_UPDATE_INSTRUCTION} and start a new MCP session; never auto-update at startup.`,
+    `If stale, ${MCP_UPDATE_INSTRUCTION}; restart the MCP session afterward. Updates never delay 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 ${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:\".",
@@ -45,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, ${MCP_UPDATE_INSTRUCTION}, 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 manual updates repeatedly.`;
 }

package/dist/setup.js

@@ -34,6 +34,7 @@ import { repoLabel, validateForensicReportForSetup } from "./forensics.js";
 import { installSaveCheckpointHooks } from "./hud/hooks.js";
 import { MCP_PACKAGE_LABEL, MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION, MCP_UPDATE_ALL_COMMAND, MCP_UPDATE_COMMAND } from "./package-metadata.js";
 import { checkLatestUpdateStatus, compareSemver, readCachedUpdateStatus } from "./update-check.js";
+import { installHeadlessRuntimeSync, readHeadlessRuntimeInstallation, } from "./headless-runtime.js";
 // The setup dashboard, account login, and encryption passphrase entry are all served by this
 // localhost bridge. The hosted API only sends OTP email, verifies the code, and mints a device token.
 const API_BASE_URL = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
@@ -239,6 +240,10 @@ export function buildServerEntry(opts = {}) {
     if (opts.devEntryPath) {
         return { command: "node", args: [opts.devEntryPath] };
     }
+    const managed = readHeadlessRuntimeInstallation();
+    if (managed) {
+        return { command: process.execPath, args: [managed.launcher] };
+    }
     // Spawn the ALREADY-INSTALLED bridge directly (this node + this script's real path) instead of
     // `npx -y @echomem/mcp`. `npx -y` re-resolves and, on a cache miss, NETWORK-fetches from the npm
     // registry on EVERY client start — on a slow/flaky network that delays the MCP handshake past the
@@ -291,51 +296,12 @@ function resolveGlobalEntry() {
     }
     return null;
 }
-export function needsDurableGlobalUpdate(runningEntry, durableEntry, targetVersion = MCP_PACKAGE_VERSION) {
-    if (!isEphemeralNpxPath(runningEntry))
-        return false;
-    const installedVersion = durableEntry
-        ? packageVersionFromPath(durableEntry)?.version
-        : undefined;
-    return installedVersion !== targetVersion;
-}
-function installDurableGlobalUpdate() {
-    const runningEntry = (() => {
-        try {
-            return fs.realpathSync(process.argv[1] || "");
-        }
-        catch {
-            return process.argv[1] || "";
-        }
-    })();
-    const currentGlobalEntry = resolveGlobalEntry();
-    if (!needsDurableGlobalUpdate(runningEntry, currentGlobalEntry))
+function installDurableHeadlessRuntime() {
+    if (process.env.ECHO_DISABLE_RUNTIME_BOOTSTRAP === "1")
         return;
-    const packageSpec = `${MCP_PACKAGE_NAME}@${MCP_PACKAGE_VERSION}`;
-    console.log(`Installing durable ${packageSpec} before updating client configs…`);
-    const npmExecPath = process.env.npm_execpath;
-    try {
-        if (npmExecPath && fs.existsSync(npmExecPath)) {
-            execFileSync(process.execPath, [npmExecPath, "install", "-g", packageSpec], {
-                stdio: "inherit",
-            });
-        }
-        else {
-            execFileSync(process.platform === "win32" ? "npm.cmd" : "npm", ["install", "-g", packageSpec], {
-                stdio: "inherit",
-            });
-        }
-    }
-    catch (error) {
-        throw new Error(`Could not install ${packageSpec} globally: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    const installedEntry = resolveGlobalEntry();
-    const installedVersion = installedEntry
-        ? packageVersionFromPath(installedEntry)?.version
-        : undefined;
-    if (installedVersion !== MCP_PACKAGE_VERSION) {
-        throw new Error(`Global EchoMem bridge is ${installedVersion || "missing"} after update; expected ${MCP_PACKAGE_VERSION}.`);
-    }
+    console.log(`Staging durable per-user ${MCP_PACKAGE_NAME}@${MCP_PACKAGE_VERSION} runtime…`);
+    const installation = installHeadlessRuntimeSync();
+    console.log(`✅ Activated ${MCP_PACKAGE_NAME}@${installation.version} for new MCP sessions.`);
 }
 /** The TOML block EchoMem adds to ~/.codex/config.toml. No secret — the bridge reads the keystore. */
 export function codexTomlBlock(entry) {
@@ -450,8 +416,30 @@ export function writeJsonClientConfig(configPath, entry) {
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
 }
 export function writeClaudeCodeConfig(entry) {
+    const addArguments = ["mcp", "add-json", "-s", "local", "echomem", JSON.stringify(entry)];
     try {
-        execFileSync("claude", ["mcp", "add-json", "echomem", JSON.stringify(entry)], {
+        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 local server. Once the replacement entry is
+    // fully constructed, remove only EchoMem and immediately re-add it; sibling MCP servers remain.
+    try {
+        execFileSync("claude", ["mcp", "remove", "echomem", "-s", "local"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 10000,
+        });
+        execFileSync("claude", addArguments, {
             encoding: "utf8",
             stdio: ["ignore", "pipe", "pipe"],
             timeout: 10000,
@@ -2652,6 +2640,14 @@ function parseFlags(argv) {
     return flags;
 }
 async function cmdSetup(flags) {
+    if (!flags.dev && !flags["skip-runtime-install"]) {
+        try {
+            installDurableHeadlessRuntime();
+        }
+        catch (error) {
+            console.log(`ℹ️  Automatic runtime staging was unavailable; keeping the existing bridge (${error instanceof Error ? error.message : String(error)}).`);
+        }
+    }
     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));
@@ -2800,8 +2796,8 @@ function writeSaveCheckpointHooksForTargets(targets) {
 }
 async function cmdUpdate(flags) {
     if (!flags.dev)
-        installDurableGlobalUpdate();
-    await cmdSetup({ ...flags, "skip-login": true });
+        installDurableHeadlessRuntime();
+    await cmdSetup({ ...flags, "skip-login": true, "skip-runtime-install": true });
     console.log(`Update config complete. Start a new MCP session to load ${MCP_PACKAGE_LABEL}.`);
 }
 function selectSetupTargets(requested, all) {

package/dist/update-check.js

@@ -107,10 +107,18 @@ export function startBackgroundUpdateCheck(onStatus) {
 export function formatUpdateNotice(status) {
     if (!status?.updateAvailable || !status.latestVersion)
         return undefined;
+    if (status.autoUpdateState === "ready") {
+        return `EchoMem ${status.latestVersion} was installed automatically. Start a new agent/MCP session to use it.`;
+    }
+    if (status.autoUpdateState === "installing") {
+        return `EchoMem ${status.latestVersion} is downloading automatically in the background. The next agent/MCP session will use it.`;
+    }
+    if (status.autoUpdateState === "failed") {
+        return `EchoMem ${status.latestVersion} could not be installed automatically. Run \`${status.command}\`, then start a new agent/MCP session.`;
+    }
     return [
         `EchoMem update available: installed ${status.currentVersion}, latest ${status.latestVersion}.`,
-        `Offer to update, then run \`${status.command}\` if the user agrees.`,
-        "After updating, start a new agent/MCP session.",
+        "It will install automatically in the background for the next agent/MCP session.",
     ].join(" ");
 }
 export function formatUpdateStatusText(status) {
@@ -120,8 +128,14 @@ export function formatUpdateStatusText(status) {
         `Update available: ${status.updateAvailable ? "yes" : "no"}`,
     ];
     if (status.updateAvailable) {
-        lines.push(`Update command: ${status.command}`);
-        lines.push("After updating, start a new agent/MCP session.");
+        if (status.autoUpdateState === "ready")
+            lines.push("Automatic update: installed for the next agent/MCP session");
+        else if (status.autoUpdateState === "installing")
+            lines.push("Automatic update: installing in the background");
+        else if (status.autoUpdateState === "failed")
+            lines.push(`Automatic update: failed; fallback command: ${status.command}`);
+        else
+            lines.push("Automatic update: scheduled in the background");
     }
     if (status.checkedAt)
         lines.push(`Checked at: ${status.checkedAt} (${status.source})`);

package/dist/v1-contract.js

@@ -34,7 +34,6 @@ export const canonicalToolNames = {
 };
 export const legacyAliasToCanonical = {
     search_memories_by_description_semantic: canonicalToolNames.search,
-    search_memories_by_time_range: canonicalToolNames.timeRange,
 };
 export function resolveCanonicalToolName(toolName) {
     return legacyAliasToCanonical[toolName] ?? toolName;
@@ -44,7 +43,6 @@ 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,
@@ -166,11 +164,11 @@ const triggerMetadataSchema = {
 };
 export const searchMemoriesSchema = z.object({
     ...triggerMetadataSchema,
-    query: z.string().optional(),
-    k: z.number().optional(),
-    limit: z.number().optional(),
-    threshold: z.number().optional().default(0.1),
-    timeFrameDays: z.number().optional(),
+    query: z.string().trim().min(1).optional(),
+    k: z.number().int().min(1).max(50).optional(),
+    limit: z.number().int().min(1).max(50).optional(),
+    threshold: z.number().min(0).max(1).optional().default(0.1),
+    timeFrameDays: z.number().int().min(1).max(3650).optional(),
     includeAnswer: z.boolean().optional().default(false),
 });
 export const saveConversationSchema = z.object({
@@ -189,11 +187,20 @@ export const saveConversationSchema = z.object({
     }))
         .optional(),
 });
+const dateBoundarySchema = z.string().trim().min(1).refine((value) => Number.isFinite(Date.parse(value)), "Expected an ISO-8601 date or date-time string");
 export const timeRangeSchema = z.object({
     ...triggerMetadataSchema,
-    startDate: z.string(),
-    endDate: z.string(),
-    limit: z.number().optional().default(50),
+    startDate: dateBoundarySchema,
+    endDate: dateBoundarySchema,
+    limit: z.number().int().min(1).max(100).optional().default(50),
+}).superRefine((value, ctx) => {
+    if (Date.parse(value.startDate) > Date.parse(value.endDate)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["startDate"],
+            message: "startDate must be earlier than or equal to endDate",
+        });
+    }
 });
 const keywordListSchema = z.preprocess((value) => {
     if (typeof value !== "string")
@@ -206,15 +213,15 @@ const keywordListSchema = z.preprocess((value) => {
 export const keywordsSchema = z.object({
     ...triggerMetadataSchema,
     keywords: keywordListSchema,
-    limit: z.number().optional().default(10),
+    limit: z.number().int().min(1).max(50).optional().default(10),
 });
 export const listFriendsSchema = z.object({
     ...triggerMetadataSchema,
 });
 export const searchUsersSchema = z.object({
     ...triggerMetadataSchema,
-    query: z.string().min(1),
-    limit: z.number().optional().default(10),
+    query: z.string().trim().min(1),
+    limit: z.number().int().min(1).max(50).optional().default(10),
 });
 export const sendFriendRequestSchema = z.object({
     ...triggerMetadataSchema,
@@ -222,17 +229,17 @@ export const sendFriendRequestSchema = z.object({
 });
 export const othersSchema = z.object({
     ...triggerMetadataSchema,
-    query: z.string().optional().default(""),
-    limit: z.number().optional().default(10),
+    query: z.string().trim().optional().default(""),
+    limit: z.number().int().min(1).max(50).optional().default(10),
     target: z.string().optional(),
     ownerUserId: z.string().optional(),
     ownerName: z.string().optional(),
     targetFriendIds: z.array(z.string()).optional(),
     targetFriendNames: z.array(z.string()).optional(),
     recordAccess: z.boolean().optional(),
-    kPerUser: z.number().optional(),
-    similarityThreshold: z.number().optional(),
-    timeFrameDays: z.number().optional(),
+    kPerUser: z.number().int().min(1).max(50).optional(),
+    similarityThreshold: z.number().min(0).max(1).optional(),
+    timeFrameDays: z.number().int().min(1).max(3650).optional(),
 });
 export const publicMemorySchema = z.object({
     ...triggerMetadataSchema,
@@ -329,8 +336,8 @@ export const deleteMemorySchema = z.object({
 });
 export const getByContextSchema = z.object({
     ...triggerMetadataSchema,
-    contextId: z.string().min(1),
-    limit: z.number().optional().default(50),
+    contextId: z.string().trim().min(1),
+    limit: z.number().int().min(1).max(100).optional().default(50),
 });
 export function listToolSpecs(opts = {}) {
     const currentTime = new Date().toISOString();
@@ -349,42 +356,64 @@ export function listToolSpecs(opts = {}) {
     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${compactGroupRoster(groupMap)}\n${groupMap}\n`
         : "";
+    const semanticSearchInputSchema = {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                minLength: 1,
+                description: "Required topic or question to search for. Never omit this field or send it as conversation.",
+            },
+            limit: { type: "integer", minimum: 1, maximum: 50, default: 10 },
+            threshold: { type: "number", minimum: 0, maximum: 1, default: 0.1 },
+            timeFrameDays: {
+                type: "integer",
+                minimum: 1,
+                maximum: 3650,
+                description: "Optional recency filter for this query, such as 14 for the last two weeks.",
+            },
+            triggerMessage: {
+                type: "string",
+                description: "Optional: the user's message that caused this recall. EchoMem stores only a redacted analytics preview and hash.",
+            },
+            triggerMessageRole: { type: "string", default: "user" },
+        },
+        required: ["query"],
+    };
+    const timeRangeInputSchema = {
+        type: "object",
+        properties: {
+            startDate: {
+                type: "string",
+                minLength: 1,
+                description: "Required ISO-8601 start date or date-time. Must not be later than endDate.",
+            },
+            endDate: {
+                type: "string",
+                minLength: 1,
+                description: "Required ISO-8601 end date or date-time. Must not be earlier than startDate.",
+            },
+            limit: { type: "integer", minimum: 1, maximum: 100, default: 50 },
+            triggerMessage: {
+                type: "string",
+                description: "Optional: the user's message that caused this lookup. EchoMem stores only a redacted analytics preview and hash.",
+            },
+            triggerMessageRole: { type: "string", default: "user" },
+        },
+        required: ["startDate", "endDate"],
+    };
     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}`),
-            inputSchema: {
-                type: "object",
-                properties: {
-                    query: { type: "string" },
-                    limit: { type: "number", default: 10 },
-                    threshold: { type: "number", default: 0.1 },
-                    timeFrameDays: { type: "number" },
-                    triggerMessage: {
-                        type: "string",
-                        description: "Optional: the user's message that caused this recall. EchoMem stores only a redacted analytics preview and hash.",
-                    },
-                    triggerMessageRole: { type: "string", default: "user" },
-                },
-            },
+            title: "Search your memories by topic",
+            description: withMcpVersion(`TOPIC SEARCH for the user's own EchoMem memories across all AI tools. Always pass a non-empty query; optionally add timeFrameDays to filter that topic to recent memories. Do not pass keywords, startDate, or endDate. For exact memory-key terms use search_memories_by_keywords. For an explicit calendar range use get_memories_by_time_range. Use this tool instead of re-deriving or re-asking what the user already settled. ${recallPlanNote} ${searchBillingReplyInstruction} ${memoryCitationInstruction}${mapSection}\nReturns ranked memories only; the MCP host model writes the final answer. Current time: ${currentTime}.${updateSection}`),
+            inputSchema: semanticSearchInputSchema,
         },
         {
             name: "search_memories_by_description_semantic",
-            description: `Legacy alias for search_memories. ${recallPlanNote} ${searchBillingReplyInstruction} ${memoryCitationInstruction}`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    query: { type: "string" },
-                    limit: { type: "number", default: 10 },
-                    threshold: { type: "number", default: 0.1 },
-                    timeFrameDays: { type: "number" },
-                    triggerMessage: {
-                        type: "string",
-                        description: "Optional: the user's message that caused this recall. EchoMem stores only a redacted analytics preview and hash.",
-                    },
-                    triggerMessageRole: { type: "string", default: "user" },
-                },
-            },
+            title: "Legacy topic search (compatibility)",
+            description: `LEGACY TOPIC SEARCH alias for search_memories. Prefer search_memories. Always pass a non-empty query; timeFrameDays is only an optional recency filter. Do not pass keywords, startDate, or endDate. ${recallPlanNote} ${searchBillingReplyInstruction} ${memoryCitationInstruction}`,
+            inputSchema: semanticSearchInputSchema,
         },
         {
             name: canonicalToolNames.save,
@@ -426,25 +455,14 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.timeRange,
-            description: `Retrieve memories within a specific date range. ${recallPlanNote} ${memoryCitationInstruction} Current time: ${currentTime}.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    startDate: { type: "string" },
-                    endDate: { type: "string" },
-                    limit: { type: "number", default: 50 },
-                    triggerMessage: {
-                        type: "string",
-                        description: "Optional: the user's message that caused this lookup. EchoMem stores only a redacted analytics preview and hash.",
-                    },
-                    triggerMessageRole: { type: "string", default: "user" },
-                },
-                required: ["startDate", "endDate"],
-            },
+            title: "Get your memories by date range",
+            description: `DATE-RANGE FETCH for the user's own memories. Always pass both startDate and endDate as ISO-8601 strings. Do not pass query, keywords, or timeFrameDays. For a topic with a recency filter use search_memories instead. ${recallPlanNote} ${memoryCitationInstruction} Current time: ${currentTime}.`,
+            inputSchema: timeRangeInputSchema,
         },
         {
             name: canonicalToolNames.keywords,
-            description: `Search memories based on keywords in keys field. Pass keywords as valid JSON: preferably an array of quoted strings, for example {"keywords":["flow-lab","flow.html","Rive"],"limit":8}. A comma-separated JSON string is also accepted as a compatibility fallback. Never emit bare comma-separated tokens. ${recallPlanNote} ${memoryCitationInstruction}`,
+            title: "Search your memory keys exactly",
+            description: `EXACT-KEYWORD SEARCH over the keys field of the user's own memories. Pass keywords as valid JSON: preferably an array of quoted strings, for example {"keywords":["flow-lab","flow.html","Rive"],"limit":8}. Do not pass query, timeFrameDays, startDate, or endDate. For natural-language topic search use search_memories. A comma-separated JSON string is accepted only as a compatibility fallback. Never emit bare comma-separated tokens. ${recallPlanNote} ${memoryCitationInstruction}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -477,6 +495,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.friends,
+            title: "List accepted EchoMem friends",
             description: "Friends: list accepted EchoMem friends with each friend's public memory count. Use this before asking a specific friend by name.",
             inputSchema: {
                 type: "object",
@@ -491,7 +510,8 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.searchUsers,
-            description: "Search EchoMem users by display name/username before sending a friend request. Results include total memories, public memories, and current relationship state.",
+            title: "Search the EchoMem user directory",
+            description: "USER-DIRECTORY SEARCH by display name or username before sending a friend request. This searches people/accounts, not memory content. Results include total memories, public memories, and current relationship state.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -530,12 +550,16 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.others,
-            description: `Search public memories from accepted friends or people who share your company group. 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 inferred identity. For onboarding and division-of-work questions, call get_group_context first, then use this tool for current evidence. Returned memories are recorded in memory_views for the owners. ${memoryCitationInstruction}${groupMapSection}`,
+            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}`,
             inputSchema: {
                 type: "object",
                 properties: {
-                    query: { type: "string" },
-                    limit: { type: "number", default: 10 },
+                    query: {
+                        type: "string",
+                        description: "Optional peer-memory topic. Omit only for an intentional broad browse; never send this field as conversation.",
+                    },
+                    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.",
@@ -562,9 +586,9 @@ export function listToolSpecs(opts = {}) {
                         type: "boolean",
                         description: "Defaults true. When true, returned public memories are recorded in memory_views.",
                     },
-                    kPerUser: { type: "number", default: 5 },
-                    similarityThreshold: { type: "number", default: 0.1 },
-                    timeFrameDays: { type: "number" },
+                    kPerUser: { type: "integer", minimum: 1, maximum: 50, default: 5 },
+                    similarityThreshold: { type: "number", minimum: 0, maximum: 1, default: 0.1 },
+                    timeFrameDays: { type: "integer", minimum: 1, maximum: 3650 },
                     triggerMessage: {
                         type: "string",
                         description: "Optional: the user's message that caused this public-memory search. EchoMem stores only a redacted analytics preview and hash.",
@@ -575,6 +599,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.publicMemory,
+            title: "Get one teammate or friend memory",
             description: `Fetch one public memory by id when its owner is an accepted friend or shares your company group. If the caller is not the owner, EchoMem records the access in memory_views. ${memoryCitationInstruction}`,
             inputSchema: {
                 type: "object",
@@ -892,6 +917,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.getByContext,
+            title: "Get the exact memories from a saved context",
             description: withMcpVersion(`Deterministically re-fetch the exact batch of memories saved under one contextId — no semantic search, no ranking, just that session's saved capsule. ${recallPlanNote} save_conversation returns a contextId; pass it here to pull back precisely those memories, e.g. to warm up a fresh session with what a prior session saved, or to verify the saved facts are still present. ${memoryCitationInstruction} Current time: ${currentTime}.`),
             inputSchema: {
                 type: "object",
@@ -909,6 +935,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.checkpointByContext,
+            title: "Rebuild a checkpoint from a saved context",
             description: withMcpVersion(`Rebuild a clean-context checkpoint / decision log from one EchoMem contextId. ${recallPlanNote} Use this when the user or EchoMem returns a contextId for a renewed coding session and you need the session handoff, not a raw memory dump. It deterministically fetches that context and formats it as orientation state: decisions, carryover, constraints, and checkpoints. ${memoryCitationInstruction} Current time: ${currentTime}.`),
             inputSchema: {
                 type: "object",
@@ -971,19 +998,6 @@ export function listToolSpecs(opts = {}) {
                 },
             },
         },
-        {
-            name: "search_memories_by_time_range",
-            description: "Legacy alias for get_memories_by_time_range.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    startDate: { type: "string" },
-                    endDate: { type: "string" },
-                    limit: { type: "number", default: 50 },
-                },
-                required: ["startDate", "endDate"],
-            },
-        },
     ];
     return tools.map(decorateLocalToolSpec);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.35",
+  "version": "1.4.37",
   "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/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/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/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",
     "prepack": "npm run build && node scripts/bundle-city.mjs"
   },
   "dependencies": {