hippo-memory 2.0.0 → 2.1.0

package/dist/api/{recall-pipeline.js → recall/pipeline.js}

@@ -1,26 +1,32 @@
 // 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 '../core/ablation.js';
-import { oneCopyPerMemory } from './context-select.js';
-import { compareEntryIdentity, compareScoresDesc } from '../core/compare.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 '../core/recall-scope.js';
-import { currentEntries } from '../search/as-of.js';
-import { STRENGTH_RANK_FLOOR, STRENGTH_RANK_SPAN } from '../search/boosts.js';
-import { hybridSearch, vectorSourceOf } from '../search/hybrid.js';
-import { searchByEngine } from '../search/engine.js';
-import { rankBothStores } from '../sharing/search-both.js';
-import { loadRecallEntries, 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. */
+import { evalNow } from '../../core/ablation.js';
+import { oneCopyPerMemory } from '../context-select.js';
+import { compareEntryIdentity, compareScoresDesc } from '../../core/compare.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 '../../core/recall-scope.js';
+import { currentEntries } from '../../search/as-of.js';
+import { STRENGTH_RANK_FLOOR, STRENGTH_RANK_SPAN } from '../../search/boosts.js';
+import { hybridSearch, vectorSourceOf } from '../../search/hybrid.js';
+import { searchByEngine } from '../../search/engine.js';
+import { CONFLICT_PEER_MULTIPLIER, SALIENCE_MIN_MULTIPLIER, UTILITY_LENGTH_PENALTY_CAP, UTILITY_LENGTH_TOKENS, VALUE_MULT_MAX, VALUE_MULT_MIN, VALUE_MULT_SLOPE, } from '../../core/search-types.js';
+import { rankBothStores } from '../../sharing/search-both.js';
+import { loadRecallEntries, recallScopeFilter } from '../../store/search-rows.js';
+import { isJsonNumber } from '../../util/json.js';
+import { currentSignal } from '../../util/request-scope.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: [] };
@@ -35,6 +41,8 @@ export async function rankRecall(ctx, opts) {
         halted,
     });
     state.results = await searchPool(ctx, opts, pool);
+    // A request past its deadline during the search has no caller left for the later stages.
+    currentSignal()?.throwIfAborted();
     if (opts.haltBefore === 'expand')
         return done(true);
     if (opts.graphHops)
