hippo-memory 1.13.1 → 1.13.3

package/dist/recall-history.js

@@ -0,0 +1,235 @@
+/**
+ * J1 anchoring detector (recall-recurrence) — pure module.
+ *
+ * Implements two detection rules from ROADMAP-RESEARCH.md L546:
+ *   R1 query_repeat: same queryHash within recentRepeatWindow returned
+ *     same topMemoryId (caller is re-asking the same question).
+ *   R2 memory_dominance: same topMemoryId across >= minDominance distinct
+ *     queryHashes (memory acts as a fixed-point anchor regardless of what
+ *     the agent asks).
+ *
+ * Per the plan v3 architectural decision: each pipeline (api.recall via
+ * HTTP, cmdRecall, MCP hippo_recall) owns its OWN ring buffer Map keyed
+ * by (tenant, session). No cross-pipeline sharing (the typical multi-
+ * process deployment makes IPC ring-sharing impractical; per-pipeline
+ * is correct because each pipeline has its own top-1 ranking anyway).
+ *
+ * Plan: docs/plans/2026-05-26-j1-anchoring-detector.md.
+ * Composes with J3.2: AnchoringHint + PlanningFallacyHint are independent
+ * signals; both can fire on the same recall.
+ */
+const DEFAULT_MIN_DOMINANCE = 3;
+const DEFAULT_RECENT_REPEAT_WINDOW = 5;
+const DEFAULT_COOLDOWN = 3;
+// ---------------------------------------------------------------------------
+// Query text normalization + hashing
+// ---------------------------------------------------------------------------
+/**
+ * Normalize + hash a query text into a 32-bit integer.
+ * Lowercase → strip non-alphanumeric → split → drop empty + short tokens →
+ * sort tokens → join → FNV-1a 32-bit.
+ *
+ * Token sort + dedup means semantically-equivalent queries with reordered
+ * words collide intentionally (the roadmap's "semantically-distinct" v1
+ * uses textual normalization; embedding-based distinctness is J1-v2).
+ *
+ * Deterministic across processes; stable across Node + V8 versions.
+ */
+export function hashQueryText(query) {
+    if (!query)
+        return 0;
+    // Token dedup before join: the R2 contract says "distinct queries"
+    // means semantically distinct, so `foo bar` and `foo foo bar` should
+    // collapse to the same hash. Without dedup, simple phrasing
+    // variations (typos, doubled tokens, intensifiers) would inflate
+    // distinct-query counts and trip R2 on essentially the same question.
+    // Codex round-1 catch.
+    // Unicode-aware tokenization (codex round-3 P2 catch): the prior
+    // ASCII-only [^a-z0-9\s] pattern stripped every non-Latin letter, so
+    // Japanese, Arabic, Cyrillic, accented-Latin etc. queries collapsed
+    // to empty token set -> hash 0 -> false R1 collisions across distinct
+    // non-English queries. \p{L} = any Unicode letter, \p{N} = any Unicode
+    // number, \p{M} = combining marks (preserve composed accented chars).
+    // Requires the /u flag and Node >= 12.
+    const normalized = query
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\p{M}\s]/gu, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length > 0);
+    // Drop tokens shorter than 3 chars to match the normalizer contract
+    // (filler / stop words). Without this, `a login bug` vs `login bug`
+    // hash differently and inflate R2 distinct-query counts, firing
+    // memory_dominance on repeated phrasings of the same question.
+    // Codex round-4 P2 catch. Matches the same >=3 filter in
+    // src/forward-claim-detector.ts for class-resolver tokens.
+    const filtered = normalized.filter((t) => t.length >= 3);
+    // Fallback when the >=3 filter would collapse the entire query to
+    // empty: CJK queries like `测试` / `环境` are 2-char tokens; English
+    // acronyms like `AI` / `UI` are 2 chars. Without this fallback they
+    // all hash to fnv1a32(''), producing false R1 collisions across
+    // distinct short-token queries. Codex round-5 P2 catch.
+    const tokens = filtered.length > 0 ? filtered : normalized;
+    const deduped = Array.from(new Set(tokens)).sort();
+    return fnv1a32(deduped.join(' '));
+}
+function fnv1a32(text) {
+    // FNV-1a 32-bit. Offset basis 2166136261, prime 16777619.
+    let hash = 2166136261;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        // 32-bit multiply via Math.imul — handles overflow correctly.
+        hash = Math.imul(hash, 16777619);
+    }
+    // Coerce to unsigned 32-bit for stable comparison.
+    return hash >>> 0;
+}
+// ---------------------------------------------------------------------------
+// Anchoring detection
+// ---------------------------------------------------------------------------
+/**
+ * Detect anchoring patterns in the recall history against the current
+ * recall's (queryHash, topMemoryId).
+ *
+ * Rule precedence: R2 (memory_dominance) wins on tie. When both R1 and R2
+ * fire on the same recall, return only the R2 hint — R2's signal is the
+ * cognitively stronger one (a memory dominating multiple DIFFERENT queries
+ * is a fixed-point anchor; R1 alone is just a literal re-ask).
+ *
+ * Cooldown: if the immediately-prior recall fired a hint on the SAME
+ * topMemoryId within `cooldown=3` history entries, suppress. Prevents
+ * spam when the agent repeatedly recalls within the dominance window.
+ * Cooldown is per-memory, not per-rule: if R2 fired on M (cooldown
+ * engaged for M), and the next recall has top=N + repeated query →
+ * R1 fires on N (different memory, not in cooldown).
+ *
+ * @returns AnchoringHint when a pattern fires; null otherwise.
+ */
+export function detectAnchoring(history, currentQueryHash, currentTopMemoryId, opts = {}) {
+    if (currentTopMemoryId === null)
+        return null;
+    const minDominance = opts.minDominance ?? DEFAULT_MIN_DOMINANCE;
+    const recentRepeatWindow = opts.recentRepeatWindow ?? DEFAULT_RECENT_REPEAT_WINDOW;
+    const cooldown = opts.cooldown ?? DEFAULT_COOLDOWN;
+    // Cooldown gate: was the most-recent hint (across the last `cooldown`
+    // entries) for THIS memory? If yes, suppress regardless of rule.
+    const cooldownSlice = history.slice(-cooldown);
+    for (const entry of cooldownSlice) {
+        if (entry.anchoredOn === currentTopMemoryId) {
+            return null;
+        }
+    }
+    // R2 check FIRST (wins on tie). Count distinct queryHashes in history
+    // where topMemoryId === currentTopMemoryId (excluding null tops).
+    const matchingQueryHashes = new Set();
+    for (const entry of history) {
+        if (entry.topMemoryId === currentTopMemoryId) {
+            matchingQueryHashes.add(entry.queryHash);
+        }
+    }
+    // Include current query in the count.
+    matchingQueryHashes.add(currentQueryHash);
+    const queryCount = matchingQueryHashes.size;
+    if (queryCount >= minDominance) {
+        return {
+            reason: 'memory_dominance',
+            memoryId: currentTopMemoryId,
+            queryCount,
+            summary: `Memory ${currentTopMemoryId} has been the top result for ${queryCount} distinct queries in this session and may be anchoring your reasoning.`,
+            source: 'j1-recurrence',
+        };
+    }
+    // R1 check: is currentQueryHash present in the last `recentRepeatWindow`
+    // entries AND was that entry's topMemoryId === currentTopMemoryId?
+    const r1Slice = history.slice(-recentRepeatWindow);
+    for (const entry of r1Slice) {
+        if (entry.queryHash === currentQueryHash && entry.topMemoryId === currentTopMemoryId) {
+            return {
+                reason: 'query_repeat',
+                memoryId: currentTopMemoryId,
+                summary: `Same query phrasing as a recent recall returned the same top result (${currentTopMemoryId}); you may be re-asking the same question.`,
+                source: 'j1-recurrence',
+            };
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// RingBuffer + caller-side state helpers
+// ---------------------------------------------------------------------------
+const MAX_HISTORY = 10;
+const DEFAULT_MAX_SESSIONS = 1000;
+/**
+ * Bounded FIFO ring of RecallHistoryEntry. Newest entries pushed via
+ * append; oldest evicted when the ring is full. The class is intentionally
+ * a thin wrapper around an array so snapshotRing returns a readonly view
+ * without copying on the hot path.
+ */
+export class RingBuffer {
+    entries = [];
+    append(entry) {
+        this.entries.push(entry);
+        if (this.entries.length > MAX_HISTORY) {
+            this.entries.shift();
+        }
+    }
+    snapshot() {
+        return this.entries;
+    }
+    size() {
+        return this.entries.length;
+    }
+}
+/**
+ * Build the (tenant, session) key for a per-session ring Map. Uses a NUL
+ * (`\x00`) byte as delimiter because tenant ids and session ids are
+ * validated elsewhere to reject NUL chars — guarantees collision-free
+ * concatenation regardless of what `:` or other delimiters might appear
+ * inside either field (notably API-key-derived subjects can contain `:`).
+ */
+export function buildSessionKey(tenantId, sessionId) {
+    return `${tenantId}\x00${sessionId}`;
+}
+/**
+ * Get-or-create a RingBuffer for a session key. Caps total tracked keys
+ * at `maxSessions` (default 1000) with LRU eviction — when the cap is
+ * hit, deletes the oldest-inserted key before inserting the new one.
+ * Map iteration order preserves insertion order per ECMA-262 spec, so
+ * "oldest" = first key returned by Map.prototype.keys().
+ */
+export function getOrCreateRing(map, key, maxSessions = DEFAULT_MAX_SESSIONS) {
+    const existing = map.get(key);
+    if (existing) {
+        // LRU touch: delete + re-insert to move to back of iteration order.
+        map.delete(key);
+        map.set(key, existing);
+        return existing;
+    }
+    if (map.size >= maxSessions) {
+        const oldest = map.keys().next().value;
+        if (oldest !== undefined)
+            map.delete(oldest);
+    }
+    const ring = new RingBuffer();
+    map.set(key, ring);
+    return ring;
+}
+/**
+ * Append a recall to a ring. The `anchoredOn` argument carries the
+ * memoryId of the AnchoringHint that fired on THIS recall (or undefined
+ * if no hint). detectAnchoring reads it next time for cooldown gating.
+ */
+export function appendRecall(ring, queryHash, topMemoryId, anchoredOn) {
+    const entry = {
+        queryHash,
+        topMemoryId,
+        ts: new Date().toISOString(),
+    };
+    if (anchoredOn !== undefined)
+        entry.anchoredOn = anchoredOn;
+    ring.append(entry);
+}
+/** Snapshot a ring as a readonly RecallHistorySnapshot. */
+export function snapshotRing(ring) {
+    return ring.snapshot();
+}
+//# sourceMappingURL=recall-history.js.map

package/dist/recall-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-history.js","sourceRoot":"","sources":["../src/recall-history.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -1,3 +1,5 @@
+/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
+export declare function __resetSessionRecallHistoryHttp(): void;
 export interface ServerHandle {
     port: number;
     url: string;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AA8HA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA0HD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAMrE;AAqgDD;;;;;;;;;;GAUG;AACH,wBAAsB,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAyIlE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAuBA,kFAAkF;AAClF,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AA6HD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA0HD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAMrE;AAqkDD;;;;;;;;;;GAUG;AACH,wBAAsB,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAyIlE"}

package/dist/server.js

@@ -3,6 +3,19 @@ import { createHash } from 'node:crypto';
 import { detectServer, writePidfile, removePidfileIfOwned } from './server-detect.js';
 import { resolveTenantId } from './tenant.js';
 import { openHippoDb, closeHippoDb } from './db.js';
+import { buildSessionKey, getOrCreateRing, appendRecall, snapshotRing, hashQueryText, } from './recall-history.js';
+import { appendAuditEvent } from './audit.js';
+// v0.33 / J1 — Module-level per-(tenant, session) recall-history ring map
+// for the HTTP pipeline. Separate from CLI/MCP rings per plan v3 (per-
+// pipeline rings; no IPC). HTTP is the only caller that threads its
+// snapshot through opts.recallHistory to api.recall — api.recall's
+// anchoringHint on the returned RecallResult IS the user-visible hint
+// here (no separate compute needed).
+const sessionRecallHistoryHttp = new Map();
+/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
+export function __resetSessionRecallHistoryHttp() {
+    sessionRecallHistoryHttp.clear();
+}
 import { PACKAGE_VERSION } from './version.js';
 import { validateApiKey } from './auth.js';
 import { createRateLimiter } from './rate-limit.js';
@@ -59,6 +72,9 @@ const VALID_AUDIT_OPS = new Set([
     'recall_autodebias_hint', // v0.32 / J3.2 — emitted by computePlanningFallacyHint on success
     'recall_autodebias_hint_no_class_match', // v0.32 / J3.2 — telemetry: forward-claim, no class scored
     'recall_autodebias_hint_tiebreak', // v0.32 / J3.2 — telemetry: forward-claim, >=2 classes tied
+    'recall_anchor_detected_query_repeat', // v0.33 / J1 — emitted by detector on R1 fire
+    'recall_anchor_detected_memory_dominance', // v0.33 / J1 — emitted by detector on R2 fire
+    'recall_anchor_skipped_no_session', // v0.33 / J1 — telemetry: no sessionId, ring skipped
 ]);
 // Cap on GET /v1/audit?limit=. Matches docs/api.md (when written) and is large
 // enough to dump a small deployment's full audit log without paginating, but
@@ -485,6 +501,55 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             ? sessionIdRaw.trim()
             : undefined;
         const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        // v0.33 / J1 — HTTP per-pipeline anchoring detector. HTTP threads its
+        // ring snapshot via opts.recallHistory so api.recall's own
+        // anchoringHint compute path activates. Unlike CLI (which computes
+        // its own hint separately because cmdRecall runs its own physics/
+        // hybrid pipeline outside api.recall), HTTP's /v1/memories response
+        // body IS api.recall's result directly. So the api.recall-computed
+        // hint flows through. HIPPO_ANCHORING=off short-circuits.
+        let httpRecallHistory;
+        let httpRingKey;
+        if (process.env.HIPPO_ANCHORING !== 'off') {
+            if (sessionId) {
+                // Codex round-5 P2 catch: do NOT mutate sessionRecallHistoryHttp
+                // before recall() preflight runs. A request with an invalid
+                // scorer_window / fresh_tail_count would create-or-touch the
+                // session ring (LRU-evicting valid sessions) even though recall
+                // throws 400. Snapshot the EXISTING ring if present; only
+                // create-or-touch after the recall returns successfully.
+                httpRingKey = buildSessionKey(ctx.tenantId, sessionId);
+                const existingRing = sessionRecallHistoryHttp.get(httpRingKey);
+                httpRecallHistory = existingRing ? snapshotRing(existingRing) : [];
+            }
+            else {
+                // Telemetry: caller had no session_id so ring tracking skipped.
+                // Per the normal recall-audit convention (api.ts:854 stores
+                // SHA-256/16 hash of the query, NOT raw text), avoid retaining
+                // prompts in audit_log here too — query content can contain
+                // secrets, PII, or RTBF-restricted material. Codex round-2 P2
+                // catch: hashQueryText is a 32-bit FNV-1a designed for recall
+                // matching, NOT a privacy hash; brute-force trivial for low-
+                // entropy queries. Use the same SHA-256/16 truncation as the
+                // canonical recall audit.
+                const dbForAudit = openHippoDb(opts.hippoRoot);
+                try {
+                    appendAuditEvent(dbForAudit, {
+                        tenantId: ctx.tenantId,
+                        actor: ctx.actor.subject,
+                        op: 'recall_anchor_skipped_no_session',
+                        targetId: undefined,
+                        metadata: {
+                            query_hash: createHash('sha256').update(q).digest('hex').slice(0, 16),
+                            query_length: q.length,
+                        },
+                    });
+                }
+                finally {
+                    closeHippoDb(dbForAudit);
+                }
+            }
+        }
         const result = recall(ctx, {
             query: q,
             limit,
@@ -496,7 +561,20 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             ...(summarizeOverflow !== undefined ? { summarizeOverflow } : {}),
             ...(scorerWindow !== undefined ? { scorerWindow } : {}),
             ...(sessionId !== undefined ? { sessionId } : {}),
+            ...(httpRecallHistory !== undefined ? { recallHistory: httpRecallHistory } : {}),
         });
+        // v0.33 / J1 — append AFTER recall completes (snapshot was taken before
+        // recall() ran). anchoredOn carries the memoryId of any hint that fired
+        // (api.recall computed it from the same snapshot we passed in), feeding
+        // the cooldown logic for the NEXT recall on this session.
+        // Codex round-5 P2 fix: create-or-touch the ring ONLY HERE, after recall
+        // returns successfully. Invalid requests that throw 400 in recall()
+        // never reach this point, so they cannot LRU-evict valid sessions.
+        if (httpRingKey) {
+            const httpRing = getOrCreateRing(sessionRecallHistoryHttp, httpRingKey);
+            const topId = result.results[0]?.id ?? null;
+            appendRecall(httpRing, hashQueryText(q), topId, result.anchoringHint?.memoryId);
+        }
         // Continuity payloads should never be cached. The caller is asking for
         // session-state-aware data; intermediaries must not reuse it across users.
         if (includeContinuity) {