@remnic/core 1.1.11 → 1.1.13

package/src/memory-worth.test.ts

@@ -0,0 +1,317 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { computeMemoryWorth } from "./memory-worth.js";
+
+/**
+ * Issue #560 PR 2 — unit tests for `computeMemoryWorth`.
+ *
+ * These tests pin the mathematical properties of the scorer:
+ *   - Uninstrumented memories score to the neutral prior (0.5).
+ *   - A single failure drags the score below 0.5 but not to 0.
+ *   - A single success raises the score above 0.5 but not to 1.
+ *   - Large counters converge toward empirical frequency.
+ *   - Corrupt inputs (negatives, NaN, floats) collapse to the prior.
+ *   - Recency decay pulls stale outcomes back toward the prior.
+ */
+
+const NOW = new Date("2026-01-01T00:00:00.000Z");
+
+test("neutral prior: no counters, no timestamps", () => {
+  const result = computeMemoryWorth({ now: NOW });
+  assert.equal(result.score, 0.5);
+  assert.equal(result.p_success, 0.5);
+  assert.equal(result.confidence, 0);
+});
+
+test("neutral prior: explicit zero counters match absent counters", () => {
+  const absent = computeMemoryWorth({ now: NOW });
+  const zero = computeMemoryWorth({ mw_success: 0, mw_fail: 0, now: NOW });
+  assert.equal(zero.score, absent.score);
+  assert.equal(zero.confidence, 0);
+});
+
+test("single failure does not exile the memory (1/3, not 0)", () => {
+  const result = computeMemoryWorth({ mw_success: 0, mw_fail: 1, now: NOW });
+  // Laplace: (0+1) / (0+1+2) = 1/3.
+  assert.ok(Math.abs(result.score - 1 / 3) < 1e-9);
+  assert.equal(result.confidence, 1);
+});
+
+test("single success does not saturate the memory (2/3, not 1)", () => {
+  const result = computeMemoryWorth({ mw_success: 1, mw_fail: 0, now: NOW });
+  // Laplace: (1+1) / (1+0+2) = 2/3.
+  assert.ok(Math.abs(result.score - 2 / 3) < 1e-9);
+  assert.equal(result.confidence, 1);
+});
+
+test("large counters converge toward empirical frequency", () => {
+  // 90 successes out of 100 → raw frequency 0.9.
+  // Laplace: (90+1) / (90+10+2) = 91 / 102 ≈ 0.8922.
+  const result = computeMemoryWorth({
+    mw_success: 90,
+    mw_fail: 10,
+    now: NOW,
+  });
+  assert.ok(Math.abs(result.score - 91 / 102) < 1e-9);
+  assert.ok(result.score > 0.88, `expected score near 0.89, got ${result.score}`);
+  assert.ok(result.score < 0.90);
+  assert.equal(result.confidence, 100);
+});
+
+test("symmetry: equal successes and failures score exactly 0.5", () => {
+  const result = computeMemoryWorth({
+    mw_success: 5,
+    mw_fail: 5,
+    now: NOW,
+  });
+  assert.equal(result.score, 0.5);
+  assert.equal(result.confidence, 10);
+});
+
+test("score is monotonic in successes (more wins ⇒ higher score)", () => {
+  const low = computeMemoryWorth({ mw_success: 1, mw_fail: 5, now: NOW });
+  const mid = computeMemoryWorth({ mw_success: 3, mw_fail: 3, now: NOW });
+  const high = computeMemoryWorth({ mw_success: 5, mw_fail: 1, now: NOW });
+  assert.ok(low.score < mid.score);
+  assert.ok(mid.score < high.score);
+});
+
+test("corrupt inputs (negative, NaN, float) fail safely to prior", () => {
+  // Negative counters → treated as 0 (upstream already rejects, but defend).
+  const negative = computeMemoryWorth({ mw_success: -5, mw_fail: -2, now: NOW });
+  assert.equal(negative.score, 0.5);
+  assert.equal(negative.confidence, 0);
+
+  // NaN / Infinity counters → treated as 0.
+  const nanCounter = computeMemoryWorth({
+    mw_success: Number.NaN,
+    mw_fail: Number.POSITIVE_INFINITY,
+    now: NOW,
+  });
+  assert.equal(nanCounter.score, 0.5);
+  assert.equal(nanCounter.confidence, 0);
+
+  // Non-integer counters are refused outright (not floored). A stored `1.9`
+  // is a corruption signal and we'd rather score to the prior than pretend
+  // it was "1 real success".
+  const floatCounter = computeMemoryWorth({
+    mw_success: 1.9,
+    mw_fail: 0,
+    now: NOW,
+  });
+  assert.equal(floatCounter.confidence, 0);
+  assert.equal(floatCounter.score, 0.5);
+});
+
+test("decay: stale outcomes are pulled back toward the prior", () => {
+  // 5 successes, 0 failures, observed exactly one half-life ago.
+  // With halfLife = 1d, decay factor = 0.5 so effective counts = (2.5, 0)
+  // and score = (2.5+1)/(2.5+0+2) = 3.5/4.5 ≈ 0.7778. Without decay it would
+  // have been (5+1)/(5+0+2) = 6/7 ≈ 0.857.
+  const dayMs = 24 * 60 * 60 * 1000;
+  const lastAccessed = new Date(NOW.getTime() - dayMs).toISOString();
+  const decayed = computeMemoryWorth({
+    mw_success: 5,
+    mw_fail: 0,
+    lastAccessed,
+    now: NOW,
+    halfLifeMs: dayMs,
+  });
+  const fresh = computeMemoryWorth({
+    mw_success: 5,
+    mw_fail: 0,
+    now: NOW,
+  });
+  assert.ok(
+    decayed.score < fresh.score,
+    `decayed score ${decayed.score} should be lower than fresh ${fresh.score}`,
+  );
+  assert.ok(Math.abs(decayed.score - 3.5 / 4.5) < 1e-9);
+  assert.ok(Math.abs(decayed.confidence - 2.5) < 1e-9);
+});
+
+test("decay: extremely old outcomes collapse toward 0.5", () => {
+  // 1000 days old with a 1-day half-life ⇒ factor ≈ 2^-1000, functionally 0.
+  // Effective counts are ~0, so the ratio lands on the uniform prior.
+  const dayMs = 24 * 60 * 60 * 1000;
+  const lastAccessed = new Date(NOW.getTime() - 1000 * dayMs).toISOString();
+  const result = computeMemoryWorth({
+    mw_success: 100,
+    mw_fail: 0,
+    lastAccessed,
+    now: NOW,
+    halfLifeMs: dayMs,
+  });
+  assert.ok(Math.abs(result.score - 0.5) < 1e-6);
+  assert.ok(result.confidence < 1e-6);
+});
+
+test("decay: zero or negative half-life disables decay", () => {
+  const dayMs = 24 * 60 * 60 * 1000;
+  const lastAccessed = new Date(NOW.getTime() - 100 * dayMs).toISOString();
+  const zero = computeMemoryWorth({
+    mw_success: 5,
+    mw_fail: 0,
+    lastAccessed,
+    now: NOW,
+    halfLifeMs: 0,
+  });
+  const negative = computeMemoryWorth({
+    mw_success: 5,
+    mw_fail: 0,
+    lastAccessed,
+    now: NOW,
+    halfLifeMs: -1,
+  });
+  const undefinedHalfLife = computeMemoryWorth({
+    mw_success: 5,
+    mw_fail: 0,
+    lastAccessed,
+    now: NOW,
+  });
+  assert.equal(zero.score, undefinedHalfLife.score);
+  assert.equal(negative.score, undefinedHalfLife.score);
+  assert.equal(zero.confidence, 5);
+});
+
+test("decay: future lastAccessed timestamps clamp to age=0", () => {
+  // If a test / tool seeds lastAccessed slightly in the future, we must not
+  // apply negative decay (which would blow up to >1). Age clamps to zero, so
+  // the raw counts are used untouched.
+  const dayMs = 24 * 60 * 60 * 1000;
+  const lastAccessed = new Date(NOW.getTime() + dayMs).toISOString();
+  const fresh = computeMemoryWorth({
+    mw_success: 3,
+    mw_fail: 1,
+    lastAccessed,
+    now: NOW,
+    halfLifeMs: dayMs,
+  });
+  const sameWithoutTimestamp = computeMemoryWorth({
+    mw_success: 3,
+    mw_fail: 1,
+    now: NOW,
+  });
+  assert.equal(fresh.score, sameWithoutTimestamp.score);
+  assert.equal(fresh.confidence, 4);
+});
+
+test("decay: unparseable lastAccessed is ignored, not fatal", () => {
+  const result = computeMemoryWorth({
+    mw_success: 2,
+    mw_fail: 1,
+    lastAccessed: "not-a-date",
+    now: NOW,
+    halfLifeMs: 1000,
+  });
+  // Same as if no timestamp were supplied at all.
+  const baseline = computeMemoryWorth({
+    mw_success: 2,
+    mw_fail: 1,
+    now: NOW,
+  });
+  assert.equal(result.score, baseline.score);
+  assert.equal(result.confidence, 3);
+});
+
+test("partial corruption fails the whole record to the prior", () => {
+  // Codex P2: `mw_success: 10` with `mw_fail: NaN` must NOT read as strong
+  // positive evidence. Either counter being corrupt must collapse both to
+  // the prior.
+  const sGoodFBad = computeMemoryWorth({
+    mw_success: 10,
+    mw_fail: Number.NaN,
+    now: NOW,
+  });
+  assert.equal(sGoodFBad.score, 0.5);
+  assert.equal(sGoodFBad.confidence, 0);
+
+  const sBadFGood = computeMemoryWorth({
+    mw_success: -1,
+    mw_fail: 10,
+    now: NOW,
+  });
+  assert.equal(sBadFGood.score, 0.5);
+  assert.equal(sBadFGood.confidence, 0);
+
+  // Sanity: an absent counter is not corruption, so a record with
+  // `mw_success: 10, mw_fail: undefined` still reads as strong positive
+  // evidence (legacy half-instrumentation is allowed).
+  const sGoodFAbsent = computeMemoryWorth({
+    mw_success: 10,
+    mw_fail: undefined,
+    now: NOW,
+  });
+  assert.ok(sGoodFAbsent.score > 0.8);
+  assert.equal(sGoodFAbsent.confidence, 10);
+});
+
+test("overflow-prone counters fail safely to the neutral prior", () => {
+  // 1e308 + 1e308 + 2 overflows to Infinity in IEEE-754, which would drive
+  // the ratio to 0 instead of the neutral 0.5. The helper must detect the
+  // corruption and collapse to the prior.
+  const huge = computeMemoryWorth({
+    mw_success: 1e308,
+    mw_fail: 1e308,
+    now: NOW,
+  });
+  assert.equal(huge.score, 0.5);
+  assert.equal(huge.confidence, 0);
+  assert.ok(Number.isFinite(huge.score));
+  assert.ok(Number.isFinite(huge.confidence));
+
+  // Merely-very-large but still safe-integer counts should pass through
+  // without collapsing. Laplace of (1000, 1000) is exactly 0.5.
+  const large = computeMemoryWorth({
+    mw_success: 1000,
+    mw_fail: 1000,
+    now: NOW,
+  });
+  assert.ok(Math.abs(large.score - 0.5) < 1e-9);
+  assert.equal(large.confidence, 2000);
+});
+
+test("invalid `now` Date does not poison output with NaN", () => {
+  // If a caller mis-constructs `now` (e.g., `new Date("bad")`), the helper
+  // must still return finite, well-clamped numbers rather than NaN — a NaN
+  // score would sort arbitrarily in downstream recall ranking.
+  const invalidNow = new Date("not-a-date");
+  const result = computeMemoryWorth({
+    mw_success: 2,
+    mw_fail: 1,
+    lastAccessed: "2025-01-01T00:00:00.000Z",
+    now: invalidNow,
+    halfLifeMs: 1000,
+  });
+  assert.ok(Number.isFinite(result.score));
+  assert.ok(Number.isFinite(result.p_success));
+  assert.ok(Number.isFinite(result.confidence));
+  assert.ok(result.score >= 0 && result.score <= 1);
+  // With decay disabled by the invalid now, raw counts (2 successes, 1
+  // failure) yield Laplace (2+1)/(2+1+2) = 3/5 = 0.6.
+  assert.ok(Math.abs(result.score - 0.6) < 1e-9);
+  assert.equal(result.confidence, 3);
+});
+
+test("score is always within [0, 1]", () => {
+  // Extreme cases: huge failure count, tiny decay factor, etc.
+  const cases = [
+    { mw_success: 0, mw_fail: 1_000_000 },
+    { mw_success: 1_000_000, mw_fail: 0 },
+    { mw_success: 1_000_000, mw_fail: 1_000_000 },
+  ];
+  for (const c of cases) {
+    const r = computeMemoryWorth({ ...c, now: NOW });
+    assert.ok(r.score >= 0 && r.score <= 1, `score out of range for ${JSON.stringify(c)}: ${r.score}`);
+    assert.ok(r.p_success >= 0 && r.p_success <= 1);
+  }
+});
+
+test("p_success mirrors score", () => {
+  // These two fields are distinct in name so observability can label them
+  // separately, but by construction they are the same number. Pin that so
+  // a future diverging refactor is caught by tests.
+  const r = computeMemoryWorth({ mw_success: 3, mw_fail: 2, now: NOW });
+  assert.equal(r.score, r.p_success);
+});

