@echomem/mcp 1.4.47 → 1.4.48

package/README.md

@@ -35,18 +35,31 @@ Unencrypted accounts are unaffected. `search_memories` returns retrieved memorie
 your MCP client does the final answer generation; pass `includeAnswer: true` only if you need the
 legacy EchoMem-synthesized recall answer.
 
-## Quick start (recommended)
+## Quick start
 
-Install Echo Desktop, sign in once, then open **Connect MCP** and choose **Connect Echo**. The app
-ships and installs the MCP runtime, configures the detected Codex and Claude hosts, mirrors the same
-device credential used by the desktop app, and verifies the MCP handshake. No terminal login is
-required.
+The standalone package installs and manages its own durable per-user MCP runtime. It configures
+detected Codex and Claude hosts, connects this device, imports selected local coding history, and
+keeps compatible runtime updates ready for the next agent session.
 
-The standalone HUD has been retired; Echo Desktop is the persistent setup and status surface. The
-bridge still reads local agent logs for on-demand context-health tools, but it no longer publishes or
-auto-launches an Electron overlay.
+Prerequisite: **Node.js 18 or newer**. Run the command in the same environment as the agent you
+want to configure. Native Windows and WSL have separate home directories and client configs, so a
+WSL install does not configure native Windows apps.
 
-For headless systems and development, the granular CLI commands remain available:
+macOS, Linux, or WSL:
+
+```bash
+npx -y @echomem/mcp@latest init
+```
+
+Windows PowerShell:
+
+```powershell
+npx.cmd -y @echomem/mcp@latest init
+```
+
+The one-off `npx` command is the recommended install path; it stages a durable per-user runtime
+and does not require a global npm install. On Windows, use a new PowerShell window after installing
+Node if `npx.cmd` is not found.
 
 | Command | What it does |
 |---|---|
@@ -95,23 +108,6 @@ Both hook entries are merged idempotently into `~/.codex/hooks.json` and
 `~/.claude/settings.json`; unrelated user hooks and settings are preserved. Hooks fail open when
 their local input is missing so they cannot prevent a conversation from starting or finishing.
 
-## Agent Doctor — local workspace forensics (new in 1.4.9)
-
-`echomem-mcp init` / `setup` now ends with an **Agent Doctor report**: a local scan of your
-Codex and Claude Code session logs that shows what your AI coding actually cost and where the
-context went dirty — rendered as an interactive 3D "repo city" plus a full forensic breakdown.
-
-- **Unified cost ledger.** Every provider request is priced individually from official API list
-  rates (model, cache write/read, long-context premiums, intro-pricing windows), so the headline
-  TOTAL SPENT, per-repo costs, per-model costs, and cost components all come from one path and
-  reconcile exactly. It is an **API-equivalent estimate of volume, not a bill you paid**.
-- **Fail-closed validation.** The report refuses to render unless every ledger reconciles
-  (tokens, costs, canonical waste analysis). Stale or preview data can never appear as your data.
-- **Wasteful-context analysis.** Canonical context windows label input tokens useful vs wasteful
-  (re-reads of unchanged files, re-finding, dead work) and project the waste over your billed input.
-- **Fully local, zero upload.** The scan reads local JSONL logs only: no transcripts are uploaded
-  and no LLM calls are made to build the report.
-
 ### Manual / headless (SSH, containers, CI)
 
 No browser? Provide secrets directly — this is the documented headless path:

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

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { resolveClaudeProjectsDir } from "../local-data-paths.js";
-import { walk } from "../report.js";
+import { walkLocalFiles } from "../local-jsonl.js";
 import { isStrongPositiveFeedback, } from "./workspace-report.js";
 const OUTPUT_TOKEN_CAP = 12_000;
 const IMAGE_TOKENS = 4_000;
