local-agentic-ai-mem 0.1.0

package/dist/db.js

@@ -0,0 +1,359 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIMS = void 0;
+exports.resolveDbPath = resolveDbPath;
+exports.db = db;
+exports.closeDb = closeDb;
+exports.encodeVec = encodeVec;
+exports.decodeVec = decodeVec;
+exports.cosine = cosine;
+exports.upsertProject = upsertProject;
+exports.insertMemory = insertMemory;
+exports.liveMemories = liveMemories;
+exports.lexicalSearch = lexicalSearch;
+exports.markRecalled = markRecalled;
+exports.replaceFacts = replaceFacts;
+exports.getFacts = getFacts;
+exports.setMeta = setMeta;
+exports.getMeta = getMeta;
+exports.recordInjection = recordInjection;
+exports.openInjections = openInjections;
+exports.resolveInjection = resolveInjection;
+exports.complianceReport = complianceReport;
+/**
+ * Local storage. No server, no account, no network.
+ *
+ * Everything lives in one SQLite file on the machine that produced it. That is
+ * not a downgrade from the hosted version — at this scale the server was doing
+ * nothing a local file cannot. A median project's whole vector index is 375 KB
+ * and a brute-force cosine scan over 2,000 vectors takes 1.7ms, so pgvector,
+ * HNSW and the entire indexing apparatus were solving a problem that does not
+ * exist for a single user.
+ *
+ * Vectors are stored as raw float32 BLOBs and scanned in JS. FTS5 handles the
+ * lexical arm, replacing the tsvector column.
+ */
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+exports.DIMS = 384;
+// ── where the database lives ─────────────────────────────────────────────────
+/**
+ * A repo containing `.agentic-memory/` keeps its memory with the code, so it
+ * travels through git to other machines and to teammates. Otherwise memory is
+ * global to the user. Both are local files; neither leaves the machine.
+ */
+function resolveDbPath(cwd = process.cwd()) {
+    const override = process.env.AGENTIC_MEMORY_DB;
+    if (override)
+        return override;
+    let dir = cwd;
+    for (let i = 0; i < 12; i++) {
+        if ((0, fs_1.existsSync)((0, path_1.join)(dir, ".agentic-memory"))) {
+            return (0, path_1.join)(dir, ".agentic-memory", "memory.db");
+        }
+        const parent = (0, path_1.dirname)(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return (0, path_1.join)((0, os_1.homedir)(), ".agentic-memory", "memory.db");
+}
+// ── schema ───────────────────────────────────────────────────────────────────
+const SCHEMA = `
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous = NORMAL;
+
+CREATE TABLE IF NOT EXISTS projects (
+  id         INTEGER PRIMARY KEY,
+  slug       TEXT NOT NULL UNIQUE,
+  root       TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS memories (
+  id            INTEGER PRIMARY KEY,
+  project_id    INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  prompt        TEXT NOT NULL,
+  content       TEXT,
+  decisions     TEXT NOT NULL DEFAULT '[]',
+  files         TEXT NOT NULL DEFAULT '[]',
+  tool_calls    TEXT NOT NULL DEFAULT '[]',
+  git_commit    TEXT,
+  anchor_sha    TEXT,
+  confidence    TEXT NOT NULL DEFAULT 'stated',
+  tier          INTEGER NOT NULL DEFAULT 3,
+  started_at    TEXT NOT NULL,
+  recall_count  INTEGER NOT NULL DEFAULT 0,
+  last_recalled TEXT,
+  archived_at   TEXT,
+  superseded_at TEXT,
+  superseded_by INTEGER,
+  session_id    TEXT,
+  vec           BLOB,
+  prompt_vec    BLOB
+);
+
+CREATE INDEX IF NOT EXISTS memories_live_idx
+  ON memories (project_id, tier)
+  WHERE archived_at IS NULL AND superseded_at IS NULL;
+CREATE INDEX IF NOT EXISTS memories_session_idx ON memories (session_id);
+
+-- Lexical arm. Embeddings are weak on opaque tokens — SHAs, error codes,
+-- symbol names — which is exactly what a developer searches for.
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+  content, prompt, decisions, files,
+  content='memories', content_rowid='id', tokenize='porter unicode61'
+);
+
+CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, content, prompt, decisions, files)
+  VALUES (new.id, new.content, new.prompt, new.decisions, new.files);
+END;
+CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, content, prompt, decisions, files)
+  VALUES ('delete', old.id, old.content, old.prompt, old.decisions, old.files);
+END;
+CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, content, prompt, decisions, files)
+  VALUES ('delete', old.id, old.content, old.prompt, old.decisions, old.files);
+  INSERT INTO memories_fts(rowid, content, prompt, decisions, files)
+  VALUES (new.id, new.content, new.prompt, new.decisions, new.files);
+END;
+
+-- Tier 1. Small, injected whole, never searched.
+CREATE TABLE IF NOT EXISTS facts (
+  id             INTEGER PRIMARY KEY,
+  project_id     INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  kind           TEXT NOT NULL,
+  fact           TEXT NOT NULL,
+  evidence       TEXT,
+  files          TEXT NOT NULL DEFAULT '[]',
+  observations   INTEGER NOT NULL DEFAULT 1,
+  confidence     TEXT NOT NULL DEFAULT 'stated',
+  last_confirmed TEXT NOT NULL DEFAULT (datetime('now')),
+  superseded_at  TEXT,
+  UNIQUE (project_id, kind, fact)
+);
+
+/**
+ * What was injected, and what the session then did about it.
+ *
+ * Every other measurement in this package is about retrieval — whether the
+ * right memory was surfaced. This is the only one about use. They are
+ * different questions and only the second decides whether any of it helps.
+ */
+CREATE TABLE IF NOT EXISTS injections (
+  id            INTEGER PRIMARY KEY,
+  session_id    TEXT NOT NULL,
+  project_id    INTEGER REFERENCES projects(id) ON DELETE CASCADE,
+  kind          TEXT NOT NULL,
+  at            TEXT NOT NULL DEFAULT (datetime('now')),
+  memory_ids    TEXT NOT NULL DEFAULT '[]',
+  files         TEXT NOT NULL DEFAULT '[]',
+  tokens        TEXT NOT NULL DEFAULT '[]',
+  pitfall_files TEXT NOT NULL DEFAULT '[]',
+  resolved_at     TEXT,
+  files_named     INTEGER,
+  files_reread    INTEGER,
+  tokens_total    INTEGER,
+  tokens_echoed   INTEGER,
+  pitfall_touched INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS injections_open_idx ON injections (session_id);
+
+CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+`;
+let _db = null;
+function db(cwd) {
+    if (_db)
+        return _db;
+    const path = resolveDbPath(cwd);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(path), { recursive: true });
+    _db = new better_sqlite3_1.default(path);
+    _db.exec(SCHEMA);
+    return _db;
+}
+function closeDb() {
+    _db?.close();
+    _db = null;
+}
+// ── vectors ──────────────────────────────────────────────────────────────────
+function encodeVec(v) {
+    const f = v instanceof Float32Array ? v : Float32Array.from(v);
+    return Buffer.from(f.buffer, f.byteOffset, f.byteLength);
+}
+function decodeVec(b) {
+    if (!b || b.byteLength < exports.DIMS * 4)
+        return null;
+    // Copy rather than view: better-sqlite3 buffers are not guaranteed aligned.
+    const out = new Float32Array(exports.DIMS);
+    for (let i = 0; i < exports.DIMS; i++)
+        out[i] = b.readFloatLE(i * 4);
+    return out;
+}
+function cosine(a, b) {
+    let dot = 0, na = 0, nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    const d = Math.sqrt(na) * Math.sqrt(nb);
+    return d === 0 ? 0 : dot / d;
+}
+// ── projects ─────────────────────────────────────────────────────────────────
+function upsertProject(slug, root) {
+    const conn = db();
+    conn.prepare("INSERT OR IGNORE INTO projects (slug, root) VALUES (?, ?)").run(slug, root ?? null);
+    const row = conn.prepare("SELECT id FROM projects WHERE slug = ?").get(slug);
+    return row.id;
+}
+function insertMemory(m) {
+    const info = db()
+        .prepare(`INSERT INTO memories
+        (project_id, prompt, content, decisions, files, tool_calls, git_commit,
+         anchor_sha, confidence, tier, started_at, session_id, vec, prompt_vec)
+       VALUES (@project_id, @prompt, @content, @decisions, @files, @tool_calls, @git_commit,
+               @anchor_sha, @confidence, @tier, @started_at, @session_id, @vec, @prompt_vec)`)
+        .run({
+        project_id: m.projectId,
+        prompt: m.prompt,
+        content: m.content,
+        decisions: JSON.stringify(m.decisions),
+        files: JSON.stringify(m.files),
+        tool_calls: JSON.stringify(m.toolCalls),
+        git_commit: m.gitCommit,
+        anchor_sha: m.anchorSha,
+        confidence: m.confidence,
+        tier: m.tier,
+        started_at: m.startedAt,
+        session_id: m.sessionId,
+        vec: encodeVec(m.vec),
+        prompt_vec: encodeVec(m.promptVec),
+    });
+    return Number(info.lastInsertRowid);
+}
+/** Live memories, optionally restricted to a tier. Vectors included. */
+function liveMemories(opts = {}) {
+    const where = ["m.archived_at IS NULL", "m.superseded_at IS NULL"];
+    const params = [];
+    if (opts.projectId !== undefined) {
+        where.push("m.project_id = ?");
+        params.push(opts.projectId);
+    }
+    if (opts.tier !== undefined) {
+        where.push("m.tier <= ?");
+        params.push(opts.tier);
+    }
+    return db()
+        .prepare(`SELECT m.*, p.slug AS project_slug
+         FROM memories m JOIN projects p ON p.id = m.project_id
+        WHERE ${where.join(" AND ")}`)
+        .all(...params);
+}
+/** FTS5 lexical search. Returns ids ranked by bm25. */
+function lexicalSearch(query, limit) {
+    // FTS5 treats punctuation as syntax; quote each term so arbitrary user text
+    // cannot produce a syntax error.
+    const terms = query
+        .toLowerCase()
+        .split(/[^a-z0-9_./-]+/)
+        .filter((t) => t.length > 2)
+        .slice(0, 12)
+        .map((t) => `"${t.replace(/"/g, "")}"`);
+    if (terms.length === 0)
+        return [];
+    try {
+        const rows = db()
+            .prepare(`SELECT rowid FROM memories_fts WHERE memories_fts MATCH ?
+          ORDER BY bm25(memories_fts) LIMIT ?`)
+            .all(terms.join(" OR "), limit);
+        return rows.map((r) => r.rowid);
+    }
+    catch {
+        return [];
+    }
+}
+function markRecalled(ids) {
+    if (ids.length === 0)
+        return;
+    const stmt = db().prepare("UPDATE memories SET recall_count = recall_count + 1, last_recalled = datetime('now') WHERE id = ?");
+    const tx = db().transaction((list) => list.forEach((id) => stmt.run(id)));
+    tx(ids);
+}
+function replaceFacts(projectId, facts) {
+    const conn = db();
+    const tx = conn.transaction(() => {
+        // Retire rather than delete: a fact that stops being derivable usually
+        // means the code moved past it, and that history is worth keeping.
+        conn.prepare("UPDATE facts SET superseded_at = datetime('now') WHERE project_id = ?").run(projectId);
+        const stmt = conn.prepare(`INSERT INTO facts (project_id, kind, fact, evidence, files, observations, confidence, superseded_at, last_confirmed)
+       VALUES (?, ?, ?, ?, ?, ?, ?, NULL, datetime('now'))
+       ON CONFLICT (project_id, kind, fact) DO UPDATE SET
+         evidence = excluded.evidence,
+         files = excluded.files,
+         observations = excluded.observations,
+         confidence = excluded.confidence,
+         superseded_at = NULL,
+         last_confirmed = datetime('now')`);
+        for (const f of facts) {
+            stmt.run(projectId, f.kind, f.fact, f.evidence, JSON.stringify(f.files), f.observations, f.confidence);
+        }
+    });
+    tx();
+}
+function getFacts(projectId, limit = 40) {
+    return db()
+        .prepare(`SELECT kind, fact, evidence, files, observations, confidence
+         FROM facts WHERE project_id = ? AND superseded_at IS NULL
+        ORDER BY observations DESC LIMIT ?`)
+        .all(projectId, limit);
+}
+function setMeta(key, value) {
+    db().prepare("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = ?").run(key, value, value);
+}
+function getMeta(key) {
+    const row = db().prepare("SELECT value FROM meta WHERE key = ?").get(key);
+    return row?.value ?? null;
+}
+function recordInjection(r) {
+    const info = db()
+        .prepare(`INSERT INTO injections (session_id, project_id, kind, memory_ids, files, tokens, pitfall_files)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`)
+        .run(r.sessionId, r.projectId, r.kind, JSON.stringify(r.memoryIds), JSON.stringify(r.files), JSON.stringify(r.tokens), JSON.stringify(r.pitfallFiles));
+    return Number(info.lastInsertRowid);
+}
+function openInjections(sessionId) {
+    return db()
+        .prepare("SELECT id, kind, files, tokens, pitfall_files FROM injections WHERE session_id = ? AND resolved_at IS NULL")
+        .all(sessionId);
+}
+function resolveInjection(id, o) {
+    db()
+        .prepare(`UPDATE injections
+          SET resolved_at = datetime('now'), files_named = ?, files_reread = ?,
+              tokens_total = ?, tokens_echoed = ?, pitfall_touched = ?
+        WHERE id = ?`)
+        .run(o.filesNamed, o.filesReread, o.tokensTotal, o.tokensEchoed, o.pitfallTouched, id);
+}
+function complianceReport() {
+    const row = db()
+        .prepare(`SELECT
+         count(*) AS resolved,
+         sum(CASE WHEN tokens_echoed > 0 THEN 1 ELSE 0 END) AS echoed,
+         sum(CASE WHEN files_named > 0 AND files_reread = 0 THEN 1 ELSE 0 END) AS avoided_reread,
+         sum(CASE WHEN files_named > 0 THEN 1 ELSE 0 END) AS had_files,
+         sum(pitfall_touched) AS pitfall_touched,
+         sum(tokens_echoed) AS tokens_echoed,
+         sum(tokens_total) AS tokens_total
+       FROM injections WHERE resolved_at IS NOT NULL`)
+        .get();
+    const open = db().prepare("SELECT count(*) n FROM injections WHERE resolved_at IS NULL").get().n;
+    return { ...row, open };
+}

package/dist/index.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * agentic-memory — local-first memory for Claude Code.
+ *
+ * No server, no account, no API key. One SQLite file on the machine that
+ * produced it.
+ */
+const install_1 = require("./commands/install");
+const uninstall_legacy_1 = require("./commands/uninstall-legacy");
+function help() {
+    console.log(`
+  agentic-memory — local-first memory for Claude Code
+
+    install [--project]   install hooks + MCP; --project stores memory in
+                          ./.agentic-memory/ so it travels through git
+    mcp                   run the MCP server on stdio (Claude Code calls this)
+    import <dump.sql>     import a MemoryOS pg_dump into the local database
+    status                what is stored, and what is left of any old install
+    purge-legacy          remove a previous MemoryOS install and stop
+
+  Everything is local. Nothing is uploaded.
+`);
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    switch (cmd) {
+        case "install":
+            (0, install_1.install)({ projectLocal: rest.includes("--project") });
+            break;
+        case "mcp":
+            require("./mcp/server").serve();
+            break;
+        case "import":
+            await require("./commands/import").importDump(rest[0]);
+            break;
+        case "status":
+            require("./commands/status").status();
+            break;
+        case "purge-legacy": {
+            const r = (0, uninstall_legacy_1.removeLegacyInstall)();
+            console.log(`  hooks removed     ${r.hooksRemoved.length}`);
+            console.log(`  MCP shim          ${r.mcpRemoved ? "removed" : "none"}`);
+            console.log(`  credential file   ${r.credentialRemoved ? "removed" : "none"}`);
+            console.log(`  settings entries  ${r.settingsCleaned}`);
+            const left = (0, uninstall_legacy_1.findLegacyLeftovers)();
+            console.log(left.length ? `  still present:\n    ${left.join("\n    ")}` : "  nothing left behind");
+            break;
+        }
+        default:
+            help();
+    }
+}
+main().catch((e) => {
+    console.error(e?.message ?? e);
+    process.exit(1);
+});

package/dist/lib/compliance.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Did the injected memory change anything?
+ *
+ * Everything else this package measures is retrieval — whether the right
+ * memory was surfaced. This is the only measurement of *use*, and it is the
+ * one that decides whether any of the rest is worth its complexity. A memory
+ * system that surfaces perfect context and is then ignored is theatre.
+ *
+ * Three signals, in ascending order of how much they prove:
+ *
+ *   echo          a distinctive token from the injected text appears in the
+ *                 assistant's output and could not have come from the prompt
+ *                 or from a file the session read. Weak — the model may
+ *                 paraphrase — so read it as a floor, not a rate.
+ *
+ *   reread        memory described a file and the session read it anyway. If
+ *                 that happens every time, the injection is not landing.
+ *                 Correlational: the session may have had another reason.
+ *
+ *   pitfall touch memory warned that an approach failed, and the session
+ *                 edited the file that pitfall was about. The closest thing
+ *                 here to a counterfactual, and the only signal worth acting
+ *                 on individually. Flagged for review, never treated as proof.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.distinctiveTokens = distinctiveTokens;
+exports.readTranscript = readTranscript;
+exports.scoreInjection = scoreInjection;
+exports.formatReport = formatReport;
+/** Words too common to prove anything if they reappear. */
+const STOPWORDS = new Set([
+    "about", "after", "again", "because", "before", "being", "between", "could",
+    "every", "first", "found", "important", "instead", "into", "issue", "later",
+    "needs", "other", "problem", "return", "should", "since", "still", "their",
+    "there", "these", "thing", "those", "through", "using", "value", "which",
+    "while", "would", "change", "changed", "changes", "check", "class", "config",
+    "error", "field", "files", "function", "import", "method", "number", "object",
+    "output", "point", "result", "server", "state", "string", "table", "there",
+    "update", "where", "write",
+]);
+/**
+ * Tokens distinctive enough that seeing them again is evidence rather than
+ * coincidence: long enough, not ordinary English, and absent from the prompt.
+ */
+function distinctiveTokens(injected, prompt, max = 25) {
+    const promptTokens = new Set(tokenize(prompt));
+    const out = [];
+    const seen = new Set();
+    for (const t of tokenize(injected)) {
+        if (t.length < 5 || t.length > 40)
+            continue;
+        if (STOPWORDS.has(t))
+            continue;
+        if (promptTokens.has(t))
+            continue;
+        if (seen.has(t))
+            continue;
+        // Prefer things that look like identifiers or paths over prose.
+        const identifierish = /[._/-]/.test(t) || /\d/.test(t);
+        seen.add(t);
+        out.push(t);
+        if (identifierish && out.length >= max)
+            break;
+    }
+    return out.slice(0, max);
+}
+function tokenize(s) {
+    return (s || "").toLowerCase().replace(/[^a-z0-9._/-]+/g, " ").split(/\s+/).filter(Boolean);
+}
+/**
+ * Pull the three things compliance needs out of a Claude Code transcript.
+ * Tolerates partial and malformed lines — a transcript being unparseable
+ * should cost a measurement, not a session.
+ */
+function readTranscript(jsonl) {
+    const read = new Set();
+    const edited = new Set();
+    const said = [];
+    for (const line of (jsonl || "").split("\n")) {
+        const t = line.trim();
+        if (!t.startsWith("{"))
+            continue;
+        let row;
+        try {
+            row = JSON.parse(t);
+        }
+        catch {
+            continue;
+        }
+        const blocks = row?.message?.content;
+        if (row?.type !== "assistant" || !Array.isArray(blocks))
+            continue;
+        for (const b of blocks) {
+            if (b?.type === "text" && typeof b.text === "string")
+                said.push(b.text);
+            else if (b?.type === "tool_use") {
+                const f = b.input?.file_path ?? b.input?.path;
+                if (typeof f !== "string")
+                    continue;
+                if (b.name === "Read")
+                    read.add(f);
+                else if (["Write", "Edit", "MultiEdit", "NotebookEdit"].includes(b.name))
+                    edited.add(f);
+            }
+        }
+    }
+    return { read, edited, said: said.join("\n").toLowerCase() };
+}
+function scoreInjection(injected, t) {
+    const sameFile = (a, b) => a === b || a.endsWith("/" + b) || b.endsWith("/" + a);
+    const filesReread = injected.files.filter((f) => [...t.read].some((r) => sameFile(r, f))).length;
+    // A token only counts as echoed if it did not arrive by another route: if
+    // the session read a file whose path contains it, the model could have seen
+    // it there rather than in the memory.
+    const readPaths = [...t.read].join(" ").toLowerCase();
+    const tokensEchoed = injected.tokens.filter((tok) => t.said.includes(tok) && !readPaths.includes(tok)).length;
+    const pitfallTouched = injected.pitfallFiles.filter((f) => [...t.edited].some((e) => sameFile(e, f))).length;
+    return {
+        filesNamed: injected.files.length,
+        filesReread,
+        tokensTotal: injected.tokens.length,
+        tokensEchoed,
+        pitfallTouched,
+    };
+}
+/** Render the report. Deliberately states what each number cannot prove. */
+function formatReport(r) {
+    const n = Number(r.resolved) || 0;
+    if (n === 0) {
+        return "\n  No resolved injections yet. Memory has to be injected and a\n  session finished before there is anything to measure.\n";
+    }
+    const pct = (x, d = n) => (d ? ((Number(x) || 0) / d * 100).toFixed(1) + "%" : "—");
+    const hadFiles = Number(r.had_files) || 0;
+    const echoRate = (Number(r.echoed) || 0) / n;
+    const avoidRate = hadFiles ? (Number(r.avoided_reread) || 0) / hadFiles : 0;
+    // The decision this instrumentation exists to serve, printed with the
+    // numbers rather than written down somewhere that will be lost. Retrieval
+    // buys +2.8 coverage points over tier-1 facts alone and costs roughly 80%
+    // of this package; it is only worth keeping if memory is actually used.
+    const verdict = n < 30
+        ? "  Too few to judge. Come back after ~3 weeks of real sessions."
+        : echoRate < 0.15 && avoidRate < 0.25
+            ? [
+                "  READ AND IGNORED. Memory is being surfaced and not used.",
+                "  Cut back to tier-1 facts plus save_memory, and delete recall.ts,",
+                "  embed.ts and the vector/FTS machinery — retrieval is buying 2.8",
+                "  coverage points for ~80% of this package.",
+            ].join("\n")
+            : echoRate < 0.15
+                ? "  Weak. Memory rarely echoed, but re-reads are being avoided.\n  Inconclusive — keep collecting, and check the pitfall list below."
+                : "  BEING USED. Memory is landing often enough to keep the retrieval half.";
+    return [
+        "",
+        `  injections measured        ${n}${r.open ? `  (${r.open} still open)` : ""}`,
+        "",
+        `  echoed a distinctive token ${pct(r.echoed)}   of injections`,
+        `    tokens echoed            ${Number(r.tokens_echoed) || 0} of ${Number(r.tokens_total) || 0}`,
+        `  avoided re-reading a file  ${pct(r.avoided_reread, hadFiles)}   of the ${hadFiles} that named files`,
+        `  pitfall files edited       ${Number(r.pitfall_touched) || 0}   worth reviewing individually`,
+        "",
+        verdict,
+        "",
+        "  Echo is a floor, not a rate — the model may use a memory and paraphrase",
+        "  it. Avoided-reread is correlational. Only the pitfall count is close to",
+        "  evidence, and it is a prompt to go look, not a verdict.",
+        "",
+    ].join("\n");
+}