pi-mega-compact 0.4.4 → 0.4.6

package/dist/src/embedder.js

@@ -0,0 +1,102 @@
+/**
+ * embedder.ts — pluggable text embedding for the local vector store.
+ *
+ * Default embedder is a zero-dependency, deterministic hashed n-gram bag
+ * encoder — no native build, no network, no external library, works offline.
+ * It is heuristic-strength (good enough to rank "which checkpoint is relevant
+ * to this query?"), not RAG-grade. A stronger LOCAL embedding backend (your own
+ * localhost ONNX/TEI/Ollama server) can be plugged in via MEGACOMPACT_EMBEDDING_URL
+ * — see httpEmbedder.ts. The `Embedder` interface is the seam both implement;
+ * this extension ships no model and makes no remote call (PREVENT-PI-004).
+ */
+import { HttpEmbedder, embeddingConfigFromEnv } from "./httpEmbedder.js";
+/** Normalize a vector to unit length (cosine-sim safe). Returns a new array. */
+export function l2Normalize(v) {
+    let sumSq = 0;
+    for (const x of v)
+        sumSq += x * x;
+    const norm = Math.sqrt(sumSq);
+    if (norm === 0)
+        return v.map(() => 0);
+    return v.map((x) => x / norm);
+}
+/** Cosine similarity in [-1, 1]. Assumes inputs are same dim. */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let 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];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/** Stable 32-bit string hash (FNV-1a). */
+function fnv1a(str) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+/**
+ * Default embedder: character 3-gram bag-of-counts, hashed into a fixed-dim
+ * vector, L2-normalized. Captures local lexical/structure overlap well enough
+ * for checkpoint relevance ranking.
+ */
+export class TrigramEmbedder {
+    dim;
+    seed;
+    constructor(dim = 512, seed = 0x9e3779b9) {
+        this.dim = dim;
+        this.seed = seed >>> 0;
+    }
+    embed(text) {
+        const vec = new Array(this.dim).fill(0);
+        const norm = text.toLowerCase().replace(/\s+/g, " ");
+        if (norm.length === 0)
+            return l2Normalize(vec);
+        // Whole-string + word + char-trigram signals.
+        vec[fnv1a(norm) % this.dim] += 1;
+        for (const word of norm.split(" ")) {
+            if (word.length === 0)
+                continue;
+            vec[fnv1a(word) % this.dim] += 1;
+            for (let i = 0; i + 3 <= word.length; i++) {
+                const gram = word.slice(i, i + 3);
+                const idx = (fnv1a(gram) ^ this.seed) % this.dim;
+                vec[idx] += 1;
+            }
+        }
+        // Edge: very short tokens still get a slot.
+        if (norm.length < 3)
+            vec[fnv1a(norm) % this.dim] += 1;
+        return l2Normalize(vec);
+    }
+}
+/**
+ * Select the default embedder used by VectorStore.
+ *
+ * - If MEGACOMPACT_EMBEDDING_URL points at a localhost server, use HttpEmbedder
+ *   (your own local embedding backend — ONNX/TEI/Ollama/etc). This is the
+ *   PREVENT-PI-004-sanctioned "bring your own" path: the endpoint is a
+ *   user-spawned loopback server, so conversation content never leaves the box.
+ * - Otherwise the TrigramEmbedder is the shipped default: zero-dependency,
+ *   deterministic, GPU-free, cross-platform, fully offline.
+ *
+ * The `Embedder` interface is the seam for any LOCAL embedder. Never point it
+ * at a remote provider — that would violate PREVENT-PI-004. A user wanting
+ * semantic-grade dedup should run a local embedding server and set the URL.
+ */
+export function defaultEmbedder() {
+    const cfg = embeddingConfigFromEnv();
+    if (cfg)
+        return new HttpEmbedder(cfg);
+    return new TrigramEmbedder();
+}

package/dist/src/engine.js

