@echomem/mcp 1.0.1 → 1.1.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,9 @@ 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";
 const ECHO_API_BASE_URL = process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app";
@@ -75,10 +78,22 @@ 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;
     whoamiCache = null;
+    /** One id per bridge process — groups all saves from this coding session under a single EchoMem context. */
+    sessionId = randomUUID();
     encConfigPromise = null;
     constructor(store) {
         this.store = store;
@@ -101,6 +116,31 @@ 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.
+     * Best-effort: returns undefined on any failure (locked vault, network) rather than blocking tools.
+     */
+    async fetchMemoryMap() {
+        try {
+            const enc = await this.encState(); // unencrypted → {enabled:false}; encrypted+locked → throws
+            const today = new Date().toISOString().slice(0, 10);
+            const response = await this.axios.post("/api/extension/memories/time-range", { startDate: "2000-01-01", endDate: today, limit: 200 }, { timeout: 6000 });
+            const data = enc.enabled ? await this.decryptResult(response.data, enc.key) : response.data;
+            const memories = Array.isArray(data?.memories) ? data.memories : [];
+            const keys = [...new Set(memories.map((m) => String(m?.keys || "").trim()).filter(Boolean))];
+            if (!keys.length)
+                return undefined;
+            return keys.slice(0, 40).map((k) => `- ${k}`).join("\n");
+        }
+        catch {
+            return undefined;
+        }
+    }
     /** Encryption config for the account, fetched once and cached. Failures are not cached. */
     async getEncryptionConfig() {
         if (!this.encConfigPromise) {
@@ -118,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) {
@@ -241,6 +286,8 @@ class EchoMemApiClient {
             sourceUrl: parsed.url,
             source: parsed.source || "mcp_server",
             title: parsed.title,
+            // Stable per-session id so multiple saves in this coding session group under one context.
+            conversationKey: this.sessionId,
         }, config);
         return response.data;
     }
@@ -283,19 +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 () => {
@@ -304,17 +357,37 @@ class EchoMemMCPServer {
         });
     }
     setupToolHandlers() {
-        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: listToolSpecs() }));
+        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:
@@ -326,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 {
@@ -361,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;
@@ -395,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.` }],
         };
@@ -481,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,
@@ -45,12 +46,16 @@ export const keywordsSchema = z.object({
 export const othersSchema = z.object({
     query: z.string(),
 });
-export function listToolSpecs() {
+export function listToolSpecs(opts = {}) {
     const currentTime = new Date().toISOString();
+    const map = opts.map?.trim();
+    const mapSection = map
+        ? `\n\nThis user's EchoMem currently covers these topics (a relevance guide — recall when the task relates to one of them):\n${map}\n`
+        : "";
     return [
         {
             name: canonicalToolNames.search,
-            description: `Recall the user's prior decisions, preferences, constraints, and context from EchoMem — their long-term memory spanning ALL their AI tools (Claude.ai, ChatGPT, other agents), not just this session. CALL THIS AT THE START of any non-trivial task, before planning or writing code, to avoid re-deriving things the user already decided. Also call it whenever the user refers to past work ("what did we decide", "like before", "the usual"). Returns ranked memories with provenance. Current time: ${currentTime}.`,
+            description: `Recall the user's prior decisions, preferences, constraints, and project context from EchoMem — their long-term memory across ALL their AI tools (Claude.ai, ChatGPT, other agents), not just this session.${mapSection}\nCall this when the task plausibly relates to that remembered context — a topic above, or when the user refers to past work ("what did we decide", "like before", "the usual") — so you don't re-derive or re-ask what they already settled. Skip it for self-contained tasks with no link to their history (e.g. a generic algorithm question). Returns ranked memories with provenance. Current time: ${currentTime}.`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -134,6 +139,11 @@ export function listToolSpecs() {
                 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.1",
+  "version": "1.1.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",
     "prepack": "npm run build"
   },
   "dependencies": {