@remnic/core 1.1.12 → 1.1.13

package/src/memory-worth-filter.ts

@@ -0,0 +1,204 @@
+/**
+ * Issue #560 PR 4 — Memory Worth recall filter.
+ *
+ * Pure helper that multiplies candidate recall scores by a Memory Worth
+ * factor (from `computeMemoryWorth`, PR 2) so memories with a history of
+ * failed sessions sink in the ranking. Reading the per-memory counters is
+ * the caller's job — this module does no I/O and depends only on PR 2's
+ * pure scorer.
+ *
+ * The filter is feature-flagged (`recallMemoryWorthFilterEnabled` on
+ * PluginConfig, default `false` in this PR) so operators can A/B it safely
+ * before PR 5 flips the default.
+ *
+ * Intentional properties:
+ *   - Pure function. No side effects, no I/O. Tested directly.
+ *   - Candidates with no counters (empty `counters` map entry) score exactly
+ *     the same as they did pre-filter (multiplier = 0.5, but we renormalize
+ *     so the neutral prior stays neutral — see the "neutral prior preserves
+ *     ranking among unseen memories" test below).
+ *   - Stable: a strictly sorted input stays in its original order among
+ *     items that all score to the prior. This matters because an ad-hoc
+ *     sort that returns 0 for ties on some comparators but not others
+ *     produces non-deterministic ordering (CLAUDE.md rule 19).
+ *   - Does not mutate inputs — returns a new array.
+ *
+ * How the multiplier is applied:
+ *   `new_score = old_score * (p_success / PRIOR)`
+ *   where PRIOR = 0.5. This way an uninstrumented memory (p_success = 0.5)
+ *   gets a multiplier of exactly 1.0 (no penalty, no boost), a memory that
+ *   always succeeds gets a multiplier approaching 2.0 (boosted) and a
+ *   memory that always fails gets a multiplier approaching 0.0 (sunk).
+ *   Using the ratio instead of raw `p_success` keeps the filter from
+ *   accidentally halving every un-instrumented memory the moment it ships.
+ *
+ * Out of scope:
+ *   - Reading counters from storage (caller does that once per recall).
+ *   - Orchestrator wiring / config plumbing (separate commit in this PR).
+ *   - Default flip to `true` (PR 5 once benchmark confirms a win).
+ */
+
+import { computeMemoryWorth, type MemoryWorthResult } from "./memory-worth.js";
+
+/**
+ * One memory's outcome history, keyed by memory path so the filter can look
+ * up a candidate's counters in O(1). `lastAccessed` is passed through to
+ * `computeMemoryWorth` where it drives optional recency decay.
+ */
+export interface MemoryWorthCounters {
+  mw_success?: number;
+  mw_fail?: number;
+  lastAccessed?: string | null;
+}
+
+/**
+ * A scored recall candidate. Defined locally (rather than importing
+ * `QmdSearchResult`) so the filter can be reused by any caller that has a
+ * `{ path, score }` shape — e.g. unit tests, bench fixtures, and future
+ * non-QMD retrieval backends.
+ */
+export interface MemoryWorthFilterCandidate {
+  path: string;
+  score: number;
+}
+
+export interface MemoryWorthFilterOptions {
+  /**
+   * Map from memory path → outcome counters. Candidates whose path is not
+   * in this map score at the neutral prior (multiplier = 1.0).
+   */
+  counters: ReadonlyMap<string, MemoryWorthCounters>;
+  /**
+   * Current time reference — passed through to `computeMemoryWorth` for
+   * decay math. Required (not defaulted) so tests and deterministic bench
+   * runs don't depend on the wall clock.
+   */
+  now: Date;
+  /**
+   * Half-life for outcome decay, in milliseconds. Optional; when omitted,
+   * decay is disabled and raw counters are used.
+   */
+  halfLifeMs?: number;
+  /**
+   * Re-sort the candidates by descending filtered score before returning.
+   * When `false`, the original input order is preserved (but the `.score`
+   * fields still reflect the multiplier). Default `true` because most
+   * callers want a ranked result; a few tests / bench fixtures want the
+   * order preserved so they can assert on position.
+   */
+  reorder?: boolean;
+}
+
+/**
+ * Output of `applyMemoryWorthFilter`. `worth` surfaces the computed
+ * `{ score, p_success, confidence }` for each candidate so observability /
+ * xray layers can report why each item moved without re-deriving it.
+ */
+export interface MemoryWorthFilterResultItem {
+  path: string;
+  /** Final score after the Memory Worth multiplier is applied. */
+  score: number;
+  /** The untouched input score — useful for telemetry and xray. */
+  originalScore: number;
+  /** The multiplier that was applied (1.0 for uninstrumented memories). */
+  multiplier: number;
+  /** The Memory Worth result (`score`, `p_success`, `confidence`). */
+  worth: MemoryWorthResult;
+}
+
+/**
+ * Neutral prior from `computeMemoryWorth`. Uninstrumented memories score
+ * exactly 0.5, so dividing by this value makes the multiplier land on 1.0
+ * for candidates with no history.
+ */
+const NEUTRAL_PRIOR = 0.5;
+
+/**
+ * Apply the Memory Worth multiplier to each candidate's score and (by
+ * default) re-sort the list by descending score.
+ *
+ * When `counters` is empty, every candidate gets a multiplier of 1.0 — the
+ * function is safe to call unconditionally when the feature flag is on,
+ * even for namespaces that have zero instrumented memories.
+ */
+export function applyMemoryWorthFilter(
+  candidates: readonly MemoryWorthFilterCandidate[],
+  options: MemoryWorthFilterOptions,
+): MemoryWorthFilterResultItem[] {
+  const reorder = options.reorder !== false;
+  const result: MemoryWorthFilterResultItem[] = [];
+
+  // Walk candidates in input order so the pre-sort ordering can act as a
+  // stable tiebreaker below. Record each candidate's position so we can
+  // break score ties deterministically (CLAUDE.md rule 19).
+  for (let i = 0; i < candidates.length; i += 1) {
+    const candidate = candidates[i]!;
+    const counters = options.counters.get(candidate.path) ?? {};
+    const worth = computeMemoryWorth({
+      mw_success: counters.mw_success,
+      mw_fail: counters.mw_fail,
+      lastAccessed: counters.lastAccessed,
+      now: options.now,
+      halfLifeMs: options.halfLifeMs,
+    });
+    const multiplier = worth.score / NEUTRAL_PRIOR;
+    // Clamp the candidate score at zero before multiplying. A negative
+    // base score (can happen when upstream penalties push a candidate
+    // below zero) would flip the intended direction: a multiplier > 1
+    // would move the score further negative (worse rank), while a
+    // multiplier < 1 would move it toward zero (better rank). That's the
+    // opposite of "failure-prone memories sink". Treat negatives as zero
+    // so the filter's semantics hold regardless of upstream arithmetic.
+    const safeBase = candidate.score < 0 ? 0 : candidate.score;
+    const scored = safeBase * multiplier;
+    result.push({
+      path: candidate.path,
+      score: scored,
+      originalScore: candidate.score,
+      multiplier,
+      worth,
+    });
+  }
+
+  if (!reorder) return result;
+
+  // Attach original position for stable sort. Node's Array.sort is stable
+  // by spec since ES2019, but we encode the tiebreaker explicitly so a
+  // comparator reviewer can see the contract.
+  const indexed = result.map((r, i) => ({ r, i }));
+  indexed.sort((a, b) => {
+    if (b.r.score !== a.r.score) return b.r.score - a.r.score;
+    return a.i - b.i;
+  });
+  return indexed.map((x) => x.r);
+}
+
+/**
+ * Convenience lookup helper for callers that already have an array of
+ * memory files with `path` and frontmatter fields on each. Keeps the map
+ * construction in one place so call sites don't drift.
+ */
+export function buildMemoryWorthCounterMap(
+  memories: readonly {
+    path: string;
+    frontmatter: {
+      mw_success?: number;
+      mw_fail?: number;
+      lastAccessed?: string | null;
+    };
+  }[],
+): Map<string, MemoryWorthCounters> {
+  const map = new Map<string, MemoryWorthCounters>();
+  for (const m of memories) {
+    const fm = m.frontmatter;
+    // Only add entries with at least one counter present — keeps the map
+    // small when the instrumented fraction is still low.
+    if (fm.mw_success === undefined && fm.mw_fail === undefined) continue;
+    map.set(m.path, {
+      mw_success: fm.mw_success,
+      mw_fail: fm.mw_fail,
+      lastAccessed: fm.lastAccessed,
+    });
+  }
+  return map;
+}

