@remnic/core 1.1.0 → 1.1.1

package/dist/memory-worth-bench.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Issue #560 PR 5 — Memory Worth recall filter benchmark.
+ *
+ * Self-contained precision benchmark for `applyMemoryWorthFilter`. Seeds a
+ * synthetic corpus where a small subset of memories have known-bad outcome
+ * history, then compares top-K precision with the filter off vs. on.
+ *
+ * Why a dedicated in-package file (rather than the full `@remnic/bench`
+ * harness): the filter is a pure function over candidate scores and counter
+ * data; it doesn't need QMD, the orchestrator, or the schema-tier fixtures.
+ * Running it as a plain `tsx` script keeps the signal tight — any drift in
+ * the scorer's math shows up as a precision delta here, no integration
+ * wiring required.
+ *
+ * The `runMemoryWorthBench()` export is the programmatic entry point;
+ * `runMemoryWorthBenchCli()` is what `tsx` calls when this file is executed
+ * directly. Both return (or print) a structured result so CI can gate on
+ * it if we later want to.
+ *
+ * Verdict for PR 5: run the bench once, confirm filter-on ≥ filter-off on
+ * precision@K across every seed, and only then flip the default to `true`.
+ */
+interface MemoryWorthBenchResult {
+    cases: number;
+    k: number;
+    /** Mean precision@K with the filter disabled. */
+    precisionAtK_off: number;
+    /** Mean precision@K with the filter enabled. */
+    precisionAtK_on: number;
+    /** `on - off`; positive means filter helps, zero means tied. */
+    delta: number;
+    /** Filter-on wins at least as often as it loses, case-by-case. */
+    filterWinsOrTies: boolean;
+}
+/**
+ * Run the benchmark over N synthetic cases using a fixed PRNG seed. Returns
+ * aggregate precision numbers + a boolean verdict.
+ */
+declare function runMemoryWorthBench(options?: {
+    cases?: number;
+    seed?: number;
+    now?: Date;
+}): MemoryWorthBenchResult;
+/**
+ * CLI entry point — run the bench and print a structured result. Exits
+ * non-zero if the filter ever loses to the no-filter baseline (so CI can
+ * gate on this in the future).
+ */
+declare function runMemoryWorthBenchCli(): void;
+
+export { type MemoryWorthBenchResult, runMemoryWorthBench, runMemoryWorthBenchCli };

package/dist/memory-worth-bench.js