@@ -33,7 +33,7 @@ const PROBLEM_META = {
 const PROBLEM_IDS = Object.keys(PROBLEM_META);
 export function buildClaudeNativeCanonicalReport(opts) {
     const claudeRoot = opts?.sessionPaths ? null : resolveClaudeProjectsDir();
-    const discovered = (opts?.sessionPaths ?? (claudeRoot ? walk(claudeRoot, (candidate) => candidate.endsWith(".jsonl") && !candidate.includes(`${path.sep}subagents${path.sep}`) && !candidate.includes(`${path.sep}workflows${path.sep}`), () => false) : [])).sort();
+    const discovered = (opts?.sessionPaths ?? (claudeRoot ? walkLocalFiles(claudeRoot, (candidate) => candidate.endsWith(".jsonl") && !candidate.includes(`${path.sep}subagents${path.sep}`) && !candidate.includes(`${path.sep}workflows${path.sep}`), () => false) : [])).sort();
     const files = typeof opts?.limitFiles === "number" ? discovered.slice(-Math.max(0, opts.limitFiles)) : discovered;
     const sessions = [];
     const errors = [];

package/dist/context-analysis/vendored-canonical.js

@@ -6,7 +6,7 @@ import readline from "node:readline";
 import { fileURLToPath } from "node:url";
 import { discoverCodexSessionFiles } from "../codex-session-files.js";
 import { resolveClaudeProjectsDir } from "../local-data-paths.js";
-import { walk } from "../report.js";
+import { walkLocalFiles } from "../local-jsonl.js";
 import { buildClaudeNativeCanonicalReport } from "./claude-native-canonical.js";
 const PROBLEM_IDS = [
     "P01", "P02", "P03", "P04", "P05", "P06", "P07", "P08", "P09", "P10", "P11", "P12", "P13",
@@ -89,7 +89,7 @@ export async function buildVendoredCanonicalReport(opts) {
             .filter(isUserInitiatedSession)
         : [];
     const discoveredClaude = sources.includes("claude-code")
-        ? (opts?.claudeSessionPaths ?? (claudeRoot ? walk(claudeRoot, (candidate) => candidate.endsWith(".jsonl") && !candidate.includes(`${path.sep}subagents${path.sep}`) && !candidate.includes(`${path.sep}workflows${path.sep}`), () => false) : [])).sort()
+        ? (opts?.claudeSessionPaths ?? (claudeRoot ? walkLocalFiles(claudeRoot, (candidate) => candidate.endsWith(".jsonl") && !candidate.includes(`${path.sep}subagents${path.sep}`) && !candidate.includes(`${path.sep}workflows${path.sep}`), () => false) : [])).sort()
         : [];
     const codexFiles = limitFiles(discoveredCodex, opts?.limitFiles);
     const claudeFiles = limitFiles(discoveredClaude, opts?.limitFiles);

package/dist/context-analysis/workspace-report.js

@@ -3,7 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { discoverCodexSessionFiles } from "../codex-session-files.js";
 import { resolveClaudeProjectsDir } from "../local-data-paths.js";
-import { eachLine, walk } from "../report.js";
+import { eachJsonLine, walkLocalFiles } from "../local-jsonl.js";
 const PROBLEMS = {
     P01: { id: "P01", label: "Outdated Images & Screenshots", bucket: "dead", category: "Runtime Bug", confidence: "high" },
     P02: { id: "P02", label: "Ignored User Instructions", bucket: "refind", category: "Model Behavior", confidence: "medium" },
@@ -52,7 +52,7 @@ export function buildWorkspaceContextReport(opts) {
         ? discoveredCodexFiles.filter(isUserInitiatedCodexSession)
         : discoveredCodexFiles;
     const claudeFiles = sources.includes("claude-code")
-        ? (opts?.claudeSessionPaths ?? (claudeRoot ? walk(claudeRoot, (p) => p.endsWith(".jsonl") && !p.includes(`${path.sep}subagents${path.sep}`) && !p.includes(`${path.sep}workflows${path.sep}`), () => false) : [])).sort()
+        ? (opts?.claudeSessionPaths ?? (claudeRoot ? walkLocalFiles(claudeRoot, (p) => p.endsWith(".jsonl") && !p.includes(`${path.sep}subagents${path.sep}`) && !p.includes(`${path.sep}workflows${path.sep}`), () => false) : [])).sort()
         : [];
     const selectedCodex = typeof opts?.limitFiles === "number" ? codexFiles.slice(-Math.max(0, opts.limitFiles)) : codexFiles;
     const selectedClaude = typeof opts?.limitFiles === "number" ? claudeFiles.slice(-Math.max(0, opts.limitFiles)) : claudeFiles;
@@ -472,7 +472,7 @@ function parseCodexSession(file) {
     const turns = [];
     const ledgerItems = [];
     const callMeta = new Map();
-    eachLine(file, (raw) => {
+    eachJsonLine(file, (raw) => {
         const top = isRecord(raw) ? raw : {};
         const payload = isRecord(top.payload) ? top.payload : top;
         const type = typeof payload.type === "string" ? payload.type : typeof top.type === "string" ? top.type : "";

package/dist/index.js

@@ -7,12 +7,11 @@ import { ZodError } from "zod";
 import { bindSourceSessionSchema, canonicalToolNames, completeGroupPublicationSchema, createGroupInviteSchema, createGroupSchema, deleteMemorySchema, flagPublicationAttentionSchema, getGroupSessionSharingSchema, getByContextSchema, groupContextSchema, joinGroupSchema, keywordsSchema, listFriendsSchema, listToolSpecs, othersSchema, publishBatchToGroupSchema, publishToGroupSchema, prepareGroupPublicationSchema, publicMemorySchema, recordMemoryCitationsSchema, requestGroupSessionSharingSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, searchUsersSchema, sendFriendRequestSchema, timeRangeSchema, updateGroupProfileSchema, setGroupSessionSharingSchema, } from "./v1-contract.js";
 import { KeyStore } from "./keystore.js";
 import { EventLogger, hashText } from "./events.js";
-import { buildReportText } from "./report.js";
 import { contextHealthMarkdown, recomposeCapsuleMarkdown } from "./hud/api.js";
 import { createHash, randomUUID } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { fetchEncryptionConfig, decryptMemoryFields, verifyKeyB64, } from "./encryption.js";
-import { runCli } from "./setup.js";
+import { refreshInstalledMemoryGuidance, 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";
@@ -1472,10 +1471,6 @@ class EchoMemMCPServer {
                     if (recallRoute.error) {
                         throw new McpError(ErrorCode.InvalidParams, recallRoute.error);
                     }
-                    // The usage report is a local, $0 audit — works with no login (value before signup).
-                    if (canonicalName === canonicalToolNames.report) {
-                        return { content: [{ type: "text", text: await buildReportText(false) }] };
-                    }
                     if (canonicalName === canonicalToolNames.updateStatus) {
                         if (DESKTOP_MANAGED) {
                             return {
@@ -1671,8 +1666,7 @@ class EchoMemMCPServer {
                     rec.ok = rec.error_kind === "none";
                     rec.latency_ms = Date.now() - t0;
                     this.events.record(rec);
-                    if (canonicalName !== canonicalToolNames.report &&
-                        canonicalName !== canonicalToolNames.updateStatus &&
+                    if (canonicalName !== canonicalToolNames.updateStatus &&
                         canonicalName !== canonicalToolNames.contextHealth &&
                         canonicalName !== canonicalToolNames.recompose &&
                         canonicalName !== canonicalToolNames.save &&
@@ -2764,6 +2758,9 @@ async function main() {
         // inherited descriptor — can't leave the terminal hanging after setup/migrate completes.
         process.exit(process.exitCode ?? 0);
     }
+    // Existing standalone users may receive a new runtime without re-running setup. Refresh only
+    // EchoMem's marker-owned block so stale Desktop-era instructions disappear automatically.
+    refreshInstalledMemoryGuidance();
     const store = new KeyStore();
     // Serve mode is meant to be SPAWNED by the MCP client (editor), which drives us over a piped stdin.
     // A human who runs the bare server in a terminal instead gets a process that blocks forever on stdio

package/dist/local-jsonl.js

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+import path from "node:path";
+/**
+ * Stream a JSONL file without loading large agent transcripts into one string.
+ * Malformed lines and unreadable files are skipped so local discovery remains recoverable.
+ */
+export function eachJsonLine(file, visit) {
+    let descriptor;
+    try {
+        descriptor = fs.openSync(file, "r");
+    }
+    catch {
+        return;
+    }
+    try {
+        const decoder = new StringDecoder("utf8");
+        const buffer = Buffer.allocUnsafe(1 << 20);
+        let remainder = "";
+        let bytesRead;
+        const consume = (chunk) => {
+            const lines = (remainder + chunk).split("\n");
+            remainder = lines.pop() ?? "";
+            for (const line of lines) {
+                const value = line.trim();
+                if (!value)
+                    continue;
+                try {
+                    visit(JSON.parse(value));
+                }
+                catch {
+                    /* Ignore malformed or partially-written rows. */
+                }
+            }
+        };
+        while ((bytesRead = fs.readSync(descriptor, buffer, 0, buffer.length, null)) > 0) {
+            consume(decoder.write(buffer.subarray(0, bytesRead)));
+        }
+        const finalValue = (remainder + decoder.end()).trim();
+        if (finalValue) {
+            try {
+                visit(JSON.parse(finalValue));
+            }
+            catch {
+                /* Ignore a malformed or partially-written final row. */
+            }
+        }
+    }
+    finally {
+        try {
+            fs.closeSync(descriptor);
+        }
+        catch {
+            /* Best effort. */
+        }
+    }
+}
+/** Recursively list matching regular files without following child symlinks. */
+export function walkLocalFiles(directory, matches, skipDirectory, output = []) {
+    let entries;
+    try {
+        entries = fs.readdirSync(directory, { withFileTypes: true });
+    }
+    catch {
+        return output;
+    }
+    for (const entry of entries) {
+        const absolute = path.join(directory, entry.name);
+        let stat;
+        try {
+            stat = fs.lstatSync(absolute);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isSymbolicLink())
+            continue;
+        if (stat.isDirectory()) {
+            if (!skipDirectory(entry.name))
+                walkLocalFiles(absolute, matches, skipDirectory, output);
+        }
+        else if (stat.isFile() && matches(absolute)) {
+            output.push(absolute);
+        }
+    }
+    return output;
+}

package/dist/migrate.js

@@ -30,7 +30,7 @@ import { KeyStore, echoConfigDir } from "./keystore.js";
 import { fetchEncryptionConfig } from "./encryption.js";
 import { discoverCodexSessionFiles } from "./codex-session-files.js";
 import { resolveClaudeCoworkSessionsDir, resolveClaudeProjectsDir } from "./local-data-paths.js";
-import { walk, eachLine } from "./report.js";
+import { eachJsonLine, walkLocalFiles } from "./local-jsonl.js";
 const API_BASE = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
 const RATE_MAX = 28; // stay under the import-jobs /run limit of 30 / 60s
 const RATE_WINDOW_MS = 60_000;
@@ -58,7 +58,8 @@ export function assembleCodex(file) {
     let firstTs = null;
     let title = "";
     const turns = [];
-    eachLine(file, (o) => {
+    eachJsonLine(file, (value) => {
+        const o = value;
         if (o && o.type === "session_meta") {
             sessionId = (o.payload && typeof o.payload.id === "string" && o.payload.id) || sessionId;
             cwd = (o.payload && typeof o.payload.cwd === "string" && o.payload.cwd) || cwd;
@@ -110,7 +111,8 @@ export function assembleClaude(file, opts = {}) {
     let firstTs = null;
     let title = "";
     const turns = [];
-    eachLine(file, (o) => {
+    eachJsonLine(file, (value) => {
+        const o = value;
         if (!cwd && typeof o.cwd === "string")
             cwd = o.cwd;
         if (!sessionId && typeof o.sessionId === "string")
@@ -203,7 +205,7 @@ function userCreatedCodexFiles(codexRoot) {
     return userCreatedCodexSessionFiles(codexRoot).map((file) => file.path);
 }
 function userCreatedClaudeFiles(claudeRoot) {
-    return walk(claudeRoot, (candidate) => candidate.endsWith(".jsonl"), (name) => name === "subagents" || name === "workflows").filter(isUserCreatedClaudeSessionFile);
+    return walkLocalFiles(claudeRoot, (candidate) => candidate.endsWith(".jsonl"), (name) => name === "subagents" || name === "workflows").filter(isUserCreatedClaudeSessionFile);
 }
 function coworkConversationId(filePath, root) {
     const relative = path.relative(root, filePath);

package/dist/onboarding-stats.js

@@ -0,0 +1,16 @@
+/**
+ * The onboarding page only needs session discovery and import state. Usage-audit calculations
+ * (tokens, cost, context reads, recall ratios, and memory totals) are intentionally excluded.
+ */
+export function buildOnboardingStatsPayload(input) {
+    return {
+        schemaVersion: 1,
+        ...(input.partial ? { partial: true } : {}),
+        discovery: input.discovery,
+        generatedFrom: ["~/.codex/sessions", "~/.claude/projects"],
+        llmCallsUsed: 0,
+        transcriptsUploaded: false,
+        sessions: input.sessions,
+        migratable: input.migratable,
+    };
+}

package/dist/save-checkpoint-hook.js

@@ -10,7 +10,7 @@ const CHECKPOINT_REASON = [
     "Private persistence happens first. For a user with a company group, call `request_group_session_sharing` near conversation start or after a qualifying private save.",
     "On the first request_group_session_sharing call in a conversation, omit groupSharingScopeId so EchoMem mints a fresh opaque scope. Reuse that exact scope only in this conversation for later get/request/set/save calls, and never persist it as memory. If multiple groups are returned, reuse the same scope and call once per groupId. Relay the tool's exact text question and call set_group_session_sharing only after an explicit Yes/No. Silence leaves that group's state unset. A Share decision syncs eligible memories from later saves carrying the same scope to that group; saves automatically sync to every approved group. Keep private keeps them private for that group.",
     "Flagged memories are withheld from automatic conversation sync and remain private.",
-    "If EchoMem reports that the encrypted vault is locked, tell the user to open Echo Desktop and unlock the vault there; on a headless system, use `echomem-mcp unlock`. Never silently skip a qualifying checkpoint.",
+    "If EchoMem reports that the encrypted vault is locked, relay its local unlock instruction; for a standalone installation, use `echomem-mcp unlock`. Never silently skip a qualifying checkpoint.",
 ].join(" ");
 function currentTurnSlice(transcript) {
     const lines = transcript.split(/\r?\n/);