package/src/memory-worth-frontmatter.test.ts

@@ -0,0 +1,311 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+
+import { StorageManager } from "./storage.js";
+import { summarizeMemoryWorthLegacyCounters } from "./operator-toolkit.js";
+
+/**
+ * Issue #560 PR 1 — Memory Worth counters: frontmatter schema + storage round-trip.
+ *
+ * These tests pin the on-disk contract for the `mw_success` and `mw_fail`
+ * frontmatter fields. They live in the core package (not the root tests/
+ * directory) so they co-locate with storage.ts, where the parser/serializer
+ * they cover resides.
+ *
+ * Scope per PR 1:
+ *   - Round-trip: explicit counters survive write → read intact.
+ *   - Legacy memories without the fields read cleanly (no crash) and return
+ *     `undefined` from the parser (matching the accessCount pattern).
+ *   - `remnic doctor` legacy-count correctly partitions instrumented from
+ *     uninstrumented memories.
+ *   - Negative values are rejected on write (silent clamping would mask
+ *     miscounts in the feedback pipeline added by PR 3).
+ *
+ * Out of scope (later PRs in issue #560):
+ *   - computeMemoryWorth() scoring helper (PR 2)
+ *   - Outcome-signal pipeline that increments the counters (PR 3)
+ *   - Recall filter gated on the computed score (PR 4)
+ *   - Benchmark + default flip (PR 5)
+ */
+
+/**
+ * Build a fact file on disk with a bare-bones frontmatter plus arbitrary
+ * extra lines. Used to synthesize legacy and instrumented memories without
+ * going through `writeMemory`, which doesn't expose mw_* options (by design —
+ * those are set by the outcome pipeline in PR 3, not at creation time).
+ */
+async function writeFactFile(
+  storage: StorageManager,
+  body: string,
+  extraFrontmatterLines: string[] = [],
+): Promise<string> {
+  const today = new Date().toISOString().slice(0, 10);
+  const id = `fact-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const lines = [
+    "---",
+    `id: ${id}`,
+    "category: fact",
+    `created: ${new Date().toISOString()}`,
+    `updated: ${new Date().toISOString()}`,
+    "source: extraction",
+    "confidence: 0.8",
+    "confidenceTier: high",
+    "tags: []",
+    ...extraFrontmatterLines,
+    "---",
+  ];
+  const factsDir = path.join((storage as unknown as { baseDir: string }).baseDir, "facts", today);
+  await mkdir(factsDir, { recursive: true });
+  await writeFile(path.join(factsDir, `${id}.md`), `${lines.join("\n")}\n\n${body}\n`, "utf-8");
+  return id;
+}
+
+/**
+ * Write a bare-bones correction file. Corrections are NOT eligible for Memory
+ * Worth instrumentation, so the doctor audit must exclude them from both the
+ * legacy and instrumented tallies.
+ */
+async function writeCorrectionFile(storage: StorageManager, body: string): Promise<string> {
+  const id = `correction-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const lines = [
+    "---",
+    `id: ${id}`,
+    "category: correction",
+    `created: ${new Date().toISOString()}`,
+    `updated: ${new Date().toISOString()}`,
+    "source: extraction",
+    "confidence: 0.8",
+    "confidenceTier: high",
+    "tags: []",
+    "---",
+  ];
+  const correctionsDir = path.join(
+    (storage as unknown as { baseDir: string }).baseDir,
+    "corrections",
+  );
+  await mkdir(correctionsDir, { recursive: true });
+  await writeFile(path.join(correctionsDir, `${id}.md`), `${lines.join("\n")}\n\n${body}\n`, "utf-8");
+  return id;
+}
+
+test("round-trip: mw_success / mw_fail survive write → readAllMemories", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-mw-roundtrip-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+
+    const id = await writeFactFile(storage, "Production DB uses pgBouncer.", [
+      "mw_success: 3",
+      "mw_fail: 1",
+    ]);
+
+    const memories = await storage.readAllMemories();
+    const written = memories.find((m) => m.frontmatter.id === id);
+    assert.ok(written, "fact must be discoverable after write");
+    assert.equal(written!.frontmatter.mw_success, 3);
+    assert.equal(written!.frontmatter.mw_fail, 1);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("round-trip: explicit zero counters are preserved (distinguishable from absent)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-mw-zero-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+
+    const id = await writeFactFile(storage, "Observed zero successes.", [
+      "mw_success: 0",
+      "mw_fail: 0",
+    ]);
+
+    const memories = await storage.readAllMemories();
+    const written = memories.find((m) => m.frontmatter.id === id);
+    assert.ok(written);
+    assert.equal(written!.frontmatter.mw_success, 0, "explicit 0 must round-trip as 0, not undefined");
+    assert.equal(written!.frontmatter.mw_fail, 0, "explicit 0 must round-trip as 0, not undefined");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("legacy memory without mw fields reads cleanly — fields are undefined", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-mw-legacy-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+
+    const id = await writeFactFile(storage, "Legacy fact pre-dating Memory Worth counters.");
+
+    const memories = await storage.readAllMemories();
+    const written = memories.find((m) => m.frontmatter.id === id);
+    assert.ok(written, "legacy fact must still be readable");
+    assert.equal(written!.frontmatter.mw_success, undefined);
+    assert.equal(written!.frontmatter.mw_fail, undefined);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("corrupt counter values (negative / non-integer) parse back as undefined, not corrupt numbers", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-mw-corrupt-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+
+    const id = await writeFactFile(storage, "Fact with hand-edited corrupt counters.", [
+      "mw_success: -2",
+      "mw_fail: 1.5",
+    ]);
+
+    const memories = await storage.readAllMemories();
+    const written = memories.find((m) => m.frontmatter.id === id);
+    assert.ok(written);
+    // Corrupt values must NOT round-trip — they fail safely to undefined so
+    // downstream scoring isn't poisoned. See parseMemoryWorthCounterField.
+    assert.equal(written!.frontmatter.mw_success, undefined);
+    assert.equal(written!.frontmatter.mw_fail, undefined);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("doctor legacy-count: mixed corpus partitions correctly", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-mw-doctor-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+
+    // Two legacy facts, one instrumented fact, one correction. The correction
+    // must be excluded from both legacy and instrumented tallies because
+    // Memory Worth is a per-fact signal (see MEMORY_WORTH_ELIGIBLE_CATEGORIES).
+    await writeFactFile(storage, "Legacy fact A.");
+    await writeFactFile(storage, "Legacy fact B.");
+    await writeFactFile(storage, "Instrumented fact.", ["mw_success: 2", "mw_fail: 0"]);
+    await writeCorrectionFile(storage, "Out-of-scope correction — must not count.");
+
+    const check = await summarizeMemoryWorthLegacyCounters(storage);
+    assert.equal(check.key, "memory_worth_legacy");
+    assert.equal(check.status, "ok", "legacy memories must never fail the doctor check");
+    const details = check.details as {
+      legacy: number;
+      instrumented: number;
+      total: number;
+      ineligible: number;
+    };
+    assert.equal(details.legacy, 2);
+    assert.equal(details.instrumented, 1);
+    assert.equal(details.total, 3, "total reflects only eligible (fact) memories");
+    assert.equal(details.ineligible, 1, "correction is counted as ineligible, not legacy");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("doctor legacy-count: non-fact memories never count as legacy", async () => {
+  // Regression guard: a pure-correction corpus must report zero legacy and
+  // zero instrumented, not N legacy. Without the category filter, operators
+  // would see the legacy bucket permanently inflated even when every fact is
+  // fully instrumented.
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-mw-doctor-corrections-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+
+    await writeCorrectionFile(storage, "Correction 1.");
+    await writeCorrectionFile(storage, "Correction 2.");
+
+    const check = await summarizeMemoryWorthLegacyCounters(storage);
+    const details = check.details as {
+      legacy: number;
+      instrumented: number;
+      total: number;
+      ineligible: number;
+    };
+    assert.equal(details.legacy, 0, "corrections must not inflate the legacy bucket");
+    assert.equal(details.instrumented, 0);
+    assert.equal(details.total, 0);
+    assert.equal(details.ineligible, 2);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("doctor legacy-count: empty memory dir reports zero without warning", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-mw-doctor-empty-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+
+    const check = await summarizeMemoryWorthLegacyCounters(storage);
+    assert.equal(check.status, "ok");
+    const details = check.details as {
+      legacy: number;
+      instrumented: number;
+      total: number;
+      ineligible: number;
+    };
+    assert.equal(details.total, 0);
+    assert.equal(details.legacy, 0);
+    assert.equal(details.instrumented, 0);
+    assert.equal(details.ineligible, 0);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Negative-value rejection on serialize.
+//
+// The serializer throws on invalid counter values, but `writeMemory` never
+// supplies mw fields (they're set by the PR 3 pipeline through spread-based
+// updates on an existing frontmatter). Exercise the validator via an update
+// path: write a fact, then attempt to update its frontmatter with a negative
+// counter. The failure must surface rather than silently clamp.
+// ---------------------------------------------------------------------------
+
+test("negative mw_success on update throws rather than silently clamping", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-mw-negative-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const id = await writeFactFile(storage, "Fact to be poisoned with a bad counter.");
+
+    // updateMemoryFrontmatter routes through serializeFrontmatter, so the
+    // validator will reject the write.
+    await assert.rejects(
+      async () =>
+        storage.updateMemoryFrontmatter(id, {
+          mw_success: -1,
+        }),
+      /mw_success/,
+      "writing a negative Memory Worth counter must throw",
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("non-integer mw_fail on update throws rather than silently truncating", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-mw-float-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const id = await writeFactFile(storage, "Fact to be poisoned with a float counter.");
+
+    await assert.rejects(
+      async () =>
+        storage.updateMemoryFrontmatter(id, {
+          mw_fail: 2.5,
+        }),
+      /mw_fail/,
+      "writing a non-integer Memory Worth counter must throw",
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});