hippo-memory 1.69.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

@@ -0,0 +1,64 @@
+/** 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;
+    /** The memory ID that is anchoring the agent's reasoning. */
+    memoryId: string;
+    /** For 'memory_dominance': how many distinct queries in the recent window
+     *  had this memory as their top-1 result. Always >= 3 when emitted. */
+    queryCount?: number;
+    /** Human-readable summary surfaced to the agent. */
+    summary: string;
+    /** Discriminator for hint origin; reserved for future variants. */
+    source: 'j1-recurrence';
+}
+export interface RecallHistoryEntry {
+    /** Hash of the queryText that produced this entry (see hashQueryText). */
+    queryHash: number;
+    /** Top-1 memory id this recall surfaced; null if zero results. */
+    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; the caller writes it after detectAnchoring returns, and the cooldown reads it next
+     * time. */
+    anchoredOn?: string;
+}
+export type RecallHistorySnapshot = readonly RecallHistoryEntry[];
+export interface DetectAnchoringOpts {
+    /** memory_dominance threshold: number of distinct queryHashes that must have returned
+     *  the same topMemoryId. Default 3. */
+    minDominance?: number;
+    /** query_repeat window: how many recent history entries to scan for query repeat.
+     *  Default 5. */
+    recentRepeatWindow?: number;
+    /** Cooldown: suppress when the prior fire (per `anchoredOn`) was for the same topMemoryId within this many history entries. Default 3. */
+    cooldown?: number;
+}
+/** 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;
+/** 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 (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;
+}
+/** 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 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;
+/** 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 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

@@ -0,0 +1,159 @@
+/** 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;
+/** 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}, \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, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length > 0);
+    // Drop tokens under 3 chars (filler words) so `a login bug` and `login bug` hash
+    // alike; matches the >=3 filter in src/learn/forward-claim-detector.ts.
+    const filtered = normalized.filter((t) => t.length >= 3);
+    // Fall back to all tokens when the filter empties the query (CJK 2-char words,
+    // acronyms like `AI`) so distinct short queries do not all hash to fnv1a32('').
+    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;
+}
+/** 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;
+    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;
+        }
+    }
+    // memory_dominance check FIRST (wins on tie).
+    const queryCount = countDistinctQueries(history, currentQueryHash, currentTopMemoryId);
+    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',
+        };
+    }
+    if (isRecentRepeat(history, recentRepeatWindow, currentQueryHash, 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;
+}
+// Count distinct queryHashes in history where topMemoryId === the current top
+// (excluding null tops), plus the current query itself.
+function countDistinctQueries(history, currentQueryHash, currentTopMemoryId) {
+    const matchingQueryHashes = new Set();
+    for (const entry of history) {
+        if (entry.topMemoryId === currentTopMemoryId) {
+            matchingQueryHashes.add(entry.queryHash);
+        }
+    }
+    matchingQueryHashes.add(currentQueryHash);
+    return matchingQueryHashes.size;
+}
+// query_repeat check: is currentQueryHash present in the last `recentRepeatWindow`
+// entries AND was that entry's topMemoryId === currentTopMemoryId?
+function isRecentRepeat(history, recentRepeatWindow, currentQueryHash, currentTopMemoryId) {
+    return history
+        .slice(-recentRepeatWindow)
+        .some((entry) => entry.queryHash === currentQueryHash && entry.topMemoryId === currentTopMemoryId);
+}
+const MAX_HISTORY = 10;
+const DEFAULT_MAX_SESSIONS = 1000;
+/** 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) {
+        this.entries.push(entry);
+        if (this.entries.length > MAX_HISTORY) {
+            this.entries.shift();
+        }
+    }
+    snapshot() {
+        return this.entries;
+    }
+    size() {
+        return this.entries.length;
+    }
+}
+/** 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 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) {
+        // 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;
+}
+/** 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,
+        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();
+}
+/** 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()
+        : !envAvailabilityOff();
+}
+//# sourceMappingURL=recall-history.js.map

package/dist/{recall-pipeline.d.ts → api/recall-pipeline.d.ts}

@@ -1,8 +1,8 @@
-import { type GoalRecallLogRow } from './goals.js';
-import { type MemoryEntry } from './memory.js';
-import type { PhysicsConfig } from './physics-config.js';
-import type { RerankerFn } from './rerankers/types.js';
-import type { ResultCost, SearchResult } from './search/types.js';
+import { type GoalRecallLogRow } from '../store/goals.js';
+import { type MemoryEntry } from '../core/memory.js';
+import type { PhysicsConfig } from '../core/physics-config.js';
+import type { RerankerFn } from '../rerankers/types.js';
+import type { ResultCost, SearchResult } from '../core/search-types.js';
 /** Stores rankRecall reads and where it sends operator notes. */
 export interface RankRecallCtx {
     hippoRoot: string;
@@ -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/{recall-pipeline.js → api/recall-pipeline.js}

@@ -1,25 +1,26 @@
 // Ranking core shared by `hippo recall` and `hippo explain`: load, search, expand, re-rank and filter, with no
 // writes and no direct output. Callers own flag parsing, printing, budget fitting and persistence.
-import { evalNow } from './ablation.js';
-import { oneCopyPerMemory } from './api.js';
-import { compareEntryIdentity } from './compare.js';
-import { closeHippoDb, openHippoDb } from './db.js';
-import { isEmbeddingAvailable } from './local-embedding.js';
-import { computeGoalStackBoost } from './goals.js';
-import { graphExpandRecall } from './graph-recall.js';
-import { DEFAULT_GRAPH_STREAM_WEIGHT } from './graph-stream.js';
-import { Layer } from './memory.js';
-import { multihopSearch } from './multihop.js';
-import { passesCliRecallScopeFilter } from './recall-scope.js';
-import { currentEntries } from './search/as-of.js';
-import { hybridSearch } from './search/hybrid.js';
-import { physicsSearch } from './search/physics-search.js';
-import { searchBothHybrid } from './shared.js';
-import { loadRecallSearchEntries, recallScopeFilter } from './store/search-rows.js';
-import { textOverlap, tokenize as tokenizeQuery } from './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. */
+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 } 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 { 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/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 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) {
@@ -155,7 +160,7 @@ function traced(opts, prev, next, step) {
 }
 /** Re-sort after a score change. Plain and stable on purpose: ties keep the prior rank, not a content order. */
 function byScore(results) {
-    return results.sort((a, b) => b.score - a.score);
+    return results.sort((a, b) => compareScoresDesc(a.score, b.score));
 }
 function applyPfcRerankers(opts, state) {
     if (opts.evcAdaptive && state.results.length >= 2)
@@ -168,8 +173,8 @@ function applyPfcRerankers(opts, state) {
             const hasPeerInResults = (r.entry.conflicts_with || []).some((peerId) => presentIds.has(peerId));
             if (!hasPeerInResults)
                 return r;
-            const next = { ...r, score: r.score * 0.3 };
-            return traced(opts, r, next, { stage: 'interference', multiplier: 0.3, scoreBefore: r.score, scoreAfter: next.score });
+            const next = { ...r, score: r.score * CONFLICT_PEER_MULTIPLIER };
+            return traced(opts, r, next, { stage: 'interference', multiplier: CONFLICT_PEER_MULTIPLIER, scoreBefore: r.score, scoreAfter: next.score });
         }));
     }
     if (opts.valueAware && state.results.length >= 1) {
@@ -179,7 +184,7 @@ function applyPfcRerankers(opts, state) {
             const neg = r.entry.outcome_negative ?? 0;
             if (pos === 0 && neg === 0)
                 return r;
-            const valueMult = Math.max(0.7, Math.min(1.3, 1 + 0.3 * Math.tanh(pos - neg)));
+            const valueMult = Math.max(VALUE_MULT_MIN, Math.min(VALUE_MULT_MAX, 1 + VALUE_MULT_SLOPE * Math.tanh(pos - neg)));
             const next = { ...r, score: r.score * valueMult };
             return traced(opts, r, next, { stage: 'value', multiplier: valueMult, scoreBefore: r.score, scoreAfter: next.score });
         }));