@@ -0,0 +1,131 @@
+import {
+  applyMemoryWorthFilter
+} from "./chunk-3GPTTA4J.js";
+import "./chunk-IISBCCWR.js";
+
+// src/memory-worth-bench.ts
+function mulberry32(seed) {
+  let t = seed >>> 0;
+  return () => {
+    t = t + 1831565813 >>> 0;
+    let r = t;
+    r = Math.imul(r ^ r >>> 15, r | 1);
+    r ^= r + Math.imul(r ^ r >>> 7, r | 61);
+    return ((r ^ r >>> 14) >>> 0) / 4294967296;
+  };
+}
+function buildCase(caseIndex, rng) {
+  const candidates = [];
+  for (let i = 0; i < 2; i += 1) {
+    candidates.push({
+      path: `case-${caseIndex}-trap-${i}.md`,
+      baseScore: 0.95 - i * 0.02,
+      isRelevant: false,
+      counters: { mw_success: 0, mw_fail: 10 }
+    });
+  }
+  for (let i = 0; i < 3; i += 1) {
+    candidates.push({
+      path: `case-${caseIndex}-noise-high-${i}.md`,
+      baseScore: 0.9 - i * 0.02,
+      isRelevant: false
+    });
+  }
+  for (let i = 0; i < 3; i += 1) {
+    candidates.push({
+      path: `case-${caseIndex}-gold-${i}.md`,
+      baseScore: 0.7 - i * 0.05,
+      isRelevant: true,
+      counters: { mw_success: 10, mw_fail: 0 }
+    });
+  }
+  for (let i = 0; i < 12; i += 1) {
+    candidates.push({
+      path: `case-${caseIndex}-noise-low-${i}.md`,
+      baseScore: rng() * 0.5,
+      isRelevant: false
+    });
+  }
+  for (let i = candidates.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(rng() * (i + 1));
+    [candidates[i], candidates[j]] = [candidates[j], candidates[i]];
+  }
+  return { id: `case-${caseIndex}`, candidates, k: 5 };
+}
+function computePrecisionAtK(orderedPaths, relevant, k) {
+  const topK = orderedPaths.slice(0, k);
+  if (topK.length === 0) return 0;
+  let hits = 0;
+  for (const p of topK) if (relevant.has(p)) hits += 1;
+  return hits / Math.min(k, topK.length);
+}
+function runMemoryWorthBench(options) {
+  const requestedCases = options?.cases ?? 50;
+  if (!Number.isFinite(requestedCases) || !Number.isInteger(requestedCases) || requestedCases < 1) {
+    throw new Error(
+      `runMemoryWorthBench: cases must be a positive integer; got ${requestedCases}`
+    );
+  }
+  const numCases = requestedCases;
+  const rng = mulberry32(options?.seed ?? 3735928559);
+  const now = options?.now ?? /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z");
+  let sumOff = 0;
+  let sumOn = 0;
+  let onWinsOrTies = 0;
+  for (let i = 0; i < numCases; i += 1) {
+    const c = buildCase(i, rng);
+    const relevant = new Set(
+      c.candidates.filter((x) => x.isRelevant).map((x) => x.path)
+    );
+    const off = [...c.candidates].sort((a, b) => b.baseScore - a.baseScore).map((x) => x.path);
+    const pOff = computePrecisionAtK(off, relevant, c.k);
+    const counters = /* @__PURE__ */ new Map();
+    for (const cand of c.candidates) {
+      if (cand.counters) counters.set(cand.path, cand.counters);
+    }
+    const filtered = applyMemoryWorthFilter(
+      c.candidates.map((x) => ({ path: x.path, score: x.baseScore })),
+      { counters, now }
+    );
+    const on = filtered.map((x) => x.path);
+    const pOn = computePrecisionAtK(on, relevant, c.k);
+    sumOff += pOff;
+    sumOn += pOn;
+    if (pOn >= pOff) onWinsOrTies += 1;
+  }
+  const avgOff = sumOff / numCases;
+  const avgOn = sumOn / numCases;
+  return {
+    cases: numCases,
+    k: 5,
+    precisionAtK_off: avgOff,
+    precisionAtK_on: avgOn,
+    delta: avgOn - avgOff,
+    filterWinsOrTies: onWinsOrTies === numCases
+  };
+}
+function runMemoryWorthBenchCli() {
+  const result = runMemoryWorthBench();
+  console.log(JSON.stringify(result, null, 2));
+  if (!result.filterWinsOrTies) {
+    console.error("memory-worth bench: filter lost to no-filter baseline on at least one case");
+    process.exit(1);
+  }
+}
+if (process.argv[1]) {
+  try {
+    const { pathToFileURL } = await import("url");
+    if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+      runMemoryWorthBenchCli();
+    }
+  } catch {
+    if (import.meta.url === `file://${process.argv[1]}`) {
+      runMemoryWorthBenchCli();
+    }
+  }
+}
+export {
+  runMemoryWorthBench,
+  runMemoryWorthBenchCli
+};
+//# sourceMappingURL=memory-worth-bench.js.map

