hippo-memory 1.70.0 → 1.72.0

package/dist/api/recall-history.js

@@ -1,46 +1,17 @@
-/**
- * Anchoring detector (recall-recurrence), pure module.
- *
- * Implements two detection rules:
- *   query_repeat: same queryHash within recentRepeatWindow returned
- *     same topMemoryId (caller is re-asking the same question).
- *   memory_dominance: same topMemoryId across >= minDominance distinct
- *     queryHashes (memory acts as a fixed-point anchor regardless of what
- *     the agent asks).
- *
- * 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).
- *
- * AnchoringHint + PlanningFallacyHint are independent
- * signals; both can fire on the same recall.
- */
+/** Anchoring detector (recall-recurrence), pure module: `query_repeat` (a queryHash re-asked within the window returns the same topMemoryId) and
+ * `memory_dominance` (the same topMemoryId across >= minDominance distinct queryHashes). Each pipeline keeps its OWN ring Map keyed by (tenant, session),
+ * because its top-1 ranking differs. AnchoringHint and PlanningFallacyHint are independent signals. */
 import { envAnchoringOff, envAvailabilityOff } from '../util/env.js';
 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 ("semantically-distinct" is approximated by
- * textual normalization, not embeddings).
- *
- * Deterministic across processes; stable across Node + V8 versions.
- */
+/** Normalizes a query (lowercase, strip non-alphanumerics, drop short tokens, sort, dedup, join) and hashes it with 32-bit FNV-1a.
+ * Reordered words collide intentionally; deterministic across processes and V8 versions. */
 export function hashQueryText(query) {
     if (!query)
         return 0;
     // Tokens are deduped before join so `foo foo bar` and `foo bar` count as one query for memory_dominance.
-    // Unicode classes (\p{L} letter, \p{N} number, \p{M} combining mark; needs /u) keep
-    // non-Latin queries from collapsing to an empty token set and colliding at hash 0.
+    // Unicode classes (\p{L}, \p{N}, \p{M}; need /u) keep non-Latin queries from collapsing to an empty token set and colliding at hash 0.
     const normalized = query
         .toLowerCase()
         .replace(/[^\p{L}\p{N}\p{M}\s]/gu, ' ')
@@ -66,27 +37,8 @@ function fnv1a32(text) {
     // 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: memory_dominance wins on tie. When both rules fire on the
- * same recall, return only memory_dominance, the stronger signal (a memory
- * dominating multiple DIFFERENT queries is a fixed-point anchor; query_repeat
- * 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 memory_dominance fired on M
- * (cooldown engaged for M), and the next recall has top=N + repeated query,
- * query_repeat fires on N (different memory, not in cooldown).
- *
- * @returns AnchoringHint when a pattern fires; null otherwise.
- */
+/** Detects anchoring against the current (queryHash, topMemoryId); memory_dominance wins when both rules fire, since it spans DIFFERENT queries.
+ * Cooldown is per memory: a hint on the SAME topMemoryId within `cooldown=3` history entries is suppressed. Returns an AnchoringHint or null. */
 export function detectAnchoring(history, currentQueryHash, currentTopMemoryId, opts = {}) {
     if (currentTopMemoryId === null)
         return null;
@@ -141,17 +93,9 @@ function isRecentRepeat(history, recentRepeatWindow, currentQueryHash, currentTo
         .slice(-recentRepeatWindow)
         .some((entry) => entry.queryHash === currentQueryHash && entry.topMemoryId === currentTopMemoryId);
 }
-// ---------------------------------------------------------------------------
-// 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.
- */
+/** Bounded FIFO ring of RecallHistoryEntry (oldest evicted when full); a thin array wrapper so snapshotRing returns a readonly view without copying. */
 export class RingBuffer {
     entries = [];
     append(entry) {
@@ -167,23 +111,13 @@ export class RingBuffer {
         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 `:`).
- */
+/** Builds the (tenant, session) key with a NUL delimiter: tenant and session ids are validated elsewhere to reject NUL,
+ * so concatenation cannot collide even though 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().
- */
+/** Get-or-create a RingBuffer per session key, capped at `maxSessions` (default 1000); at the cap the oldest-inserted key (first from Map.keys()) is
+ * evicted. */
 export function getOrCreateRing(map, key, maxSessions = DEFAULT_MAX_SESSIONS) {
     const existing = map.get(key);
     if (existing) {
@@ -201,11 +135,7 @@ export function getOrCreateRing(map, key, maxSessions = DEFAULT_MAX_SESSIONS) {
     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.
- */
+/** Appends a recall to a ring; `anchoredOn` is the memoryId of the hint that fired on THIS recall (or undefined), read by detectAnchoring for cooldown. */
 export function appendRecall(ring, queryHash, topMemoryId, anchoredOn) {
     const entry = {
         queryHash,
@@ -220,10 +150,7 @@ export function appendRecall(ring, queryHash, topMemoryId, anchoredOn) {
 export function snapshotRing(ring) {
     return ring.snapshot();
 }
-/**
- * Whether a recall bias hint is enabled. Reads the env at call time, so
- * `HIPPO_ANCHORING=off` or `HIPPO_AVAILABILITY=off` disables only that kind.
- */
+/** Whether a recall bias hint is enabled; reads env at call time, so `HIPPO_ANCHORING=off` or `HIPPO_AVAILABILITY=off` disables only that kind. */
 export function biasHintEnabled(kind) {
     return kind === 'anchoring'
         ? !envAnchoringOff()

package/dist/api/recall-pipeline.d.ts

@@ -94,8 +94,7 @@ export interface RankRecallResult {
     /** True when ranking stopped at `haltBefore`. */
     halted: boolean;
 }
-/** Ranks memories for a query as `hippo recall` does, through the `limit` slice. Reads stores, embeddings and
- *  physics state; writes nothing and prints nothing (notes go to `ctx.note`). The caller supplies the cost
- *  function and reranker in `opts`, and persists the returned goal-log rows. */
+/** Ranks memories for a query as `hippo recall` does, through the `limit` slice. Reads stores, embeddings and physics state; writes and prints nothing
+ *  (notes go to `ctx.note`). The caller supplies the cost function and reranker in `opts` and persists the returned goal-log rows. */
 export declare function rankRecall(ctx: RankRecallCtx, opts: RankRecallOpts): Promise<RankRecallResult>;
 //# sourceMappingURL=recall-pipeline.d.ts.map

package/dist/api/recall-pipeline.js

@@ -3,23 +3,24 @@
 import { evalNow } from '../core/ablation.js';
 import { oneCopyPerMemory } from './context-select.js';
 import { compareEntryIdentity, compareScoresDesc } from '../core/compare.js';
-import { isEmbeddingAvailable } from '../store/embeddings/local.js';
-import { activeGoalsWithPolicies, boostByGoals } from '../store/goals.js';
+import { isEmbeddingAvailable } from '../embeddings/local.js';
+import { activeGoalsWithPolicies } from '../store/goals.js';
+import { boostByGoals } from '../search/goal-boost.js';
 import { graphExpandRecall } from '../graph/recall.js';
 import { DEFAULT_GRAPH_STREAM_WEIGHT } from '../graph/stream.js';
 import { Layer } from '../core/memory.js';
 import { multihopSearch } from '../search/multihop.js';
-import { passesCliRecallScopeFilter } from '../store/recall-scope.js';
+import { passesCliRecallScopeFilter } from '../core/recall-scope.js';
 import { currentEntries } from '../search/as-of.js';
 import { STRENGTH_RANK_FLOOR, STRENGTH_RANK_SPAN } from '../search/boosts.js';
 import { hybridSearch } from '../search/hybrid.js';
 import { physicsSearch } from '../search/physics-search.js';
-import { searchBothHybrid } from '../sharing/shared.js';
+import { rankBothStores } from '../sharing/search-both.js';
 import { loadRecallSearchEntries, recallScopeFilter } from '../store/search-rows.js';
+import { isJsonNumber } from '../util/json.js';
 import { textOverlap, tokenize as tokenizeQuery } from '../util/tokenize.js';
-/** Ranks memories for a query as `hippo recall` does, through the `limit` slice. Reads stores, embeddings and
- *  physics state; writes nothing and prints nothing (notes go to `ctx.note`). The caller supplies the cost
- *  function and reranker in `opts`, and persists the returned goal-log rows. */
+/** Ranks memories for a query as `hippo recall` does, through the `limit` slice. Reads stores, embeddings and physics state; writes and prints nothing
+ *  (notes go to `ctx.note`). The caller supplies the cost function and reranker in `opts` and persists the returned goal-log rows. */
 export async function rankRecall(ctx, opts) {
     const pool = loadRecallPool(ctx, opts);
     const state = { results: [], droppedPreRank: pool.dropped, graphAdded: 0, goalRecallLog: [] };
@@ -97,7 +98,7 @@ async function searchPool(ctx, opts, pool) {
         });
     }
     if (search.multihop) {
-        // Unlike searchBothHybrid below, multihop ranks one pooled list, so a shared memory's two copies both compete.
+        // Unlike rankBothStores below, multihop ranks one pooled list, so a shared memory's two copies both compete.
         const allEntries = oneCopyPerMemory(pool.local, pool.global, evalNow()).flat();
         return multihopSearch(query, allEntries, { budget, cost, hippoRoot: ctx.hippoRoot, minResults, includeSuperseded, asOf });
     }
@@ -111,17 +112,20 @@ async function searchPool(ctx, opts, pool) {
     if (search.usePhysics && !globalRoot) {
         // Explain leaves minResults and includeSuperseded out to hold its output steady; asOf must reach physics or later rows leak.
         const temporal = explain ? { asOf } : { minResults, includeSuperseded, asOf };
-        return physicsSearch(query, pool.local, { budget, cost, hippoRoot: ctx.hippoRoot, physicsConfig: search.physicsConfig, scope, explain, vectorCandidates, ...temporal });
+        return physicsSearch(query, pool.local, {
+            budget, cost, hippoRoot: ctx.hippoRoot, physicsConfig: search.physicsConfig, scope, explain, vectorCandidates, ...temporal
+        });
     }
     if (globalRoot) {
-        // searchBothHybrid reloads candidates itself, so the scope rule is passed in rather than inherited from the pool.
-        return searchBothHybrid(query, ctx.hippoRoot, globalRoot, {
+        // The pool already holds searchBothHybrid's additive-scope load for each store, so rank it rather than read both stores again.
+        return rankBothStores(query, { local: ctx.hippoRoot, global: globalRoot }, { local: pool.local, global: pool.global }, vectorCandidates, {
             budget, cost, explain, mmr, mmrLambda, localBump: search.localBump, minResults, scope, tenantId: ctx.tenantId,
             includeSuperseded, asOf,
-            recallScope: opts.explicitScope ? { requested: opts.explicitScope, additive: true } : {},
         });
     }
-    return hybridSearch(query, pool.local, { budget, cost, hippoRoot: ctx.hippoRoot, explain, mmr, mmrLambda, minResults, scope, includeSuperseded, asOf, vectorCandidates });
+    return hybridSearch(query, pool.local, {
+        budget, cost, hippoRoot: ctx.hippoRoot, explain, mmr, mmrLambda, minResults, scope, includeSuperseded, asOf, vectorCandidates
+    });
 }
 /** Adds memories reached by walking the entity graph out from the lexical seeds. */
 function expandGraph(ctx, opts, graph, state) {
@@ -187,7 +191,7 @@ function applyPfcRerankers(opts, state) {
     if (opts.rerankUtility) {
         // utility = score * (0.5 + 0.5 * strength) * (1 - min(0.3, tokens / 10000)); long evidence-rich rows pay for length.
         state.results = byScore(state.results.map((r) => {
-            const strength = typeof r.entry.strength === 'number' ? r.entry.strength : 1.0;
+            const strength = isJsonNumber(r.entry.strength) ? r.entry.strength : 1.0;
             const utilityMult = (STRENGTH_RANK_FLOOR + STRENGTH_RANK_SPAN * strength) * (1 - Math.min(UTILITY_LENGTH_PENALTY_CAP, (r.tokens || 0) / UTILITY_LENGTH_TOKENS));
             const utility = r.score * utilityMult;
             return traced(opts, r, { ...r, score: utility }, { stage: 'utility', multiplier: utilityMult, scoreBefore: r.score, scoreAfter: utility });
@@ -263,7 +267,9 @@ function applyGoalBoosts(ctx, opts, state) {
             if (!r.entry.tags?.includes(goalTag))
                 return r;
             const boosted = { ...r, score: r.score * GOAL_TAG_BOOST };
-            return traced(opts, r, boosted, { stage: 'goal', multiplier: GOAL_TAG_BOOST, scoreBefore: r.score, scoreAfter: r.score * GOAL_TAG_BOOST, note: `--goal ${goalTag}` });
+            return traced(opts, r, boosted, {
+                stage: 'goal', multiplier: GOAL_TAG_BOOST, scoreBefore: r.score, scoreAfter: r.score * GOAL_TAG_BOOST, note: `--goal ${goalTag}`
+            });
         }));
         return;
     }

package/dist/api/recall-request.js

@@ -1,6 +1,6 @@
 // The recall and context input rules in one copy, so MCP and HTTP reject the same inputs with the same messages.
 import { BadRequestError } from '../core/api-errors.js';
-import { MAX_ID_LEN } from '../util/http-util.js';
+import { MAX_ID_LEN } from '../util/limits.js';
 import { isJsonString } from '../util/json.js';
 const MAX_RECALL_LIMIT = 1000;
 // recall() owns the shape rule for scorer_window (invalid_scorer_window); this cap bounds remote cost.