@echomem/mcp 1.4.1 → 1.4.2

package/dist/hud/report.js

@@ -0,0 +1,125 @@
+// Context X-ray report — scans many local sessions and aggregates honest, data-backed numbers.
+// Everything here is measured from the user's own logs. Pollution is a tracked lower bound; the
+// Echo-usage split is observational (not a controlled A/B). No projections, no fabricated savings.
+import fs from "node:fs";
+import { adapters } from "./adapters.js";
+import { formatTokens } from "./metric.js";
+// A session "used Echo" if it called an EchoMem MCP tool (memory search / save_conversation).
+const ECHO_TOOL = /memor|^save_conversation$|^echomem|^mcp__echomem/i;
+export function runReport(mode, opts = {}) {
+    const limit = opts.limit && opts.limit > 0 ? opts.limit : 40;
+    const client = pickClient(mode);
+    const adapter = adapters[client];
+    const files = adapter
+        .findAll()
+        .map((f) => ({ f, m: safeMtime(f) }))
+        .sort((a, b) => b.m - a.m)
+        .slice(0, limit)
+        .map((x) => x.f);
+    const scores = [];
+    for (const file of files) {
+        try {
+            scores.push(adapter.score(file));
+        }
+        catch {
+            // Skip unreadable / partially-written sessions.
+        }
+    }
+    const ct = scores.map((s) => s.ctTokens || 0).filter((n) => n > 0);
+    const pollution = scores.map((s) => s.pollutionPct || 0);
+    const outAgg = {};
+    const toolAgg = {};
+    const echoPol = [];
+    const coldPol = [];
+    let reclaimableTotal = 0;
+    let echoSessions = 0;
+    for (const s of scores) {
+        reclaimableTotal += s.pollutionTok || 0;
+        for (const [k, v] of Object.entries(s.outputTokensByTool || {}))
+            outAgg[k] = (outAgg[k] || 0) + v;
+        for (const [k, v] of Object.entries(s.tools || {}))
+            toolAgg[k] = (toolAgg[k] || 0) + v;
+        const usedEcho = Object.keys(s.tools || {}).some((t) => ECHO_TOOL.test(t));
+        if (usedEcho) {
+            echoSessions += 1;
+            echoPol.push(s.pollutionPct || 0);
+        }
+        else {
+            coldPol.push(s.pollutionPct || 0);
+        }
+    }
+    return {
+        client,
+        sessions: files.length,
+        scored: scores.length,
+        window: { median: median(ct), p90: percentile(ct, 90), max: ct.length ? Math.max(...ct) : 0 },
+        reclaimableTotal,
+        pollutionMedian: median(pollution),
+        outputByTool: topEntries(outAgg, 8),
+        toolsTop: topEntries(toolAgg, 8),
+        echoSessions,
+        echoPollutionMedian: echoPol.length ? median(echoPol) : null,
+        coldPollutionMedian: coldPol.length ? median(coldPol) : null,
+        generatedAt: new Date().toISOString(),
+    };
+}
+export function renderReportText(r) {
+    const lines = [];
+    lines.push(`EchoMem Context X-ray — ${r.client} · ${r.scored}/${r.sessions} sessions analyzed`);
+    lines.push("");
+    lines.push("Window size");
+    lines.push(`  median ${formatTokens(r.window.median)} · p90 ${formatTokens(r.window.p90)} · largest ${formatTokens(r.window.max)}`);
+    lines.push("");
+    lines.push("Provably reclaimable — repeated rereads (tracked lower bound)");
+    lines.push(`  ≈ ${formatTokens(r.reclaimableTotal)} across these sessions · median ${r.pollutionMedian}% of window / session`);
+    lines.push("");
+    lines.push("Output volume by tool — what filled context (≈ tokens, cumulative)");
+    for (const [k, v] of r.outputByTool)
+        lines.push(`  ${k.padEnd(30)} ${formatTokens(v)}`);
+    lines.push("");
+    lines.push("Most-used tools (calls)");
+    for (const [k, v] of r.toolsTop)
+        lines.push(`  ${k.padEnd(30)} ${v}`);
+    lines.push("");
+    lines.push("Echo usage (observational — your own sessions, not a controlled A/B)");
+    lines.push(`  ${r.echoSessions}/${r.scored} sessions called Echo (memory search / save_conversation)`);
+    if (r.echoPollutionMedian !== null && r.coldPollutionMedian !== null) {
+        lines.push(`  median pollution — with Echo ${r.echoPollutionMedian}% · without ${r.coldPollutionMedian}%`);
+    }
+    lines.push("");
+    lines.push("Honesty: pollution = tracked repeated-read lower bound (provider eviction is unobservable).");
+    lines.push("Output volume is cumulative tool output seen over each session, not current-window-only.");
+    return lines.join("\n");
+}
+function pickClient(mode) {
+    if (mode === "codex" || mode === "claude-code" || mode === "claude-desktop")
+        return mode;
+    // auto / both → the client with the most sessions on disk
+    const counts = Object.keys(adapters).map((c) => [c, adapters[c].findAll().length]);
+    counts.sort((a, b) => b[1] - a[1]);
+    return counts[0] && counts[0][1] > 0 ? counts[0][0] : "codex";
+}
+function safeMtime(file) {
+    try {
+        return fs.statSync(file).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+function median(xs) {
+    if (!xs.length)
+        return 0;
+    const a = [...xs].sort((x, y) => x - y);
+    const m = Math.floor(a.length / 2);
+    return a.length % 2 ? a[m] : Math.round((a[m - 1] + a[m]) / 2);
+}
+function percentile(xs, p) {
+    if (!xs.length)
+        return 0;
+    const a = [...xs].sort((x, y) => x - y);
+    return a[Math.min(a.length - 1, Math.floor((p / 100) * a.length))];
+}
+function topEntries(map, n) {
+    return Object.entries(map).filter((e) => e[1] > 0).sort((a, b) => b[1] - a[1]).slice(0, n);
+}

package/dist/hud/server.js

@@ -0,0 +1,95 @@
+import http from "node:http";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { HudMonitor } from "./monitor.js";
+import { HUD_HTML } from "./web.js";
+import { buildCapsuleText } from "./capsule.js";
+export async function createHudServer(opts = {}) {
+    const mode = opts.mode || "auto";
+    const port = opts.port ?? 17377;
+    const clients = new Set();
+    const monitor = new HudMonitor(mode, opts.pollMs ?? 750);
+    let latest = monitor.snapshot();
+    monitor.on("state", (state) => {
+        latest = state;
+        const payload = `data: ${JSON.stringify(latest)}\n\n`;
+        for (const res of clients)
+            res.write(payload);
+    });
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
+        if (serveHudAsset(url.pathname, res))
+            return;
+        if (url.pathname === "/events") {
+            res.writeHead(200, {
+                "content-type": "text/event-stream",
+                "cache-control": "no-cache",
+                connection: "keep-alive",
+            });
+            res.write(`data: ${JSON.stringify(latest)}\n\n`);
+            clients.add(res);
+            req.on("close", () => clients.delete(res));
+            return;
+        }
+        if (url.pathname === "/state") {
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify(latest, null, 2));
+            return;
+        }
+        if (url.pathname === "/capsule") {
+            const active = latest.active;
+            if (!active) {
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify({ ok: false, reason: "no_active_session" }));
+                return;
+            }
+            const text = buildCapsuleText(active);
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify({ ok: true, capsule: text }));
+            return;
+        }
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        res.end(HUD_HTML);
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    monitor.start();
+    const address = server.address();
+    const actualPort = typeof address === "object" && address ? address.port : port;
+    return {
+        port: actualPort,
+        url: `http://127.0.0.1:${actualPort}`,
+        state: () => latest,
+        close: () => new Promise((resolve) => {
+            monitor.stop();
+            for (const res of clients)
+                res.end();
+            server.close(() => resolve());
+        }),
+    };
+}
+function serveHudAsset(pathname, res) {
+    const assets = {
+        "/assets/hud/echo-face-cutout.png": "../../assets/hud/echo-face-cutout.png",
+    };
+    const asset = assets[pathname];
+    if (!asset)
+        return false;
+    const assetPath = fileURLToPath(new URL(asset, import.meta.url));
+    if (!fs.existsSync(assetPath)) {
+        res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+        res.end("HUD asset not found");
+        return true;
+    }
+    res.writeHead(200, {
+        "content-type": "image/png",
+        "cache-control": "public, max-age=31536000, immutable",
+    });
+    fs.createReadStream(assetPath).pipe(res);
+    return true;
+}