@echomem/mcp 1.0.3 → 1.2.0

package/dist/events.js

@@ -0,0 +1,60 @@
+/**
+ * Local, privacy-preserving telemetry for the MCP bridge — the "what EchoMem did" half of the
+ * with/without comparison dataset (the token/time half lives in the agent's own transcript files).
+ *
+ * Design goals (see docs/mcp-feature/mcp-telemetry-spec-2026-06-15.md):
+ *  - Record one structured event per tool call: which tool fired, what it returned, which memories,
+ *    latency, outcome. This is the data the agent transcript does NOT cleanly expose.
+ *  - NEVER store raw conversation/query text — only a length + a salted-free sha256 prefix so we can
+ *    detect repeats without keeping content. Privacy is a feature (mirrors Pieces' local-first posture).
+ *  - Append-only JSONL at <config-dir>/events.jsonl, alongside credentials. Local only — never sent
+ *    over the network by the bridge. A future opt-in syncs *aggregates* (not raw events) for the web report.
+ *  - Best-effort: recording must never throw, never block, never change tool behavior.
+ *
+ * Opt out with ECHO_TELEMETRY=0 (or ECHO_DISABLE_TELEMETRY=1).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { echoConfigDir } from "./keystore.js";
+export const TELEMETRY_SCHEMA_VERSION = 1;
+/** sha256 prefix of free text — lets us count repeats of the same query without storing the query. */
+export function hashText(text) {
+    return createHash("sha256").update(text).digest("hex").slice(0, 12);
+}
+export class EventLogger {
+    base;
+    file;
+    enabled;
+    client = "unknown";
+    constructor(base) {
+        this.base = base;
+        this.enabled = !(process.env.ECHO_TELEMETRY === "0" || process.env.ECHO_DISABLE_TELEMETRY);
+        this.file = path.join(echoConfigDir(), "events.jsonl");
+    }
+    /** Set the detected MCP client once known (after the initialize handshake). */
+    setClient(name) {
+        if (name)
+            this.client = name;
+    }
+    /** Append one event. Best-effort: swallows every error so telemetry can never break a tool call. */
+    record(partial) {
+        if (!this.enabled)
+            return;
+        try {
+            const event = {
+                v: TELEMETRY_SCHEMA_VERSION,
+                ts: new Date().toISOString(),
+                session_id: this.base.session_id,
+                client: this.client,
+                app_version: this.base.app_version,
+                ...partial,
+            };
+            fs.mkdirSync(path.dirname(this.file), { recursive: true, mode: 0o700 });
+            fs.appendFileSync(this.file, JSON.stringify(event) + "\n");
+        }
+        catch {
+            /* telemetry is best-effort; never surface */
+        }
+    }
+}

package/dist/index.js