@@ -65,7 +73,12 @@ function loadRecallPool(ctx, opts) {
     // An explicit --scope unlocks that envelope scope; the regex-only `<source>:private:*` deny is the JS half below.
     const requested = opts.explicitScope || undefined;
     const loadSuperseded = opts.includeSuperseded || Boolean(opts.asOf);
-    const load = { tenantId: ctx.tenantId, requestedScope: requested, explicitScopeMode: 'additive', includeSuperseded: loadSuperseded };
+    const load = {
+        tenantId: ctx.tenantId,
+        requestedScope: requested,
+        explicitScopeMode: 'additive',
+        includeSuperseded: loadSuperseded,
+    };
     let local = loadRecallEntries(ctx.hippoRoot, opts.query, load);
     let global = ctx.globalRoot ? loadRecallEntries(ctx.globalRoot, opts.query, load) : [];
     // SQL-excluded rows are pre-candidate, so the total is taken before the JS filters, which normally drop nothing.
@@ -78,47 +91,95 @@ function loadRecallPool(ctx, opts) {
     global = currentEntries(global, currentness);
     return { local, global, total, dropped: total - (local.length + global.length) };
 }
-async function searchPool(ctx, opts, pool) {
+function graphStreamSearch(ctx, opts, graphStream, pool) {
     const { query, budget, cost, includeSuperseded, asOf, activeScope: scope, search } = opts;
-    const { mmr, mmrLambda, minResults, explain } = search;
+    const { mmr, mmrLambda, minResults } = search;
     const globalRoot = pool.global.length > 0 ? ctx.globalRoot : undefined;
-    if (search.graphStream) {
-        // Without embeddings hybridSearch falls back to BM25-only and the stream is inert; say so rather than no-op.
-        if (!isEmbeddingAvailable()) {
-            ctx.note?.('[note] --graph-stream needs embeddings (rrf fusion); none available, so the graph stream is inert. Run `hippo embed` first.');
-        }
-        if (globalRoot)
-            ctx.note?.('[note] --graph-stream searches the local store only; global graph fusion is a follow-up.');
-        // With seedCount or fewer candidates every one is a seed and the stream degrades to the 2-list fusion.
-        return hybridSearch(query, pool.local, {
-            budget, cost, hippoRoot: ctx.hippoRoot, mmr, mmrLambda, minResults, scope, includeSuperseded, asOf,
-            scoring: 'rrf',
-            graphStream: { weight: DEFAULT_GRAPH_STREAM_WEIGHT, tenantId: ctx.tenantId, hops: search.graphStream.hops, seedCount: search.graphStream.seeds },
-        });
+    // Without embeddings hybridSearch falls back to BM25-only and the stream is inert; say so rather than no-op.
+    if (!isEmbeddingAvailable()) {
+        ctx.note?.('[note] --graph-stream needs embeddings (rrf fusion); none available, so the graph stream is inert. Run ' +
+            '`hippo embed` first.');
     }
-    if (search.multihop) {
-        // 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 });
+    if (globalRoot) {
+        ctx.note?.('[note] --graph-stream searches the local store only; global graph fusion is a follow-up.');
     }
+    // With seedCount or fewer candidates every one is a seed and the stream degrades to the 2-list fusion.
+    return hybridSearch(query, pool.local, {
+        budget, cost, hippoRoot: ctx.hippoRoot, mmr, mmrLambda, minResults, scope, includeSuperseded, asOf,
+        scoring: 'rrf',
+        graphStream: {
+            weight: DEFAULT_GRAPH_STREAM_WEIGHT,
+            tenantId: ctx.tenantId,
+            hops: graphStream.hops,
+            seedCount: graphStream.seeds,
+        },
+    });
+}
+function multihopPoolSearch(ctx, opts, pool) {
+    const { query, budget, cost, includeSuperseded, asOf, search } = opts;
+    const { minResults } = search;
+    // 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,
+    });
+}
+function poolVectorCandidates(ctx, opts) {
     const requested = opts.explicitScope || undefined;
-    const vectorCandidates = {
+    return {
         tenantId: ctx.tenantId,
         scope: recallScopeFilter(requested, 'additive'),
-        includeSuperseded: includeSuperseded || Boolean(asOf),
+        includeSuperseded: opts.includeSuperseded || Boolean(opts.asOf),
         admit: (e) => passesCliRecallScopeFilter(e.scope ?? null, requested),
     };
+}
+async function searchPool(ctx, opts, pool) {
+    const { query, budget, cost, includeSuperseded, asOf, activeScope: scope, search } = opts;
+    const { mmr, mmrLambda, minResults, explain } = search;
+    const globalRoot = pool.global.length > 0 ? ctx.globalRoot : undefined;
+    if (search.graphStream)
+        return graphStreamSearch(ctx, opts, search.graphStream, pool);
+    if (search.multihop)
+        return multihopPoolSearch(ctx, opts, pool);
+    const vectorCandidates = poolVectorCandidates(ctx, opts);
     if (globalRoot) {
-        // The pool already holds searchBothHybrid's additive-scope load for each store, so rank it rather than read both stores again.
+        // 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,
+            budget,
+            cost,
+            explain,
+            mmr,
+            mmrLambda,
+            localBump: search.localBump,
+            minResults,
+            scope,
+            tenantId: ctx.tenantId,
+            includeSuperseded,
+            asOf,
         });
     }
     const physics = search.usePhysics ? search.physicsConfig : null;
-    // Physics takes no MMR; explain drops minResults and includeSuperseded to hold its output steady; asOf must reach physics or later rows leak.
-    const tuning = !physics ? { mmr, mmrLambda, minResults, includeSuperseded, asOf } : explain ? { asOf } : { minResults, includeSuperseded, asOf };
-    return searchByEngine(hippoDbSource(ctx.hippoRoot), query, pool.local, physics, { budget, cost, scope, explain, vectorCandidates, ...tuning });
+    // Physics takes no MMR; explain drops minResults and includeSuperseded to hold its output steady; asOf must reach
+    // physics or later rows leak.
+    const tuning = !physics
+        ? { mmr, mmrLambda, minResults, includeSuperseded, asOf }
+        : explain
+            ? { asOf }
+            : { minResults, includeSuperseded, asOf };
+    return searchByEngine(hippoDbSource(ctx.hippoRoot), query, pool.local, physics, {
+        budget,
+        cost,
+        scope,
+        explain,
+        vectorCandidates,
+        ...tuning,
+    });
 }
 /** The CLI core holds no store: it ranks on hippo.db under its root, as its loads above do. */
 function hippoDbSource(hippoRoot) {
@@ -161,57 +222,67 @@ function traced(opts, prev, next, step) {
 function byScore(results) {
     return results.sort((a, b) => compareScoresDesc(a.score, b.score));
 }
+function demoteConflictPeers(opts, state) {
+    // Recorded conflicts only: a lexical-overlap gate once wrecked benchmark recall. Down-rank, never delete.
+    const presentIds = new Set(state.results.map((r) => r.entry.id));
+    state.results = byScore(state.results.map((r) => {
+        const hasPeerInResults = (r.entry.conflicts_with || []).some((peerId) => presentIds.has(peerId));
+        if (!hasPeerInResults)
+            return r;
+        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,
+        });
+    }));
+}
+function applyValueAware(opts, state) {
+    // Wider clamp than the always-on outcome boost, so outcome history can decide the order.
+    state.results = byScore(state.results.map((r) => {
+        const pos = r.entry.outcome_positive ?? 0;
+        const neg = r.entry.outcome_negative ?? 0;
+        if (pos === 0 && neg === 0)
+            return r;
+        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,
+        });
+    }));
+}
+function applyUtilityRank(opts, state) {
+    // 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 = 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 });
+    }));
+}
 function applyPfcRerankers(opts, state) {
     if (opts.evcAdaptive && state.results.length >= 2)
         state.results = evcAdaptive(opts.query, state.results);
     if (opts.filterConflicts) {
         dropUnless(state, (r) => !r.entry.superseded_by);
-        // Recorded conflicts only: a lexical-overlap gate once wrecked benchmark recall. Down-rank, never delete.
-        const presentIds = new Set(state.results.map((r) => r.entry.id));
-        state.results = byScore(state.results.map((r) => {
-            const hasPeerInResults = (r.entry.conflicts_with || []).some((peerId) => presentIds.has(peerId));
-            if (!hasPeerInResults)
-                return r;
-            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) {
-        // Wider clamp than the always-on outcome boost, so outcome history can decide the order.
-        state.results = byScore(state.results.map((r) => {
-            const pos = r.entry.outcome_positive ?? 0;
-            const neg = r.entry.outcome_negative ?? 0;
-            if (pos === 0 && neg === 0)
-                return r;
-            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 });
-        }));
-    }
-    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 = 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 });
-        }));
+        demoteConflictPeers(opts, state);
     }
