pi-mega-compact 0.4.28 → 0.5.1

package/src/memory.test.ts

@@ -0,0 +1,46 @@
+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" },
+  ] as any;
+  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" },
+  ] as any;
+  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" }] as any;
+  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" },
+  ] as any;
+  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" }] as any;
+  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/src/memory.ts

@@ -0,0 +1,164 @@
+/**
+ * memory.ts — auto-review + consolidation + recall-merge for the memories
+ * table (S20/S21). Local, hallucination-guarded. No LLM by default (extractive
+ * from the conversation); optional localhost Ollama mirroring RAPTOR. The review
+ * runs every N turns and emits add/replace/remove ops.
+ * PREVENT-PI-004: local only.
+ */
+import type { EngineMessage } from "./types.js";
+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";
+export type MemoryOp =
+  | { op: "add"; memory: { content: string; category: string; target?: string; sourceTurn: number } }
+  | { op: "replace"; targetContent: string; memory: { content: string; category: string; sourceTurn: number } }
+  | { op: "remove"; content: string };
+
+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: EngineMessage[], existing: { content: string }[] = []): MemoryOp[] {
+  const ops: MemoryOp[] = [];
+  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: string, b: string): boolean {
+  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: string, b: string): boolean { return !nearDup(a, b); }
+function nearDup(a: string, b: string): boolean {
+  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: string, loser: string): string {
+  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: string = getStateDir(),
+  repo: string | null = null,
+  threshold: number = DedupConfig.CONSOLIDATE_COSINE,
+): Promise<number> {
+  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 } as any;
+      merges++;
+    }
+  }
+  return merges;
+}

package/src/memoryConsolidate.test.ts

@@ -0,0 +1,47 @@
+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/src/memoryOps.test.ts

@@ -0,0 +1,53 @@
+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" as const, 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/src/memoryOps.ts