package/dist/memory-worth-bench.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/memory-worth-bench.ts"],"sourcesContent":["/**\n * Issue #560 PR 5 — Memory Worth recall filter benchmark.\n *\n * Self-contained precision benchmark for `applyMemoryWorthFilter`. Seeds a\n * synthetic corpus where a small subset of memories have known-bad outcome\n * history, then compares top-K precision with the filter off vs. on.\n *\n * Why a dedicated in-package file (rather than the full `@remnic/bench`\n * harness): the filter is a pure function over candidate scores and counter\n * data; it doesn't need QMD, the orchestrator, or the schema-tier fixtures.\n * Running it as a plain `tsx` script keeps the signal tight — any drift in\n * the scorer's math shows up as a precision delta here, no integration\n * wiring required.\n *\n * The `runMemoryWorthBench()` export is the programmatic entry point;\n * `runMemoryWorthBenchCli()` is what `tsx` calls when this file is executed\n * directly. Both return (or print) a structured result so CI can gate on\n * it if we later want to.\n *\n * Verdict for PR 5: run the bench once, confirm filter-on ≥ filter-off on\n * precision@K across every seed, and only then flip the default to `true`.\n */\n\nimport {\n  applyMemoryWorthFilter,\n  type MemoryWorthCounters,\n} from \"./memory-worth-filter.js\";\n\n/**\n * One synthetic query + candidate pool + relevance labels.\n *\n * Candidates are scored by the pretend retrieval tier (`baseScore`); the\n * ground-truth relevance is `isRelevant`; `counters` seeds each candidate's\n * outcome history. Some \"bad\" candidates have baseline scores just above\n * the \"good\" candidates — the filter should be able to demote them.\n */\ninterface BenchCase {\n  id: string;\n  candidates: {\n    path: string;\n    baseScore: number;\n    isRelevant: boolean;\n    counters?: MemoryWorthCounters;\n  }[];\n  /** Top-K used for precision@K. */\n  k: number;\n}\n\n/**\n * Deterministic pseudo-random number generator (mulberry32) so the bench\n * produces identical results across runs, making precision changes easy to\n * attribute to code rather than seed drift.\n */\nfunction mulberry32(seed: number): () => number {\n  let t = seed >>> 0;\n  return () => {\n    t = (t + 0x6d2b79f5) >>> 0;\n    let r = t;\n    r = Math.imul(r ^ (r >>> 15), r | 1);\n    r ^= r + Math.imul(r ^ (r >>> 7), r | 61);\n    return ((r ^ (r >>> 14)) >>> 0) / 4294967296;\n  };\n}\n\n/**\n * Generate a synthetic test case.\n *\n * Corpus design:\n *   - 20 candidates per case.\n *   - Top 5 by base score include 2 \"traps\" — memories that the retriever\n *     ranks highly but whose outcome history is 10/0 failures. These should\n *     be sunk by the filter.\n *   - 3 lower-ranked memories are genuinely relevant with 10/0 success\n *     history. The filter should promote them into the top 5.\n *   - Remaining 15 are noise at the neutral prior (no counter data).\n *\n * `k = 5`, so the ideal precision@K is 3/5 = 0.6 (three genuinely relevant\n * items, after filter promotion). Without the filter, precision@5 is 0/5\n * because the top 5 by base score are the 2 traps + 3 irrelevant neutral\n * items.\n */\nfunction buildCase(caseIndex: number, rng: () => number): BenchCase {\n  const candidates: BenchCase[\"candidates\"] = [];\n  // 2 high-ranked traps: high base score, bad outcome history, NOT relevant.\n  for (let i = 0; i < 2; i += 1) {\n    candidates.push({\n      path: `case-${caseIndex}-trap-${i}.md`,\n      baseScore: 0.95 - i * 0.02,\n      isRelevant: false,\n      counters: { mw_success: 0, mw_fail: 10 },\n    });\n  }\n  // 3 high-ranked irrelevant neutral items.\n  for (let i = 0; i < 3; i += 1) {\n    candidates.push({\n      path: `case-${caseIndex}-noise-high-${i}.md`,\n      baseScore: 0.9 - i * 0.02,\n      isRelevant: false,\n    });\n  }\n  // 3 lower-ranked TRUE POSITIVES with strong success history — the filter\n  // must float these into the top 5.\n  for (let i = 0; i < 3; i += 1) {\n    candidates.push({\n      path: `case-${caseIndex}-gold-${i}.md`,\n      baseScore: 0.7 - i * 0.05,\n      isRelevant: true,\n      counters: { mw_success: 10, mw_fail: 0 },\n    });\n  }\n  // 12 irrelevant noise candidates at random lower scores.\n  for (let i = 0; i < 12; i += 1) {\n    candidates.push({\n      path: `case-${caseIndex}-noise-low-${i}.md`,\n      baseScore: rng() * 0.5,\n      isRelevant: false,\n    });\n  }\n  // Shuffle to remove any input-order bias.\n  for (let i = candidates.length - 1; i > 0; i -= 1) {\n    const j = Math.floor(rng() * (i + 1));\n    [candidates[i], candidates[j]] = [candidates[j]!, candidates[i]!];\n  }\n  return { id: `case-${caseIndex}`, candidates, k: 5 };\n}\n\nfunction computePrecisionAtK(\n  orderedPaths: string[],\n  relevant: Set<string>,\n  k: number,\n): number {\n  const topK = orderedPaths.slice(0, k);\n  if (topK.length === 0) return 0;\n  let hits = 0;\n  for (const p of topK) if (relevant.has(p)) hits += 1;\n  return hits / Math.min(k, topK.length);\n}\n\nexport interface MemoryWorthBenchResult {\n  cases: number;\n  k: number;\n  /** Mean precision@K with the filter disabled. */\n  precisionAtK_off: number;\n  /** Mean precision@K with the filter enabled. */\n  precisionAtK_on: number;\n  /** `on - off`; positive means filter helps, zero means tied. */\n  delta: number;\n  /** Filter-on wins at least as often as it loses, case-by-case. */\n  filterWinsOrTies: boolean;\n}\n\n/**\n * Run the benchmark over N synthetic cases using a fixed PRNG seed. Returns\n * aggregate precision numbers + a boolean verdict.\n */\nexport function runMemoryWorthBench(options?: {\n  cases?: number;\n  seed?: number;\n  now?: Date;\n}): MemoryWorthBenchResult {\n  const requestedCases = options?.cases ?? 50;\n  // Reject non-positive-integer case counts. Passing 0 would divide by zero\n  // and produce a NaN precision that the `filterWinsOrTies` boolean would\n  // still mark as `true` — dangerously misleading since this result is used\n  // to justify the default flip. Fractional values would inflate precision\n  // because the loop rounds up (Array.from ceil) but the average divides\n  // by the fractional input.\n  if (\n    !Number.isFinite(requestedCases) ||\n    !Number.isInteger(requestedCases) ||\n    requestedCases < 1\n  ) {\n    throw new Error(\n      `runMemoryWorthBench: cases must be a positive integer; got ${requestedCases}`,\n    );\n  }\n  const numCases = requestedCases;\n  const rng = mulberry32(options?.seed ?? 0xdeadbeef);\n  const now = options?.now ?? new Date(\"2026-01-01T00:00:00.000Z\");\n\n  let sumOff = 0;\n  let sumOn = 0;\n  let onWinsOrTies = 0;\n\n  for (let i = 0; i < numCases; i += 1) {\n    const c = buildCase(i, rng);\n    const relevant = new Set(\n      c.candidates.filter((x) => x.isRelevant).map((x) => x.path),\n    );\n\n    // Filter OFF: sort by baseScore descending.\n    const off = [...c.candidates]\n      .sort((a, b) => b.baseScore - a.baseScore)\n      .map((x) => x.path);\n    const pOff = computePrecisionAtK(off, relevant, c.k);\n\n    // Filter ON: build counter map and apply the filter.\n    const counters = new Map<string, MemoryWorthCounters>();\n    for (const cand of c.candidates) {\n      if (cand.counters) counters.set(cand.path, cand.counters);\n    }\n    const filtered = applyMemoryWorthFilter(\n      c.candidates.map((x) => ({ path: x.path, score: x.baseScore })),\n      { counters, now },\n    );\n    const on = filtered.map((x) => x.path);\n    const pOn = computePrecisionAtK(on, relevant, c.k);\n\n    sumOff += pOff;\n    sumOn += pOn;\n    if (pOn >= pOff) onWinsOrTies += 1;\n  }\n\n  const avgOff = sumOff / numCases;\n  const avgOn = sumOn / numCases;\n  return {\n    cases: numCases,\n    k: 5,\n    precisionAtK_off: avgOff,\n    precisionAtK_on: avgOn,\n    delta: avgOn - avgOff,\n    filterWinsOrTies: onWinsOrTies === numCases,\n  };\n}\n\n/**\n * CLI entry point — run the bench and print a structured result. Exits\n * non-zero if the filter ever loses to the no-filter baseline (so CI can\n * gate on this in the future).\n */\nexport function runMemoryWorthBenchCli(): void {\n  const result = runMemoryWorthBench();\n  // eslint-disable-next-line no-console\n  console.log(JSON.stringify(result, null, 2));\n  if (!result.filterWinsOrTies) {\n    // eslint-disable-next-line no-console\n    console.error(\"memory-worth bench: filter lost to no-filter baseline on at least one case\");\n    process.exit(1);\n  }\n}\n\n// When this file is invoked directly (e.g. `tsx memory-worth-bench.ts`),\n// run the CLI. Use url.pathToFileURL to produce a normalized file:// URL\n// from `process.argv[1]` — that handles Windows drive letters,\n// URL-encoded characters (spaces, etc.), and symlinked entrypoints. A\n// naïve `file://${process.argv[1]}` comparison fails on all three and\n// would silently skip runMemoryWorthBenchCli() on those platforms.\nif (process.argv[1]) {\n  try {\n    // Lazy import so this file can still be loaded in environments that\n    // don't have node:url (browsers, Deno test runners in some modes).\n    const { pathToFileURL } = await import(\"node:url\");\n    if (import.meta.url === pathToFileURL(process.argv[1]).href) {\n      runMemoryWorthBenchCli();\n    }\n  } catch {\n    // If the normalization fails for any reason, fall back to the naive\n    // comparison. Worse case: the bench doesn't auto-run; callers can\n    // always invoke `runMemoryWorthBenchCli()` or `runMemoryWorthBench()`\n    // explicitly.\n    if (import.meta.url === `file://${process.argv[1]}`) {\n      runMemoryWorthBenchCli();\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/memory-worth-filter.d.ts

