pi-mega-compact 0.4.28 → 0.5.0

package/dist/src/driftDetection.js

@@ -0,0 +1,103 @@
+/**
+ * driftDetection.ts — R4: cross-repo drift detection over the machine-wide
+ * repo_registry (index.sqlite). Reads the registry, classifies each repo
+ * against simple drift signals, and returns a structured report that the
+ * dashboard's Multi-repo tab and the /api/drift endpoint can render.
+ *
+ * Signals (all derived from repo_registry alone — no checkpoint scans):
+ *   - stale: last_seen older than STALE_DAYS (default 30). Repo is up but
+ *     hasn't touched the dashboard in a while — usually parked work.
+ *   - compaction_lag: last_seen within ACTIVE_DAYS (default 7) but
+ *     last_compacted_at is null or > 24h behind. The repo is actively running
+ *     work but compaction isn't keeping pace — usually a config regression.
+ *   - model_churn: model_captured_at within MODEL_CHURN_DAYS (default 7) —
+ *     the active model changed recently. Could be a routine upgrade or a
+ *     silent fallback; both worth flagging.
+ *
+ * Scope: read-only by design. No writes — drift reporting should never mutate
+ * the registry. Severity classification is conservative: warnings, not alarms.
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { getIndexDir } from "./store/sqlite.js";
+const DAY_SEC = 86_400;
+const STALE_DAYS = 30;
+const ACTIVE_DAYS = 7;
+const MODEL_CHURN_DAYS = 7;
+/** Compaction lag threshold: last_seen newer than this AND last_compacted_at
+ *  more than this far behind. 24h is generous — compactions usually fire in
+ *  minutes; >24h usually means something is wedged. */
+const COMPACTION_LAG_SEC = 24 * 3600;
+/** Read all repos from the machine-wide registry, classify drift, return report. */
+export function detectCrossRepoDrift(indexDir = getIndexDir()) {
+    const generatedAt = Math.floor(Date.now() / 1000);
+    const indexPath = join(indexDir, "index.sqlite");
+    const totals = { ok: 0, warn: 0, stale: 0, compactionLag: 0, modelChurn: 0 };
+    if (!existsSync(indexPath))
+        return { generatedAt, totals, repos: [] };
+    let db;
+    try {
+        db = new DatabaseSync(indexPath, { readOnly: true });
+        db.exec("PRAGMA journal_mode = WAL");
+        const rows = db
+            .prepare(`SELECT repo_root, display_name, last_seen, last_compacted_at,
+                model_name, provider, model_captured_at
+           FROM repo_registry`)
+            .all();
+        const repos = [];
+        for (const r of rows) {
+            const lastSeen = r.last_seen ?? 0;
+            const lastCompacted = r.last_compacted_at ?? null;
+            const modelCaptured = r.model_captured_at ?? null;
+            const signals = [];
+            if (lastSeen > 0 && generatedAt - lastSeen > STALE_DAYS * DAY_SEC) {
+                const daysAgo = Math.floor((generatedAt - lastSeen) / DAY_SEC);
+                signals.push({ kind: "stale", severity: "info", detail: `last activity ${daysAgo}d ago` });
+                totals.stale++;
+            }
+            if (lastSeen > 0 &&
+                generatedAt - lastSeen <= ACTIVE_DAYS * DAY_SEC &&
+                (lastCompacted === null || generatedAt - lastCompacted > COMPACTION_LAG_SEC)) {
+                const lagSec = lastCompacted ? generatedAt - lastCompacted : generatedAt - lastSeen;
+                const lagH = Math.floor(lagSec / 3600);
+                signals.push({
+                    kind: "compaction_lag",
+                    severity: "warn",
+                    detail: lastCompacted ? `${lagH}h behind last activity` : "never compacted",
+                });
+                totals.compactionLag++;
+            }
+            if (modelCaptured && generatedAt - modelCaptured <= MODEL_CHURN_DAYS * DAY_SEC) {
+                const label = [r.provider, r.model_name].filter(Boolean).join("/") || "model";
+                signals.push({ kind: "model_churn", severity: "info", detail: `${label} captured recently` });
+                totals.modelChurn++;
+            }
+            const status = signals.some((s) => s.severity === "warn") ? "warn" : "ok";
+            if (status === "warn")
+                totals.warn++;
+            else
+                totals.ok++;
+            repos.push({
+                repoRoot: r.repo_root,
+                displayName: r.display_name ?? r.repo_root,
+                lastSeen,
+                lastCompactedAt: lastCompacted,
+                modelCapturedAt: modelCaptured,
+                signals,
+                status,
+            });
+        }
+        // Sort: warn first, then by lastSeen desc so the active ones are on top.
+        repos.sort((a, b) => {
+            if (a.status !== b.status)
+                return a.status === "warn" ? -1 : 1;
+            return b.lastSeen - a.lastSeen;
+        });
+        return { generatedAt, totals, repos };
+    }
+    finally {
+        db?.close();
+    }
+}