@@ -187,13 +192,27 @@ 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 utilityMult = (0.5 + 0.5 * strength) * (1 - Math.min(0.3, (r.tokens || 0) / 10000));
+            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 });
         }));
     }
 }
+// A recorded conflict peer in the same result list is cut to this share of its score.
+const CONFLICT_PEER_MULTIPLIER = 0.3;
+// The value-aware clamp is wider than the always-on outcome nudge, so outcome history can decide the order.
+const VALUE_MULT_SLOPE = 0.3;
+const VALUE_MULT_MIN = 0.7;
+const VALUE_MULT_MAX = 1.3;
+const UTILITY_LENGTH_PENALTY_CAP = 0.3;
+const UTILITY_LENGTH_TOKENS = 10000;
+// evcAdaptive acts when the top hits overlap this much; it keeps rows near the best score or covering the query.
+const NEAR_DUPLICATE_OVERLAP_MIN = 0.4;
+const SCORE_FLOOR_FRACTION = 0.5;
+const QUERY_COVERAGE_MIN = 0.6;
+const GOAL_TAG_BOOST = 1.5;
+const SALIENCE_MIN_MULTIPLIER = 0.5;
 /** When the top hits are near-duplicates (same topic, different facts), surface the newest on-topic row first. */
 function evcAdaptive(query, results) {
     const slice = results.slice(0, Math.min(3, results.length));
@@ -205,11 +224,11 @@ function evcAdaptive(query, results) {
             pairs++;
         }
     }