package/src/memory-worth.ts

@@ -0,0 +1,215 @@
+/**
+ * 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.
+ */
+export 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".
+ */
+export 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;
+}
+
+/**
+ * Treat fractional or negative counter inputs as zero. Upstream writers in
+ * PR 1 already reject these, but this helper is also called from tests and
+ * benchmark seeders that build inputs by hand, so we defend here too.
+ */
+/**
+ * Upper bound for a plausible counter. `Number.MAX_SAFE_INTEGER` would
+ * be technically correct but still overflows the sum `sEff + fEff + 2`
+ * when both counters are near the max. A more conservative cap also
+ * doubles as a sanity check against clearly-corrupt frontmatter (no
+ * single memory should have 10B recorded outcomes), and leaves plenty
+ * of headroom for the sum.
+ */
+const MAX_COUNTER = 1e12;
+
+/**
+ * Classify a counter into `{ok, value}` for the scorer:
+ *   - `{ok: true, value}` means the input was absent or a valid non-negative
+ *     integer within range. Treated as a normal signal.
+ *   - `{ok: false}` means the caller supplied a value but it was corrupt
+ *     (negative, NaN, Infinity, non-integer, or absurdly large). The scorer
+ *     treats the record as corrupted and collapses BOTH counters to the
+ *     prior — a partial-corruption record (e.g. `mw_success: 10` with
+ *     `mw_fail: NaN`) must not be read as strong evidence.
+ */
+function classifyCounter(value: number | undefined): { ok: true; value: number } | { ok: false } {
+  // Absent counter is a legitimate "no data yet" signal, not corruption.
+  if (value === undefined) return { ok: true, value: 0 };
+  if (typeof value !== "number") return { ok: false };
+  if (!Number.isFinite(value)) return { ok: false };
+  if (value < 0) return { ok: false };
+  // Non-integer counters are refused outright (not floored). Fractional
+  // counters can only arise from hand-edited frontmatter or a mis-seeded
+  // bench fixture — the PR 1 serializer rejects them on write. Treating
+  // `1.9` as `1` would give obviously-corrupt data non-zero confidence and
+  // shift the score away from the neutral prior.
+  if (!Number.isInteger(value)) return { ok: false };
+  // Overflow guard. `mw_success: 1e308` (or anything past `MAX_COUNTER`)
+  // would let `sEff + fEff + 2` overflow to `Infinity` and drive the
+  // computed score to 0 for symmetric counts — exactly the opposite of
+  // the neutral-prior fail-safe contract.
+  if (value > MAX_COUNTER) return { ok: false };
+  return { ok: true, value };
+}
+
+/**
+ * Parse `lastAccessed` into a millisecond timestamp. Any parse failure
+ * collapses to `null`, which disables decay rather than throwing.
+ */
+function parseLastAccessedMs(lastAccessed: string | null | undefined): number | null {
+  if (!lastAccessed) return null;
+  const parsed = Date.parse(lastAccessed);
+  if (!Number.isFinite(parsed)) return null;
+  return parsed;
+}
+
+/**
+ * Compute the decay multiplier for an observation of age `ageMs` given a
+ * `halfLifeMs`. Returns `1` when decay is disabled or age is non-positive
+ * (can happen if a test seeds `lastAccessed` slightly in the future).
+ */
+function decayFactor(ageMs: number, halfLifeMs: number | undefined): number {
+  if (typeof halfLifeMs !== "number") return 1;
+  if (!Number.isFinite(halfLifeMs)) return 1;
+  if (halfLifeMs <= 0) return 1;
+  if (ageMs <= 0) return 1;
+  return Math.pow(2, -ageMs / halfLifeMs);
+}
+
+/**
+ * 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.
+ */
+export function computeMemoryWorth(input: ComputeMemoryWorthInput): MemoryWorthResult {
+  const sClass = classifyCounter(input.mw_success);
+  const fClass = classifyCounter(input.mw_fail);
+  // If EITHER counter is corrupt, fail the whole record to the prior. A
+  // partially-corrupt record (e.g. `mw_success: 10` with `mw_fail: NaN`)
+  // would otherwise read as strong positive evidence — the exact opposite
+  // of the documented "corrupt inputs fail safely" contract.
+  if (!sClass.ok || !fClass.ok) {
+    return { score: 0.5, p_success: 0.5, confidence: 0 };
+  }
+  const rawS = sClass.value;
+  const rawF = fClass.value;
+
+  const lastAccessedMs = parseLastAccessedMs(input.lastAccessed);
+  const nowMs = input.now.getTime();
+  // An invalid `now` Date (`new Date("bad")`) would otherwise propagate
+  // NaN through `ageMs` → `decayFactor` → score and poison any downstream
+  // sort that treats NaN as "less than everything". Skip decay in that
+  // case — the raw counters are still well-defined.
+  const nowUsable = Number.isFinite(nowMs);
+  const ageMs =
+    !nowUsable || lastAccessedMs === null ? 0 : Math.max(0, nowMs - lastAccessedMs);
+  const factor = nowUsable ? decayFactor(ageMs, input.halfLifeMs) : 1;
+
+  const sEff = rawS * factor;
+  const fEff = rawF * factor;
+
+  // Laplace smoothing: Beta(1,1) prior ⇒ (s+1) / (s+f+2).
+  // This is equivalent to adding one imaginary success + one imaginary
+  // failure before computing the ratio, and guarantees a finite non-zero
+  // result even when both counters are 0.
+  const pSuccess = (sEff + 1) / (sEff + fEff + 2);
+
+  // Clamp defensively — floating-point noise can push (s+1)/(s+f+2) a hair
+  // outside [0, 1] when `factor` is very small, and the callers (recall
+  // score multiplication) expect a well-formed probability.
+  const clamped = Math.max(0, Math.min(1, pSuccess));
+
+  return {
+    score: clamped,
+    p_success: clamped,
+    confidence: sEff + fEff,
+  };
+}