@echomem/mcp 1.2.0 → 1.3.1

package/dist/index.js

@@ -4,11 +4,11 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
 import { ZodError } from "zod";
-import { canonicalToolNames, keywordsSchema, listToolSpecs, othersSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, timeRangeSchema, } from "./v1-contract.js";
+import { canonicalToolNames, deleteMemorySchema, keywordsSchema, listToolSpecs, othersSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, timeRangeSchema, } from "./v1-contract.js";
 import { KeyStore } from "./keystore.js";
 import { EventLogger, hashText } from "./events.js";
 import { buildReportText } from "./report.js";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { fetchEncryptionConfig, decryptMemoryFields } from "./encryption.js";
 import { runCli } from "./setup.js";
 const ECHO_API_BASE_URL = process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app";
@@ -88,6 +88,277 @@ function classifyError(error) {
         return "invalid_args";
     return "api_error";
 }
+const URL_RE = /\bhttps?:\/\/[^\s<>"')\]]+/i;
+const SECRET_LIKE_RE = /(sk-[A-Za-z0-9_-]{20,}|xox[baprs]-[A-Za-z0-9-]+|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{20,}|-----BEGIN [A-Z ]+PRIVATE KEY-----|\b(api[_-]?key|token|secret|password)\s*[:=])/i;
+const CODE_LIKE_RE = /(```|^\s*(import|export|const|let|var|function|class|interface|type)\s|\b(def|async|await)\s+\w+)/m;
+const DELETE_CONFIRMATION_TTL_MS = 15 * 60 * 1000;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(record, key) {
+    const value = record[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function readNumber(record, key) {
+    const value = record[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function compactOneLine(value, maxLength) {
+    if (!value)
+        return undefined;
+    const compact = value.replace(/\s+/g, " ").trim();
+    if (!compact)
+        return undefined;
+    return compact.length > maxLength ? `${compact.slice(0, maxLength - 3)}...` : compact;
+}
+function memoryDeleteFingerprint(memory) {
+    return [
+        readString(memory, "id"),
+        readString(memory, "updated_at"),
+        readString(memory, "created_at"),
+        readString(memory, "time"),
+        readString(memory, "keys") ?? readString(memory, "key"),
+    ].filter(Boolean).join("|");
+}
+function formatDeletePreview(memory) {
+    const lines = [
+        `Memory ID: ${readString(memory, "id") ?? "(unknown)"}`,
+        readString(memory, "keys") || readString(memory, "key")
+            ? `Keys: ${readString(memory, "keys") ?? readString(memory, "key")}`
+            : "",
+        readString(memory, "time") ? `Time: ${readString(memory, "time")}` : "",
+        readString(memory, "location") ? `Location: ${readString(memory, "location")}` : "",
+        readString(memory, "category") ? `Category: ${readString(memory, "category")}` : "",
+        readString(memory, "object") ? `Object: ${readString(memory, "object")}` : "",
+        readString(memory, "emotion") ? `Emotion: ${readString(memory, "emotion")}` : "",
+        compactOneLine(readString(memory, "description"), 320)
+            ? `Description: ${compactOneLine(readString(memory, "description"), 320)}`
+            : "",
+        compactOneLine(readString(memory, "details"), 240)
+            ? `Details: ${compactOneLine(readString(memory, "details"), 240)}`
+            : "",
+    ].filter(Boolean);
+    return lines.join("\n");
+}
+function redactAnalyticsText(text) {
+    return text
+        .replace(URL_RE, "[url]")
+        .replace(SECRET_LIKE_RE, "[secret-like-text]")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function safeTextAnalytics(prefix, text, previewChars = 300) {
+    if (typeof text !== "string" || text.length === 0) {
+        return {
+            [`${prefix}_available`]: false,
+            [`${prefix}_length`]: 0,
+        };
+    }
+    return {
+        [`${prefix}_available`]: true,
+        [`${prefix}_preview`]: redactAnalyticsText(text).slice(0, previewChars),
+        [`${prefix}_length`]: text.length,
+        [`${prefix}_hash`]: `sha256:${createHash("sha256").update(text).digest("hex")}`,
+        [`${prefix}_contains_url`]: URL_RE.test(text),
+        [`${prefix}_contains_code`]: CODE_LIKE_RE.test(text),
+        [`${prefix}_contains_secret_like_text`]: SECRET_LIKE_RE.test(text),
+    };
+}
+function hashAnalyticsText(text) {
+    return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+function isUserRole(role) {
+    return typeof role === "string" && ["user", "human"].includes(role.toLowerCase());
+}
+function conversationAnalyticsFromMessages(value) {
+    if (!Array.isArray(value))
+        return {};
+    const records = value.filter(isRecord);
+    const userMessages = records
+        .filter((item) => isUserRole(item.role) && readString(item, "content"))
+        .map((item) => readString(item, "content") ?? "");
+    const assistantMessages = records
+        .filter((item) => typeof item.role === "string" && ["assistant", "ai"].includes(item.role.toLowerCase()))
+        .map((item) => readString(item, "content") ?? "");
+    const conversationText = records
+        .map((item) => `${readString(item, "role") ?? "unknown"}: ${typeof item.content === "string" ? item.content : ""}`)
+        .join("\n\n");
+    return {
+        conversation_length: conversationText.length,
+        conversation_hash: conversationText ? hashAnalyticsText(conversationText) : undefined,
+        conversation_message_count: value.length,
+        user_message_count: userMessages.length,
+        assistant_message_count: assistantMessages.length,
+        ...safeTextAnalytics("first_user_message", userMessages[0]),
+        ...safeTextAnalytics("last_user_message", userMessages.at(-1)),
+    };
+}
+function lastUserMessageFromMessages(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    for (let i = value.length - 1; i >= 0; i--) {
+        const item = value[i];
+        if (!isRecord(item) || !isUserRole(item.role))
+            continue;
+        const content = readString(item, "content");
+        if (content)
+            return content;
+    }
+    return undefined;
+}
+function lastUserMessageFromConversationText(value) {
+    if (typeof value !== "string" || !value)
+        return undefined;
+    const markdownUserTurns = [...value.matchAll(/(?:^|\n)##\s+(?:User|Human)[^\n]*\n([\s\S]*?)(?=\n---\n|\n##\s+(?:User|Human|Assistant|AI|System)\b|$)/gi)];
+    const lastMarkdownTurn = markdownUserTurns.at(-1)?.[1]?.trim();
+    if (lastMarkdownTurn)
+        return lastMarkdownTurn;
+    const roleLines = value.split(/\n/);
+    let currentRole = null;
+    let current = [];
+    let lastUser = "";
+    const flush = () => {
+        if (currentRole && isUserRole(currentRole)) {
+            const content = current.join("\n").trim();
+            if (content)
+                lastUser = content;
+        }
+    };
+    for (const line of roleLines) {
+        const match = line.match(/^\s*(user|human|assistant|ai|system)\s*:\s*(.*)$/i);
+        if (match) {
+            flush();
+            currentRole = match[1];
+            current = [match[2] ?? ""];
+        }
+        else if (currentRole) {
+            current.push(line);
+        }
+    }
+    flush();
+    return lastUser || undefined;
+}
+function normalizeRetrievalCandidate(value, fallbackRank) {
+    if (!isRecord(value))
+        return null;
+    const id = readString(value, "memory_id") ?? readString(value, "id");
+    if (!id)
+        return null;
+    return {
+        id,
+        bucket: readString(value, "bucket") ?? "primary",
+        rank: readNumber(value, "rank") ?? fallbackRank,
+        score: readNumber(value, "retrieval_similarity_score")
+            ?? readNumber(value, "similarity_score")
+            ?? readNumber(value, "similarity"),
+        key: readString(value, "key") ?? readString(value, "keys"),
+        time: readString(value, "time"),
+        isPublic: typeof value.is_public === "boolean" ? value.is_public : undefined,
+    };
+}
+function withinTimeFrame(memory, candidate, timeFrameDays) {
+    if (!timeFrameDays)
+        return true;
+    const timestamp = readString(memory, "time") ?? readString(memory, "created_at") ?? candidate.time;
+    if (!timestamp)
+        return true;
+    const ms = Date.parse(timestamp);
+    if (!Number.isFinite(ms))
+        return true;
+    return ms >= Date.now() - timeFrameDays * 24 * 60 * 60 * 1000;
+}
+function numberArg(args, key) {
+    return typeof args[key] === "number" && Number.isFinite(args[key]) ? args[key] : undefined;
+}
+function triggerAnalyticsForTool(canonicalName, args) {
+    const a = isRecord(args) ? args : {};
+    const explicitTrigger = readString(a, "triggerMessage");
+    let triggerText = explicitTrigger;
+    let triggerSource = explicitTrigger ? "tool_argument" : "not_provided_by_mcp_client";
+    if (!triggerText && canonicalName === canonicalToolNames.save) {
+        triggerText =
+            lastUserMessageFromMessages(a.messages) ??
+                lastUserMessageFromConversationText(a.conversation);
+        triggerSource = triggerText ? "conversation_payload_inferred" : triggerSource;
+    }
+    if (!triggerText) {
+        return {
+            trigger_message_available: false,
+            trigger_message_source: triggerSource,
+        };
+    }
+    return {
+        trigger_message_source: triggerSource,
+        trigger_message_role: readString(a, "triggerMessageRole") ?? "user",
+        ...safeTextAnalytics("trigger_message", triggerText),
+    };
+}
+function inputAnalyticsForTool(canonicalName, args) {
+    const a = isRecord(args) ? args : {};
+    switch (canonicalName) {
+        case canonicalToolNames.search: {
+            const query = readString(a, "query");
+            const queryAnalytics = safeTextAnalytics("query", query);
+            return {
+                ...queryAnalytics,
+                query_preview_safe: queryAnalytics.query_preview,
+                query_length: query?.length ?? 0,
+                limit: numberArg(a, "limit") ?? numberArg(a, "k"),
+                threshold: numberArg(a, "threshold"),
+                time_frame_days: numberArg(a, "timeFrameDays"),
+                include_answer: typeof a.includeAnswer === "boolean" ? a.includeAnswer : undefined,
+            };
+        }
+        case canonicalToolNames.save: {
+            const messages = Array.isArray(a.messages) ? a.messages : undefined;
+            const conversation = typeof a.conversation === "string" ? a.conversation : undefined;
+            return {
+                input_mode: messages?.length ? "messages" : "conversation",
+                message_count: messages?.length,
+                content_length: messages?.reduce((sum, item) => {
+                    if (!isRecord(item))
+                        return sum;
+                    return sum + String(item.content ?? "").length;
+                }, 0) ?? conversation?.length ?? 0,
+                ...(messages?.length
+                    ? conversationAnalyticsFromMessages(messages)
+                    : {
+                        conversation_length: conversation?.length ?? 0,
+                        conversation_hash: conversation ? hashAnalyticsText(conversation) : undefined,
+                    }),
+                has_title: !!readString(a, "title"),
+                has_url: !!readString(a, "url"),
+                has_source: !!readString(a, "source"),
+                tag_count: Array.isArray(a.tags) ? a.tags.length : undefined,
+            };
+        }
+        case canonicalToolNames.timeRange:
+            return {
+                limit: numberArg(a, "limit"),
+                has_start_date: !!readString(a, "startDate"),
+                has_end_date: !!readString(a, "endDate"),
+            };
+        case canonicalToolNames.keywords:
+            return {
+                keyword_count: Array.isArray(a.keywords) ? a.keywords.length : 0,
+                limit: numberArg(a, "limit"),
+            };
+        case canonicalToolNames.others: {
+            const query = readString(a, "query");
+            const queryAnalytics = safeTextAnalytics("query", query);
+            return {
+                ...queryAnalytics,
+                query_preview_safe: queryAnalytics.query_preview,
+                query_length: query?.length ?? 0,
+            };
+        }
+        default:
+            return {};
+    }
+}
+function toolEventName(canonicalName, status) {
+    return `[MCP] ${canonicalName} ${status}`;
+}
 class EchoMemApiClient {
     store;
     axios;
@@ -95,6 +366,7 @@ class EchoMemApiClient {
     /** One id per bridge process — groups all saves from this coding session under a single EchoMem context. */
     sessionId = randomUUID();
     encConfigPromise = null;
+    deleteConfirmations = new Map();
     constructor(store) {
         this.store = store;
         this.axios = axios.create({
@@ -120,6 +392,16 @@ class EchoMemApiClient {
     getSessionId() {
         return this.sessionId;
     }
+    async trackMcpAnalyticsEvent(eventType, eventProperties) {
+        if (!this.hasToken())
+            return;
+        try {
+            await this.axios.post("/api/extension/mcp/events", { eventType, eventProperties }, { timeout: 1500 });
+        }
+        catch {
+            // Remote analytics is best-effort and must never change MCP behavior.
+        }
+    }
     /**
      * Compact topic map of the user's memory for the search-tool description — a cheap "what's in here"
      * index built from memory keys so the agent knows the boundary up front and recalls proactively.
@@ -171,10 +453,17 @@ class EchoMemApiClient {
             throw new LockedError(this.store.isKeyExpired());
         return { enabled: false };
     }
+    pruneDeleteConfirmations(now = Date.now()) {
+        for (const [memoryId, confirmation] of this.deleteConfirmations) {
+            if (confirmation.expiresAtMs <= now) {
+                this.deleteConfirmations.delete(memoryId);
+            }
+        }
+    }
     async whoami() {
         if (!this.whoamiCache) {
             this.whoamiCache = this.axios
-                .get("/api/openclaw/v1/whoami")
+                .get("/api/openclaw/v1/whoami", { timeout: 6000 })
                 .then((response) => response.data)
                 .catch((error) => {
                 this.whoamiCache = null; // don't pin a token-less failure; retry once a token exists
@@ -190,6 +479,89 @@ class EchoMemApiClient {
         const idx = desc.indexOf("Content:");
         return (idx >= 0 ? desc.slice(idx + "Content:".length) : desc).trim();
     }
+    async fetchMemoryById(id, enc) {
+        try {
+            const response = await this.axios.get(`/api/extension/memories/${encodeURIComponent(id)}`, {
+                timeout: 10_000,
+            });
+            const row = isRecord(response.data) ? response.data : {};
+            return enc.enabled ? await decryptMemoryFields(row, enc.key) : row;
+        }
+        catch (error) {
+            if (axios.isAxiosError(error) && error.response?.status === 404) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async searchMemoriesRaw(query, opts, enc, retrievalOnly = false) {
+        const response = await this.axios.post("/api/extension/memories/search", {
+            query,
+            k: opts.limit,
+            similarityThreshold: opts.threshold,
+            timeFrameDays: opts.timeFrameDays,
+        });
+        const data = enc.enabled ? await this.decryptResult(response.data, enc.key) : response.data;
+        return retrievalOnly && isRecord(data)
+            ? { ...data, retrievalOnly: true, tuned: false }
+            : data;
+    }
+    async searchMemoriesRetrieved(query, opts, enc) {
+        const response = await this.axios.post("/api/extension/memories/deep-search/candidates", {
+            query,
+            userTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
+        });
+        const data = response.data ?? {};
+        if (data.success === false) {
+            throw new Error(`deep-search candidates proxy error: ${data.error || "unknown"}`);
+        }
+        const rawCandidates = Array.isArray(data.personalCandidates) ? data.personalCandidates : [];
+        const candidates = rawCandidates
+            .map((candidate, index) => normalizeRetrievalCandidate(candidate, index))
+            .filter((candidate) => candidate !== null);
+        const primaryIds = new Set(candidates.filter((c) => c.bucket === "primary").map((c) => c.id));
+        const seen = new Set();
+        const dedupedCandidates = candidates.filter((candidate) => {
+            if (candidate.bucket === "inference" && primaryIds.has(candidate.id))
+                return false;
+            if (candidate.score !== undefined && candidate.score < opts.threshold)
+                return false;
+            if (seen.has(candidate.id))
+                return false;
+            seen.add(candidate.id);
+            return true;
+        });
+        const memories = [];
+        for (const candidate of dedupedCandidates) {
+            const row = await this.fetchMemoryById(candidate.id, enc);
+            if (!row || !withinTimeFrame(row, candidate, opts.timeFrameDays))
+                continue;
+            const key = readString(row, "key") ?? readString(row, "keys") ?? candidate.key ?? "";
+            const memory = {
+                ...row,
+                id: readString(row, "id") ?? candidate.id,
+                key,
+                keys: readString(row, "keys") ?? key,
+                retrieval_bucket: candidate.bucket,
+                retrieval_rank: candidate.rank,
+                is_public: typeof row.is_public === "boolean" ? row.is_public : candidate.isPublic,
+            };
+            if (candidate.score !== undefined) {
+                memory.similarity = candidate.score;
+                memory.similarity_score = candidate.score;
+                memory.retrieval_similarity_score = candidate.score;
+            }
+            memories.push(memory);
+            if (memories.length >= opts.limit)
+                break;
+        }
+        return {
+            success: true,
+            tuned: true,
+            retrievalOnly: true,
+            memories,
+        };
+    }
     // Tuned recall. Routes through echo-mem-chrome's AUTHENTICATED deep-search proxy
     // (the same route the Chrome extension uses): it verifies our ec_ token, derives
     // user_id server-side, and forwards to dg-web's two-phase retriever. The bridge
@@ -233,29 +605,26 @@ class EchoMemApiClient {
             });
             return enc.enabled ? await this.decryptResult(response.data, enc.key) : response.data;
         }
+        const searchOpts = { limit, threshold, timeFrameDays: parsed.timeFrameDays };
+        if (!parsed.includeAnswer) {
+            try {
+                return await this.searchMemoriesRetrieved(query, searchOpts, enc);
+            }
+            catch {
+                return await this.searchMemoriesRaw(query, searchOpts, enc, true);
+            }
+        }
         // Encrypted account: the server can't synthesize over plaintext it doesn't hold, so use the raw
         // retriever (returns ciphertext) and decrypt locally — zero-knowledge preserved end-to-end.
         if (enc.enabled) {
-            const response = await this.axios.post("/api/extension/memories/search", {
-                query,
-                k: limit,
-                similarityThreshold: threshold,
-                timeFrameDays: parsed.timeFrameDays,
-            });
-            return await this.decryptResult(response.data, enc.key);
+            return await this.searchMemoriesRaw(query, searchOpts, enc);
         }
         // Unencrypted: prefer the tuned two-phase retriever; degrade gracefully to the untuned path.
         try {
             return await this.searchMemoriesTuned(query);
         }
         catch {
-            const response = await this.axios.post("/api/extension/memories/search", {
-                query,
-                k: limit,
-                similarityThreshold: threshold,
-                timeFrameDays: parsed.timeFrameDays,
-            });
-            return response.data;
+            return await this.searchMemoriesRaw(query, searchOpts, enc);
         }
     }
     /** Decrypt the model-visible fields on a `{ memories: [...] }` response locally. */
@@ -288,9 +657,57 @@ class EchoMemApiClient {
             title: parsed.title,
             // Stable per-session id so multiple saves in this coding session group under one context.
             conversationKey: this.sessionId,
+            triggerMessage: parsed.triggerMessage ||
+                lastUserMessageFromMessages(parsed.messages) ||
+                lastUserMessageFromConversationText(parsed.conversation),
+            triggerMessageRole: parsed.triggerMessageRole || "user",
         }, config);
         return response.data;
     }
+    async deleteMemory(args) {
+        const parsed = deleteMemorySchema.parse(args);
+        const enc = await this.encState();
+        const memory = await this.fetchMemoryById(parsed.memoryId, enc);
+        if (!memory) {
+            return { success: false, notFound: true, memoryId: parsed.memoryId };
+        }
+        this.pruneDeleteConfirmations();
+        const fingerprint = memoryDeleteFingerprint(memory);
+        if (!parsed.confirmed) {
+            const token = randomUUID();
+            const expiresAtMs = Date.now() + DELETE_CONFIRMATION_TTL_MS;
+            this.deleteConfirmations.set(parsed.memoryId, { token, expiresAtMs, fingerprint });
+            return {
+                success: true,
+                confirmationRequired: true,
+                memory,
+                confirmationToken: token,
+                expiresAt: new Date(expiresAtMs).toISOString(),
+            };
+        }
+        const confirmation = this.deleteConfirmations.get(parsed.memoryId);
+        if (!parsed.confirmationToken || !confirmation || confirmation.token !== parsed.confirmationToken) {
+            throw new McpError(ErrorCode.InvalidParams, "Deletion requires the exact confirmationToken returned by a prior delete_memory preview call.");
+        }
+        if (confirmation.expiresAtMs <= Date.now()) {
+            this.deleteConfirmations.delete(parsed.memoryId);
+            throw new McpError(ErrorCode.InvalidParams, "Deletion confirmation expired. Call delete_memory again with confirmed=false to generate a fresh preview.");
+        }
+        if (confirmation.fingerprint !== fingerprint) {
+            this.deleteConfirmations.delete(parsed.memoryId);
+            throw new McpError(ErrorCode.InvalidParams, "Memory changed after the confirmation preview. Call delete_memory again with confirmed=false before deleting.");
+        }
+        const response = await this.axios.delete(`/api/extension/memories/${encodeURIComponent(parsed.memoryId)}`, {
+            timeout: 10_000,
+        });
+        this.deleteConfirmations.delete(parsed.memoryId);
+        return {
+            success: true,
+            deleted: response.data?.success === true,
+            memory,
+            memoryId: parsed.memoryId,
+        };
+    }
     async getMemoriesByTimeRange(args) {
         const parsed = timeRangeSchema.parse(args);
         const enc = await this.encState();
@@ -313,9 +730,7 @@ class EchoMemApiClient {
     async searchOthersMemories(args) {
         const parsed = othersSchema.parse(args);
         try {
-            const whoami = await this.whoami();
-            const response = await axios.post(`${MEMORY_FEED_API_URL.replace(/\/$/, "")}/api/search`, {
-                userId: whoami.user_id,
+            const response = await axios.post(`${MEMORY_FEED_API_URL.replace(/\/$/, "")}/api/search/public`, {
                 query: parsed.query,
                 excludedMemoryIds: [],
             }, {
@@ -361,15 +776,36 @@ class EchoMemMCPServer {
             this.events.setClient(this.server.getClientVersion()?.name);
             // Inject a compact topic map of the user's memory into the search-tool description so the agent
             // knows the boundary up front and recalls proactively (cached; best-effort — no map on failure).
-            if (this.client.hasToken() && !this.mapCache)
+            if (this.client.hasToken() && !this.mapCache) {
                 this.mapCache = this.client.fetchMemoryMap();
-            const map = this.mapCache ? await this.mapCache : undefined;
+                // Don't poison the cache on a transient failure → clear it so a later listing can retry.
+                this.mapCache.then((m) => { if (!m)
+                    this.mapCache = null; }).catch(() => { this.mapCache = null; });
+            }
+            // NEVER block tool-listing on the network. A flaky/unreachable API would otherwise hang the MCP
+            // handshake and freeze the whole agent ("connection timed out after 30000ms"). The map is
+            // best-effort: cap the wait, and it'll be injected on the next listing once it resolves.
+            const map = this.mapCache
+                ? await Promise.race([this.mapCache, new Promise((r) => setTimeout(() => r(undefined), 2500))])
+                : undefined;
             this.mapInjected = !!map;
             return { tools: listToolSpecs({ map }) };
         });
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const canonicalName = resolveCanonicalToolName(request.params.name);
             const t0 = Date.now();
+            const analyticsBase = {
+                surface: "mcp",
+                event_family: "mcp",
+                integration: "echomem_mcp",
+                telemetry_source: "local_bridge",
+                codex_session_id: this.client.getSessionId(),
+                conversation_id: this.client.getSessionId(),
+                tool_name: request.params.name,
+                canonical_tool_name: canonicalName,
+                ...triggerAnalyticsForTool(canonicalName, request.params.arguments),
+                ...inputAnalyticsForTool(canonicalName, request.params.arguments),
+            };
             // One event per call. Handlers enrich `rec` with tool-specific detail; we finalize + log in `finally`.
             const rec = {
                 type: "tool_call",
@@ -383,6 +819,13 @@ class EchoMemMCPServer {
                 }
                 if (!this.client.hasToken())
                     throw new NoTokenError();
+                if (canonicalName !== canonicalToolNames.save) {
+                    void this.client.trackMcpAnalyticsEvent("[MCP] EchoMem Tool Called", analyticsBase);
+                    void this.client.trackMcpAnalyticsEvent(toolEventName(canonicalName, "Called"), analyticsBase);
+                }
+                if (canonicalName !== canonicalToolNames.save && analyticsBase.trigger_message_available === true) {
+                    void this.client.trackMcpAnalyticsEvent("[MCP] EchoMem Triggered By User Turn", analyticsBase);
+                }
                 switch (canonicalName) {
                     case canonicalToolNames.search:
                         return await this.handleSearch(request.params.arguments, rec);
@@ -394,6 +837,8 @@ class EchoMemMCPServer {
                         return await this.handleKeywords(request.params.arguments);
                     case canonicalToolNames.others:
                         return await this.handleOthers(request.params.arguments);
+                    case canonicalToolNames.delete:
+                        return await this.handleDelete(request.params.arguments, rec);
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
                 }
@@ -441,6 +886,24 @@ class EchoMemMCPServer {
                 rec.ok = rec.error_kind === "none";
                 rec.latency_ms = Date.now() - t0;
                 this.events.record(rec);
+                if (canonicalName !== canonicalToolNames.report &&
+                    canonicalName !== canonicalToolNames.save &&
+                    this.client.hasToken()) {
+                    const finalAnalytics = {
+                        ...analyticsBase,
+                        success: rec.ok,
+                        duration_ms: rec.latency_ms,
+                        error_type: rec.error_kind === "none" ? undefined : rec.error_kind,
+                        result_count: rec.results_count,
+                        returned_text_length: rec.results_chars,
+                        tuned: rec.tuned,
+                        map_injected: rec.map_injected,
+                        encrypted_user: rec.encrypted,
+                        extracted_memory_count: rec.memories_extracted,
+                    };
+                    void this.client.trackMcpAnalyticsEvent(rec.ok ? "[MCP] EchoMem Tool Succeeded" : "[MCP] EchoMem Tool Failed", finalAnalytics);
+                    void this.client.trackMcpAnalyticsEvent(toolEventName(canonicalName, rec.ok ? "Succeeded" : "Failed"), finalAnalytics);
+                }
             }
         });
     }
@@ -459,6 +922,47 @@ class EchoMemMCPServer {
             rec.results_chars = mems.reduce((n, m) => n + String(m?.description ?? "").length, 0);
             rec.memory_keys = mems.map((m) => String(m?.key ?? m?.keys ?? "").trim()).filter(Boolean).slice(0, 40);
         }
+        // Default MCP recall path: return only retrieved memories. The calling agent does the answer
+        // generation, so we avoid spending an extra EchoMem model call and avoid double synthesis.
+        if (result?.retrievalOnly) {
+            const memories = Array.isArray(result.memories) ? result.memories.filter(isRecord) : [];
+            if (!memories.length) {
+                return { content: [{ type: "text", text: "No relevant memories found." }] };
+            }
+            const formattedResults = memories
+                .map((m, idx) => {
+                const key = readString(m, "key") ?? readString(m, "keys") ?? "Saved memory";
+                const score = readNumber(m, "similarity")
+                    ?? readNumber(m, "similarity_score")
+                    ?? readNumber(m, "retrieval_similarity_score");
+                const meta = [
+                    readString(m, "time") ? `Time: ${readString(m, "time")}` : "",
+                    readString(m, "location") ? `Location: ${readString(m, "location")}` : "",
+                    readString(m, "category") ? `Category: ${readString(m, "category")}` : "",
+                    readString(m, "object") ? `Object: ${readString(m, "object")}` : "",
+                    readString(m, "emotion") ? `Emotion: ${readString(m, "emotion")}` : "",
+                    readString(m, "retrieval_bucket") ? `Bucket: ${readString(m, "retrieval_bucket")}` : "",
+                ].filter(Boolean).join(" | ");
+                const description = typeof m.description === "string"
+                    ? m.description
+                    : m.description == null
+                        ? ""
+                        : String(m.description);
+                const details = typeof m.details === "string"
+                    ? m.details.trim()
+                    : m.details == null
+                        ? ""
+                        : String(m.details).trim();
+                return [
+                    `[${idx + 1}] ${key}${typeof score === "number" ? ` (score ${score.toFixed(3)})` : ""}`,
+                    meta,
+                    `Description: ${description}`,
+                    details ? `Details: ${details}` : "",
+                ].filter(Boolean).join("\n");
+            })
+                .join("\n\n");
+            return { content: [{ type: "text", text: `Retrieved ${memories.length} memories:\n\n${formattedResults}` }] };
+        }
         // Tuned two-phase path: synthesized brief + ranked source memories.
         if (result?.tuned) {
             const { answer, memories } = result;
@@ -584,6 +1088,56 @@ Details: ${m.details || "N/A"}`)
             ],
         };
     }