@@ -0,0 +1,137 @@
+/**
+ * engine.ts — Layer 4 (PERSIST / checkpoint) orchestration.
+ *
+ * Ties the Sprint 1–2 primitives into the compaction pipeline the extension
+ * calls. Pure of any pi runtime type: it consumes EngineMessage[] and talks to
+ * the on-disk VectorStore. The extension adapts pi messages -> EngineMessage
+ * (see adapt.ts) and reports status.
+ *
+ * Pipeline (mirrors the PLAN Trident stack):
+ *   SUPERSEDE (drop obsolete file reads)
+ *   -> COLLAPSE (summarize the compacted slice)
+ *   -> CLUSTER  (embed + persist a checkpoint to the vector store)
+ */
+import { findSuperseded, supersede } from "./supersede.js";
+import { summarizeMessages, mergeCompactSummaries, formatCompactSummary } from "./compact.js";
+import { extractiveSummarize } from "./extractive.js";
+import { estimateSessionTokens, estimateBlockTokens } from "./tokens.js";
+import { computeRegionHash, VectorStore } from "./vectorStore.js";
+/** Default store used by the convenience `compactSession`. */
+let defaultStore;
+export function getDefaultStore(stateDir) {
+    if (!defaultStore)
+        defaultStore = new VectorStore({ stateDir });
+    return defaultStore;
+}
+/** Replace the default store (used by tests to inject a temp dir). */
+export function setDefaultStore(store) {
+    defaultStore = store;
+}
+/**
+ * Run the Trident pipeline over a message slice and persist a checkpoint.
+ *
+ * `messages` is the FULL session view; `keepFrom` marks where the verbatim tail
+ * starts, so indices stay absolute and the caller can map the drop range back
+ * onto the real (pi) message array via adapt.ts. Returns a `skipped` result
+ * when the compactable slice is empty.
+ */
+export function compactSession(input, store = getDefaultStore()) {
+    const keepFrom = input.keepFrom ?? input.messages.length;
+    const compactable = input.messages.slice(0, keepFrom);
+    const compactedFrom = keepFrom;
+    if (compactable.length === 0) {
+        return {
+            skipped: true,
+            deduped: false,
+            summary: "",
+            regionHash: "",
+            tokenEstimate: 0,
+            originalTokenEstimate: 0,
+            compactedFrom,
+        };
+    }
+    // LAYER 1 — SUPERSEDE: zero-cost factual pruning of obsolete file reads.
+    const supersededIdx = new Set(findSuperseded(compactable));
+    const keep = compactable.filter((_m, i) => !supersededIdx.has(i));
+    // LAYER 2 — COLLAPSE: build (or accept) the summary.
+    // When useExtractiveSummary is enabled (default), use the deterministic
+    // extractive engine that compresses ~70K tokens → ~2K tokens with structured
+    // fields populated. Falls back to legacy concatenation when disabled.
+    const useExtractive = input.useExtractiveSummary !== false;
+    let summary;
+    let topicSummary;
+    let keyDecisions;
+    let nextSteps;
+    let filesModified;
+    if (useExtractive && !input.summary) {
+        const ext = extractiveSummarize(keep);
+        summary = ext.topicSummary;
+        topicSummary = ext.topicSummary;
+        keyDecisions = input.keyDecisions ?? ext.keyDecisions;
+        nextSteps = input.nextSteps ?? ext.nextSteps;
+        filesModified = input.filesModified ?? ext.filesModified;
+    }
+    else {
+        const collapsed = input.summary ?? summarizeMessages(keep);
+        summary = formatCompactSummary(collapsed);
+        topicSummary = undefined;
+        keyDecisions = input.keyDecisions ?? [];
+        nextSteps = input.nextSteps ?? [];
+        filesModified = input.filesModified ?? [];
+    }
+    // Honest "tokens saved" accounting:
+    //  - originalTokenEstimate = the dropped region's token count (what context
+    //    held before compaction) = the compacted slice's tokens.
+    //  - storedTokens = the persisted summary's token count, computed from the
+    //    actual summary string so it's honest for BOTH the extractive and legacy
+    //    COLLAPSE paths (the legacy path's fallback estimateSessionTokens is the
+    //    *original* size, not the stored size).
+    const originalTokenEstimate = estimateSessionTokens(compactable);
+    const storedTokens = estimateBlockTokens(summary);
+    // Region text = the compacted slice, used for dedup + embedding.
+    const regionText = input.regionText ?? keep.map((m) => m.text).join("\n");
+    const regionHash = computeRegionHash(regionText);
+    const add = store.add({
+        sessionId: input.sessionId,
+        summary,
+        topicSummary,
+        keyDecisions,
+        nextSteps,
+        filesModified,
+        regionText,
+        tokenEstimate: storedTokens,
+        originalTokenEstimate,
+        timestamp: input.timestamp ?? 0,
+    });
+    return {
+        skipped: false,
+        deduped: add.deduped,
+        dedupReason: add.reason,
+        checkpointId: add.checkpoint.checkpointId,
+        summary,
+        regionHash,
+        tokenEstimate: storedTokens,
+        originalTokenEstimate,
+        compactedFrom,
+    };
+}
+/**
+ * Layer 5 (query side, shared by auto-inline + on-demand): search the store and
+ * drop any checkpoint already injected this session. The caller decides how to
+ * inject (Sprint 4 wires injection); this module only does the deduped search.
+ */
+export function recall(input, store = getDefaultStore()) {
+    const hits = store.search(input.sessionId, input.query, input.limit ?? 3);
+    const newHits = input.skipInjected === false ? hits : hits.filter((h) => !store.wasInjected(input.sessionId, h.checkpoint.checkpointId));
+    return { hits, newHits };
+}
+/** Merge a freshly compacted summary into the prior persisted summary text. */
+export function mergeSummary(existing, next) {
+    return mergeCompactSummaries(existing, next);
+}
+/** Exposed for callers that want raw supersede stats (status reporting). */
+export function supersededCount(messages) {
+    return new Set(findSuperseded(messages)).size;
+}
+/** Re-export so the extension has one import surface. */
+export { supersede, summarizeMessages, formatCompactSummary };

