@echomem/mcp 1.4.3 → 1.4.5

package/README.md

@@ -49,18 +49,22 @@ your editor and you're done.
 |---|---|
 | `npm i -g @echomem/mcp@latest && echomem-mcp setup` | Install the CLI globally and run setup in one explicit step |
 | `npx -y @echomem/mcp@latest setup` | One-off setup without keeping a global CLI command |
-| `echomem-mcp setup [--client cursor\|windsurf\|claude-desktop]` | Write client config + log in |
-| `echomem-mcp setup --skip-login [--client cursor\|windsurf\|claude-desktop\|codex]` | Write client config without opening the browser or changing credentials |
-| `npx -y @echomem/mcp@latest update [--client cursor\|windsurf\|claude-desktop\|codex]` | One-shot update: repoint the client config to the latest bridge, with no browser login |
+| `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: repoint detected client configs to the latest bridge, with no browser login |
+| `npx -y @echomem/mcp@latest update --client codex` | Update one client only |
 | `echomem-mcp setup --with-hud [--client codex]` | Write client config + log in + launch the EchoMem context HUD |
 | `echomem-mcp login` | Approve device in browser (or use `--token` / `--passphrase`) |
 | `echomem-mcp unlock` | Re-derive the encryption key after its TTL (or `--passphrase`) |
-| `echomem-mcp status` | Show token / key / detected clients |
+| `echomem-mcp status` | Show token / key / detected clients, configured bridge versions, and update guidance |
+| `echomem-mcp doctor [--no-network]` | Diagnose configured client bridge versions |
 | `echomem-mcp logout` | Remove stored credentials |
 
-The bridge reports its package version in MCP server instructions and in the `search_memories`
-tool description. Agents should use that version signal to update once when stale, not auto-update
-on every MCP startup.
+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.
 
 ## EchoMem Context HUD
 
@@ -185,6 +189,7 @@ 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.
 * **`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:

package/dist/hud/capsule.js

@@ -9,10 +9,13 @@ import { formatTokens } from "./metric.js";
 const MAX_TURN_CHARS = 280;
 const MAX_FILES = 10;
 export function buildCapsuleText(score) {
-    const { turns, edited } = scanSession(score.sourcePath);
+    const { turns, edited, cwd } = scanSession(score.sourcePath);
     const goal = turns[0];
     const lastAsk = turns.length > 1 ? turns[turns.length - 1] : undefined;
-    const reads = readFiles(score, edited);
+    // Normalize every path to repo-relative so "editing" (recorded absolute) and "read"
+    // (recorded relative) dedupe correctly and the capsule isn't bloated by the cwd prefix.
+    const editedRel = edited.map((f) => relToCwd(f, cwd));
+    const reads = readFiles(score, editedRel, cwd);
     const sat = score.saturationPct !== null
         ? ` · ${score.saturationPct}% of ${formatTokens(score.modelContextWindow || 0)} window`
         : "";
@@ -25,21 +28,23 @@ export function buildCapsuleText(score) {
     ];
     if (lastAsk)
         lines.push("", "## Most recent instruction", lastAsk);
-    if (edited.length)
-        lines.push("", "## Files being edited", ...edited.slice(0, MAX_FILES).map((f) => `- ${f}`));
+    if (editedRel.length)
+        lines.push("", "## Files being edited", ...editedRel.slice(0, MAX_FILES).map((f) => `- ${f}`));
     if (reads.length)
         lines.push("", "## Other files read", ...reads.slice(0, MAX_FILES).map((f) => `- ${f}`));
     lines.push("", "## Where things stand", `- Turns ${score.turn} · reads ${score.reads} · edits ${score.stats?.patchEdits ?? 0} · compactions ${score.stats?.compactMarkers ?? 0}`, `- Tracked dead-weight ≥ ${formatTokens(score.pollutionTok)} (${score.pollutionPct}% pollution, lower bound)`, "", "---", "Start a fresh session and paste this capsule (or call search_memories) so the new window begins clean — you keep the goal, the working set, and your last instruction without re-reading everything. This is a clean recompose, not a provider compaction.");
     return lines.join("\n");
 }
 // Read files the scorer already tracked, minus anything we know was edited (shown separately).