+    async handleDelete(args, rec) {
+        const parsed = deleteMemorySchema.parse(args);
+        if (rec) {
+            rec.memory_id_hash = hashText(parsed.memoryId);
+            rec.delete_confirmed = parsed.confirmed;
+        }
+        const result = await this.client.deleteMemory(args);
+        if (result.notFound) {
+            return {
+                content: [{ type: "text", text: `Memory ${result.memoryId} was not found or is not accessible.` }],
+            };
+        }
+        if (result.confirmationRequired) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Deletion requires explicit user confirmation. No memory was deleted.",
+                            "",
+                            formatDeletePreview(result.memory),
+                            "",
+                            `confirmationToken: ${result.confirmationToken}`,
+                            `expiresAt: ${result.expiresAt}`,
+                            "",
+                            "Ask the user whether to delete this memory. If and only if they confirm, call delete_memory again with confirmed=true and this exact confirmationToken.",
+                            "This deletes the memory row only; raw source_of_truth conversation records are preserved.",
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
+        if (!result.deleted) {
+            throw new Error("EchoMem API Error: delete request did not report success.");
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `Deleted memory ${result.memoryId}.`,
+                        "",
+                        formatDeletePreview(result.memory),
+                        "",
+                        "Raw source_of_truth conversation records were preserved.",
+                    ].join("\n"),
+                },
+            ],
+        };
+    }
     async run() {
         const transport = new StdioServerTransport();
         await this.server.connect(transport);