@@ -0,0 +1,128 @@
+import { MemoryWorthResult } from './memory-worth.js';
+
+/**
+ * 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).
+ */
+
+/**
+ * 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.
+ */
+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.
+ */
+interface MemoryWorthFilterCandidate {
+    path: string;
+    score: number;
+}
+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.
+ */
+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;
+}
+/**
+ * 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.
+ */
+declare function applyMemoryWorthFilter(candidates: readonly MemoryWorthFilterCandidate[], options: MemoryWorthFilterOptions): MemoryWorthFilterResultItem[];
+/**
+ * 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.
+ */
+declare function buildMemoryWorthCounterMap(memories: readonly {
+    path: string;
+    frontmatter: {
+        mw_success?: number;
+        mw_fail?: number;
+        lastAccessed?: string | null;
+    };
+}[]): Map<string, MemoryWorthCounters>;
+
+export { type MemoryWorthCounters, type MemoryWorthFilterCandidate, type MemoryWorthFilterOptions, type MemoryWorthFilterResultItem, applyMemoryWorthFilter, buildMemoryWorthCounterMap };

package/dist/memory-worth-filter.js

@@ -0,0 +1,10 @@
+import {
+  applyMemoryWorthFilter,
+  buildMemoryWorthCounterMap
+} from "./chunk-3GPTTA4J.js";
+import "./chunk-IISBCCWR.js";
+export {
+  applyMemoryWorthFilter,
+  buildMemoryWorthCounterMap
+};
+//# sourceMappingURL=memory-worth-filter.js.map