-    if ((pairs > 0 ? overlapSum / pairs : 0) < 0.4)
+    if ((pairs > 0 ? overlapSum / pairs : 0) < NEAR_DUPLICATE_OVERLAP_MIN)
         return results;
     const poolSize = Math.min(results.length, Math.max(slice.length * 3, 9));
     const pool = results.slice(0, poolSize);
-    const scoreFloor = pool.reduce((m, r) => Math.max(m, r.score), 0) * 0.5;
+    const scoreFloor = pool.reduce((m, r) => Math.max(m, r.score), 0) * SCORE_FLOOR_FRACTION;
     // Query coverage catches the differently phrased update a score floor alone would miss.
     const queryTokens = new Set(tokenizeQuery(query));
     const onTopic = [];
@@ -223,7 +242,7 @@ function evcAdaptive(query, results) {
                     hits++;
         }
         const queryCoverage = queryTokens.size > 0 ? hits / queryTokens.size : 0;
-        (r.score >= scoreFloor || queryCoverage >= 0.6 ? onTopic : offTopic).push(r);
+        (r.score >= scoreFloor || queryCoverage >= QUERY_COVERAGE_MIN ? onTopic : offTopic).push(r);
     }
     // Recency is the primary key; identity only breaks exact-timestamp ties.
     onTopic.sort((a, b) => {
@@ -248,29 +267,22 @@ function applyGoalBoosts(ctx, opts, state) {
         state.results = byScore(state.results.map((r) => {
             if (!r.entry.tags?.includes(goalTag))
                 return r;
-            const boosted = { ...r, score: r.score * 1.5 };
-            return traced(opts, r, boosted, { stage: 'goal', multiplier: 1.5, scoreBefore: r.score, scoreAfter: r.score * 1.5, note: `--goal ${goalTag}` });
+            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;
     }
     if (!opts.sessionId)
         return;
-    const db = openHippoDb(ctx.hippoRoot);
     // The helper re-spreads rows, so its steps come back in a map keyed by entry id.
     const goalBoostTrace = opts.why ? new Map() : undefined;
-    try {
-        const boost = computeGoalStackBoost(db, state.results, {
-            sessionId: opts.sessionId,
-            tenantId: ctx.tenantId,
-            limit: opts.limit,
-            trace: goalBoostTrace,
-        });
-        state.results = boost.results;
-        state.goalRecallLog = boost.log;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    const session = { sessionId: opts.sessionId, tenantId: ctx.tenantId };
+    // The log may name global rows; the store drops those when it writes, as it does for api.recall.
+    const boost = boostByGoals(state.results, activeGoalsWithPolicies(ctx.hippoRoot, session), { ...session, limit: opts.limit, trace: goalBoostTrace });
+    state.results = boost.results;
+    state.goalRecallLog = boost.log;
     if (goalBoostTrace && goalBoostTrace.size > 0) {
         state.results = state.results.map((r) => {
             const step = goalBoostTrace.get(r.entry.id);
@@ -284,7 +296,7 @@ function applySalience(opts, threshold, results) {
         const count = r.entry.retrieval_count ?? 0;
         if (count >= threshold)
             return r;
-        const mult = Math.max(0.5, count / threshold);
+        const mult = Math.max(SALIENCE_MIN_MULTIPLIER, count / threshold);
         const next = { ...r, score: r.score * mult };
         return traced(opts, r, next, { stage: 'retrieval-count-downweight', multiplier: mult, scoreBefore: r.score, scoreAfter: next.score });
     }));

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

@@ -1,6 +1,8 @@
-import { type AppendAuditOpts, type AuditOp } from '../audit.js';
-import type { AvailabilityHint } from '../availability.js';
-import { RingBuffer, type AnchoringHint, type RecallHistorySnapshot } from '../recall-history.js';
+import { type AppendAuditOpts, type AuditOp } from '../store/audit.js';
+import type { AvailabilityHint } from './availability.js';
+import { RingBuffer, type AnchoringHint, type RecallHistorySnapshot } from './recall-history.js';
+import type { RecallWrites } from '../store/index.js';
+import type { Context } from './types.js';
 export type RecallSurface = 'cli' | 'mcp' | 'http';
 /** The session's ring, created on first use; null when anchoring is off or the call has no session. */
 export declare function sessionRing(surface: RecallSurface, tenantId: string, sessionId: string | undefined): RingBuffer | null;
@@ -9,19 +11,16 @@ export declare function peekSessionRing(surface: RecallSurface, tenantId: string
 /** Records this recall's top row and hint, which the next recall's cooldown reads. */
 export declare function noteRecall(ring: RingBuffer, query: string, topId: string | null, anchoredOn: string | undefined): void;
 export declare function resetSessionRings(surface: RecallSurface): void;
-export interface RecallAuditor {
-    readonly hippoRoot: string;
+/** Whom a recall audit row names. */
+export interface RecallAuditCaller {
     readonly tenantId: string;
     readonly actor: string;
-    /** Log and count a failed write instead of throwing, for a CLI command that has already done its work. */
-    readonly bestEffort?: boolean;
 }
-/** Whom a recall audit row names; a surface that writes through the store port needs no root. */
-export type RecallAuditCaller = Pick<RecallAuditor, 'tenantId' | 'actor'>;
+export declare function callerOf(ctx: Context): RecallAuditCaller;
+/** The strengthen every ranker of `retrieve` hands to the recall's write: the shown ids, in the caller's tenant. */
+export declare function strengthenOf(ctx: Context, ids: readonly string[]): NonNullable<RecallWrites['strengthen']>;
 type RecallAuditMetadata = Readonly<Record<string, string | number | null>>;
 export declare function recallAuditRow(who: RecallAuditCaller, op: AuditOp, targetId?: string, metadata?: RecallAuditMetadata): AppendAuditOpts;
-/** One audit row on its own short-lived handle. */
-export declare function appendRecallAudit(who: RecallAuditor, op: AuditOp, targetId?: string, metadata?: RecallAuditMetadata): void;
 export declare function recallAuditMetadata(query: string, results: number): {
     results: number;
     query_hash: string;
@@ -40,7 +39,5 @@ export interface ShownRecall {
 }
 /** The hint rows for a list a surface showed, so a surface on the store port can hand them to the recall's one write. */
 export declare function shownRecallRows(who: RecallAuditCaller, shown: ShownRecall): AppendAuditOpts[];
-/** For a surface that computes its hints over the list it shows: feeds the ring after the final detect, then audits the hints. */
-export declare function recordShownRecall(who: RecallAuditor, shown: ShownRecall): void;
 export {};
 //# sourceMappingURL=recall-record.d.ts.map

package/dist/api/recall-record.js

@@ -1,7 +1,7 @@
 // The recall session rings and the recall audit rows, in one place for the CLI, MCP and HTTP surfaces.
-import { appendAuditEvent, auditQueryFields, reportAuditWriteFailure } from '../audit.js';
-import { closeHippoDb, openHippoDb } from '../db.js';
-import { appendRecall, biasHintEnabled, buildSessionKey, getOrCreateRing, hashQueryText, snapshotRing, } from '../recall-history.js';
+import { isRecallBoostAblated } from '../core/ablation.js';
+import { auditQueryFields } from '../store/audit.js';
+import { appendRecall, biasHintEnabled, buildSessionKey, getOrCreateRing, hashQueryText, snapshotRing, } from './recall-history.js';
 // One map per surface, each with its own LRU cap, so a repeat on one surface is a first recall on another.
 const rings = {
     cli: new Map(),
@@ -26,28 +26,15 @@ export function noteRecall(ring, query, topId, anchoredOn) {
 export function resetSessionRings(surface) {
     rings[surface].clear();
 }
-export function recallAuditRow(who, op, targetId, metadata) {
-    return { tenantId: who.tenantId, actor: who.actor, op, targetId, metadata };
+export function callerOf(ctx) {
+    return { tenantId: ctx.tenantId, actor: ctx.actor.subject };
 }
-function writeRecallAudit(who, row) {
-    try {
-        const db = openHippoDb(who.hippoRoot);
-        try {
-            appendAuditEvent(db, row);
-        }
-        finally {
-            closeHippoDb(db);
-        }
-    }
-    catch (err) {
-        if (!who.bestEffort)
-            throw err;
-        reportAuditWriteFailure(row.op, String(err), row.targetId);
-    }
+/** The strengthen every ranker of `retrieve` hands to the recall's write: the shown ids, in the caller's tenant. */
+export function strengthenOf(ctx, ids) {
+    return { ids, opts: { tenantId: ctx.tenantId, recallBoostAblated: isRecallBoostAblated() } };
 }
-/** One audit row on its own short-lived handle. */
-export function appendRecallAudit(who, op, targetId, metadata) {
-    writeRecallAudit(who, recallAuditRow(who, op, targetId, metadata));
+export function recallAuditRow(who, op, targetId, metadata) {
+    return { tenantId: who.tenantId, actor: who.actor, op, targetId, metadata };
 }
 // The row stores a hash of the query, never its text, so an archived memory's words cannot persist there.
 export function recallAuditMetadata(query, results) {
@@ -88,11 +75,4 @@ export function shownRecallRows(who, shown) {
         ...availabilityRows(who, shown.availability),
     ];
 }
-/** For a surface that computes its hints over the list it shows: feeds the ring after the final detect, then audits the hints. */
-export function recordShownRecall(who, shown) {
-    if (shown.ring)
-        noteRecall(shown.ring, shown.query, shown.topId, shown.anchoring?.memoryId);
-    for (const row of shownRecallRows(who, shown))
-        writeRecallAudit(who, row);
-}
 //# sourceMappingURL=recall-record.js.map

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

@@ -1,5 +1,5 @@
-import { BadRequestError } from '../api-errors.js';
-import { type JsonValue } from '../json.js';
+import { BadRequestError } from '../core/api-errors.js';
+import { type JsonValue } from '../util/json.js';
 import type { ContextOpts } from './context-types.js';
 import type { RecallOpts } from './recall-types.js';
 /** A recall or context input the caller must fix; MCP answers it with an isError result, HTTP with a 400. */

package/dist/api/recall-request.js

@@ -1,7 +1,7 @@
 // The recall and context input rules in one copy, so MCP and HTTP reject the same inputs with the same messages.
-import { BadRequestError } from '../api-errors.js';
-import { MAX_ID_LEN } from '../http-util.js';
-import { isJsonString } from '../json.js';
+import { BadRequestError } from '../core/api-errors.js';
+import { MAX_ID_LEN } from '../util/http-util.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.
 const MAX_SCORER_WINDOW = 1000;