hippo-memory 1.13.5 → 1.14.0

package/dist/availability.js

@@ -0,0 +1,94 @@
+// ---------------------------------------------------------------------------
+// J2 — Availability-bias detector (Track J: biases-over-memory-state)
+// ---------------------------------------------------------------------------
+//
+// Flags when a recall's returned top-K is dominated by recent entries while
+// substantially older relevant candidates in the same MATCHED pool were passed
+// over. This is the availability / recency heuristic (Tversky-Kahneman): what
+// is most mentally available (recent) gets over-weighted relative to what is
+// most relevant. Hippo's substrate makes this measurable: every entry carries a
+// creation timestamp, so we can compare the age distribution of what was
+// RETURNED against the age distribution of the pool it was drawn from.
+//
+// Soft warning ONLY (ROADMAP-RESEARCH.md Track J discipline note): this never
+// filters, reorders, or suppresses a result. It surfaces a hint the calling
+// agent may choose to act on, exactly like J1 anchoringHint / J3
+// planningFallacyHint / C5 suppressionSummary.
+//
+// PURE: no I/O, no env reads. The env gate (HIPPO_AVAILABILITY=off) and the
+// audit emission live in the callers (api.recall, cmdRecall, MCP), mirroring
+// detectAnchoring in recall-history.ts.
+export const DEFAULT_RECENCY_WINDOW_MS = 24 * 60 * 60 * 1000;
+export const DEFAULT_RECENT_FRACTION_THRESHOLD = 0.7;
+export const DEFAULT_MIN_RETURNED = 3;
+export const DEFAULT_MIN_POOL = 10;
+export const DEFAULT_MIN_OLDER_PASSED_OVER = 3;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const MS_PER_HOUR = 60 * 60 * 1000;
+function median(nums) {
+    if (nums.length === 0)
+        return 0;
+    const sorted = [...nums].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+/**
+ * Detect availability/recency bias in a recall result.
+ *
+ * Returns an AvailabilityHint when ALL of the following hold:
+ *   1. topK.length >= minReturned AND pool.length >= minPool (enough signal);
+ *   2. recentFraction > recentFractionThreshold (returned slice is recency-dominated);
+ *   3. poolMedianAgeDays > topKMedianAgeDays (the pool genuinely skews older,
+ *      so recency is not just the corpus being young);
+ *   4. olderCandidatesPassedOver >= minOlderPassedOver (older matched memories
+ *      actually existed and were not returned).
+ * Otherwise returns null.
+ *
+ * Entries with an unparseable `created` are dropped defensively so a malformed
+ * row cannot poison the medians with NaN.
+ */
+export function detectAvailabilityBias(opts) {
+    const now = opts.now ?? Date.now();
+    const recencyWindowMs = opts.recencyWindowMs ?? DEFAULT_RECENCY_WINDOW_MS;
+    const recentFractionThreshold = opts.recentFractionThreshold ?? DEFAULT_RECENT_FRACTION_THRESHOLD;
+    const minReturned = opts.minReturned ?? DEFAULT_MIN_RETURNED;
+    const minPool = opts.minPool ?? DEFAULT_MIN_POOL;
+    const minOlderPassedOver = opts.minOlderPassedOver ?? DEFAULT_MIN_OLDER_PASSED_OVER;
+    const topK = opts.topK
+        .map((e) => ({ id: e.id, ts: Date.parse(e.created) }))
+        .filter((e) => Number.isFinite(e.ts));
+    const pool = opts.pool
+        .map((e) => ({ id: e.id, ts: Date.parse(e.created) }))
+        .filter((e) => Number.isFinite(e.ts));
+    if (topK.length < minReturned || pool.length < minPool)
+        return null;
+    const recentCount = topK.filter((e) => now - e.ts <= recencyWindowMs).length;
+    const recentFraction = recentCount / topK.length;
+    if (recentFraction <= recentFractionThreshold)
+        return null;
+    const topKMedianAgeDays = median(topK.map((e) => (now - e.ts) / MS_PER_DAY));
+    const poolMedianAgeDays = median(pool.map((e) => (now - e.ts) / MS_PER_DAY));
+    if (poolMedianAgeDays <= topKMedianAgeDays)
+        return null;
+    const topKIds = new Set(topK.map((e) => e.id));
+    const olderCandidatesPassedOver = pool.filter((e) => !topKIds.has(e.id) && (now - e.ts) / MS_PER_DAY > topKMedianAgeDays).length;
+    if (olderCandidatesPassedOver < minOlderPassedOver)
+        return null;
+    const pct = Math.round(recentFraction * 100);
+    const windowHours = Math.round(recencyWindowMs / MS_PER_HOUR);
+    const summary = `Availability bias risk: ${recentCount} of ${topK.length} returned results are from the ` +
+        `last ${windowHours}h (${pct}%), but ${olderCandidatesPassedOver} older matched memories ` +
+        `were passed over. Returned median age ${topKMedianAgeDays.toFixed(1)}d vs pool median ` +
+        `${poolMedianAgeDays.toFixed(1)}d. The most relevant answer may not be the most recent.`;
+    return {
+        recentCount,
+        returnedCount: topK.length,
+        recentFraction,
+        topKMedianAgeDays,
+        poolMedianAgeDays,
+        olderCandidatesPassedOver,
+        summary,
+        source: 'j2-recency',
+    };
+}
+//# sourceMappingURL=availability.js.map

package/dist/availability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"availability.js","sourceRoot":"","sources":["../src/availability.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,sEAAsE;AACtE,8EAA8E;AAC9E,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,gFAAgF;AAChF,yEAAyE;AACzE,uEAAuE;AACvE,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,iEAAiE;AACjE,+CAA+C;AAC/C,EAAE;AACF,4EAA4E;AAC5E,6EAA6E;AAC7E,wCAAwC;AAgDxC,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAC7D,MAAM,CAAC,MAAM,iCAAiC,GAAG,GAAG,CAAC;AACrD,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AACtC,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AACnC,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC;AAE/C,MAAM,UAAU,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACvC,MAAM,WAAW,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEnC,SAAS,MAAM,CAAC,IAAuB;IACrC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAChC,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC1C,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAgC;IACrE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IACnC,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,yBAAyB,CAAC;IAC1E,MAAM,uBAAuB,GAC3B,IAAI,CAAC,uBAAuB,IAAI,iCAAiC,CAAC;IACpE,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,gBAAgB,CAAC;IACjD,MAAM,kBAAkB,GAAG,IAAI,CAAC,kBAAkB,IAAI,6BAA6B,CAAC;IAEpF,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI;SACnB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;SACrD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI;SACnB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;SACrD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAExC,IAAI,IAAI,CAAC,MAAM,GAAG,WAAW,IAAI,IAAI,CAAC,MAAM,GAAG,OAAO;QAAE,OAAO,IAAI,CAAC;IAEpE,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,IAAI,eAAe,CAAC,CAAC,MAAM,CAAC;IAC7E,MAAM,cAAc,GAAG,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC;IACjD,IAAI,cAAc,IAAI,uBAAuB;QAAE,OAAO,IAAI,CAAC;IAE3D,MAAM,iBAAiB,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAC7E,MAAM,iBAAiB,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAC7E,IAAI,iBAAiB,IAAI,iBAAiB;QAAE,OAAO,IAAI,CAAC;IAExD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/C,MAAM,yBAAyB,GAAG,IAAI,CAAC,MAAM,CAC3C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,UAAU,GAAG,iBAAiB,CAC3E,CAAC,MAAM,CAAC;IACT,IAAI,yBAAyB,GAAG,kBAAkB;QAAE,OAAO,IAAI,CAAC;IAEhE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,GAAG,GAAG,CAAC,CAAC;IAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,GAAG,WAAW,CAAC,CAAC;IAC9D,MAAM,OAAO,GACX,2BAA2B,WAAW,OAAO,IAAI,CAAC,MAAM,iCAAiC;QACzF,QAAQ,WAAW,MAAM,GAAG,WAAW,yBAAyB,0BAA0B;QAC1F,yCAAyC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,mBAAmB;QACxF,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,yDAAyD,CAAC;IAE3F,OAAO;QACL,WAAW;QACX,aAAa,EAAE,IAAI,CAAC,MAAM;QAC1B,cAAc;QACd,iBAAiB;QACjB,iBAAiB;QACjB,yBAAyB;QACzB,OAAO;QACP,MAAM,EAAE,YAAY;KACrB,CAAC;AACJ,CAAC"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAwBH,OAAO,EASL,WAAW,EAGZ,MAAM,aAAa,CAAC;AAiGrB,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAkChC,kFAAkF;AAClF,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AAqpED;;;GAGG;AACH,oHAAoH;AACpH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CA2C/D;AAy6CD,oHAAoH;AACpH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,EACtF,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,MAAkB,GAC1B,IAAI,CA6BN"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAwBH,OAAO,EASL,WAAW,EAGZ,MAAM,aAAa,CAAC;AAiGrB,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAmChC,kFAAkF;AAClF,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AA+rED;;;GAGG;AACH,oHAAoH;AACpH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CA2C/D;AAy6CD,oHAAoH;AACpH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,EACtF,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,MAAkB,GAC1B,IAAI,CA6BN"}