+    if (opts.valueAware && state.results.length >= 1)
+        applyValueAware(opts, state);
+    if (opts.rerankUtility)
+        applyUtilityRank(opts, state);
 }
-// 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));
@@ -268,7 +339,11 @@ function applyGoalBoosts(ctx, opts, state) {
                 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}`
+                stage: 'goal',
+                multiplier: GOAL_TAG_BOOST,
+                scoreBefore: r.score,
+                scoreAfter: r.score * GOAL_TAG_BOOST,
+                note: `--goal ${goalTag}`,
             });
         }));
         return;
@@ -279,7 +354,11 @@ function applyGoalBoosts(ctx, opts, state) {
     const goalBoostTrace = opts.why ? new Map() : undefined;
     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 });
+    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) {
@@ -297,7 +376,12 @@ function applySalience(opts, threshold, results) {
             return r;
         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 });
+        return traced(opts, r, next, {
+            stage: 'retrieval-count-downweight',
+            multiplier: mult,
+            scoreBefore: r.score,
+            scoreAfter: next.score,
+        });
     }));
 }
 function dropUnless(state, keep) {
@@ -305,4 +389,4 @@ function dropUnless(state, keep) {
     state.results = state.results.filter(keep);
     state.droppedPreRank += before - state.results.length;
 }
-//# sourceMappingURL=recall-pipeline.js.map
+//# sourceMappingURL=pipeline.js.map

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

@@ -0,0 +1,6 @@
+import type { RecallOpts, RecallResult } from './types.js';
+import { type StoreContext } from '../types.js';
+/** The one recall entry: ranks with the ranker `opts` names, then writes the recall, and records it in full for a
+ * surface that sets `recordAs`. Only the CLI core ranker writes last_retrieval_ids (contract lock). */
+export declare function retrieve(ctx: StoreContext, opts: RecallOpts): Promise<RecallResult>;
+//# sourceMappingURL=recall.d.ts.map

package/dist/api/{recall.js → recall/recall.js}

@@ -1,25 +1,25 @@
 // Read path: retrieve, the one recall entry.
-import { envRequireSessionScopedFreshTail } from '../util/env.js';
-import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
-import { recallScopeFilter } from '../store/search-rows.js';
-import { estimateTokens } from '../util/token-text.js';
-import { formatHandoffEvidenceLine } from '../core/handoff.js';
-import { boostByGoals } from '../search/goal-boost.js';
-import { storeFor } from '../store/sqlite/store.js';
-import { searchByEngine } from '../search/engine.js';
-import { churnStaleFactor } from '../search/boosts.js';
-import { compareEntryIdentity } from '../core/compare.js';
-import { dropHeldCopies, duplicateKey, storedTextKeys } from '../util/same-text.js';
-import { isSharedStore, loadConfig } from '../core/config.js';
-import { classifyOriginProject, projectNames } from '../core/project-identity.js';
-import { decidePlanningFallacy, detectPlanningClaim } from '../predictions/planning-fallacy.js';
-import { detectAnchoring, hashQueryText, biasHintEnabled } from './recall-history.js';
-import { detectAvailabilityBias } from './availability.js';
-import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../core/recall-scope.js';
-import { ownerOrSubject, RecallContractError } from './types.js';
-import { anchoringRows, availabilityRows, callerOf, recallAuditMetadata, recallAuditRow, strengthenOf } from './recall-record.js';
-import { retrieveWithCliCore } from './recall-core.js';
-import { recallLead, recordShownRecall } from './recall-finish.js';
+import { envRequireSessionScopedFreshTail } from '../../util/env.js';
+import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../../store/rows.js';
+import { recallScopeFilter } from '../../store/search-rows.js';
+import { estimateTokens } from '../../util/token-text.js';
+import { formatHandoffEvidenceLine } from '../../core/handoff.js';
+import { boostByGoals } from '../../search/goal-boost.js';
+import { searchByEngine } from '../../search/engine.js';
+import { churnStaleFactor } from '../../search/boosts.js';
+import { compareEntryIdentity } from '../../core/compare.js';
+import { dropHeldCopies, duplicateKey, storedTextKeys } from '../../util/same-text.js';
+import { isSharedStore } from '../../core/config.js';
+import { configOf } from '../config-of.js';
+import { classifyOriginProject, projectNames } from '../../core/project-identity.js';
+import { decidePlanningFallacy, detectPlanningClaim } from '../../predictions/planning-fallacy.js';
+import { detectAnchoring, hashQueryText, biasHintEnabled } from './finish.js';
+import { detectAvailabilityBias } from '../availability.js';
+import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../../core/recall-scope.js';
+import { ownerOrSubject, RecallContractError } from '../types.js';
+import { anchoringRows, availabilityRows, callerOf, recallAuditMetadata, recallAuditRow, strengthenOf, } from './finish.js';
+import { retrieveWithCliCore } from './request.js';
+import { recallLead, recordShownRecall } from './finish.js';
 const DEFAULT_RECALL_LIMIT = 10;
 function recallOrigin(opts) {
     return opts.project ? projectNames(opts.project) : undefined;
@@ -27,8 +27,8 @@ function recallOrigin(opts) {
 function inCallerProject(entry, opts) {
     return !opts.project || classifyOriginProject(entry.origin_project, opts.project) !== 'cross-project';
 }
-/** The one recall entry: ranks with the ranker `opts` names, then writes the recall, and records it in full for a surface that sets `recordAs`.
- *  Only the CLI core ranker writes last_retrieval_ids (contract lock). */
+/** The one recall entry: ranks with the ranker `opts` names, then writes the recall, and records it in full for a
+ * surface that sets `recordAs`. Only the CLI core ranker writes last_retrieval_ids (contract lock). */
 export async function retrieve(ctx, opts) {
     assertScopeRequestAllowed(ctx.actor, opts.scope);
     if (opts.cliCore)
@@ -38,7 +38,7 @@ export async function retrieve(ctx, opts) {
     const own = personalScopeOf(ctx.actor) ?? undefined;
     if (opts.showRanked)
         return retrieveFromStore(ctx, opts, windowSize, opts.showRanked, own);
-    const store = storeFor(ctx);
+    const store = ctx.store;
     const how = opts.recordAs;
     if (!how)
         return retrieveBand(ctx, store, opts, windowSize, own);
@@ -46,7 +46,8 @@ export async function retrieve(ctx, opts) {
     await recordShownRecall(ctx, store, how, shownBand(opts, result));
     return result;
 }
-/** What the band ranker hands to the record: the rows it returns, and the continuity block the reply carries beside them. */
+/** What the band ranker hands to the record: the rows it returns,
+ * and the continuity block the reply carries beside them. */
 function shownBand(opts, result) {
     return {
         query: opts.query,
@@ -56,14 +57,19 @@ function shownBand(opts, result) {
         items: result.results.length,
         tokens: result.tokens + (result.continuityTokens ?? 0),
         ledgerSessionId: opts.sessionId ?? null,
-        written: true, // a failed audit write throws out of the band ranker, so this point is never reached without the rows
+        // A failed audit write throws out of the band ranker, so this point is never reached without the rows.
+        written: true,
     };
 }
 /** The default ranker: the SQL BM25 band, reordered by hybrid or physics search when `mode` asks. */
 async function retrieveBand(ctx, store, opts, windowSize, own) {
     let candidates = await store.searchRecallEntries(opts.query, recallSearchArgs(ctx, opts, windowSize, own));
     if (opts.mode === 'hybrid' || opts.mode === 'physics') {
-        const searchOpts = { budget: Infinity, scope: opts.scope ?? null, vectorCandidates: recallVectorSpec(ctx, opts, own) };
+        const searchOpts = {
+            budget: Infinity,
+            scope: opts.scope ?? null,
+            vectorCandidates: recallVectorSpec(ctx, opts, own),
+        };
         const ranked = await searchByEngine({ root: ctx.hippoRoot, store }, opts.query, candidates, physicsFor(ctx, opts), searchOpts);
         const rankedIds = new Set(ranked.map((r) => r.entry.id));
         candidates = [...ranked.map((r) => r.entry), ...candidates.filter((e) => !rankedIds.has(e.id))];
@@ -84,7 +90,7 @@ async function finishBandRecall(store, ctx, opts, writes, shownIds) {
 }
 /** `mode` names the engine: physics with the store's config, hybrid otherwise. */
 function physicsFor(ctx, opts) {
-    return opts.mode === 'physics' ? loadConfig(ctx.hippoRoot).physics : null;
+    return opts.mode === 'physics' ? configOf(ctx).physics : null;
 }
 /** The recall load's arguments: exact scope, current rows only, the caller's project and personal scope. */
 function recallSearchArgs(ctx, opts, limit, own) {
@@ -110,40 +116,23 @@ function recallVectorSpec(ctx, opts, own) {
 }
 // Tag, pin and recency boosts can lift a row from deep in the BM25 order, so MCP ranks a wide lexical window.
 const SHOW_RANKED_LEXICAL_WINDOW = 1000;
-/** `retrieve` under `showRanked`: physics when `mode` says so, hybrid otherwise, over a wide lexical window plus the nearest vectors. */
+/** `retrieve` under `showRanked`: physics when `mode` says so, hybrid
+ * otherwise, over a wide lexical window plus the nearest vectors. */
 async function retrieveFromStore(ctx, opts, windowSize, show, own) {
-    const store = storeFor(ctx);
+    const store = ctx.store;
     const loaded = await store.searchRecallEntries(opts.query, recallSearchArgs(ctx, opts, Math.max(windowSize, SHOW_RANKED_LEXICAL_WINDOW), own));
     const pool = loaded.filter((e) => passesScopeFilterForRecall(e.scope ?? null, opts.scope, own));
     // No scope option: the scope boost follows HIPPO_SCOPE and the skill env, as MCP recall always ranked.
     const searchOpts = { budget: Infinity, vectorCandidates: recallVectorSpec(ctx, opts, own) };
-    let ranked = await searchByEngine({ root: ctx.hippoRoot, store }, opts.query, pool, physicsFor(ctx, opts), searchOpts);
-    // One goal read serves both boosts; the ranked list's log rows come first, so its scores win the log's first-write.
-    const goals = opts.sessionId && !opts.goalTag ? await store.activeGoals({ sessionId: opts.sessionId, tenantId: ctx.tenantId }) : null;
-    let rankedLog = [];
-    if (goals && opts.sessionId) {
-        const boost = boostByGoals(ranked, goals, { sessionId: opts.sessionId, tenantId: ctx.tenantId, limit: ranked.length });
-        ranked = boost.results;
-        rankedLog = boost.log;
-    }
+    const searched = await searchByEngine({ root: ctx.hippoRoot, store }, opts.query, pool, physicsFor(ctx, opts), searchOpts);
+    const { ranked, goals, rankedLog } = await boostRankedByGoals(ctx, opts, searched);
     const window = ranked.slice(0, windowSize).map((r) => r.entry);
     const bandOpts = { ...opts, suppressRecallTrace: true };
     const plan = planRecall(ctx, bandOpts, window, own);
     const reads = await readRecall(store, ctx, bandOpts, plan, goals);
     const { result, writes } = composeRecall(ctx, bandOpts, { windowSize, all: window, plan, reads, auditBand: false });
-    // Rows the vector arm added count as candidates too.
-    const inPool = new Set(pool.map((e) => e.id));
-    const candidates = [...pool, ...ranked.map((r) => r.entry).filter((e) => !inPool.has(e.id))];
-    const shown = show({ ranked, pool: candidates, droppedByScope: loaded.length - pool.length }, result);
-    const scores = new Map(ranked.map((r) => [r.entry.id, r.score]));
-    const shownRow = recallAuditRow(callerOf(ctx), 'recall', undefined, recallAuditMetadata(opts.query, shown.ids.length));
-    const trace = opts.suppressRecallTrace ? undefined : {
-        tenantId: ctx.tenantId,
-        sessionId: opts.sessionId ?? null,
-        pipeline: 'mcp',
-        query: opts.query,
-        results: shown.ids.map((id) => ({ memoryId: id, score: scores.get(id) ?? 0 })),
-    };
+    const shown = show({ ranked, pool: withVectorCandidates(pool, ranked), droppedByScope: loaded.length - pool.length }, result);
+    const { shownRow, trace } = shownAuditAndTrace(ctx, opts, shown.ids, ranked);
     await finishBandRecall(store, ctx, opts, {
         goalLog: [...rankedLog, ...writes.goalLog],
         audit: [...writes.audit, shownRow, ...shown.audit],
@@ -151,6 +140,40 @@ async function retrieveFromStore(ctx, opts, windowSize, show, own) {
     }, shown.ids);
     return result;
 }
+// One goal read serves both boosts; the ranked list's log rows come first, so its scores win the log's first-write.
+async function boostRankedByGoals(ctx, opts, ranked) {
+    const noLog = [];
+    const goals = opts.sessionId && !opts.goalTag
+        ? await ctx.store.activeGoals({ sessionId: opts.sessionId, tenantId: ctx.tenantId })
+        : null;
+    if (!goals || !opts.sessionId)
+        return { ranked, goals, rankedLog: noLog };
+    const boost = boostByGoals(ranked, goals, {
+        sessionId: opts.sessionId,
+        tenantId: ctx.tenantId,
+        limit: ranked.length,
+    });
+    return { ranked: boost.results, goals, rankedLog: boost.log };
+}
+// Rows the vector arm added count as candidates too.
+function withVectorCandidates(pool, ranked) {
+    const inPool = new Set(pool.map((e) => e.id));
+    return [...pool, ...ranked.map((r) => r.entry).filter((e) => !inPool.has(e.id))];
+}
+function shownAuditAndTrace(ctx, opts, shownIds, ranked) {
+    const scores = new Map(ranked.map((r) => [r.entry.id, r.score]));
+    const shownRow = recallAuditRow(callerOf(ctx), 'recall', undefined, recallAuditMetadata(opts.query, shownIds.length));
+    const trace = opts.suppressRecallTrace
+        ? undefined
+        : {
+            tenantId: ctx.tenantId,
+            sessionId: opts.sessionId ?? null,
+            pipeline: 'mcp',
+            query: opts.query,
+            results: shownIds.map((id) => ({ memoryId: id, score: scores.get(id) ?? 0 })),
+        };
+    return { shownRow, trace };
+}
 /** Contract preflight: throws before any store-touching work. */
 function recallWindowSize(opts) {
     // Throw before loadSearchEntries, which runs initStore and migrates legacy state on first call.
@@ -193,16 +216,22 @@ async function readRecall(store, ctx, opts, plan, goals) {
     const parentIds = plan.overflow.size > 0 ? [...plan.overflow.keys()] : null;
     const continuity = opts.includeContinuity ? { key: continuityKey(ctx, opts) } : null;
     return {
-        goals: goals !== undefined ? goals : plan.goalBoost ? await store.activeGoals({ sessionId: plan.goalBoost.sessionId, tenantId }) : null,
+        goals: goals !== undefined
+            ? goals
+            : plan.goalBoost
+                ? await store.activeGoals({ sessionId: plan.goalBoost.sessionId, tenantId })
+                : null,
         parents: parentIds ? await store.entriesByIds(parentIds, tenantId) : [],
-        freshRaws: freshCount > 0 ? await store.freshRawEntries(freshCount, tenantId, opts.freshTailSessionId, recallOrigin(opts) ?? null) : [],
+        freshRaws: freshCount > 0
+            ? await store.freshRawEntries(freshCount, tenantId, opts.freshTailSessionId, recallOrigin(opts) ?? null)
+            : [],
         continuity: continuity ? await store.continuity(tenantId, CONTINUITY_EVENT_LIMIT, continuity.key) : undefined,
         planning: plan.claim ? await store.planningFallacyEvidence(tenantId, plan.claim.classQueryTokens) : null,
     };
 }
 // On a shared store the tenant's newest row is another developer's; no project keys to nothing, so the block is empty.
 function continuityKey(ctx, opts) {
-    if (!isSharedStore(ctx.hippoRoot))
+    if (!(ctx.reach ? ctx.reach.shared : isSharedStore(ctx.hippoRoot)))
         return null;
     return { owner: ownerOrSubject(ctx.actor), project: opts.project ? projectNames(opts.project) : [] };
 }
@@ -213,7 +242,9 @@ function composeRecall(ctx, opts, options) {
     const rankedOut = bands.rankedOut;
     const continuity = reads.continuity ? scopeContinuity(reads.continuity, opts, plan.own) : undefined;
     // Query-derived, so MCP and CLI read this one hint instead of recomputing; HIPPO_AUTODEBIAS=off disables it.
-    const planning = plan.claim && reads.planning ? decidePlanningFallacy(plan.claim, reads.planning, ctx.tenantId, ctx.actor.subject) : null;
+    const planning = plan.claim && reads.planning
+        ? decidePlanningFallacy(plan.claim, reads.planning, ctx.tenantId, ctx.actor.subject)
+        : null;
     const { anchoringHint, suppressedByInterference } = detectRecallAnchoring(opts, rankedOut[0]?.id ?? null);
     const availabilityHint = detectRecallAvailability(opts, bands.baseSlice, window.entries);
     const result = {
@@ -242,7 +273,9 @@ function composeRecall(ctx, opts, options) {
     if (availabilityHint)
         result.availabilityHint = availabilityHint;
     const who = callerOf(ctx);
-    const audit = auditBand ? [recallAuditRow(who, 'recall', undefined, recallAuditMetadata(opts.query, rankedOut.length))] : [];
+    const audit = auditBand
+        ? [recallAuditRow(who, 'recall', undefined, recallAuditMetadata(opts.query, rankedOut.length))]
+        : [];
     if (planning?.audit)
         audit.push(planning.audit);
     audit.push(...anchoringRows(who, anchoringHint), ...availabilityRows(who, availabilityHint));
@@ -297,7 +330,11 @@ function rankBands(opts, plan, reads) {
     const summaryRanked = substituted.map((s) => summaryItem(s, opts));
     const freshRanked = (opts.freshTailCount ?? 0) > 0
         ? freshTailBand(opts, {
-            recent: reads.freshRaws, baseRanked, summaryRanked, shownEntries: opts.keepHeldCopies ? [] : [...baseSlice, ...substituted.map((s) => s.entry)], own,
+            recent: reads.freshRaws,
+            baseRanked,
+            summaryRanked,
+            shownEntries: opts.keepHeldCopies ? [] : [...baseSlice, ...substituted.map((s) => s.entry)],
+            own,
         })
         : [];
     return {
@@ -312,7 +349,10 @@ function rankBands(opts, plan, reads) {
 // When the overflow holds 2+ children of one level-2 summary, that summary stands in for them, capped at 30% of
 // `limit`. Each one is tenant-scoped and re-checked against the scope filter; drillDown recovers the children.
 function substituteOverflow(opts, overflowByParent, parents, limit, own) {
-    const eligibleParents = parents.filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by && passesScopeFilterForRecall(p.scope ?? null, opts.scope, own) && inCallerProject(p, opts));
+    const eligibleParents = parents.filter((p) => (p.dag_level ?? 0) === 2 &&
+        !p.superseded_by &&
+        passesScopeFilterForRecall(p.scope ?? null, opts.scope, own) &&
+        inCallerProject(p, opts));
     const maxSub = Math.max(1, Math.ceil(limit * SUMMARY_SUB_FRACTION));
     // Most overflowed children first; compareEntryIdentity only breaks a tie, which used to fall to scan order.
     eligibleParents.sort((a, b) => {
@@ -325,7 +365,8 @@ function substituteOverflow(opts, overflowByParent, parents, limit, own) {
         childIds: (overflowByParent.get(p.id) ?? []).map((e) => e.id),
     }));
 }
-/** Overflowed leaf rows by summary parent, kept only for a parent with 2+ of them that is not already in the base band. */
+/** Overflowed leaf rows by summary parent, kept only for a
+ * parent with 2+ of them that is not already in the base band. */
 function overflowGroups(window, limit) {
     // The goal boost only re-scores the base band, so its ids are known before the boost runs.
     const baseIds = new Set(window.baseSlice.map((e) => e.id));