package/dist/memory-worth-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/memory-worth-outcomes.d.ts

@@ -0,0 +1,118 @@
+import { StorageManager } from './storage.js';
+import { MemoryFrontmatter } from './types.js';
+import './page-versioning.js';
+import './consolidation-operator.js';
+import './memory-projection-store-DeSXPh1j.js';
+import 'better-sqlite3';
+
+/**
+ * Issue #560 PR 3 — Memory Worth outcome signal pipeline.
+ *
+ * PR 1 added `mw_success` / `mw_fail` fields to MemoryFrontmatter. PR 2 added
+ * a pure scoring helper. This module adds the one piece tying the two
+ * together: a way for callers to record a single outcome observation against
+ * a memory, which increments the appropriate counter in frontmatter.
+ *
+ * The public entry point is `recordMemoryOutcome({ memoryPath, outcome, ... })`.
+ * Callers pass the full path to the memory file (not just the ID) because in
+ * the usual outcome source — the observation ledger — the memory path is
+ * already captured in the event payload, and path-based lookup avoids a
+ * full-corpus scan.
+ *
+ * Intentional properties:
+ *   - Works on a per-memory basis (no bulk API in this slice). Bulk update is
+ *     an easy layer on top of this once a second caller needs it.
+ *   - Reuses the existing `updateMemoryFrontmatter(id, patch)` write path so
+ *     unrelated fields (confidence, importance, lifecycle hooks, etc.) are
+ *     preserved. The PR 1 serializer rejects negative / non-integer counters,
+ *     so we rely on that for defensive validation rather than duplicating it.
+ *   - Only instruments categories in `MEMORY_WORTH_OUTCOME_ELIGIBLE_CATEGORIES`
+ *     (currently `fact`, matching `MEMORY_WORTH_ELIGIBLE_CATEGORIES` in
+ *     operator-toolkit.ts for the doctor audit). Non-eligible memories return
+ *     `{ ok: false, reason: "ineligible_category" }` rather than throwing so
+ *     the caller — typically a ledger consumer draining heterogeneous events
+ *     — doesn't need to pre-filter by category.
+ *   - Missing / unknown memory IDs return `{ ok: false, reason: "not_found" }`
+ *     rather than throwing, because outcome events may reference memories
+ *     that were archived/deleted between the session and the ledger drain.
+ *     That isn't an operator-actionable error.
+ *   - On success, returns the new counter values so observability surfaces
+ *     can report the increment without a second read.
+ *
+ * Out of scope (later PRs):
+ *   - Recall filter reading the counters (PR 4).
+ *   - Benchmark + default flip (PR 5).
+ *   - Automatic increments from extraction or summarization. Only the
+ *     explicit `MEM_OUTCOME` ledger tag or an MCP tool call drives writes.
+ */
+
+/**
+ * Exported so downstream tests / operators can query the allowlist without
+ * re-declaring it. Returned as a frozen copy so consumers cannot mutate the
+ * module-internal set.
+ */
+declare function memoryWorthOutcomeEligibleCategories(): ReadonlySet<MemoryFrontmatter["category"]>;
+/**
+ * The direction of an outcome — whether the session that consumed this
+ * memory succeeded or failed. Restricted to a string literal union so
+ * callers in TypeScript land can't pass arbitrary tags.
+ */
+type MemoryOutcomeKind = "success" | "failure";
+/**
+ * Arguments to `recordMemoryOutcome`.
+ *
+ * `memoryPath` is the filesystem path to the memory; we derive the ID from
+ * the basename, matching how the operator-toolkit and recall layers map
+ * paths to IDs.
+ */
+interface RecordMemoryOutcomeInput {
+    /**
+     * Absolute or repo-relative path to the memory file. Typically the value
+     * of `MemoryFile.path` for a memory returned by `readAllMemories`.
+     */
+    memoryPath: string;
+    /** Outcome direction — "success" bumps mw_success; "failure" bumps mw_fail. */
+    outcome: MemoryOutcomeKind;
+    /**
+     * Optional observation timestamp for audit / telemetry. This PR doesn't
+     * persist the timestamp (PR 4/5 will use `lastAccessed`, which already
+     * covers the recency-decay requirement), but accepting it here keeps the
+     * call shape stable so future ledger integrations don't need a breaking
+     * change.
+     */
+    timestamp?: Date | string;
+}
+/**
+ * Outcome of a `recordMemoryOutcome` call.
+ *
+ * `ok: true` means the counter was incremented and flushed. The returned
+ * values reflect the post-increment state, so callers can log
+ * `"fact-xyz: 4/1 → 5/1"` without re-reading.
+ *
+ * `ok: false` carries a short machine-readable `reason` so a ledger drainer
+ * can aggregate metrics ("how many events hit not_found this hour?"). The
+ * human-readable `message` is a friendlier version for logs.
+ */
+type RecordMemoryOutcomeResult = {
+    ok: true;
+    memoryId: string;
+    /** New value of `mw_success` after the increment. */
+    mw_success: number;
+    /** New value of `mw_fail` after the increment. */
+    mw_fail: number;
+} | {
+    ok: false;
+    reason: "not_found" | "ineligible_category" | "invalid_outcome" | "invalid_path";
+    message: string;
+};
+/**
+ * Record a single outcome observation against a memory. Increments
+ * `mw_success` or `mw_fail` on the memory's frontmatter (preserving all
+ * other fields) via the existing `updateMemoryFrontmatter` write path.
+ *
+ * See the top-of-file doc comment for policy details (eligible categories,
+ * error semantics, and what is intentionally out of scope).
+ */
+declare function recordMemoryOutcome(storage: StorageManager, input: RecordMemoryOutcomeInput): Promise<RecordMemoryOutcomeResult>;
+
+export { type MemoryOutcomeKind, type RecordMemoryOutcomeInput, type RecordMemoryOutcomeResult, memoryWorthOutcomeEligibleCategories, recordMemoryOutcome };