@@ -0,0 +1,75 @@
+/**
+ * memoryOps.ts — apply reviewConversation() MemoryOp results to the durable
+ * memories store (S20.3). Thin layer over the SQLite memories helpers in
+ * src/store/sqlite.ts; no raw SQL here. Local only (PREVENT-PI-004).
+ * @module
+ */
+import type { MemoryOp } from "./memory.js";
+import {
+  addMemory,
+  listMemories,
+  replaceMemory,
+  removeMemory,
+  type MemoryRecord,
+} from "./store/sqlite.js";
+
+/** Find a memory row whose content exactly matches (case-insensitive). */
+function findByContent(memories: MemoryRecord[], content: string): MemoryRecord | undefined {
+  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: MemoryOp[], stateDir: string): Promise<void> {
+  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/src/memoryRecall.test.ts

@@ -0,0 +1,100 @@
+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 { recallMemories } from "./memoryRecall.js";
+import { addMemory, getMemory } from "./store/sqlite.js";
+
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-memrec-"));
+
+function biGramEmbedder() {
+  // Deterministic test embedder — bigger dim + binary encoding so two semantically
+  // related strings have higher cosine than unrelated ones.
+  const dim = 64;
+  return {
+    dim,
+    embed(text: string): number[] {
+      const v = new Array(dim).fill(0);
+      const norm = text.toLowerCase().replace(/[^a-z0-9 ]/g, "").trim();
+      for (let i = 0; i < norm.length - 1; i++) {
+        const idx = ((norm.charCodeAt(i) * 31 + norm.charCodeAt(i + 1)) >>> 0) % dim;
+        v[idx] = 1;
+      }
+      return v;
+    },
+  };
+}
+
+test("recallMemories: ranks relevant memory above unrelated", async () => {
+  const dir = join(baseTmp, "rank");
+  addMemory({ content: "we use sqlite for the durable store", category: "decision" }, null, dir);
+  addMemory({ content: "the threshold is 100 thousand tokens", category: "decision" }, null, dir);
+  addMemory({ content: "katz says hi", category: "note" }, null, dir);
+  const hits = await recallMemories("what store do we use?", dir, {
+    embedder: biGramEmbedder(),
+    topK: 3,
+    minSimilarity: 0.0,
+  });
+  assert.ok(hits.length >= 2, "finds relevant");
+  assert.ok(/sqlite/.test(hits[0].memory.content), "top hit is sqlite one");
+  assert.ok(!/katz/.test(hits[0].memory.content), "unrelated not on top");
+});
+
+test("recallMemories: marks referenced hits (last_referenced updated)", async () => {
+  const dir = join(baseTmp, "ref");
+  addMemory({ content: "policy is local-only", category: "rule" }, null, dir);
+  const hits = await recallMemories("local-only policy", dir, { embedder: biGramEmbedder() });
+  assert.ok(hits.length >= 1);
+  const fresh = getMemory(hits[0].memory.id, dir);
+  assert.ok(fresh && fresh.lastReferenced && fresh.lastReferenced > 0, "lastReferenced set");
+});
+
+test("recallMemories: empty store returns []", async () => {
+  const dir = join(baseTmp, "empty");
+  const hits = await recallMemories("anything", dir, { embedder: biGramEmbedder() });
+  assert.deepEqual(hits, []);
+});
+
+test("recallMemories: decision category beats fact category at equal similarity", async () => {
+  const dir = join(baseTmp, "category");
+  // Two memories that share many bigrams with the query — both will have very
+  // similar cosine. The decision category should win because of categoryWeight.
+  addMemory({ content: "we use redis for cache" }, null, dir);
+  const aId = addMemory({ content: "we use redis as primary cache key", category: "fact" }, null, dir);
+  const dId = addMemory({ content: "we use redis as primary cache layer", category: "decision" }, null, dir);
+  const hits = await recallMemories("redis cache layer", dir, {
+    embedder: biGramEmbedder(),
+    topK: 3,
+    minSimilarity: 0.0,
+  });
+  assert.ok(hits.length >= 2);
+  assert.equal(hits[0].memory.id, dId, "decision-tagged memory outranks fact-tagged");
+  assert.notEqual(hits[0].memory.id, aId, "top is the decision row, not the unknown-category row");
+});
+
+test("recallMemories: fresher reference beats older at equal similarity", async () => {
+  const dir = join(baseTmp, "recency");
+  const aId = addMemory({ content: "we use redis for cache", category: "fact" }, null, dir);
+  const bId = addMemory({ content: "we use redis for cache layer", category: "fact" }, null, dir);
+  // Backdate aId so its last_referenced is older; bId stays fresh.
+  const { openStore, closeStore } = await import("./store/sqlite.js");
+  const db = openStore(dir);
+  const longAgo = Math.floor(Date.now() / 1000) - 30 * 86_400; // 30d
+  db.prepare("UPDATE memories SET last_referenced = ? WHERE id = ?").run(longAgo, aId);
+  // closeStore evicts the cached handle — calling db.close() directly would
+  // leave a stale closed DB in the openStore cache and break subsequent
+  // callers (the "database is not open" failure under parallel runs).
+  closeStore(dir);
+  const hits = await recallMemories("redis cache layer", dir, {
+    embedder: biGramEmbedder(),
+    topK: 3,
+    minSimilarity: 0.0,
+  });
+  assert.ok(hits.length >= 2);
+  assert.equal(hits[0].memory.id, bId, "freshly-referenced memory outranks 30-day-old one");
+});
+
+test("cleanup memrec", () => {
+  rmSync(baseTmp, { recursive: true, force: true });
+});

package/src/memoryRecall.ts

@@ -0,0 +1,83 @@
+/**
+ * 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, type MemoryRecord } from "./store/sqlite.js";
+
+export interface RecallMemoriesOptions {
+  /** Max memories to return. Default 10. */
+  topK?: number;
+  /** Min cosine similarity (0..1) to include. Default 0.2 — filters unrelated. */
+  minSimilarity?: number;
+  /** If true, mark returned memories as referenced. Default true. */
+  markReferenced?: boolean;
+  /** Override the embedder (test-only seam). */
+  embedder?: { embed(text: string): number[] };
+  /** Repo filter; null = current repo's memories. */
+  repo?: string | null;
+  /** Per-category ranking weights. Categories not listed default to 1.0. */
+  categoryWeights?: Record<string, number>;
+  /** Recency boost strength. Default 0.05 (5% bonus per log-day since reference). */
+  recencyWeight?: number;
+}
+
+/** Default category weights — `decision` wins ties on tied cosine. */
+export const DEFAULT_CATEGORY_WEIGHTS: Record<string, number> = {
+  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: string,
+  stateDir: string,
+  opts: RecallMemoriesOptions = {},
+): Promise<Array<{ memory: MemoryRecord; score: number }>> {
+  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: Array<{ memory: MemoryRecord; score: number }> = [];
+  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;
+}

package/src/recall.test.ts

@@ -5,7 +5,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { VectorStore } from "./vectorStore.js";
 import { compactSession } from "./engine.js";
