@echomem/mcp 1.4.19 → 1.4.21

package/dist/v1-contract.js

@@ -117,7 +117,7 @@ export function listToolSpecs(opts = {}) {
     return [
         {
             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}${mapSection}\nReturns the ranked memories; set includeAnswer=true only if you need the legacy synthesized answer. Current time: ${currentTime}.${updateSection}`),
+            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}${mapSection}\nReturns ranked memories only; the MCP host model writes the final answer. Current time: ${currentTime}.${updateSection}`),
             inputSchema: {
                 type: "object",
                 properties: {
@@ -125,11 +125,6 @@ export function listToolSpecs(opts = {}) {
                     limit: { type: "number", default: 10 },
                     threshold: { type: "number", default: 0.1 },
                     timeFrameDays: { type: "number" },
-                    includeAnswer: {
-                        type: "boolean",
-                        default: false,
-                        description: "Default false: return only retrieved memories and skip answer generation. Set true for the legacy synthesized recall answer.",
-                    },
                     triggerMessage: {
                         type: "string",
                         description: "Optional: the user's message that caused this recall. EchoMem stores only a redacted analytics preview and hash.",
@@ -148,11 +143,6 @@ export function listToolSpecs(opts = {}) {
                     limit: { type: "number", default: 10 },
                     threshold: { type: "number", default: 0.1 },
                     timeFrameDays: { type: "number" },
-                    includeAnswer: {
-                        type: "boolean",
-                        default: false,
-                        description: "Default false: return only retrieved memories and skip answer generation. Set true for the legacy synthesized recall answer.",
-                    },
                     triggerMessage: {
                         type: "string",
                         description: "Optional: the user's message that caused this recall. EchoMem stores only a redacted analytics preview and hash.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.19",
+  "version": "1.4.21",
   "description": "EchoMem MCP bridge: cloud-first memory tools, local context HUD, and the Agent Doctor workspace forensics report (cost ledger + 3D repo city)",
   "main": "dist/index.js",
   "type": "module",
@@ -22,7 +22,11 @@
     "dev": "node dist/index.js",
     "smoke": "node smoke.mjs",
     "preview:extraction": "npm run build && node scripts/preview-extraction.mjs",
-    "test": "npm run build && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.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/update-check.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/hud.test.mjs",
+    "test:artifact": "npm run build && node test/package-artifact.test.mjs",
+    "test:registry": "node test/registry-artifact.test.mjs",
+    "test:registry-ui": "npm run build && node test/registry-ui.test.mjs",
+    "test:ui": "npm run build && node test/setup-ui.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/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/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/hud.test.mjs",
     "prepack": "npm run build && node scripts/bundle-city.mjs"
   },
   "dependencies": {

package/templates/codex-skills/echomem-forget/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: echomem-forget
+description: Find, review, and delete outdated or incorrect memories from EchoMem. Use when the user asks EchoMem to forget, remove, or correct remembered information, or says a stored fact is no longer true. Require an explicit confirmation before the destructive delete step and do not operate on another memory provider unless requested.
+---
+
+# EchoMem Forget
+
+Use EchoMem's two-step deletion workflow.
+
+1. Search EchoMem when needed to identify the exact memory and its ID.
+2. Call `delete_memory` with the memory ID only to preview the target and receive a confirmation token.
+3. Show the preview and ask the user to confirm deletion of that exact memory.
+4. Only after confirmation, call `delete_memory` with `confirmed: true` and the exact token.
+5. If the user supplied corrected information, offer to save the replacement with `save_conversation` after deletion.
+
+Never bypass the preview or confirmation step.

package/templates/codex-skills/echomem-forget/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "EchoMem Forget"
+  short_description: "Review and delete an EchoMem memory"
+  default_prompt: "Use $echomem-forget to find the outdated memory, show me what will be deleted, and ask for confirmation."
+policy:
+  allow_implicit_invocation: true

package/templates/codex-skills/echomem-login/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: echomem-login
+description: Connect, authenticate, diagnose, or unlock the local EchoMem MCP bridge. Use when EchoMem reports a missing token, locked or expired encryption key, disconnected MCP server, setup problem, or when the user asks to log in, connect a device, check EchoMem status, or unlock their memory vault.
+---
+
+# EchoMem Login
+
+Use the installed EchoMem CLI and keep credentials out of chat and client configuration.
+
+- Run `echomem-mcp status` to diagnose the current connection.
+- Run `echomem-mcp login` to connect the device through the browser approval flow.
+- EchoMem treats the MCP bridge as a trusted device. A verified local key stays available until the
+  user runs `echomem-mcp lock`, logs out, or removes the local credentials. When the key is absent,
+  tell the user to open their own Terminal and run `echomem-mcp unlock`.
+- Run `echomem-mcp setup --client codex --skip-login` when the MCP entry itself is missing.
+
+Do not run the bare interactive `echomem-mcp unlock` command through an agent shell: it waits for a
+private passphrase that the user must enter themselves. Tell the user that the prompt reads
+`Vault passphrase (typing is hidden):`, no characters appear while typing, and they should press
+Return when finished. After it succeeds, retry the MCP action in the current session; no editor
+restart is needed.
+
+Use `echomem-mcp lock` when the user wants to remove the local vault key without disconnecting their
+device login.
+
+Prefer the interactive browser flow for login. Never print, log, or ask the user to paste tokens,
+passphrases, or encryption keys into the conversation or expose them through command-line flags.

package/templates/codex-skills/echomem-login/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "EchoMem Login"
+  short_description: "Connect or unlock EchoMem locally"
+  default_prompt: "Use $echomem-login to connect this device to EchoMem or unlock my encrypted memory vault."
+policy:
+  allow_implicit_invocation: true

package/templates/codex-skills/echomem-save/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: echomem-save
+description: Save durable knowledge to EchoMem, the user's cross-agent long-term memory. Use when the user asks to remember, save, preserve, or carry forward information, or when active EchoMem guidance requires capturing a meaningful decision, resolved bug, architectural choice, preference, or project milestone. Prefer EchoMem when it is connected; do not silently save to another memory provider.
+---
+
+# EchoMem Save
+
+Use the `save_conversation` tool from the `echomem` MCP server.
+
+1. Capture the goal, decision or outcome, important reasoning, and relevant files or constraints. Omit noise and unrelated transcript content.
+2. Prefer structured `messages`; add a concise title, source, and useful tags.
+3. Use `passthrough: true` only when the user explicitly needs a verbatim session capsule.
+4. Never include secrets, credentials, or unnecessary sensitive content.
+5. Confirm what EchoMem saved. If saving fails, report the failure without switching providers silently.

package/templates/codex-skills/echomem-save/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "EchoMem Save"
+  short_description: "Save durable project knowledge to EchoMem"
+  default_prompt: "Use $echomem-save to preserve this decision and its important context in EchoMem."
+policy:
+  allow_implicit_invocation: true

package/templates/codex-skills/echomem-search/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: echomem-search
+description: Search EchoMem, the user's cross-agent long-term memory, for prior decisions, preferences, project context, and past work. Use when a request refers to previous work or sessions, asks what was decided or how something was implemented, needs a catch-up, or plausibly depends on context the user settled before. Prefer EchoMem when it is connected; do not silently substitute another memory provider.
+---
+
+# EchoMem Search
+
+Use the `echomem` MCP server as the source of long-term memory.
+
+1. Call `search_memories` with a concise query describing the context needed. Keep `includeAnswer` false unless an EchoMem-generated synthesis is specifically useful.
+2. Use `get_memories_by_time_range` for explicit dates, `search_memories_by_keywords` for exact terms, and `get_checkpoint_by_context` when a carryover references an EchoMem checkpoint.
+3. Distinguish recalled facts from inference and preserve dates or provenance returned by EchoMem.
+4. If EchoMem returns an action-required URL, give the user that exact URL and explanation.
+5. If EchoMem is unavailable, say so. Do not switch to another memory provider unless the user requests it.

package/templates/codex-skills/echomem-search/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "EchoMem Search"
+  short_description: "Recall decisions and context from EchoMem"
+  default_prompt: "Use $echomem-search to recall my prior decisions and relevant project context before continuing."
+policy:
+  allow_implicit_invocation: true

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

@@ -1,315 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-/**
- * Convert a Claude Code transcript into the event vocabulary consumed by the
- * vendored canonical scorer. The scorer itself remains provider-independent:
- * this adapter is the only place where Claude's JSONL shape is interpreted.
- */
-export function normalizeClaudeSessionForCanonical(file) {
-    const rows = readRows(file);
-    const sessionId = firstString(rows, "sessionId") || path.basename(file, ".jsonl");
-    const cwd = firstString(rows, "cwd");
-    const dynamicTools = collectToolNames(rows).map((name) => ({ name }));
-    const inferredOverheadTokens = inferClaudeOverheadTokens(rows);
-    const toolTokens = Math.round(JSON.stringify(dynamicTools).length / 3.3);
-    const instructionTokens = Math.max(0, inferredOverheadTokens - toolTokens);
-    const records = [codexRecord("session_meta", {
-            type: "session_meta",
-            id: sessionId,
-            cwd,
-            base_instructions: { text: "x".repeat(instructionTokens * 4) },
-            dynamic_tools: dynamicTools,
-        }, firstTimestamp(rows))];
-    const calls = new Map();
-    let hasUserTurn = false;
-    for (const row of rows) {
-        const timestamp = stringValue(row.timestamp) || firstTimestamp(rows);
-        const type = stringValue(row.type);
-        if (type === "user") {
-            const message = recordValue(row.message);
-            const content = message.content;
-            if (isToolResultContent(content)) {
-                if (!hasUserTurn)
-                    continue;
-                for (const block of arrayValue(content)) {
-                    if (!isRecord(block) || block.type !== "tool_result")
-                        continue;
-                    const callId = stringValue(block.tool_use_id);
-                    const call = calls.get(callId);
-                    if (!call || call.mode === "write")
-                        continue;
-                    records.push(codexRecord("response_item", {
-                        type: "function_call_output",
-                        call_id: callId,
-                        output: normalizeToolResult(block.content),
-                    }, timestamp));
-                }
-                continue;
-            }
-            const messageText = extractText(content);
-            const imageCount = countImages(content);
-            records.push(codexRecord("event_msg", {
-                type: "user_message",
-                message: messageText,
-                ...(imageCount > 0 ? { images: Array.from({ length: imageCount }, () => ({ type: "input_image" })) } : {}),
-            }, timestamp));
-            hasUserTurn = true;
-            continue;
-        }
-        if (type === "system" && hasUserTurn && (row.subtype === "compact_boundary" || row.subtype === "context_compacted")) {
-            records.push(codexRecord("event_msg", { type: "context_compacted" }, timestamp));
-            continue;
-        }
-        if (type !== "assistant" || !hasUserTurn)
-            continue;
-        const message = recordValue(row.message);
-        const usage = recordValue(message.usage);
-        const inputTokens = claudeOfficialInputTokens(usage);
-        if (inputTokens > 0) {
-            records.push(codexRecord("event_msg", {
-                type: "token_count",
-                info: {
-                    last_token_usage: {
-                        input_tokens: inputTokens,
-                        cached_input_tokens: numberValue(usage.cache_read_input_tokens),
-                        output_tokens: numberValue(usage.output_tokens),
-                    },
-                },
-            }, timestamp));
-        }
-        for (const block of arrayValue(message.content)) {
-            if (!isRecord(block))
-                continue;
-            if (block.type === "thinking") {
-                records.push(codexRecord("response_item", { type: "reasoning" }, timestamp));
-                continue;
-            }
-            if (block.type === "text") {
-                const text = stringValue(block.text);
-                if (text)
-                    records.push(codexRecord("event_msg", { type: "agent_message", message: text }, timestamp));
-                continue;
-            }
-            if (block.type !== "tool_use")
-                continue;
-            const normalized = normalizeToolUse(block);
-            if (!normalized)
-                continue;
-            calls.set(normalized.call.callId, normalized.call);
-            records.push(...normalized.records.map((record) => ({ ...record, timestamp })));
-        }
-    }
-    return {
-        jsonl: `${records.map((record) => JSON.stringify(record)).join("\n")}\n`,
-        sessionId,
-        cwd,
-        inferredOverheadTokens,
-    };
-}
-function normalizeToolUse(block) {
-    const name = stringValue(block.name);
-    const callId = stringValue(block.id);
-    if (!name || !callId)
-        return null;
-    const input = recordValue(block.input);
-    if (/^(Write|Edit|MultiEdit|NotebookEdit)$/i.test(name)) {
-        const file = stringValue(input.file_path) || stringValue(input.notebook_path) || stringValue(input.path) || "unknown";
-        const patch = syntheticPatch(name, file, input);
-        return {
-            call: { mode: "write", callId },
-            records: [
-                codexRecord("response_item", { type: "custom_tool_call", name: "apply_patch", call_id: callId, input: patch }, ""),
-                codexRecord("event_msg", { type: "patch_apply_end", changes: { [file]: { kind: /^Write$/i.test(name) ? "added" : "modified" } } }, ""),
-            ],
-        };
-    }
-    const command = commandForClaudeTool(name, input);
-    if (command) {
-        return {
-            call: { mode: "function", callId },
-            records: [codexRecord("response_item", {
-                    type: "function_call",
-                    name: "exec_command",
-                    call_id: callId,
-                    arguments: JSON.stringify({ cmd: command }),
-                }, "")],
-        };
-    }
-    return {
-        call: { mode: "function", callId },
-        records: [codexRecord("response_item", {
-                type: "function_call",
-                name: visualToolName(name) ? "view_image" : name,
-                call_id: callId,
-                arguments: JSON.stringify(input),
-            }, "")],
-    };
-}
-function commandForClaudeTool(name, input) {
-    if (/^Bash$/i.test(name))
-        return stringValue(input.command) || "bash";
-    if (/^(Read|NotebookRead)$/i.test(name)) {
-        const file = stringValue(input.file_path) || stringValue(input.notebook_path) || stringValue(input.path) || "unknown";
-        const offset = Math.max(1, numberValue(input.offset) || 1);
-        const limit = Math.max(1, numberValue(input.limit) || 2000);
-        return `sed -n '${offset},${offset + limit - 1}p' ${quoteArg(file)}`;
-    }
-    if (/^Grep$/i.test(name)) {
-        const pattern = stringValue(input.pattern) || stringValue(input.query) || "unknown";
-        const target = stringValue(input.path) || ".";
-        return `rg -n ${quoteArg(pattern)} ${quoteArg(target)}`;
-    }
-    if (/^Glob$/i.test(name))
-        return `rg --files ${quoteArg(stringValue(input.path) || ".")}`;
-    if (/^(LS|ListFiles)$/i.test(name))
-        return `ls ${quoteArg(stringValue(input.path) || ".")}`;
-    if (/^(WebSearch|WebFetch)$/i.test(name)) {
-        const query = stringValue(input.query) || stringValue(input.url) || "web";
-        return `rg ${quoteArg(`web:${query}`)} web`;
-    }
-    return null;
-}
-function syntheticPatch(name, file, input) {
-    const chunks = [];
-    const content = stringValue(input.content) || stringValue(input.new_string) || stringValue(input.new_source);
-    if (content)
-        chunks.push(content);
-    for (const edit of arrayValue(input.edits)) {
-        if (!isRecord(edit))
-            continue;
-        const value = stringValue(edit.new_string) || stringValue(edit.new_source) || stringValue(edit.content);
-        if (value)
-            chunks.push(value);
-    }
-    const body = chunks.join("\n") || `${name} ${file}`;
-    return `*** Begin Patch\n*** ${/^Write$/i.test(name) ? "Add" : "Update"} File: ${file}\n@@\n${body}\n*** End Patch\n`;
-}
-function inferClaudeOverheadTokens(rows) {
-    let firstUserTokens = 0;
-    let firstUserImages = 0;
-    let awaitingUsage = false;
-    for (const row of rows) {
-        const type = stringValue(row.type);
-        if (type === "user" && !isToolResultContent(recordValue(row.message).content)) {
-            if (!awaitingUsage) {
-                const content = recordValue(row.message).content;
-                firstUserTokens = Math.round(extractText(content).length / 4);
-                firstUserImages = countImages(content);
-                awaitingUsage = true;
-            }
-            continue;
-        }
-        if (type !== "assistant" || !awaitingUsage)
-            continue;
-        const total = claudeOfficialInputTokens(recordValue(recordValue(row.message).usage));
-        if (total <= 0)
-            continue;
-        const structureFloor = Math.round(total * 0.03);
-        return Math.max(0, total - firstUserTokens - firstUserImages * 4000 - structureFloor);
-    }
-    return 0;
-}
-function claudeOfficialInputTokens(usage) {
-    return numberValue(usage.input_tokens)
-        + numberValue(usage.cache_read_input_tokens)
-        + numberValue(usage.cache_creation_input_tokens);
-}
-function normalizeToolResult(value) {
-    if (typeof value === "string")
-        return value;
-    const output = [];
-    for (const block of arrayValue(value)) {
-        if (!isRecord(block))
-            continue;
-        if (block.type === "text" && typeof block.text === "string")
-            output.push(block.text);
-        else if (block.type === "image")
-            output.push({ type: "input_image" });
-        else
-            output.push(block);
-    }
-    return output.length === 1 ? output[0] : output;
-}
-function extractText(value) {
-    if (typeof value === "string")
-        return value;
-    return arrayValue(value).map((block) => {
-        if (!isRecord(block))
-            return "";
-        if (typeof block.text === "string")
-            return block.text;
-        return "";
-    }).filter(Boolean).join("\n");
-}
-function countImages(value) {
-    if (!value)
-        return 0;
-    if (Array.isArray(value))
-        return value.reduce((sum, item) => sum + countImages(item), 0);
-    if (!isRecord(value))
-        return 0;
-    const own = value.type === "image" || value.type === "input_image" ? 1 : 0;
-    return own + Object.values(value).reduce((sum, item) => sum + countImages(item), 0);
-}
-function collectToolNames(rows) {
-    const names = new Set();
-    for (const row of rows) {
-        for (const block of arrayValue(recordValue(row.message).content)) {
-            if (isRecord(block) && block.type === "tool_use" && typeof block.name === "string")
-                names.add(block.name);
-        }
-    }
-    return [...names].sort();
-}
-function readRows(file) {
-    const rows = [];
-    for (const line of fs.readFileSync(file, "utf8").split(/\n/)) {
-        if (!line.trim())
-            continue;
-        try {
-            const value = JSON.parse(line);
-            if (isRecord(value))
-                rows.push(value);
-        }
-        catch {
-            // Claude may leave a partial final line while a session is active.
-        }
-    }
-    return rows;
-}
-function firstString(rows, key) {
-    for (const row of rows)
-        if (typeof row[key] === "string" && row[key])
-            return row[key];
-    return null;
-}
-function firstTimestamp(rows) {
-    return firstString(rows, "timestamp") || new Date(0).toISOString();
-}
-function codexRecord(type, payload, timestamp) {
-    return { timestamp, type, payload };
-}
-function isToolResultContent(value) {
-    return arrayValue(value).some((block) => isRecord(block) && block.type === "tool_result");
-}
-function visualToolName(name) {
-    return /screenshot|image|browser|playwright/i.test(name);
-}
-function quoteArg(value) {
-    return `"${value.replace(/["\\]/g, "_")}"`;
-}
-function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-function recordValue(value) {
-    return isRecord(value) ? value : {};
-}
-function arrayValue(value) {
-    return Array.isArray(value) ? value : [];
-}
-function stringValue(value) {
-    return typeof value === "string" ? value : "";
-}
-function numberValue(value) {
-    return typeof value === "number" && Number.isFinite(value) ? value : 0;
-}