package/dist/memory-worth-outcomes.js

@@ -0,0 +1,9 @@
+import {
+  memoryWorthOutcomeEligibleCategories,
+  recordMemoryOutcome
+} from "./chunk-EIR5VLIH.js";
+export {
+  memoryWorthOutcomeEligibleCategories,
+  recordMemoryOutcome
+};
+//# sourceMappingURL=memory-worth-outcomes.js.map

package/dist/memory-worth-outcomes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/memory-worth.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Issue #560 PR 2 — Memory Worth scoring (pure helper).
+ *
+ * Given per-memory outcome counters (`mw_success`, `mw_fail` — added to
+ * frontmatter in PR 1), compute a scalar worth score plus interpretable
+ * metadata. The score is a Laplace-smoothed success probability with an
+ * optional recency decay, and is meant to be used as a multiplier on existing
+ * recall scores (PR 4) to sink memories that consistently lead to failed
+ * sessions and keep uninstrumented memories at a neutral baseline.
+ *
+ * Intentional properties:
+ *   - Pure function. No I/O, no time-of-import side effects. Testable in
+ *     isolation; callers pass `now` so tests don't depend on the wall clock.
+ *   - Laplace-smoothed ratio `(s + 1) / (s + f + 2)` ensures a memory with
+ *     zero observations scores exactly 0.5 — neither boosted nor penalized.
+ *     A single failure on a new memory lands at 1/3, not 0, so one bad
+ *     session doesn't permanently exile a fact.
+ *   - Recency decay is optional. When a memory hasn't been touched in a long
+ *     time, its `p_success` is pulled back toward 0.5 (the prior). Decay is
+ *     exponential with an operator-configured half-life so old verdicts
+ *     aren't treated as equally informative as fresh ones.
+ *   - Corrupt / missing inputs fail safely to the prior. Callers upstream of
+ *     this helper (see `storage.parseMemoryWorthCounterField` in PR 1) already
+ *     strip negatives and non-integers, but the helper re-validates so it
+ *     survives being called directly from tests / ad-hoc tooling.
+ *   - Confidence is the effective number of observations (post-decay). PR 4
+ *     and PR 5 use it to decide whether the Memory Worth multiplier should
+ *     actually be applied vs. left at 1.0 (i.e., "not enough signal yet").
+ *
+ * Out of scope here:
+ *   - Mutating frontmatter (PR 3).
+ *   - Recall integration / feature flag (PR 4).
+ *   - Benchmark & default-flip (PR 5).
+ */
+/**
+ * Input to `computeMemoryWorth`.
+ *
+ * All fields are optional so a legacy (pre-PR-1) memory can be passed through
+ * without upstream guards — it will simply score to the neutral prior.
+ */
+interface ComputeMemoryWorthInput {
+    /** Count of sessions where this memory was recalled and the outcome was success. */
+    mw_success?: number;
+    /** Count of sessions where this memory was recalled and the outcome was failure. */
+    mw_fail?: number;
+    /**
+     * ISO timestamp of the most recent outcome observation for this memory.
+     * When provided together with `halfLifeMs`, observations decay exponentially
+     * toward the uniform prior as they age. Absent / unparseable timestamp →
+     * decay is skipped and raw counters are used directly.
+     */
+    lastAccessed?: string | null;
+    /**
+     * Current wall-clock reference. Required in the signature (not defaulted to
+     * `Date.now()`) so the function stays pure and tests are deterministic.
+     */
+    now: Date;
+    /**
+     * Half-life for outcome decay, in milliseconds. When `undefined` or `<= 0`,
+     * no decay is applied (raw counts are used). When positive, counter weights
+     * are multiplied by `2^(-age / halfLifeMs)`.
+     */
+    halfLifeMs?: number;
+}
+/**
+ * Output of `computeMemoryWorth`.
+ *
+ * `score` is the value recall callers multiply into their base score.
+ * `p_success` is the same number pre-clamped — exposed separately so
+ * observability surfaces can log the probability distinctly from the
+ * multiplier. `confidence` is the effective observation count after decay,
+ * useful for UIs that want to render "strong signal" vs. "tentative".
+ */
+interface MemoryWorthResult {
+    /**
+     * The Laplace-smoothed success probability, post-decay, clamped to
+     * `[0, 1]`. This is the multiplier PR 4 applies to the base recall score.
+     */
+    score: number;
+    /**
+     * Same as `score` conceptually, surfaced separately so telemetry /
+     * xray surfaces can report probability independently of whatever final
+     * multiplier PR 4 chooses to apply.
+     */
+    p_success: number;
+    /**
+     * Effective observation count (`s_eff + f_eff`). With decay enabled this is
+     * fractional; without decay it equals `mw_success + mw_fail` exactly.
+     * Zero indicates no signal — callers should treat the score as a prior.
+     */
+    confidence: number;
+}
+/**
+ * Score a single memory's worth based on outcome history.
+ *
+ * Returns the neutral prior (`0.5`, `confidence=0`) for uninstrumented
+ * memories so the caller can treat "no data" and "data says 50/50"
+ * identically — neither should be penalized.
+ */
+declare function computeMemoryWorth(input: ComputeMemoryWorthInput): MemoryWorthResult;
+
+export { type ComputeMemoryWorthInput, type MemoryWorthResult, computeMemoryWorth };