package/dist/src/driftDetection.test.js

@@ -0,0 +1,87 @@
+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 { upsertRepoRegistry } from "./store/sqlite.js";
+import { detectCrossRepoDrift } from "./driftDetection.js";
+const NOW = Math.floor(Date.now() / 1000);
+const D = 86_400;
+test("driftDetection: empty registry returns ok report", () => {
+    const dir = mkdtempSync(join(tmpdir(), "drift-empty-"));
+    try {
+        const report = detectCrossRepoDrift(dir);
+        assert.equal(report.totals.ok, 0);
+        assert.equal(report.totals.warn, 0);
+        assert.equal(report.repos.length, 0);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("driftDetection: flags stale repos older than 30 days", () => {
+    const dir = mkdtempSync(join(tmpdir(), "drift-stale-"));
+    try {
+        upsertRepoRegistry({ repoRoot: "/r/old", displayName: "old", stateDir: "/r/old", checkpointCount: 1, tokensSaved: 0, compressedOriginalBytes: 0, lastSeen: NOW - 45 * D }, dir);
+        const report = detectCrossRepoDrift(dir);
+        assert.equal(report.repos.length, 1);
+        assert.ok(report.repos[0].signals.some((s) => s.kind === "stale"), "stale signal present");
+        assert.equal(report.repos[0].status, "ok", "stale alone is info, not warn");
+        assert.equal(report.totals.stale, 1);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("driftDetection: active repo with no compaction flagged as warn", () => {
+    const dir = mkdtempSync(join(tmpdir(), "drift-lag-"));
+    try {
+        upsertRepoRegistry({ repoRoot: "/r/active", displayName: "active", stateDir: "/r/active", checkpointCount: 1, tokensSaved: 0, compressedOriginalBytes: 0, lastSeen: NOW - 1 * D }, dir);
+        const report = detectCrossRepoDrift(dir);
+        const r = report.repos[0];
+        assert.ok(r.signals.some((s) => s.kind === "compaction_lag"), "lag signal present");
+        assert.equal(r.status, "warn", "compaction lag is warn-level");
+        assert.equal(report.totals.warn, 1);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("driftDetection: active repo with recent compaction is ok", () => {
+    const dir = mkdtempSync(join(tmpdir(), "drift-ok-"));
+    try {
+        upsertRepoRegistry({ repoRoot: "/r/healthy", displayName: "healthy", stateDir: "/r/healthy", checkpointCount: 1, tokensSaved: 0, compressedOriginalBytes: 0, lastSeen: NOW, lastCompactedAt: NOW }, dir);
+        const report = detectCrossRepoDrift(dir);
+        const r = report.repos[0];
+        assert.equal(r.status, "ok");
+        assert.equal(r.signals.length, 0);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("driftDetection: recent model churn flagged as info", () => {
+    const dir = mkdtempSync(join(tmpdir(), "drift-model-"));
+    try {
+        upsertRepoRegistry({
+            repoRoot: "/r/swap",
+            displayName: "swap",
+            stateDir: "/r/swap",
+            checkpointCount: 1,
+            tokensSaved: 0,
+            compressedOriginalBytes: 0,
+            lastSeen: NOW,
+            lastCompactedAt: NOW,
+            provider: "anthropic",
+            providerName: "Anthropic",
+            modelName: "sonnet-4.6",
+            modelCapturedAt: NOW - 1 * D,
+        }, dir);
+        const report = detectCrossRepoDrift(dir);
+        assert.ok(report.repos[0].signals.some((s) => s.kind === "model_churn"), "model churn detected");
+        assert.equal(report.totals.modelChurn, 1);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});

package/dist/src/memory.js

@@ -0,0 +1,147 @@
+import { collectRecentUserRequests } from "./compact.js";
+import { cosineSimilarity, defaultEmbedder } from "./embedder.js";
+import { DedupConfig } from "./config/dedup.js";
+import { listMemories, removeMemory, replaceMemory } from "./store/sqlite.js";
+import { getStateDir } from "./store.js";
+const DECISION_PATTERNS = [
+    /\bwe (?:use|chose|decided|will use|standardized on|go with)\b/i,
+    /\b(?:the|our) (?:threshold|policy|rule|convention|default) is\b/i,
+    /\bactually\b/i, /\braise (?:the )?|lower (?:the )?|switch (?:to )?\b/i,
+];
+// Patterns that signal an explicit memory drop. Grounded only when the user
+// references an existing memory's content (handled in reviewConversation).
+const DROP_PATTERNS = [
+    /\b(?:stop using|don't use|dont use|drop(?:ping)?|forget|remove from memory|no longer)\b/i,
+];
+/** Heuristic, extractive review. No LLM. Downgrades un-grounded claims to none. */
+export function reviewConversation(messages, existing = []) {
+    const ops = [];
+    const requests = collectRecentUserRequests(messages, 20);
+    for (let i = 0; i < requests.length; i++) {
+        const r = requests[i];
+        const isDecision = DECISION_PATTERNS.some((p) => p.test(r));
+        const isDrop = DROP_PATTERNS.some((p) => p.test(r));
+        // A "stop using/drop/forget" signal takes precedence over a decision — the
+        // user asking to forget a memory supersedes any "switch to" phrasing it
+        // happens to contain (which would otherwise route into REPLACE).
+        if (isDrop && existing.some((e) => sharesTopic(e.content, r))) {
+            const target = existing.find((e) => sharesTopic(e.content, r));
+            if (target)
+                ops.push({ op: "remove", content: target.content });
+            continue;
+        }
+        if (isDrop) {
+            // Drop pattern matched but no existing topic-overlapping memory — nothing
+            // to remove. Don't fall through to the decision branch (the request might
+            // also contain 'switch to' phrasing).
+            continue;
+        }
+        if (!isDecision)
+            continue;
+        // Treat earlier in-conversation decisions as "existing" too, so later messages
+        // that contradict them emit a REPLACE instead of an ADD.
+        const inConvoExisting = requests.slice(0, i).map((r) => ({ content: r }));
+        const contradicted = [...inConvoExisting, ...existing].find((e) => sharesTopic(e.content, r) && differs(e.content, r));
+        if (contradicted) {
+            ops.push({ op: "replace", targetContent: contradicted.content, memory: { content: r, category: "decision", sourceTurn: i } });
+        }
+        else if (!existing.some((e) => nearDup(e.content, r))) {
+            ops.push({ op: "add", memory: { content: r, category: "decision", sourceTurn: i } });
+        }
+    }
+    // Guardrail: drop any add/replace op whose memory content isn't grounded in a
+    // real message (hallucination prevention). REMOVE ops are exempt — their
+    // `content` is an EXISTING memory (matched by topic overlap), so it predates
+    // the current conversation and won't appear verbatim in any message.
+    return ops.filter((o) => o.op === "remove"
+        ? true
+        : messages.some((m) => String(m.text ?? "").includes(o.memory.content)));
+}
+function sharesTopic(a, b) {
+    const aw = new Set(a.toLowerCase().split(/\W+/).filter((w) => w.length > 3));
+    const bw = new Set(b.toLowerCase().split(/\W+/).filter((w) => w.length > 3));
+    let shared = 0;
+    for (const w of bw)
+        if (aw.has(w))
+            shared++;
+    return shared >= 1;
+}
+function differs(a, b) { return !nearDup(a, b); }
+function nearDup(a, b) {
+    const aw = new Set(a.toLowerCase().split(/\W+/));
+    const bw = new Set(b.toLowerCase().split(/\W+/));
+    let shared = 0;
+    for (const w of bw)
+        if (aw.has(w))
+            shared++;
+    return shared / Math.max(1, bw.size) >= 0.8;
+}
+/**
+ * mergePhrases — for two near-duplicate texts (cosine >= threshold), build a
+ * merged content string. If the loser's token set is mostly contained in the
+ * survivor's, the survivor already covers the meaning and we keep it as-is.
+ * Otherwise we append the loser's text as a new paragraph so no phrasing is
+ * lost.
+ */
+function mergePhrases(survivor, loser) {
+    if (nearDup(survivor, loser))
+        return survivor;
+    return `${survivor}\n\n${loser}`;
+}
+/**
+ * consolidateMemories — merge near-duplicate rows in the `memories` table
+ * (Sprint 21, Task S21.2). Pure local cosine over `defaultEmbedder`
+ * embeddings (zero-net, deterministic, no LLM). Uses the consolidation
+ * threshold `DedupConfig.CONSOLIDATE_COSINE` (default 0.7) — lower than the
+ * off-line SemDeDup threshold (0.95) because drift between manually-typed
+ * memories about the same topic is expected, and the goal is to clean it up
+ * rather than be paranoid about over-merging. One row survives; redundant
+ * rows are removed. Returns the number of merges performed.
+ *
+ * Algorithm:
+ *   1. Load all memories for the repo (or all repos when repo is null).
+ *   2. Embed their `content` field.
+ *   3. For every pair, if cosine >= threshold AND same category → merge:
+ *      survivor is the newest (largest id). Loser's content is appended as a
+ *      paragraph to the survivor's content if it adds non-redundant phrasing,
+ *      otherwise dropped. Loser's row is removed.
+ *
+ * PREVENT-PI-004: local-only embedding, no network.
+ */
+export async function consolidateMemories(stateDir = getStateDir(), repo = null, threshold = DedupConfig.CONSOLIDATE_COSINE) {
+    const rows = listMemories(repo, 1000, stateDir);
+    if (rows.length < 2)
+        return 0;
+    const emb = defaultEmbedder();
+    const vectors = rows.map((r) => emb.embed(r.content));
+    let merges = 0;
+    // Iterate once per row. Older rows are processed first; the merge keeps the
+    // newer (larger id), so we always merge away the older side.
+    for (let i = 0; i < rows.length; i++) {
+        if (rows[i].id == null)
+            continue; // safety: in case the row was removed mid-loop
+        for (let j = i + 1; j < rows.length; j++) {
+            if (rows[j].id == null)
+                continue;
+            if (rows[i].category !== rows[j].category)
+                continue; // different buckets: not a dup
+            const sim = cosineSimilarity(vectors[i], vectors[j]);
+            if (sim < threshold)
+                continue;
+            // Pick survivor: largest id (most recently inserted / referenced wins).
+            const survivorId = rows[i].id > rows[j].id ? rows[i].id : rows[j].id;
+            const loserId = survivorId === rows[i].id ? rows[j].id : rows[i].id;
+            const survivor = survivorId === rows[i].id ? rows[i] : rows[j];
+            const loser = survivorId === rows[i].id ? rows[j] : rows[i];
+            // Merge content: keep survivor's content; if loser's content adds a
+            // phrase (token overlap < 80% with survivor) append it as a paragraph.
+            const mergedContent = mergePhrases(survivor.content, loser.content);
+            replaceMemory(survivorId, { content: mergedContent }, stateDir);
+            removeMemory(loserId, stateDir);
+            // Mark the loser row in the surviving array so we skip it on later pairs.
+            rows[loserId === rows[i].id ? i : j] = { ...loser, id: undefined };
+            merges++;
+        }
+    }
+    return merges;
+}

package/dist/src/memory.test.js

@@ -0,0 +1,41 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { reviewConversation } from "./memory.js";
+test("reviewConversation: yields an ADD op for a stated decision", () => {
+    const msgs = [
+        { role: "user", text: "we use node:sqlite as the store" },
+        { role: "assistant", text: "got it, node:sqlite is the source of truth" },
+    ];
+    const ops = reviewConversation(msgs);
+    assert.ok(ops.some((o) => o.op === "add" && /sqlite|store/i.test(o.memory.content)), "adds a decision memory");
+});
+test("reviewConversation: REPLACE when a later message contradicts an earlier one", () => {
+    const msgs = [
+        { role: "user", text: "the threshold is 50k" },
+        { role: "assistant", text: "ok 50k threshold" },
+        { role: "user", text: "actually raise the threshold to 100k" },
+    ];
+    const ops = reviewConversation(msgs);
+    assert.ok(ops.some((o) => o.op === "replace"), "replaces the superseded value");
+});
+test("reviewConversation: no ops on pure smalltalk (no durable fact)", () => {
+    const msgs = [{ role: "user", text: "hi" }, { role: "assistant", text: "hey" }];
+    assert.equal(reviewConversation(msgs).length, 0);
+});
+test("reviewConversation: emits REMOVE when a user asks to drop an existing memory", () => {
+    const existing = [{ content: "we use node:sqlite as the store" }];
+    // Plain drop statement — no "switch to …" phrasing so we don't accidentally
+    // match DECISION_PATTERNS and route into the replace branch instead.
+    const msgs = [
+        { role: "user", text: "stop using node:sqlite for the store — drop it from memory" },
+        { role: "assistant", text: "ok dropped" },
+    ];
+    const ops = reviewConversation(msgs, existing);
+    assert.ok(ops.some((o) => o.op === "remove" && /sqlite/i.test(o.content)), "emits a remove op targeting the old memory");
+});
+test("reviewConversation: REMOVE requires topic overlap (no accidental drop)", () => {
+    const existing = [{ content: "the timezone is America/Los_Angeles" }];
+    const msgs = [{ role: "user", text: "drop it" }];
+    const ops = reviewConversation(msgs, existing);
+    assert.equal(ops.filter((o) => o.op === "remove").length, 0, "vague 'drop it' with no topic overlap does not remove anything");
+});

package/dist/src/memoryConsolidate.test.js

@@ -0,0 +1,38 @@
+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 { consolidateMemories } from "./memory.js";
+import { addMemory, listMemories } from "./store/sqlite.js";
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-consolidate-"));
+test("consolidateMemories: merges near-duplicate memories (one kept, one removed)", async () => {
+    const dir = join(baseTmp, "merge");
+    // Two near-identical memories — same topic, minor wording drift.
+    addMemory({ content: "we use node:sqlite as the store", category: "decision" }, null, dir);
+    addMemory({ content: "we use node:sqlite for our store", category: "decision" }, null, dir);
+    const merged = await consolidateMemories(dir);
+    assert.equal(merged, 1, "one merge was performed");
+    const rows = listMemories(null, 50, dir);
+    // Exactly one of the two near-dupes survives.
+    assert.equal(rows.length, 1, "exactly one memory remains after merge");
+    assert.match(rows[0].content, /node:sqlite.*store/i, "survivor mentions node:sqlite + store");
+});
+test("consolidateMemories: leaves unrelated memories alone", async () => {
+    const dir = join(baseTmp, "noop");
+    addMemory({ content: "we use node:sqlite as the store", category: "decision" }, null, dir);
+    addMemory({ content: "the gpt-5 release is on hold pending benchmark results", category: "note" }, null, dir);
+    const merged = await consolidateMemories(dir);
+    assert.equal(merged, 0, "no merges on unrelated memories");
+    const rows = listMemories(null, 50, dir);
+    assert.equal(rows.length, 2, "both memories survive");
+});
+test("consolidateMemories: empty store returns 0 and changes nothing", async () => {
+    const dir = join(baseTmp, "empty");
+    const merged = await consolidateMemories(dir);
+    assert.equal(merged, 0, "no merges on empty store");
+    assert.equal(listMemories(null, 50, dir).length, 0, "store still empty");
+});
+test("cleanup memops", () => {
+    rmSync(baseTmp, { recursive: true, force: true });
+});

package/dist/src/memoryOps.js

@@ -0,0 +1,58 @@
+import { addMemory, listMemories, replaceMemory, removeMemory, } from "./store/sqlite.js";
+/** Find a memory row whose content exactly matches (case-insensitive). */
+function findByContent(memories, content) {
+    const norm = content.trim().toLowerCase();
+    return memories.find((m) => m.content.trim().toLowerCase() === norm);
+}
+/**
+ * Apply add/replace/remove ops to the memories table. Replaces are matched by
+ * existing content; removes by content. Idempotent: an add that already exists
+ * is a no-op, a replace of a missing memory degrades to an add.
+ */
+export async function applyMemoryOps(ops, stateDir) {
+    if (!ops.length)
+        return;
+    const repo = null; // memories are repo-scoped by stateDir, not by the repo arg here
+    const existing = listMemories(repo, 1000, stateDir);
+    for (const op of ops) {
+        if (op.op === "add") {
+            // Skip if an identical memory already exists.
+            if (findByContent(existing, op.memory.content))
+                continue;
+            addMemory({
+                kind: op.memory.category,
+                content: op.memory.content,
+                tags: [],
+                category: op.memory.category,
+                target: op.memory.target,
+                sourceTurn: op.memory.sourceTurn,
+            }, repo, stateDir);
+        }
+        else if (op.op === "replace") {
+            const match = findByContent(existing, op.targetContent);
+            if (match) {
+                replaceMemory(match.id, {
+                    kind: op.memory.category,
+                    content: op.memory.content,
+                    category: op.memory.category,
+                    sourceTurn: op.memory.sourceTurn,
+                }, stateDir);
+            }
+            else {
+                // Target missing (e.g. earlier in-conversation contradiction) → add.
+                addMemory({
+                    kind: op.memory.category,
+                    content: op.memory.content,
+                    tags: [],
+                    category: op.memory.category,
+                    sourceTurn: op.memory.sourceTurn,
+                }, repo, stateDir);
+            }
+        }
+        else {
+            const match = findByContent(existing, op.content);
+            if (match)
+                removeMemory(match.id, stateDir);
+        }
+    }
+}

package/dist/src/memoryOps.test.js

@@ -0,0 +1,41 @@
+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 { applyMemoryOps } from "./memoryOps.js";
+import { addMemory, listMemories } from "./store/sqlite.js";
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-memops-"));
+test("applyMemoryOps: ADD inserts a new memory", async () => {
+    const dir = join(baseTmp, "add");
+    await applyMemoryOps([{ op: "add", memory: { content: "we use node:sqlite as the store", category: "decision", sourceTurn: 0 } }], dir);
+    const rows = listMemories(null, 50, dir);
+    assert.ok(rows.some((m) => /node:sqlite/.test(m.content)), "added memory present");
+    assert.equal(rows[0].category, "decision", "category persisted");
+});
+test("applyMemoryOps: ADD is idempotent (no duplicate)", async () => {
+    const dir = join(baseTmp, "dup");
+    const op = { op: "add", memory: { content: "threshold is 50k", category: "decision", sourceTurn: 0 } };
+    await applyMemoryOps([op], dir);
+    await applyMemoryOps([op], dir);
+    const rows = listMemories(null, 50, dir);
+    assert.equal(rows.filter((m) => /threshold is 50k/.test(m.content)).length, 1, "no duplicate");
+});
+test("applyMemoryOps: REPLACE updates the matching memory", async () => {
+    const dir = join(baseTmp, "replace");
+    addMemory({ content: "the threshold is 50k", category: "decision" }, null, dir);
+    await applyMemoryOps([{ op: "replace", targetContent: "the threshold is 50k", memory: { content: "the threshold is 100k", category: "decision", sourceTurn: 2 } }], dir);
+    const rows = listMemories(null, 50, dir);
+    assert.ok(rows.some((m) => /100k/.test(m.content)), "replaced content present");
+    assert.ok(!rows.some((m) => /50k/.test(m.content)), "old content gone");
+});
+test("applyMemoryOps: REMOVE deletes the matching memory", async () => {
+    const dir = join(baseTmp, "remove");
+    addMemory({ content: "obsolete note", category: "note" }, null, dir);
+    await applyMemoryOps([{ op: "remove", content: "obsolete note" }], dir);
+    const rows = listMemories(null, 50, dir);
+    assert.ok(!rows.some((m) => /obsolete note/.test(m.content)), "removed");
+});
+test("cleanup memops", () => {
+    rmSync(baseTmp, { recursive: true, force: true });
+});

package/dist/src/memoryRecall.js

@@ -0,0 +1,60 @@
+/**
+ * memoryRecall.ts — semantic recall over the durable memories table (S21).
+ * Embeds a query with the same local embedder used by RAPTOR, ranks every
+ * memory in the current repo's SQLite by cosine similarity combined with a
+ * category-weighted + recency-boosted score, and returns the top-k. Side
+ * effect: marks returned memories as referenced (last_referenced) so drift
+ * can be measured. PREVENT-PI-004 — embedder is the same local one used
+ * everywhere else; no remote calls are introduced here.
+ * @module
+ */
+import { defaultEmbedder, cosineSimilarity } from "./embedder.js";
+import { listMemories, referenceMemory } from "./store/sqlite.js";
+/** Default category weights — `decision` wins ties on tied cosine. */
+export const DEFAULT_CATEGORY_WEIGHTS = {
+    decision: 1.10,
+    preference: 1.05,
+    fact: 1.0,
+};
+const DEFAULT_RECENCY_WEIGHT = 0.05;
+/**
+ * Rank memories by a blended score of cosine similarity, category weight, and
+ * recency of last_referenced (with createdAt as a fallback). Returns the
+ * top-k above minSimilarity, sorted by blended score descending. Empty on
+ * no matches.
+ */
+export async function recallMemories(query, stateDir, opts = {}) {
+    const topK = opts.topK ?? 10;
+    const minSimilarity = opts.minSimilarity ?? 0.2;
+    const markReferenced = opts.markReferenced ?? true;
+    const embedder = opts.embedder ?? defaultEmbedder();
+    const repo = opts.repo === undefined ? null : opts.repo;
+    const categoryWeights = { ...DEFAULT_CATEGORY_WEIGHTS, ...(opts.categoryWeights ?? {}) };
+    const recencyWeight = opts.recencyWeight ?? DEFAULT_RECENCY_WEIGHT;
+    const queryVec = embedder.embed(query);
+    const memories = listMemories(repo, 1000, stateDir);
+    if (!memories.length || !query.trim())
+        return [];
+    const nowSec = Math.floor(Date.now() / 1000);
+    const scored = [];
+    for (const mem of memories) {
+        const vec = embedder.embed(mem.content);
+        const sim = cosineSimilarity(queryVec, vec);
+        if (sim < minSimilarity)
+            continue;
+        const categoryW = categoryWeights[mem.category ?? "fact"] ?? 1.0;
+        const lastTouch = mem.lastReferenced ?? mem.createdAt ?? nowSec;
+        // log(1 + daysSince) grows slowly — half-life-style decay.
+        const daysSince = Math.max(0, (nowSec - lastTouch) / 86_400);
+        const recencyBoost = Math.log1p(daysSince) * recencyWeight;
+        const finalScore = sim * categoryW * (1 + recencyBoost);
+        scored.push({ memory: mem, score: finalScore });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    const top = scored.slice(0, topK);
+    if (markReferenced) {
+        for (const hit of top)
+            referenceMemory(hit.memory.id, stateDir);
+    }
+    return top;
+}