package/dist/src/engine.test.js

@@ -0,0 +1,111 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { VectorStore } from "./vectorStore.js";
+import { compactSession, recall, mergeSummary, supersededCount } from "./engine.js";
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-engine-"));
+let counter = 0;
+function store() {
+    return new VectorStore({ dedupSim: 0.9, stateDir: join(baseTmp, `run-${counter++}`) });
+}
+const SESS = "sess_engine";
+function msg(role, text, toolName) {
+    return toolName ? { role, text, toolName, input: text, output: text } : { role, text };
+}
+test("compactSession supersedes then persists a checkpoint", () => {
+    const s = store();
+    const messages = [
+        msg("user", "read src/server.ts"),
+        msg("assistant", "ok", "Read"),
+        msg("user", "edit src/server.ts"),
+        msg("assistant", "ok", "Edit"),
+        msg("user", "now fix the bug in src/server.ts"),
+        msg("assistant", "done", "Edit"),
+    ];
+    const r = compactSession({ sessionId: SESS, messages, keepFrom: 4, timestamp: 1 }, s);
+    assert.equal(r.skipped, false);
+    assert.equal(r.deduped, false);
+    assert.match(r.checkpointId ?? "", /^chkpt_001$/);
+    assert.ok(r.summary.length > 0, "summary produced by COLLAPSE");
+    assert.ok(r.regionHash.length > 0);
+    // SUPERSEDE dropped the obsolete first read turn (user read @0 superseded by
+    // the edit @2) — so exactly one superseded message in the compacted slice.
+    assert.equal(supersededCount(messages.slice(0, 4)), 1);
+    assert.equal(r.compactedFrom, 4);
+    // The persisted checkpoint is searchable.
+    assert.equal(s.search(SESS, "bug src/server.ts", 5).length, 1);
+});
+test("compactSession is idempotent on identical region (dedup sentinel)", () => {
+    const s = store();
+    const messages = [
+        msg("user", "alpha work on the parser"),
+        msg("assistant", "did it", "Edit"),
+        msg("user", "beta work on the renderer"),
+        msg("assistant", "done", "Edit"),
+    ];
+    const r1 = compactSession({ sessionId: SESS, messages, keepFrom: 4, timestamp: 1 }, s);
+    const r2 = compactSession({ sessionId: SESS, messages, keepFrom: 4, timestamp: 2 }, s);
+    assert.equal(r1.deduped, false);
+    assert.equal(r2.deduped, true);
+    assert.equal(r1.checkpointId, r2.checkpointId);
+    assert.equal(s.search(SESS, "parser", 10).length, 1);
+});
+test("compactSession skipped when slice is empty", () => {
+    const s = store();
+    const r = compactSession({ sessionId: SESS, messages: [msg("user", "only tail")], keepFrom: 0 }, s);
+    assert.equal(r.skipped, true);
+    assert.equal(s.search(SESS, "x", 5).length, 0);
+});
+test("recall drops already-injected checkpoints", () => {
+    const s = store();
+    compactSession({ sessionId: SESS, messages: [msg("user", "investigated src/vectorStore.ts"), msg("assistant", "ok", "Edit")], keepFrom: 2, timestamp: 1 }, s);
+    const first = recall({ sessionId: SESS, query: "vectorStore", limit: 5, skipInjected: true }, s);
+    assert.equal(first.newHits.length, 1);
+    s.markInjected(SESS, first.hits[0].checkpoint.checkpointId);
+    const second = recall({ sessionId: SESS, query: "vectorStore", limit: 5, skipInjected: true }, s);
+    assert.equal(second.newHits.length, 0);
+    // Without the skip flag, both hits still surface.
+    assert.equal(second.hits.length, 1);
+});
+test("mergeSummary accumulates prior + new context", () => {
+    const prior = "<summary>Conversation summary:\n- Key files referenced: src/a.ts.\n</summary>";
+    const next = "<summary>Conversation summary:\n- Key files referenced: src/b.ts.\n</summary>";
+    const merged = mergeSummary(prior, next);
+    assert.ok(merged.includes("src/a.ts"));
+    assert.ok(merged.includes("src/b.ts"));
+    assert.ok(merged.includes("Newly compacted"));
+});
+test("supersededCount reports obsolete reads", () => {
+    const messages = [
+        msg("user", "read src/x.ts"),
+        msg("assistant", "ok", "Read"),
+        msg("user", "write src/x.ts"),
+        msg("assistant", "ok", "Edit"),
+    ];
+    assert.equal(supersededCount(messages), 1);
+});
+test("compactSession with useExtractive produces topicSummary on checkpoint", () => {
+    const s = store();
+    const messages = [
+        msg("user", "let's refactor the auth module in src/auth.ts"),
+        msg("assistant", "I'll start by reading the current implementation", "Read"),
+        msg("user", "extract the login logic into a separate function"),
+        msg("assistant", "Extracted login() into src/auth.ts:45", "Edit"),
+        msg("user", "now add the session token generation"),
+        msg("assistant", "Added generateSessionToken in src/auth.ts:78", "Edit"),
+    ];
+    const r = compactSession({ sessionId: "sess_extr", messages, keepFrom: 4, timestamp: 1, useExtractiveSummary: true }, s);
+    assert.equal(r.skipped, false);
+    assert.ok(r.checkpointId, "checkpoint created");
+    // The checkpoint should have topicSummary populated
+    const hits = s.search("sess_extr", "auth refactor", 5);
+    assert.ok(hits.length > 0);
+    // topicSummary should be present on the stored checkpoint (via extractive path)
+    assert.ok(hits[0].checkpoint.topicSummary, "topicSummary should be populated when useExtractive is true");
+    assert.ok(hits[0].checkpoint.topicSummary.length > 0);
+});
+test("cleanup", () => {
+    rmSync(baseTmp, { recursive: true, force: true });
+});