-import { recallAndInline, formatRecallBlock } from "./recall.js";
+import { recallAndInline, recallAndInlineAsync, formatRecallBlock } from "./recall.js";
+import { markInjectedGlobal, wasInjectedGlobal, closeIndexStore } from "./store/sqlite.js";
 import type { EngineMessage } from "./types.js";
 
 const baseTmp = mkdtempSync(join(tmpdir(), "mc-recall-"));
@@ -47,6 +48,26 @@ test("formatRecallBlock is empty for no hits", () => {
   assert.equal(formatRecallBlock([]), "");
 });
 
+test("formatRecallBlock (S17): labels a cross-repo hit with its source repo", () => {
+  const hit = {
+    checkpoint: { checkpointId: "chkpt_x", summary: "did thing Y", filesModified: ["a.ts"] },
+    score: 0.91,
+    repoId: "/home/u/rad-gateway",
+  } as any;
+  const block = formatRecallBlock([hit]);
+  assert.ok(block.includes("from repo"), "labels cross-repo source");
+  assert.ok(block.includes("rad-gateway"), "includes the repo display name");
+});
+
+test("formatRecallBlock (S17): omits the label for same-repo hits (no repoId)", () => {
+  const hit = {
+    checkpoint: { checkpointId: "c1", summary: "s", filesModified: [] },
+    score: 0.9,
+  } as any;
+  const block = formatRecallBlock([hit]);
+  assert.ok(!block.includes("from repo"), "no source label for same-repo hits");
+});
+
 test("recallAndInline empty when store has nothing for query", () => {
   const s = store();
   const r = recallAndInline({ sessionId: SESS, query: "no such topic exists here", limit: 5, source: "command" }, s as any);
@@ -98,6 +119,61 @@ test("Fix C: inline dedupe drops a hit already resident in the live window", ()
   );
 });
 
+test("S18: global injected-set skips a foreign checkpoint already injected machine-wide", async () => {
+  const indexDir = mkdtempSync(join(tmpdir(), "mc-gi-"));
+  try {
+    const sess = "sess_cross";
+    // A foreign checkpoint already marked injected globally (in this session).
+    markInjectedGlobal("chkpt_foreign", "/repo/other", sess, indexDir);
+    assert.equal(wasInjectedGlobal("chkpt_foreign", sess, indexDir), true);
+    // searchAsync returns the foreign hit; recallAndInlineAsync must skip it
+    // (globally injected) → toInject is empty.
+    const mockStore = {
+      searchAsync: async () => [{
+        checkpoint: { checkpointId: "chkpt_foreign", summary: "foreign work", filesModified: [], dedupStatus: "active" },
+        score: 0.92,
+        repoId: "/repo/other",
+      }],
+      wasInjected: () => false,
+      markInjected: () => {},
+    } as any;
+    const r = await recallAndInlineAsync(
+      { sessionId: sess, query: "foreign", limit: 3, source: "command", crossRepo: true, globalIndexDir: indexDir },
+      mockStore,
+    );
+    assert.equal(r.toInject.length, 0, "globally-injected foreign checkpoint skipped");
+  } finally {
+    closeIndexStore();
+    rmSync(indexDir, { recursive: true, force: true });
+  }
+});
+
+test("S18: a fresh foreign checkpoint is injected AND recorded globally", async () => {
+  const indexDir = mkdtempSync(join(tmpdir(), "mc-gi2-"));
+  try {
+    const sess = "sess_fresh";
+    assert.equal(wasInjectedGlobal("chkpt_new", sess, indexDir), false);
+    const mockStore = {
+      searchAsync: async () => [{
+        checkpoint: { checkpointId: "chkpt_new", summary: "brand new foreign work", filesModified: [], dedupStatus: "active" },
+        score: 0.93,
+        repoId: "/repo/alpha",
+      }],
+      wasInjected: () => false,
+      markInjected: () => {},
+    } as any;
+    const r = await recallAndInlineAsync(
+      { sessionId: sess, query: "foreign", limit: 3, source: "command", crossRepo: true, globalIndexDir: indexDir },
+      mockStore,
+    );
+    assert.equal(r.toInject.length, 1, "fresh foreign checkpoint injected");
+    assert.equal(wasInjectedGlobal("chkpt_new", sess, indexDir), true, "recorded machine-wide");
+  } finally {
+    closeIndexStore();
+    rmSync(indexDir, { recursive: true, force: true });
+  }
+});
+
 test("cleanup", () => {
   rmSync(baseTmp, { recursive: true, force: true });
 });