@@ -6,6 +6,8 @@ import axios from "axios";
 import { ZodError } from "zod";
 import { canonicalToolNames, 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 { fetchEncryptionConfig, decryptMemoryFields } from "./encryption.js";
 import { runCli } from "./setup.js";
@@ -76,6 +78,16 @@ function describeError(error) {
     const fallback = stringifyErrorValue(error);
     return fallback || "Unknown error";
 }
+/** Map a thrown error to the telemetry error_kind taxonomy. */
+function classifyError(error) {
+    if (error instanceof NoTokenError)
+        return "no_token";
+    if (error instanceof LockedError)
+        return "locked";
+    if (error instanceof ZodError)
+        return "invalid_args";
+    return "api_error";
+}
 class EchoMemApiClient {
     store;
     axios;
@@ -104,6 +116,10 @@ class EchoMemApiClient {
     hasToken() {
         return !!this.store.getToken();
     }
+    /** The per-process session id — the join key telemetry shares with grouped saves. */
+    getSessionId() {
+        return this.sessionId;
+    }
     /**
      * 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.
@@ -142,13 +158,18 @@ class EchoMemApiClient {
      * handing the model ciphertext. For unencrypted accounts it returns `{ enabled: false }`.
      */
     async encState() {
-        const cfg = await this.getEncryptionConfig();
-        if (!cfg.enabled)
-            return { enabled: false };
+        // A stored key ONLY exists because the user unlocked an ENCRYPTED vault, so treat it as
+        // authoritative: a flaky/failed `/account/encryption` fetch (which defaults to enabled:false) must
+        // NOT downgrade an unlocked encrypted account to plaintext — that causes a 422 on save and leaks
+        // ciphertext on read. So if we hold a usable key, we're encrypted-and-unlocked, period.
         const key = this.store.getKey();
-        if (!key)
+        if (key)
+            return { enabled: true, key };
+        // No usable key: consult the server to tell "unencrypted" apart from "encrypted but locked/expired".
+        const cfg = await this.getEncryptionConfig();
+        if (cfg.enabled)
             throw new LockedError(this.store.isKeyExpired());
-        return { enabled: true, key };
+        return { enabled: false };
     }
     async whoami() {
         if (!this.whoamiCache) {
@@ -309,20 +330,25 @@ class EchoMemApiClient {
         }
     }
 }
+const SERVER_VERSION = "1.1.0";
 class EchoMemMCPServer {
     server;
     client;
     mapCache = null;
+    events;
+    /** Whether the most recent ListTools response carried the memory map (per-session recall signal). */
+    mapInjected = false;
     constructor(store) {
         this.server = new Server({
             name: "echomem-mcp",
-            version: "1.1.0",
+            version: SERVER_VERSION,
         }, {
             capabilities: {
                 tools: {},
             },
         });
         this.client = new EchoMemApiClient(store);
+        this.events = new EventLogger({ session_id: this.client.getSessionId(), app_version: SERVER_VERSION });
         this.setupToolHandlers();
         this.server.onerror = (error) => console.error("[MCP Error]", error);
         process.on("SIGINT", async () => {
@@ -332,23 +358,36 @@ class EchoMemMCPServer {
     }
     setupToolHandlers() {
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            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)
                 this.mapCache = this.client.fetchMemoryMap();
             const map = this.mapCache ? await this.mapCache : undefined;
+            this.mapInjected = !!map;
             return { tools: listToolSpecs({ map }) };
         });
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const canonicalName = resolveCanonicalToolName(request.params.name);
+            const t0 = Date.now();
+            // One event per call. Handlers enrich `rec` with tool-specific detail; we finalize + log in `finally`.
+            const rec = {
+                type: "tool_call",
+                tool: canonicalName,
+                map_injected: this.mapInjected,
+            };
             try {
+                // 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 (!this.client.hasToken())
                     throw new NoTokenError();
                 switch (canonicalName) {
                     case canonicalToolNames.search:
-                        return await this.handleSearch(request.params.arguments);
+                        return await this.handleSearch(request.params.arguments, rec);
                     case canonicalToolNames.save:
-                        return await this.handleSave(request.params.arguments);
+                        return await this.handleSave(request.params.arguments, rec);
                     case canonicalToolNames.timeRange:
                         return await this.handleTimeRange(request.params.arguments);
                     case canonicalToolNames.keywords:
@@ -360,6 +399,7 @@ class EchoMemMCPServer {
                 }
             }
             catch (error) {
+                rec.error_kind = classifyError(error);
                 if (error instanceof NoTokenError) {
                     // Not isError: a normal "not connected yet" state. Once `login` runs, the next call works.
                     return {
@@ -395,10 +435,30 @@ class EchoMemMCPServer {
                     isError: true,
                 };
             }
+            finally {
+                if (!rec.error_kind)
+                    rec.error_kind = "none";
+                rec.ok = rec.error_kind === "none";
+                rec.latency_ms = Date.now() - t0;
+                this.events.record(rec);
+            }
         });
     }
-    async handleSearch(args) {
+    async handleSearch(args, rec) {
+        const query = typeof args?.query === "string" ? args.query.trim() : "";
+        if (rec && query) {
+            rec.query_len = query.length;
+            rec.query_hash = hashText(query);
+        }
         const result = await this.client.searchMemories(args);
+        if (rec) {
+            // "Which memories were used": topic keys + delivered context size, for the comparison dataset.
+            const mems = Array.isArray(result?.memories) ? result.memories : [];
+            rec.tuned = !!result?.tuned;
+            rec.results_count = mems.length;
+            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);
+        }
         // Tuned two-phase path: synthesized brief + ranked source memories.
         if (result?.tuned) {
             const { answer, memories } = result;
@@ -429,10 +489,22 @@ Details: ${m.details || "N/A"}`)
             .join("\n\n");
         return { content: [{ type: "text", text: `Found ${memories.length} relevant memories:\n\n${formattedResults}` }] };
     }
-    async handleSave(args) {
+    async handleSave(args, rec) {
+        if (rec) {
+            const a = args;
+            const text = typeof a?.conversation === "string"
+                ? a.conversation
+                : Array.isArray(a?.messages)
+                    ? a.messages.map((m) => String(m?.content ?? "")).join("\n")
+                    : "";
+            rec.conversation_chars = text.length;
+            rec.save_source = typeof a?.source === "string" ? a.source : "mcp_server";
+        }
         const { success, memoriesExtracted, error } = await this.client.saveConversation(args);
         if (!success)
             throw new Error(`EchoMem API Error: ${error}`);
+        if (rec)
+            rec.memories_extracted = typeof memoriesExtracted === "number" ? memoriesExtracted : undefined;
         return {
             content: [{ type: "text", text: `Successfully ingested conversation. Extracted ${memoriesExtracted} memory distinct events.` }],
         };
@@ -515,6 +587,7 @@ Details: ${m.details || "N/A"}`)
     async run() {
         const transport = new StdioServerTransport();
         await this.server.connect(transport);
+        this.events.record({ type: "session_start" });
         console.error("EchoMem MCP server running on stdio");
     }
 }

package/dist/keystore.js

@@ -17,9 +17,13 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 export const DEFAULT_KEY_TTL_MS = 7 * 24 * 60 * 60 * 1000;
-function configDir() {
+/** The bridge's local config dir (`~/.echomem` or `$ECHO_CONFIG_DIR`) — home for credentials + telemetry. */
+export function echoConfigDir() {
     return process.env.ECHO_CONFIG_DIR || path.join(os.homedir(), ".echomem");
 }
+function configDir() {
+    return echoConfigDir();
+}
 function credentialsPath() {
     return path.join(configDir(), "credentials.json");
 }

package/dist/report.js

@@ -0,0 +1,513 @@
+/**
+ * `echomem-mcp report` — the orientation audit (deterministic, $0 LLM).
+ *
+ * Reads the user's LOCAL coding-agent transcripts (Codex rollout logs + Claude Code session files)
+ * and shows how rarely the agent RECALLS prior context versus re-gathering it from scratch — the
+ * thing EchoMem actually changes. No model is called; transcripts never leave the machine.
+ *
+ * Honesty notes (the team will sanity-check this — see the fresh-review findings):
+ *   - HERO metric = recalls vs context-gathering tool calls. These are real tool invocations counted
+ *     from the logs; this is the metric that maps to what EchoMem replaces (cross-session re-reading).
+ *   - The token total is CUMULATIVE billing — every turn re-sends the growing context window, so it
+ *     double-counts the conversation. We label it "processed across all turns" and explicitly say most
+ *     of it is the conversation re-loading itself (intrinsic to agents), NOT something memory removes.
+ *     We do NOT multiply that billing total by the experiment ratio (different unit).
+ *   - The ~1.8× figure is an EARLY signal from a small controlled test (N=3, a stand-in agent), clearly
+ *     labeled — not a measurement on this account.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import axios from "axios";
+import { KeyStore } from "./keystore.js";
+const API_BASE = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
+// Early signal from the controlled sub-agent experiment, NOT measured on this account.
+// (docs/mcp-feature/LIVE-measured-orientation-experiment-2026-06-12.md — N=3 per arm, proxy agent.)
+const PROJ_CONTEXT = "~1.8×";
+const PROJ_SPEED = "~1.5×";
+const PROJ_CORRECT = "0/3 → 3/3";
+// ---------------------------------------------------------------------------
+// Tool classification — only count true retrieval as "context-gathering", so the hero metric
+// doesn't conflate edits/builds/tests with reading. Conservative: anything ambiguous → "act".
+// ---------------------------------------------------------------------------
+const CLAUDE_READ = new Set(["read", "grep", "glob", "ls", "notebookread", "webfetch", "websearch"]);
+const SHELL_READ = new Set([
+    "cat", "head", "tail", "less", "more", "bat", "grep", "egrep", "fgrep", "rg", "ag", "ack",
+    "ls", "find", "fd", "tree", "wc", "stat", "file", "sed", "awk", "cut", "nl", "column",
+    "readlink", "realpath", "od", "strings",
+]);
+const GIT_READ = new Set(["log", "show", "diff", "status", "blame", "ls-files", "ls-tree", "cat-file", "grep"]);
+/**
+ * Classify a shell command as a read (retrieval) or an act. Splits on shell operators so chains like
+ * `cd src && cat x` and pipes like `cat x | grep y` are judged by their real commands; navigation
+ * (cd/pushd/popd) is ignored; a chain containing any non-read command is an act (conservative).
+ */
+export function classifyShellCmd(cmd) {
+    const segments = String(cmd).split(/&&|\|\||[;|\n]/).map((s) => s.trim()).filter(Boolean);
+    let sawRead = false;
+    for (const seg of segments) {
+        const t = seg.split(/\s+/);
+        let i = 0;
+        while (i < t.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(t[i]))
+            i++; // skip FOO=bar env prefixes
+        let bin = (t[i] || "").split("/").pop() || "";
+        if (bin === "sudo") {
+            i++;
+            bin = (t[i] || "").split("/").pop() || "";
+        }
+        if (bin === "cd" || bin === "pushd" || bin === "popd")
+            continue; // navigation — ignore
+        if (bin === "git") {
+            let j = i + 1;
+            while (j < t.length && t[j].startsWith("-")) {
+                if (t[j] === "-C" || t[j] === "-c")
+                    j++;
+                j++;
+            } // skip global flags (+arg)
+            if (GIT_READ.has(t[j] || "")) {
+                sawRead = true;
+                continue;
+            }
+            return "act";
+        }
+        if (SHELL_READ.has(bin)) {
+            sawRead = true;
+            continue;
+        }
+        return "act"; // a real non-read command → act
+    }
+    return sawRead ? "read" : "act";
+}
+/** Classify a Codex function_call (non-echomem) as read or act. */
+function classifyCodexCall(name, argsRaw) {
+    const n = String(name || "").toLowerCase();
+    if (n.includes("github_fetch_file") || n.includes("github_search") || n === "read_thread_terminal" || n === "view_image")
+        return "read";
+    if (n === "exec_command" || n === "shell") {
+        try {
+            const cmd = JSON.parse(typeof argsRaw === "string" ? argsRaw : "{}").cmd;
+            if (typeof cmd === "string")
+                return classifyShellCmd(cmd);
+        }
+        catch {
+            /* fall through */
+        }
+        return "act";
+    }
+    return "act";
+}
+/** Classify a Claude tool_use (non-echomem) as read or act. */
+function classifyClaudeTool(name) {
+    const base = String(name || "").toLowerCase().replace(/^mcp__.+?__/, "");
+    return CLAUDE_READ.has(base) ? "read" : "act";
+}
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+/**
+ * Stream a .jsonl file line-by-line, decoding in 1 MB chunks. Streaming (rather than
+ * readFileSync().split()) avoids both loading a multi-hundred-MB session into one string and the
+ * V8 ~512 MB max-string cliff that would silently drop a large session. Never throws.
+ */
+function eachLine(file, fn) {
+    let fd;
+    try {
+        fd = fs.openSync(file, "r");
+    }
+    catch {
+        return;
+    }
+    try {
+        const decoder = new StringDecoder("utf8");
+        const buf = Buffer.allocUnsafe(1 << 20);
+        let leftover = "";
+        let bytes;
+        const flush = (chunk) => {
+            const lines = (leftover + chunk).split("\n");
+            leftover = lines.pop() ?? "";
+            for (const line of lines) {
+                const s = line.trim();
+                if (!s)
+                    continue;
+                try {
+                    fn(JSON.parse(s));
+                }
+                catch {
+                    /* skip malformed line */
+                }
+            }
+        };
+        while ((bytes = fs.readSync(fd, buf, 0, buf.length, null)) > 0) {
+            flush(decoder.write(buf.subarray(0, bytes)));
+        }
+        const last = (leftover + decoder.end()).trim();
+        if (last) {
+            try {
+                fn(JSON.parse(last));
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    finally {
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+/** Codex rollout: token_count is CUMULATIVE (take the last); function_call is per tool invocation. */
+export function parseCodex(file) {
+    let tot = null;
+    const meta = { first: null };
+    let echo = 0;
+    let reads = 0;
+    let acts = 0;
+    eachLine(file, (o) => {
+        if (meta.first === null && typeof o.timestamp === "string")
+            meta.first = o.timestamp;
+        const p = o && typeof o.payload === "object" && o.payload ? o.payload : o;
+        if (!p || typeof p !== "object")
+            return;
+        if (p.type === "token_count") {
+            const u = p.info && p.info.total_token_usage;
+            if (u)
+                tot = u;
+        }
+        else if (p.type === "function_call") {
+            const ns = (String(p.namespace || "") + String(p.name || "")).toLowerCase();
+            if (ns.includes("echomem"))
+                echo++;
+            else if (classifyCodexCall(p.name, p.arguments) === "read")
+                reads++;
+            else
+                acts++;
+        }
+    });
+    if (!tot || !(tot.total_tokens > 0))
+        return null;
+    return {
+        source: "codex",
+        date: meta.first ? meta.first.slice(0, 10) : null,
+        month: meta.first ? meta.first.slice(0, 7) : null,
+        total: tot.total_tokens || 0,
+        cached: tot.cached_input_tokens || 0,
+        output: tot.output_tokens || 0,
+        toolsRead: reads,
+        toolsAct: acts,
+        toolsEcho: echo,
+    };
+}
+/** Claude Code: usage is PER assistant turn (SUM); tool_use blocks live in message.content. */
+export function parseClaude(file) {
+    let total = 0;
+    let cached = 0;
+    let output = 0;
+    let echo = 0;
+    let reads = 0;
+    let acts = 0;
+    const meta = { first: null };
+    let sawUsage = false;
+    eachLine(file, (o) => {
+        if (meta.first === null && typeof o.timestamp === "string")
+            meta.first = o.timestamp;
+        if (o.type !== "assistant" || !o.message)
+            return;
+        const u = o.message.usage;
+        if (u) {
+            sawUsage = true;
+            const inp = u.input_tokens || 0;
+            const cr = u.cache_read_input_tokens || 0;
+            const cc = u.cache_creation_input_tokens || 0;
+            const out = u.output_tokens || 0;
+            total += inp + cr + cc + out;
+            cached += cr; // re-read only (cache_creation is a first-time write, not a re-read)
+            output += out;
+        }
+        const content = o.message.content;
+        if (Array.isArray(content)) {
+            for (const b of content) {
+                if (b && b.type === "tool_use") {
+                    if (String(b.name || "").toLowerCase().includes("echomem"))
+                        echo++;
+                    else if (classifyClaudeTool(b.name) === "read")
+                        reads++;
+                    else
+                        acts++;
+                }
+            }
+        }
+    });
+    if (!sawUsage || total === 0)
+        return null;
+    return {
+        source: "claude-code",
+        date: meta.first ? meta.first.slice(0, 10) : null,
+        month: meta.first ? meta.first.slice(0, 7) : null,
+        total,
+        cached,
+        output,
+        toolsRead: reads,
+        toolsAct: acts,
+        toolsEcho: echo,
+    };
+}
+function walk(dir, match, skipDir, out = []) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            if (!skipDir(e.name))
+                walk(full, match, skipDir, out);
+        }
+        else if (match(full)) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+export function collect() {
+    const stats = [];
+    const codexRoot = path.join(os.homedir(), ".codex", "sessions");
+    for (const f of walk(codexRoot, (p) => /rollout-.*\.jsonl$/.test(p), () => false)) {
+        const s = parseCodex(f);
+        if (s)
+            stats.push(s);
+    }
+    // Claude Code: top-level session files only (skip subagent/workflow dirs to avoid double-counting).
+    const claudeRoot = path.join(os.homedir(), ".claude", "projects");
+    for (const f of walk(claudeRoot, (p) => p.endsWith(".jsonl"), (name) => name === "subagents" || name === "workflows")) {
+        const s = parseClaude(f);
+        if (s)
+            stats.push(s);
+    }
+    return stats;
+}
+// ---------------------------------------------------------------------------
+// Aggregation (pure — unit-tested in test/report.test.mjs)
+// ---------------------------------------------------------------------------
+function median(nums) {
+    if (!nums.length)
+        return 0;
+    const s = [...nums].sort((a, b) => a - b);
+    return s[Math.floor(s.length / 2)];
+}
+export function aggregate(stats) {
+    const total = stats.reduce((n, s) => n + s.total, 0);
+    const cached = stats.reduce((n, s) => n + s.cached, 0);
+    const output = stats.reduce((n, s) => n + s.output, 0);
+    const reads = stats.reduce((n, s) => n + s.toolsRead, 0);
+    const acts = stats.reduce((n, s) => n + s.toolsAct, 0);
+    const recalls = stats.reduce((n, s) => n + s.toolsEcho, 0);
+    const toolTotal = reads + acts + recalls;
+    const fresh = total - cached;
+    const noncached = Math.max(0, total - cached - output);
+    const dates = stats.map((s) => s.date).filter(Boolean).sort();
+    const byMonth = new Map();
+    for (const s of stats) {
+        if (!s.month)
+            continue;
+        const m = byMonth.get(s.month) || { t: 0, c: 0, n: 0 };
+        m.t += s.total;
+        m.c += s.cached;
+        m.n += 1;
+        byMonth.set(s.month, m);
+    }
+    const months = [...byMonth.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([month, d]) => ({
+        month, tokens: d.t, sessions: d.n, rereadPct: d.t ? Math.round((d.c / d.t) * 100) : 0,
+    }));
+    const totals = stats.map((s) => s.total).sort((a, b) => b - a);
+    const topN = Math.max(1, Math.floor(totals.length * 0.1));
+    const topShare = total ? Math.round((totals.slice(0, topN).reduce((n, x) => n + x, 0) / total) * 100) : 0;
+    // Rough $ — cache priced CHEAP at both ends (~0.1–0.5×); never bill cache at the full input rate.
+    const costLow = noncached / 1e6 * 1.25 + cached / 1e6 * 0.1 + output / 1e6 * 10;
+    const costHigh = noncached / 1e6 * 5 + cached / 1e6 * 0.5 + output / 1e6 * 15;
+    return {
+        sessions: stats.length,
+        codexN: stats.filter((s) => s.source === "codex").length,
+        claudeN: stats.filter((s) => s.source === "claude-code").length,
+        total, cached, output, fresh, noncached, reads, acts, recalls, toolTotal,
+        rereadPct: total ? Math.round((cached / total) * 100) : 0,
+        ratio: recalls > 0 ? Math.round(reads / recalls) : null,
+        first: dates[0] || null,
+        last: dates[dates.length - 1] || null,
+        days: new Set(dates).size,
+        months, topShare, medianSession: median(stats.map((s) => s.total)),
+        costLow, costHigh,
+    };
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+function makeColor(enabled) {
+    const w = (code) => (s) => (enabled ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+    return { bold: w("1"), dim: w("2"), red: w("31"), green: w("32"), blue: w("34"), magenta: w("35"), cyan: w("36") };
+}
+function human(n) {
+    const a = Math.abs(n);
+    if (a >= 1e9)
+        return (n / 1e9).toFixed(2) + "B";
+    if (a >= 1e6)
+        return (n / 1e6).toFixed(2) + "M";
+    if (a >= 1e3)
+        return (n / 1e3).toFixed(1) + "K";
+    return String(Math.round(n));
+}
+/**
+ * How many memories the EchoMem platform has captured for this account. Best-effort: needs a stored
+ * token; returns null otherwise. Reads the FEED route on purpose — `time-range`/`graph` still filter
+ * out encrypted memories (a deployed bug), but the feed route has no such filter. Never throws.
+ */
+async function fetchMemoryCount() {
+    const token = new KeyStore().getToken();
+    if (!token)
+        return null;
+    try {
+        const res = await axios.get(`${API_BASE}/api/extension/memories`, {
+            headers: { Authorization: `Bearer ${token}` },
+            timeout: 5000,
+        });
+        const count = res.data?.count;
+        return typeof count === "number" ? count : null;
+    }
+    catch {
+        return null;
+    }
+}
+function renderJson(a, memCount) {
+    return JSON.stringify({
+        generatedFrom: ["~/.codex/sessions", "~/.claude/projects"],
+        llmCallsUsed: 0,
+        transcriptsUploaded: false,
+        window: { first: a.first, last: a.last, activeDays: a.days },
+        sessions: { total: a.sessions, codex: a.codexN, claudeCode: a.claudeN },
+        contextGathering: { reads: a.reads, memoryRecalls: a.recalls, readsPerRecall: a.ratio, otherActions: a.acts, note: "reads = file reads + searches only; edits/writes/builds/tests excluded (memory doesn't replace them)" },
+        memoriesCaptured: memCount,
+        tokensProcessedCumulative: { total: a.total, cacheReadShare: a.rereadPct, fresh: a.fresh, output: a.output, note: "cumulative across turns; most cache-read is the conversation re-loading itself, not EchoMem-addressable" },
+        concentration: { topTenPctShare: a.topShare, medianSession: a.medianSession },
+        months: a.months,
+        earlySignal: { source: "controlled test, N=3 per arm, proxy agent", context: PROJ_CONTEXT, speed: PROJ_SPEED, correctness: PROJ_CORRECT, measuredOnThisAccount: false },
+        estSpendUsdRough: { low: Math.round(a.costLow), high: Math.round(a.costHigh), note: "cache priced at ~0.1-0.5x; rough" },
+    }, null, 2);
+}
+/** Render the report to a string. `useColor=false` for the MCP tool (clean text); true for the terminal. */
+function renderText(a, memCount, useColor) {
+    const c = makeColor(useColor);
+    const out = [];
+    const L = (s = "") => out.push("  " + s);
+    const NL = () => out.push("");
+    const sources = [a.codexN ? `${a.codexN} Codex` : "", a.claudeN ? `${a.claudeN} Claude Code` : ""].filter(Boolean).join(" + ");
+    NL();
+    L(c.bold(c.magenta("EchoMem · your AI coding memory audit")));
+    L(c.dim(`${sources} sessions · ${a.first} → ${a.last} · ${a.days} active days`));
+    L(c.dim(`computed locally from your own logs — transcripts never leave your machine`));
+    NL();
+    // ---- HERO: reads/searches (what recall replaces) vs recalls — edits/builds excluded ----
+    L(c.bold("THE HEADLINE"));
+    L(`Across ${c.bold(a.sessions + " sessions")}, your agents read or searched your code`);
+    L(`${c.bold(a.reads.toLocaleString())} times to rebuild context — and recalled it from memory ${c.bold(c.red(String(a.recalls)))} ${a.recalls === 1 ? "time" : "times"}.`);
+    NL();
+    const rw = 40;
+    L(`reads & searches  ${c.red("█".repeat(rw))} ${c.bold(a.reads.toLocaleString())}`);
+    const recallBar = a.recalls > 0 ? "█".repeat(Math.max(1, Math.round((a.recalls / Math.max(a.reads, 1)) * rw))) : "·";
+    L(`memory recalls    ${c.green(recallBar)} ${c.bold(String(a.recalls))}`);
+    if (a.ratio)
+        L(c.dim(`≈ ${a.ratio.toLocaleString()} : 1 — the agent re-reads instead of remembering. EchoMem flips this.`));
+    else
+        L(c.dim(`the agent rebuilds context from scratch every time. EchoMem turns that into recall.`));
+    L(c.dim(`(plus ${a.acts.toLocaleString()} edits, builds & other actions — memory doesn't change those.)`));
+    NL();
+    // ---- memories / zero-state ----
+    if (memCount && memCount > 0) {
+        const word = memCount === 1 ? "memory" : "memories";
+        L(`You've started: EchoMem holds ${c.bold(c.cyan(memCount + " " + word))}, so every ${c.bold("new")} session can`);
+        L(`now recall instead of re-gathering. (The history above predates them.)`);
+    }
+    else {
+        L(`And ${c.bold(c.red("none of it was kept"))} — ${c.bold(a.sessions + " sessions")}, ${c.bold("0 memories")} saved for the next one.`);
+        L(c.dim(`Each session started cold and re-gathered everything from scratch.`));
+    }
+    NL();
+    // ---- SCALE (token total — honestly labeled, with the within-session caveat stated up front) ----
+    L(c.bold("THE SCALE OF IT") + c.dim("  (tokens processed across all turns)"));
+    L(`Your agents processed ${c.bold(human(a.total))} tokens; ${c.bold(a.rereadPct + "%")} was context re-sent every turn.`);
+    L(c.dim(`Most of that is the conversation re-loading itself — how agents bill, not something`));
+    L(c.dim(`memory removes. What memory removes is the re-gathering and cold starts above.`));
+    NL();
+    if (a.months.length > 1) {
+        L(c.bold("BY MONTH") + c.dim("  (tokens processed)"));
+        const maxT = Math.max(...a.months.map((m) => m.tokens));
+        for (const m of a.months) {
+            const w = Math.max(1, Math.round((m.tokens / maxT) * 24));
+            L(`${m.month}  ${c.blue("█".repeat(w))}${c.dim("░".repeat(24 - w))}  ${human(m.tokens).padStart(8)}  ${c.dim(m.sessions + " sess")}`);
+        }
+        NL();
+    }
+    // ---- WHAT CHANGES (plain language — the things a dev feels) ----
+    L(c.bold(c.green("WHAT CHANGES WHEN YOU CONNECT ECHOMEM")));
+    NL();
+    const pair = (bad, good) => {
+        L(c.red("✗ ") + c.dim("today: ") + c.dim(bad));
+        L(c.green("✓ ") + good);
+        NL();
+    };
+    pair("the agent re-reads your codebase every session just to catch up", "it recalls what it already learned — no re-gathering from scratch");
+    pair("it starts cold, guessing your setup from old files and stale docs", "it picks up from your latest decisions and where you actually left off");
+    if (memCount && memCount > 0)
+        pair("context is thrown away when the session ends", `it keeps compounding — every session adds to your ${c.bold(String(memCount))} memories`);
+    else
+        pair("nothing is saved — every session vanishes when it ends", "every session starts building a memory that compounds over time");
+    L(c.dim(`Early signal: in a small controlled test (3 runs, a stand-in agent), giving the agent`));
+    L(c.dim(`memory cut the context it needed to orient by ${PROJ_CONTEXT} and stopped it acting on stale code.`));
+    L(c.dim(`That's a directional test, not a measurement on your account — connect to get your real number.`));
+    NL();
+    // ---- CTA ----
+    if (memCount && memCount > 0) {
+        L(c.green(`✓ You're connected — every new session now builds on your ${memCount} memories.`));
+    }
+    else {
+        L(c.green("→ Start now (no signup wall):  ") + c.bold("npx -y @echomem/mcp setup"));
+        L(c.dim(`  ~1 minute. Your next coding session recalls instead of re-reading.`));
+    }
+    NL();
+    // ---- trust line ----
+    L(c.dim("─".repeat(62)));
+    L(`${c.bold(c.green("$0"))} to produce this — ${c.bold("no AI model was called")}.`);
+    L(c.dim(`Transcripts never leave your machine${memCount !== null ? " (only your memory count was fetched)" : ""}. Re-run anytime.`));
+    NL();
+    return out.join("\n");
+}
+const NO_HISTORY = "EchoMem report: no coding-agent history found yet.\n" +
+    "Looked in ~/.codex/sessions and ~/.claude/projects. Use a coding agent, then run `echomem-mcp report`.";
+/** Build the report as a plain string — used by the MCP `usage_report` tool (no color) and `setup`. */
+export async function buildReportText(useColor = false) {
+    const stats = collect();
+    if (stats.length === 0)
+        return NO_HISTORY;
+    return renderText(aggregate(stats), await fetchMemoryCount(), useColor);
+}
+export async function runReport(flags) {
+    const stats = collect();
+    if (stats.length === 0) {
+        console.log(NO_HISTORY);
+        return;
+    }
+    const a = aggregate(stats);
+    const memCount = await fetchMemoryCount();
+    if (flags.json === true) {
+        console.log(renderJson(a, memCount));
+        return;
+    }
+    const useColor = process.stdout.isTTY === true && !process.env.NO_COLOR && flags["no-color"] !== true;
+    console.log(renderText(a, memCount, useColor));
+}

package/dist/setup.js

@@ -22,6 +22,7 @@ import readline from "node:readline";
 import axios from "axios";
 import { KeyStore } from "./keystore.js";
 import { fetchEncryptionConfig, deriveAndVerifyKey, verifyKeyB64 } from "./encryption.js";
+import { runReport, buildReportText } from "./report.js";
 // The connect-device page lives on the main site (WebPageReactVersion → yeahecho.com), where the
 // user already has a session. It calls the EchoMem API cross-origin. Override with ECHO_WEB_URL.
 const WEB_URL = (process.env.ECHO_WEB_URL || "https://yeahecho.com").replace(/\/$/, "");
@@ -291,6 +292,13 @@ async function cmdSetup(flags) {
     }
     console.log("");
     await cmdLogin(flags);
+    // Onboarding reveal: show the local usage audit right after connecting (proactive trigger).
+    try {
+        console.log("\n" + (await buildReportText(true)));
+    }
+    catch {
+        /* report is best-effort — never block setup */
+    }
 }
 async function cmdLogin(flags) {
     // Manual path (also the headless path): secrets supplied as flags.
@@ -378,6 +386,7 @@ Usage:
   echomem-mcp unlock                Re-derive the encryption key after its TTL (or --passphrase)
   echomem-mcp status                Show token/key/clients
   echomem-mcp logout                Remove stored credentials
+  echomem-mcp report [--json]       Your AI coding memory audit (local, no login, $0)
 
 Manual / headless:
   echomem-mcp login --token ec_xxx [--passphrase <vault pass> | --key <base64>]
@@ -403,6 +412,9 @@ export async function runCli(argv) {
         case "logout":
             cmdLogout();
             return true;
+        case "report":
+            await runReport(flags);
+            return true;
         case "help":
         case "--help":
         case "-h":

package/dist/v1-contract.js

@@ -5,6 +5,7 @@ export const canonicalToolNames = {
     timeRange: "get_memories_by_time_range",
     keywords: "search_memories_by_keywords",
     others: "search_others_memories",
+    report: "echomem_usage_report",
 };
 export const legacyAliasToCanonical = {
     search_memories_by_description_semantic: canonicalToolNames.search,
@@ -138,6 +139,11 @@ export function listToolSpecs(opts = {}) {
                 required: ["query"],
             },
         },
+        {
+            name: canonicalToolNames.report,
+            description: "Show the user a one-screen audit of THEIR OWN AI coding usage — computed locally from their Codex/Claude Code logs ($0, nothing uploaded): how many tokens their agents spent, how much was re-reading context, reads vs memory recalls, and what changes with EchoMem. Call this when the user asks about their usage, token spend, cost, how much they're wasting, or wants a summary of their agent activity — and you may offer it once right after EchoMem is first connected. Returns formatted text to show the user verbatim. Needs no login.",
+            inputSchema: { type: "object", properties: {} },
+        },
         {
             name: "search_memories_by_time_range",
             description: "Legacy alias for get_memories_by_time_range.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "EchoMem Cloud-First MCP Server",
   "main": "dist/index.js",
   "type": "module",
@@ -17,7 +17,7 @@
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
     "smoke": "node smoke.mjs",
-    "test": "npm run build && node test/crypto.test.mjs && node test/integration.test.mjs && node test/no-restart.test.mjs",
+    "test": "npm run build && node test/crypto.test.mjs && node test/integration.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/tools.test.mjs",
     "prepack": "npm run build"
   },
   "dependencies": {