@remnic/core 1.1.0 → 1.1.2

package/dist/local-llm.js

@@ -1,7 +1,7 @@
 import {
   LocalLlmClient
-} from "./chunk-JL2PU6AI.js";
-import "./chunk-LK6SGL53.js";
+} from "./chunk-R2XRID2N.js";
+import "./chunk-OR64ZGRZ.js";
 import "./chunk-MARWOCVP.js";
 import "./chunk-2ODBA7MQ.js";
 export {

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":[]}