package/dist/memory-worth.js

@@ -0,0 +1,7 @@
+import {
+  computeMemoryWorth
+} from "./chunk-IISBCCWR.js";
+export {
+  computeMemoryWorth
+};
+//# sourceMappingURL=memory-worth.js.map

package/dist/memory-worth.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/operator-toolkit.d.ts

@@ -1,7 +1,12 @@
+import { StorageManager } from './storage.js';
 import { EvalHarnessStatus, validateEvalBenchmarkPack, EvalBaselineDeltaReport, EvalCiGateReport } from './evals.js';
 import { GraphHealthReport } from './graph.js';
 import { SessionIntegrityReport, SessionRepairPlan, SessionRepairApplyResult } from './session-integrity.js';
 import { PluginConfig } from './types.js';
+import './page-versioning.js';
+import './consolidation-operator.js';
+import './memory-projection-store-DeSXPh1j.js';
+import 'better-sqlite3';
 
 interface QmdRuntimeLike {
     probe(): Promise<boolean>;
@@ -297,8 +302,42 @@ interface OperatorRepairOptions {
 declare function runOperatorSetup(options: OperatorSetupOptions): Promise<OperatorSetupReport>;
 declare function runOperatorConfigReview(options: OperatorConfigReviewOptions): Promise<OperatorConfigReviewReport>;
 declare function runOperatorDoctor(options: OperatorDoctorOptions): Promise<OperatorDoctorReport>;
+/**
+ * Count memories that pre-date the Memory Worth counters introduced in issue
+ * #560 — i.e., neither `mw_success` nor `mw_fail` is set on the frontmatter.
+ *
+ * Only memories whose category is eligible for Memory Worth (see
+ * `MEMORY_WORTH_ELIGIBLE_CATEGORIES`) are considered. Procedures, corrections,
+ * and other kinds that are not instrumented are excluded entirely — they're
+ * neither "legacy" nor "instrumented" for the purposes of this audit. The
+ * total in the returned details reflects only eligible memories.
+ *
+ * Returned as an `ok` check regardless of count, since legacy memories are
+ * fully functional (readers treat missing counters as zero observations). The
+ * numbers are informational for operators following the #560 rollout.
+ *
+ * Exported so unit tests can exercise the classification logic without
+ * booting a full orchestrator.
+ */
+declare function summarizeMemoryWorthLegacyCounters(storage: StorageManager): Promise<OperatorDoctorCheck>;
+/**
+ * Summarize the recent buffer-surprise telemetry distribution for the
+ * Doctor report (issue #563 PR 3).
+ *
+ * Reports mean/median/p90 surprise scores and the triggered-flush rate
+ * over the most recent window of ledger rows. An empty ledger is the
+ * expected state until `bufferSurpriseTriggerEnabled` is turned on — the
+ * check never escalates beyond `ok` / `warn` (ledger unreadable).
+ *
+ * Exported so tests can exercise the formatting without booting a real
+ * orchestrator.
+ */
+declare function summarizeBufferSurpriseDistribution(storage: StorageManager, config: PluginConfig): Promise<OperatorDoctorCheck>;
+declare function summarizeConsolidationProvenance(storage: StorageManager, config: Pick<PluginConfig, "memoryDir"> & {
+    versioningSidecarDir?: string;
+}): Promise<OperatorDoctorCheck>;
 declare function runOperatorInventory(options: OperatorInventoryOptions): Promise<OperatorInventoryReport>;
 declare function runBenchmarkRecall(options: BenchmarkRecallOptions): Promise<BenchmarkRecallReport>;
 declare function runOperatorRepair(options: OperatorRepairOptions): Promise<OperatorRepairReport>;
 
-export { type BenchmarkRecallOptions, type BenchmarkRecallReport, type OperatorConfigLoadResult, type OperatorConfigReviewFinding, type OperatorConfigReviewOptions, type OperatorConfigReviewReport, type OperatorDoctorCheck, type OperatorDoctorOptions, type OperatorDoctorReport, type OperatorInventoryNamespaceSummary, type OperatorInventoryOptions, type OperatorInventoryReport, type OperatorRepairOptions, type OperatorRepairReport, type OperatorSetupOptions, type OperatorSetupReport, type OperatorToolkitOrchestrator, runBenchmarkRecall, runOperatorConfigReview, runOperatorDoctor, runOperatorInventory, runOperatorRepair, runOperatorSetup };
+export { type BenchmarkRecallOptions, type BenchmarkRecallReport, type OperatorConfigLoadResult, type OperatorConfigReviewFinding, type OperatorConfigReviewOptions, type OperatorConfigReviewReport, type OperatorDoctorCheck, type OperatorDoctorOptions, type OperatorDoctorReport, type OperatorInventoryNamespaceSummary, type OperatorInventoryOptions, type OperatorInventoryReport, type OperatorRepairOptions, type OperatorRepairReport, type OperatorSetupOptions, type OperatorSetupReport, type OperatorToolkitOrchestrator, runBenchmarkRecall, runOperatorConfigReview, runOperatorDoctor, runOperatorInventory, runOperatorRepair, runOperatorSetup, summarizeBufferSurpriseDistribution, summarizeConsolidationProvenance, summarizeMemoryWorthLegacyCounters };