@echomem/mcp 1.4.44 → 1.4.45

package/dist/report.js

@@ -0,0 +1,721 @@
+/**
+ * `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 path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import axios from "axios";
+import { discoverCodexSessionFiles } from "./codex-session-files.js";
+import { resolveClaudeProjectsDir } from "./local-data-paths.js";
+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";
+}
+function normalizeCwd(cwd) {
+    if (!cwd)
+        return null;
+    const m = cwd.match(/worktrees\/[^/]+\/(.+)$/);
+    return m ? m[1] : cwd;
+}
+function basenameProject(cwd) {
+    if (!cwd)
+        return null;
+    const name = path.basename(cwd);
+    return name && name !== "." && name !== "/" ? name : null;
+}
+function epochMs(ts) {
+    if (!ts)
+        return null;
+    const n = Date.parse(ts);
+    return Number.isFinite(n) ? n : null;
+}
+function localDate(ts) {
+    const ms = epochMs(ts);
+    if (ms == null)
+        return null;
+    const d = new Date(ms);
+    const pad = (value) => String(value).padStart(2, "0");
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+function durationBetween(startTs, lastTs) {
+    const start = epochMs(startTs);
+    const last = epochMs(lastTs);
+    if (start == null || last == null)
+        return 0;
+    return Math.max(0, Math.round((last - start) / 1000));
+}
+// ---------------------------------------------------------------------------
+// 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.
+ */
+export 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, last: null, cwd: null };
+    let echo = 0;
+    let reads = 0;
+    let acts = 0;
+    eachLine(file, (o) => {
+        if (typeof o.timestamp === "string") {
+            const ms = epochMs(o.timestamp);
+            if (ms != null && (meta.first === null || ms < (epochMs(meta.first) ?? Number.POSITIVE_INFINITY)))
+                meta.first = o.timestamp;
+            if (ms != null && (meta.last === null || ms > (epochMs(meta.last) ?? Number.NEGATIVE_INFINITY)))
+                meta.last = o.timestamp;
+        }
+        if (o && o.type === "session_meta" && o.payload && typeof o.payload === "object") {
+            if (typeof o.payload.cwd === "string")
+                meta.cwd = o.payload.cwd;
+            if (typeof o.payload.timestamp === "string") {
+                const launchMs = epochMs(o.payload.timestamp);
+                if (launchMs != null && (meta.first === null || launchMs < (epochMs(meta.first) ?? Number.POSITIVE_INFINITY))) {
+                    meta.first = o.payload.timestamp;
+                }
+            }
+            return;
+        }
+        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: localDate(meta.first),
+        month: localDate(meta.first)?.slice(0, 7) ?? null,
+        startTs: meta.first,
+        lastTs: meta.last,
+        durationSec: durationBetween(meta.first, meta.last),
+        cwd: normalizeCwd(meta.cwd),
+        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) {
+    const usageByRequest = new Map();
+    const seenToolUses = new Set();
+    let anonymousRequestSeq = 0;
+    let echo = 0;
+    let reads = 0;
+    let acts = 0;
+    const meta = {
+        first: null,
+        last: null,
+        cwd: null,
+        durationSec: 0,
+        prevMs: null,
+    };
+    const requestKey = (row) => {
+        const messageId = typeof row.message?.id === "string" ? row.message.id.trim() : "";
+        if (messageId)
+            return `message:${messageId}`;
+        const requestId = typeof row.requestId === "string" ? row.requestId.trim() : "";
+        if (requestId)
+            return `request:${requestId}`;
+        const uuid = typeof row.uuid === "string" ? row.uuid.trim() : "";
+        return uuid ? `event:${uuid}` : `anonymous:${++anonymousRequestSeq}`;
+    };
+    eachLine(file, (o) => {
+        if (!meta.cwd && typeof o.cwd === "string")
+            meta.cwd = o.cwd;
+        if (typeof o.timestamp === "string") {
+            const ms = epochMs(o.timestamp);
+            if (ms != null) {
+                if (meta.first === null || ms < (epochMs(meta.first) ?? Number.POSITIVE_INFINITY))
+                    meta.first = o.timestamp;
+                if (meta.last === null || ms > (epochMs(meta.last) ?? Number.NEGATIVE_INFINITY))
+                    meta.last = o.timestamp;
+                if (meta.prevMs != null) {
+                    meta.durationSec += Math.min(300, Math.max(0, Math.round((ms - meta.prevMs) / 1000)));
+                }
+                meta.prevMs = ms;
+            }
+        }
+        if (o.type !== "assistant" || !o.message)
+            return;
+        const key = requestKey(o);
+        const u = o.message.usage;
+        if (u) {
+            const candidate = {
+                input: Math.max(0, Number(u.input_tokens) || 0),
+                cacheRead: Math.max(0, Number(u.cache_read_input_tokens) || 0),
+                cacheCreate: Math.max(0, Number(u.cache_creation_input_tokens) || 0),
+                output: Math.max(0, Number(u.output_tokens) || 0),
+            };
+            const existing = usageByRequest.get(key);
+            if (!existing || candidate.input + candidate.cacheRead + candidate.cacheCreate > existing.input + existing.cacheRead + existing.cacheCreate) {
+                if (existing)
+                    candidate.output = Math.max(candidate.output, existing.output);
+                usageByRequest.set(key, candidate);
+            }
+            else if (candidate.output > existing.output) {
+                existing.output = candidate.output;
+            }
+        }
+        const content = o.message.content;
+        if (Array.isArray(content)) {
+            for (let index = 0; index < content.length; index += 1) {
+                const b = content[index];
+                if (b && b.type === "tool_use") {
+                    const toolKey = typeof b.id === "string" && b.id ? `id:${b.id}` : `${key}:${index}:${String(b.name || "")}`;
+                    if (seenToolUses.has(toolKey))
+                        continue;
+                    seenToolUses.add(toolKey);
+                    if (String(b.name || "").toLowerCase().includes("echomem"))
+                        echo++;
+                    else if (classifyClaudeTool(b.name) === "read")
+                        reads++;
+                    else
+                        acts++;
+                }
+            }
+        }
+    });
+    const usage = [...usageByRequest.values()];
+    const cached = usage.reduce((sum, row) => sum + row.cacheRead, 0);
+    const output = usage.reduce((sum, row) => sum + row.output, 0);
+    const total = usage.reduce((sum, row) => sum + row.input + row.cacheRead + row.cacheCreate + row.output, 0);
+    if (!usage.length || total === 0)
+        return null;
+    return {
+        source: "claude-code",
+        date: localDate(meta.first),
+        month: localDate(meta.first)?.slice(0, 7) ?? null,
+        startTs: meta.first,
+        lastTs: meta.last,
+        durationSec: meta.durationSec,
+        cwd: normalizeCwd(meta.cwd),
+        total,
+        cached,
+        output,
+        toolsRead: reads,
+        toolsAct: acts,
+        toolsEcho: echo,
+    };
+}
+export 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);
+        let stat;
+        try {
+            // Never follow entries that changed into symlinks/special files after readdir. A validated root
+            // may itself be a user-controlled symlink, but traversal stays inside regular child entries.
+            stat = fs.lstatSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isSymbolicLink())
+            continue;
+        if (stat.isDirectory()) {
+            if (!skipDir(e.name))
+                walk(full, match, skipDir, out);
+        }
+        else if (stat.isFile() && match(full)) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+export function collect() {
+    const stats = [];
+    const codexDiscovery = discoverCodexSessionFiles({ includeArchived: true });
+    if (codexDiscovery.files.length) {
+        for (const { path: f } of codexDiscovery.files) {
+            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 = resolveClaudeProjectsDir();
+    if (claudeRoot) {
+        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 lastDates = stats.map((s) => localDate(s.lastTs)).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 byDay = new Map();
+    for (const d of dates)
+        byDay.set(d, (byDay.get(d) || 0) + 1);
+    const busiestDayEntry = [...byDay.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0];
+    const hourHistogram = Array.from({ length: 24 }, () => 0);
+    for (const s of stats) {
+        const ms = epochMs(s.startTs);
+        if (ms == null)
+            continue;
+        const hour = new Date(ms).getHours();
+        if (hour >= 0 && hour < 24)
+            hourHistogram[hour] += 1;
+    }
+    const hourMax = Math.max(...hourHistogram);
+    const hourLocal = hourMax > 0 ? hourHistogram.findIndex((n) => n === hourMax) : null;
+    const approxHours = stats.reduce((n, s) => n + s.durationSec, 0) / 3600;
+    const longestSessionMin = Math.max(0, ...stats.map((s) => s.durationSec)) / 60;
+    const byProject = new Map();
+    for (const s of stats) {
+        const name = basenameProject(s.cwd);
+        if (!name)
+            continue;
+        byProject.set(name, (byProject.get(name) || 0) + 1);
+    }
+    const topProjects = [...byProject.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, 10)
+        .map(([name, sessions]) => ({ name, sessions }));
+    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: lastDates[lastDates.length - 1] || dates[dates.length - 1] || null,
+        days: new Set(dates).size,
+        months,
+        busiestDay: { date: busiestDayEntry?.[0] || null, sessions: busiestDayEntry?.[1] || 0 },
+        hourHistogram,
+        hourLocal,
+        approxHours,
+        longestSessionMin,
+        topProjects,
+        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);
+}
+function round1(n) {
+    return Math.round(n * 10) / 10;
+}
+/** Build the localhost onboarding dashboard payload. This is intentionally separate from report --json. */
+export async function buildStatsPayload(stats, inject) {
+    const a = aggregate(stats);
+    const memCount = inject?.skipMemoryCount
+        ? null
+        : Object.prototype.hasOwnProperty.call(inject || {}, "memoriesCaptured")
+            ? inject?.memoriesCaptured ?? null
+            : await fetchMemoryCount();
+    const busiestMonth = [...a.months].sort((x, y) => y.sessions - x.sessions || x.month.localeCompare(y.month))[0];
+    const sessionCounts = inject?.sessions ?? { total: a.sessions, codex: a.codexN, claudeCode: a.claudeN };
+    return {
+        schemaVersion: 1,
+        ...(inject?.partial ? { partial: true } : {}),
+        ...(inject?.discovery ? { discovery: inject.discovery } : {}),
+        generatedFrom: ["~/.codex/sessions", "~/.claude/projects"],
+        llmCallsUsed: 0,
+        transcriptsUploaded: false,
+        window: { first: a.first, last: a.last, activeDays: a.days },
+        sessions: sessionCounts,
+        migratable: {
+            pending: inject?.migratable?.pending ?? 0,
+            alreadyMigrated: inject?.migratable?.alreadyMigrated ?? 0,
+            ...inject?.migratable,
+        },
+        busiest: {
+            month: { month: busiestMonth?.month || null, sessions: busiestMonth?.sessions || 0 },
+            day: a.busiestDay,
+            hourLocal: a.hourLocal,
+            hourHistogram: a.hourHistogram,
+        },
+        time: { approxHours: round1(a.approxHours), approx: true, longestSessionMin: Math.round(a.longestSessionMin) },
+        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)",
+        },
+        tokens: {
+            totalCumulative: a.total,
+            rereadPctOfTokens: a.rereadPct,
+            fresh: a.fresh,
+            output: a.output,
+            note: "cumulative across turns; re-read % is a TOKEN share (context re-sent each turn), NOT time",
+        },
+        concentration: { topTenPctShare: a.topShare, medianSession: a.medianSession },
+        topProjects: a.topProjects,
+        memoriesCaptured: memCount,
+    };
+}
+/** 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("npm i -g @echomem/mcp@latest && echomem-mcp init"));
+        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));
+}