-function readFiles(score, edited) {
-    const editedSet = new Set(edited);
+// Both sides are relativized to cwd first so the edited/read dedupe actually matches.
+function readFiles(score, editedRel, cwd) {
+    const editedSet = new Set(editedRel);
     const seen = new Set();
     for (const files of Object.values(score.filesByTool || {})) {
         for (const file of files) {
-            if (file && !editedSet.has(file))
-                seen.add(file);
+            const rel = relToCwd(file, cwd);
+            if (rel && !editedSet.has(rel))
+                seen.add(rel);
         }
     }
     return [...seen];
@@ -47,45 +52,83 @@ function readFiles(score, edited) {
 function scanSession(file) {
     const turns = [];
     const edited = new Set();
+    let cwd = "";
     let records = [];
     try {
         records = readJsonl(file);
     }
     catch {
-        return { turns, edited: [] };
+        return { turns, edited: [], cwd };
     }
     for (const record of records) {
         if (!isRecord(record))
             continue;
+        if (!cwd)
+            cwd = recordCwd(record);
         const text = userTextFromRecord(record);
         if (text)
             turns.push(text);
         collectEdited(record, edited);
     }
-    return { turns, edited: [...edited] };
+    return { turns, edited: [...edited], cwd };
 }
-// Tolerant across Codex (payload.role/payload.content) and Claude (message.role/message.content)
-// shapes. Skips tool results, assistant turns, and injected <context> wrappers; degrades to nothing
-// rather than throwing, so the capsule still renders from the working set + health.
+function recordCwd(record) {
+    if (typeof record.cwd === "string")
+        return record.cwd;
+    const payload = isRecord(record.payload) ? record.payload : null;
+    if (payload && typeof payload.cwd === "string")
+        return payload.cwd;
+    return "";
+}
+function relToCwd(file, cwd) {
+    if (!file)
+        return file;
+    if (cwd && (file === cwd || file.startsWith(`${cwd}/`)))
+        return file.slice(cwd.length + 1) || file;
+    return file;
+}
+// Reads the user's real turns, matching the same sources assembleCodex/assembleClaude use so the
+// goal/last-instruction can't be the injected preamble:
+//   - Codex: the `user_message` EVENT (payload.message is a plain string). The AGENTS.md preamble is a
+//     separate `message`/role:user ITEM, so reading events excludes it by construction — no blocklist.
+//   - Claude: the top-level `type:"user"` turn with message.content text blocks.
+// Degrades to nothing rather than throwing, so the capsule still renders from the working set + health.
 function userTextFromRecord(record) {
     const payload = isRecord(record.payload) ? record.payload : record;
-    const message = isRecord(payload.message) ? payload.message : isRecord(record.message) ? record.message : null;
-    let role = "";
-    if (typeof payload.role === "string")
-        role = payload.role;
-    else if (message && typeof message.role === "string")
-        role = message.role;
-    else if (typeof record.type === "string")
-        role = record.type;
-    const ptype = typeof payload.type === "string" ? payload.type : "";
-    if (role !== "user" && ptype !== "user_message")
+    // Codex user input.
+    if (payload.type === "user_message" && typeof payload.message === "string") {
+        return finishTurn(clean(stripCodexScaffolding(payload.message)));
+    }
+    // Claude user turn (top-level type:"user"). Codex `message`/role:user items are NOT type:"user",
+    // so they never reach here — that's what keeps the AGENTS.md item and duplicate turns out.
+    if (record.type !== "user")
         return null;
-    const raw = (message ? message.content : undefined) ?? payload.content ?? payload.text;
+    const message = isRecord(record.message) ? record.message : null;
+    const raw = message ? message.content : undefined;
     const text = clean(flatten(raw));
-    if (!text || text.startsWith("<") || text.length < 3)
+    if (!text || text.startsWith("<"))
+        return null;
+    if (isInstructionsPreamble(text))
+        return null; // Claude project-rules / caveat injections
+    return finishTurn(text);
+}
+function finishTurn(text) {
+    if (!text || text.length < 3)
         return null;
     return text.length > MAX_TURN_CHARS ? `${text.slice(0, MAX_TURN_CHARS)}…` : text;
 }
+// Strip Codex's synthetic wrapper blocks from a user message (mirrors migrate.ts cleanCodexUser).
+function stripCodexScaffolding(msg) {
+    return String(msg || "")
+        .replace(/<(environment_context|user_instructions|permissions|app-context)>[\s\S]*?<\/\1>/g, "")
+        .trim();
+}
+// Claude-side injected preambles (project rules / harness caveats). Anchored to the START so a real
+// instruction that merely mentions these words isn't dropped. Codex's AGENTS.md is handled
+// structurally above, so it isn't listed here.
+function isInstructionsPreamble(text) {
+    return /^#\s*claudeMd\b/i.test(text) || text.startsWith("Caveat:");
+}
 function collectEdited(record, set) {
     const payload = isRecord(record.payload) ? record.payload : record;
     if (payload.type === "patch_apply_end" && isRecord(payload.changes)) {

package/dist/hud/electron-main.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { app, BrowserWindow, ipcMain, Menu, screen } from "electron";
+import { app, BrowserWindow, ipcMain, Menu, screen, shell } from "electron";
 import { createHudServer } from "./server.js";
 const flags = parseFlags(process.argv.slice(2));
 const mode = parseMode(flags.client);
@@ -32,8 +32,16 @@ app.whenReady().then(async () => {
         writeBounds(win);
     });
     const preferredUrl = `http://127.0.0.1:${port}`;
+    const onReveal = (filePath) => {
+        try {
+            shell.showItemInFolder(filePath);
+        }
+        catch {
+            /* best-effort */
+        }
+    };
     try {
-        hudServer = await createHudServer({ mode, port });
+        hudServer = await createHudServer({ mode, port, onReveal });
         createWindow(hudServer.url);
     }
     catch (error) {
@@ -41,7 +49,7 @@ app.whenReady().then(async () => {
             createWindow(preferredUrl);
             return;
         }
-        hudServer = await createHudServer({ mode, port: 0 });
+        hudServer = await createHudServer({ mode, port: 0, onReveal });
         createWindow(hudServer.url);
     }
 }).catch((error) => {

package/dist/hud/metric.js

@@ -7,6 +7,10 @@ export const BUCKETS = {
 };
 const SHELL_READ_BINS = new Set(["cat", "head", "tail", "sed", "nl", "less", "more", "bat"]);
 const EXT = /\.[A-Za-z0-9]{1,8}$/;
+// A re-read counts as redundant only if a prior read substantially re-covers THIS read. A shared
+// boundary line (sequential paging, e.g. sed 1,260p then 260,620p) is not a re-read; requiring ≥50%
+// of the new range to be already-seen keeps paging out while still catching genuine sub-range re-reads.
+const REDUNDANT_OVERLAP_FRACTION = 0.5;
 export function newMetricState() {
     return {
         turn: 0,
@@ -45,7 +49,13 @@ export function recordRead(state, file, start = 1, end = 1e9) {
     const tokens = estimateReadTokens(safeStart, safeEnd);
     const previous = state.readHist.get(file) || [];
     const lastEdit = state.editTurn.get(file) ?? -1;
-    const redundant = previous.some((read) => read.turn >= lastEdit && safeStart <= read.end && safeEnd >= read.start);
+    const newLines = Math.max(1, safeEnd - safeStart + 1);
+    const redundant = previous.some((read) => {
+        if (read.turn < lastEdit)
+            return false; // an edit since this read invalidated it — re-read is fresh
+        const overlap = Math.min(safeEnd, read.end) - Math.max(safeStart, read.start) + 1;
+        return overlap > 0 && overlap / newLines >= REDUNDANT_OVERLAP_FRACTION;
+    });
     state.reads += 1;
     if (redundant) {
         addBucket(state, BUCKETS.rangeRedundant, tokens, 1);
@@ -132,9 +142,12 @@ function estimateReadTokens(start, end) {
     return Math.min(8000, Math.max(40, lines * 12));
 }
 function qualityColor(pollutionPct, saturationPct) {
-    if (pollutionPct > 40 || (saturationPct !== null && saturationPct >= 95))
+    if (pollutionPct >= 35 ||
+        (saturationPct !== null && saturationPct >= 95) ||
+        (saturationPct !== null && saturationPct >= 85 && pollutionPct >= 20)) {
         return "red";
-    if (pollutionPct >= 25 || (saturationPct !== null && saturationPct >= 90))
+    }
+    if (pollutionPct >= 18 || (saturationPct !== null && saturationPct >= 75))
         return "amber";
     return "green";
 }