hippo-memory 1.70.0 → 1.71.0

package/dist/api/recall-finish.js

@@ -0,0 +1,30 @@
+import { biasHintEnabled } from './recall-history.js';
+import { anchorSkippedRows, callerOf, noteRecall, peekSessionRing, sessionRing } from './recall-record.js';
+import { recordTokens } from './tokens.js';
+/** The surfaces `retrieve` records in full. MCP is pending: src/mcp still feeds its own ring and books its own ledger row, and counts no stats. */
+export const RECALL_RECORDING = {
+    http: { ring: 'http', ledger: 'http_recall', stats: 'every' },
+    cli: { ring: 'cli', ledger: 'recall', stats: 'shown' },
+};
+/** For a surface whose hint `retrieve` judges: the session's history, or the row saying the recall named no session. */
+export function recallLead(ctx, how, query, sessionId) {
+    return {
+        // Peeked, never created: a recall that then fails must not LRU-evict a live session.
+        recallHistory: sessionId && biasHintEnabled('anchoring') ? peekSessionRing(how.ring, ctx.tenantId, sessionId) : undefined,
+        // Written first in the recall's own write, so a recall that fails leaves no row.
+        leadingAudit: sessionId ? [] : anchorSkippedRows(callerOf(ctx), query),
+    };
+}
+/** Runs after the recall's own write, in this order: the ring, then the counter, then the ledger. */
+export async function recordShownRecall(ctx, store, how, shown) {
+    // A surface that only peeked has its ring created here, after the write, so a recall that fails cannot LRU-evict a live session.
+    const ring = sessionRing(how.ring, ctx.tenantId, shown.sessionId);
+    if (ring)
+        noteRecall(ring, shown.query, shown.topId, shown.anchoredOn);
+    // A recall with no audit row counts nothing, as it strengthens and traces nothing.
+    if (shown.written && (how.stats === 'every' || shown.items > 0))
+        await store.bumpRecallStats(shown.items);
+    // The ledger books text that was sent, so its row does not wait on the audit write.
+    await recordTokens(ctx, how.ledger, { items: shown.items, tokens: shown.tokens, sessionId: shown.ledgerSessionId });
+}
+//# sourceMappingURL=recall-finish.js.map

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

@@ -1,22 +1,6 @@
-/**
- * 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. */
 export type AnchoringReason = 'query_repeat' | 'memory_dominance';
 export interface AnchoringHint {
     reason: AnchoringReason;
@@ -37,10 +21,8 @@ export interface RecallHistoryEntry {
     topMemoryId: string | null;
     /** ISO-8601 timestamp; advisory, not used by the detection rules. */
     ts: string;
-    /** Memory id of the AnchoringHint that fired on this recall, if any.
-     *  Used by the cooldown logic to prevent re-emitting the same hint on
-     *  consecutive recalls within the dominance window. Caller-written
-     *  AFTER detectAnchoring returns; reads next time detectAnchoring runs. */
+    /** Memory id of the AnchoringHint that fired on this recall, if any; the caller writes it after detectAnchoring returns, and the cooldown reads it next
+     * time. */
     anchoredOn?: string;
 }
 export type RecallHistorySnapshot = readonly RecallHistoryEntry[];
@@ -51,81 +33,32 @@ export interface DetectAnchoringOpts {
     /** query_repeat window: how many recent history entries to scan for query repeat.
      *  Default 5. */
     recentRepeatWindow?: number;
-    /** Cooldown: if the immediately-prior fire (per `anchoredOn`) was for
-     *  the same topMemoryId within this many history entries, suppress.
-     *  Default 3. */
+    /** Cooldown: suppress when the prior fire (per `anchoredOn`) was for the same topMemoryId within this many history entries. Default 3. */
     cooldown?: number;
 }
-/**
- * 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 declare function hashQueryText(query: string): number;
-/**
- * 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 declare function detectAnchoring(history: RecallHistorySnapshot, currentQueryHash: number, currentTopMemoryId: string | null, opts?: DetectAnchoringOpts): AnchoringHint | null;
-/**
- * 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 declare class RingBuffer {
     private entries;
     append(entry: RecallHistoryEntry): void;
     snapshot(): RecallHistorySnapshot;
     size(): number;
 }
-/**
- * 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 declare function buildSessionKey(tenantId: string, sessionId: string): string;
-/**
- * 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 declare function getOrCreateRing(map: Map<string, RingBuffer>, key: string, maxSessions?: number): RingBuffer;
-/**
- * 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 declare function appendRecall(ring: RingBuffer, queryHash: number, topMemoryId: string | null, anchoredOn?: string): void;
 /** Snapshot a ring as a readonly RecallHistorySnapshot. */
 export declare function snapshotRing(ring: RingBuffer): RecallHistorySnapshot;
-/**
- * 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 declare function biasHintEnabled(kind: 'anchoring' | 'availability'): boolean;
 //# sourceMappingURL=recall-history.d.ts.map

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

@@ -4,7 +4,8 @@ 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 { 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';
@@ -14,12 +15,12 @@ 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 { searchBothHybrid } 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: [] };
@@ -111,7 +112,9 @@ 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.
@@ -121,7 +124,9 @@ async function searchPool(ctx, opts, pool) {
             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 +192,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 +268,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;
     }