package/dist/src/extractive.js

@@ -0,0 +1,209 @@
+/**
+ * extractive.ts — deterministic, LLM-free extractive summary engine.
+ *
+ * Replaces the "Key timeline" dump in compact.ts with structured extraction:
+ * topicSummary (one paragraph), keyDecisions, nextSteps, filesModified.
+ *
+ * Target compression: 70K tokens → ~2K tokens (35:1).
+ * Deterministic: same messages → same output, every time.
+ */
+import { estimateBlockTokens } from "./tokens.js";
+// ---- Limits ----------------------------------------------------------------
+const MAX_RECENT_USER = 3;
+const MAX_DECISIONS = 5;
+const MAX_FILES = 10;
+const MAX_PENDING = 5;
+const MAX_TOPIC_LINES = 12;
+// ---- Truncation helper -----------------------------------------------------
+function truncate(s, maxLen) {
+    if (s.length <= maxLen)
+        return s;
+    return s.slice(0, maxLen - 1) + "…";
+}
+/**
+ * Build a one-paragraph topic summary from the message slice.
+ *
+ * This is the compressed replacement for the raw "Key timeline" loop.
+ * Captures: tools used, recent user requests, current work, key files,
+ * pending work. Typically 12 lines / ~500 tokens instead of ~70K.
+ */
+function buildTopicSummary(messages, tools, recentUser, currentWork, keyFiles, pending) {
+    const lines = [];
+    // Scope line
+    const users = messages.filter((m) => m.role === "user");
+    const assistants = messages.filter((m) => m.role === "assistant");
+    const toolMsgs = messages.filter((m) => m.role === "tool");
+    lines.push(`Conversation: ${messages.length} messages (${users.length} user, ` +
+        `${assistants.length} assistant, ${toolMsgs.length} tool). ` +
+        (tools.length ? `Tools: ${tools.join(", ")}.` : "No tools used."));
+    // Recent user requests
+    if (recentUser.length) {
+        lines.push("User requests:");
+        for (const r of recentUser)
+            lines.push(`  • ${r}`);
+    }
+    // Current work
+    if (currentWork)
+        lines.push(`Current work: ${currentWork}`);
+    // Key files
+    if (keyFiles.length)
+        lines.push(`Key files: ${keyFiles.join(", ")}.`);
+    // Pending work
+    if (pending.length) {
+        lines.push("Pending work:");
+        for (const p of pending)
+            lines.push(`  • ${p}`);
+    }
+    // Cap total length
+    return lines.slice(0, MAX_TOPIC_LINES).join("\n");
+}
+// ---- File path extraction --------------------------------------------------
+const INTERESTING_EXT = new Set(["rs", "ts", "tsx", "js", "json", "md"]);
+const FILE_PATH_RE = /(?:^|\s)([^\s"`']+\.(rs|ts|tsx|js|json|md|py|sh|sql|toml|yaml|yml|css|html))\b/g;
+function extractFilePaths(text) {
+    const paths = [];
+    for (const m of text.matchAll(FILE_PATH_RE)) {
+        const filePath = m[1];
+        const ext = m[2];
+        const basename = filePath.split("/").pop() ?? filePath;
+        if (basename === "node_modules" || filePath.includes("node_modules/"))
+            continue;
+        if (INTERESTING_EXT.has(ext))
+            paths.push(filePath);
+    }
+    return paths;
+}
+// ---- Recent user requests (existing logic, kept) ---------------------------
+function collectRecentUserRequests(messages, limit) {
+    const requests = [];
+    for (let i = messages.length - 1; i >= 0 && requests.length < limit; i--) {
+        if (messages[i].role === "user") {
+            let snippet = messages[i].text.split("\n").slice(0, 3).join(" ");
+            snippet = snippet.replace(/^.+\nProcessed\$?\s*/i, "").replace(/\n/g, " ");
+            requests.push(truncate(snippet, 200));
+        }
+    }
+    return requests.reverse();
+}
+// ---- Pending work (existing logic, kept) -----------------------------------
+const PENDING_WORDS = ["todo", "next", "pending", "follow up", "remaining"];
+function inferPendingWork(messages) {
+    const pending = [];
+    const recent = messages.slice(-5);
+    for (const m of recent) {
+        const t = m.text.toLowerCase();
+        if (PENDING_WORDS.some((w) => t.includes(w))) {
+            const snippet = m.text.split("\n").find((l) => PENDING_WORDS.some((w) => l.toLowerCase().includes(w)));
+            if (snippet)
+                pending.push(truncate(snippet.trim(), 180));
+        }
+    }
+    return [...new Set(pending)].slice(0, MAX_PENDING);
+}
+// ---- Current work (existing logic, kept) -----------------------------------
+function inferCurrentWork(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.role !== "assistant")
+            continue;
+        const path = m.text.match(/(?:^|\s)([^\s"`':]+\.(rs|ts|tsx|js|json|md|py|toml|yaml|yml|sql))\b/m);
+        if (path) {
+            const line = m.text.split("\n").slice(0, 2).join(" ");
+            return truncate(line, 200);
+        }
+    }
+    return undefined;
+}
+// ---- Key decisions ---------------------------------------------------------
+const DECISION_PATTERNS = [
+    /(?:I('ll| will| decided to| chose to| recommend| suggest))\s+(.{10,120})/i,
+    /(?:let's|we('ll| should| can| will))\s+(.{10,120})/i,
+    /(?:the (?:plan|approach|decision|strategy) is (?:to )?)\s*(.{10,120})/i,
+    /(?:going (?:with|forward))\s+(.{10,120})/i,
+];
+function extractDecisions(messages) {
+    const decisions = [];
+    // Only look at assistant messages (they make/receive decisions)
+    for (const m of messages) {
+        if (m.role !== "assistant")
+            continue;
+        const text = m.text;
+        if (!text || text.length < 20)
+            continue;
+        for (const pat of DECISION_PATTERNS) {
+            const match = text.match(pat);
+            if (match) {
+                const decision = match[2]?.trim();
+                if (decision && decision.length > 10) {
+                    decisions.push(truncate(decision, 150));
+                }
+            }
+        }
+        if (decisions.length >= MAX_DECISIONS)
+            break;
+    }
+    return [...new Set(decisions)];
+}
+// ---- Files modified --------------------------------------------------------
+function extractFilesModified(tools) {
+    const files = new Set();
+    for (const m of tools) {
+        if (!m.toolName)
+            continue;
+        const name = m.toolName.toLowerCase();
+        if (name === "write" || name === "edit" || name === "notebookedit") {
+            // Extract file path from input payload
+            const input = m.input ?? m.text;
+            const pathMatch = input.match(/["']?(\/[^\s"']+\.\w+)["']?/);
+            if (pathMatch)
+                files.add(pathMatch[1]);
+        }
+        if (name === "bash") {
+            const cmd = m.input ?? m.text;
+            if (cmd.includes("git add") || cmd.includes("git commit") || cmd.includes("git diff")) {
+                for (const p of extractFilePaths(cmd))
+                    files.add(p);
+            }
+        }
+    }
+    return [...files].slice(0, MAX_FILES);
+}
+// ---- Public API ------------------------------------------------------------
+/**
+ * Deterministic extractive summary. Same messages → same output, every time.
+ *
+ * Returns structured data + a pre-formatted topicSummary string.
+ * Compression target: 70K tokens → ~2K tokens.
+ */
+export function extractiveSummarize(messages) {
+    if (messages.length === 0) {
+        return { topicSummary: "(empty)", keyDecisions: [], nextSteps: [], filesModified: [], tokenEstimate: 0 };
+    }
+    const toolMsgs = messages.filter((m) => m.role === "tool");
+    const tools = [...new Set(messages.flatMap((m) => (m.toolName ? [m.toolName] : [])))].sort();
+    const recentUser = collectRecentUserRequests(messages, MAX_RECENT_USER);
+    const currentWork = inferCurrentWork(messages);
+    const keyFiles = collectKeyFiles(messages);
+    const pending = inferPendingWork(messages);
+    const keyDecisions = extractDecisions(messages);
+    const filesModified = extractFilesModified(toolMsgs);
+    const topicSummary = buildTopicSummary(messages, tools, recentUser, currentWork, keyFiles, pending);
+    const tokenEstimate = estimateBlockTokens(topicSummary);
+    return { topicSummary, keyDecisions, nextSteps: pending, filesModified, tokenEstimate };
+}
+// ---- Key files (existing logic from compact.ts, moved here) ----------------
+const MAX_KEY_FILES = 5;
+const FRESHNESS_WINDOW = 10;
+function collectKeyFiles(messages) {
+    const recent = messages.slice(-FRESHNESS_WINDOW);
+    const pathFreq = new Map();
+    for (const m of recent) {
+        for (const p of extractFilePaths(m.text)) {
+            pathFreq.set(p, (pathFreq.get(p) ?? 0) + 1);
+        }
+    }
+    return [...pathFreq.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, MAX_KEY_FILES)
+        .map(([p]) => p);
+}