hippo-memory 1.69.0 → 1.71.0

package/dist/search/boosts.js

@@ -1,23 +1,38 @@
-import { envSummaryDeboost } from '../env.js';
-import { calculateStrength, CHURN_STALE_TAG } from '../memory.js';
-import { isOutcomeFastAblated, isRecencyAblated, evalRecencyScaleDays } from '../ablation.js';
-import { pathBoostMultiplier } from '../path-context.js';
-import { scopeMatch } from '../scope.js';
+import { envSummaryDeboost } from '../util/env.js';
+import { calculateStrength, CHURN_STALE_TAG } from '../core/memory.js';
+import { isOutcomeFastAblated, isRecencyAblated, evalRecencyScaleDays } from '../core/ablation.js';
+import { pathBoostMultiplier } from './path-context.js';
+import { scopeMatch } from '../sharing/scope.js';
 import { temporalBoost } from './temporal.js';
-export const CHURN_STALE_RANK_MULTIPLIER = 0.5; // SHORTCUT: untuned; measure on real recall before any default.
+import { DAY_MS } from '../util/time.js';
+const CHURN_STALE_RANK_MULTIPLIER = 0.5; // SHORTCUT: untuned; measure on real recall before any default.
 const DECISION_TAG_BOOST = 1.2;
+// A memory tagged for the active scope outranks a neutral one; one tagged for another scope is demoted.
+const SCOPE_MATCH_BOOST = 1.5;
+const SCOPE_MISMATCH_BOOST = 0.5;
+const EXTRACTION_TAG_BOOST = 1.3;
+// The outcome nudge is 1 + slope * tanh(net / 2), clamped so one outcome streak cannot swamp lexical rank.
+const OUTCOME_NUDGE_SLOPE = 0.15;
+const OUTCOME_NUDGE_MIN = 0.85;
+const OUTCOME_NUDGE_MAX = 1.15;
+// Strength and recency enter the rank as floor + span * signal, so a weak or old memory keeps most of its lexical score.
+export const STRENGTH_RANK_FLOOR = 0.5;
+export const STRENGTH_RANK_SPAN = 0.5;
+const RECENCY_RANK_FLOOR = 0.8;
+const RECENCY_RANK_SPAN = 0.2;
+const RECENCY_SCALE_DAYS = 30;
 const DEFAULT_SUMMARY_DEBOOST = 0.85;
 const DEFAULT_FRESHNESS_BOOST = 1.05;
-const FRESHNESS_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const FRESHNESS_WINDOW_MS = 7 * DAY_MS;
 export function churnStaleFactor(entry) {
     return entry.tags.includes(CHURN_STALE_TAG) ? CHURN_STALE_RANK_MULTIPLIER : 1.0;
 }
-export function recencyBoost(entry, now) {
+function recencyBoost(entry, now) {
     if (isRecencyAblated())
         return 1; // EVAL-ONLY ablation (see ablation.ts)
     const created = new Date(entry.created);
-    const ageDays = (now.getTime() - created.getTime()) / (1000 * 60 * 60 * 24);
-    return Math.exp(-ageDays / (evalRecencyScaleDays() ?? 30));
+    const ageDays = (now.getTime() - created.getTime()) / DAY_MS;
+    return Math.exp(-ageDays / (evalRecencyScaleDays() ?? RECENCY_SCALE_DAYS));
 }
 /** Retrieval-time outcome nudge in [0.85, 1.15]; the bm25-outcome eval baseline ranks with it too. */
 export function outcomeMultiplier(entry) {
@@ -25,7 +40,7 @@ export function outcomeMultiplier(entry) {
     const neg = entry.outcome_negative ?? 0;
     if (isOutcomeFastAblated() || (pos === 0 && neg === 0))
         return 1.0; // EVAL-ONLY ablation (see ablation.ts)
-    return Math.max(0.85, Math.min(1.15, 1 + 0.15 * Math.tanh((pos - neg) / 2)));
+    return Math.max(OUTCOME_NUDGE_MIN, Math.min(OUTCOME_NUDGE_MAX, 1 + OUTCOME_NUDGE_SLOPE * Math.tanh((pos - neg) / 2)));
 }
 /** A DAG summary is a topic summary (level 2) or an entity profile (level 3); both take the same deboost. */
 export function isDagSummary(entry) {
@@ -66,7 +81,14 @@ export function summaryMultipliers(entry, now, s) {
     return { deboost: s.deboost, freshness: s.freshness ? summaryFreshnessMultiplier(entry, now) : 1.0 };
 }
 export function strengthRecencyMultipliers(entry, now) {
-    return { strength: 0.5 + 0.5 * calculateStrength(entry, now), recency: 0.8 + 0.2 * recencyBoost(entry, now) };
+    return {
+        strength: STRENGTH_RANK_FLOOR + STRENGTH_RANK_SPAN * calculateStrength(entry, now),
+        recency: RECENCY_RANK_FLOOR + RECENCY_RANK_SPAN * recencyBoost(entry, now),
+    };
+}
+/** The rank multiplier for a scopeMatch signal: match, mismatch or neutral. */
+export function scopeBoostFor(signal) {
+    return signal === 1 ? SCOPE_MATCH_BOOST : signal === -1 ? SCOPE_MISMATCH_BOOST : 1.0;
 }
 /** Applies every rank multiplier one at a time, in a fixed order, so float rounding matches across paths. */
 export function applyRankBoosts(score, entry, ctx) {
@@ -74,9 +96,8 @@ export function applyRankBoosts(score, entry, ctx) {
     const churnStaleMultiplier = churnStaleFactor(entry);
     const pathBoost = pathBoostMultiplier(entry.tags, ctx.pathTags);
     const outcomeBoost = ctx.outcome ? outcomeMultiplier(entry) : 1.0;
-    const scopeSignal = scopeMatch(entry.tags, ctx.scope);
-    const scopeBoost = scopeSignal === 1 ? 1.5 : scopeSignal === -1 ? 0.5 : 1.0;
-    const extractionBoost = entry.tags.includes('extracted') ? 1.3 : 1.0;
+    const scopeBoost = scopeBoostFor(scopeMatch(entry.tags, ctx.scope));
+    const extractionBoost = entry.tags.includes('extracted') ? EXTRACTION_TAG_BOOST : 1.0;
     const summary = summaryMultipliers(entry, ctx.now, ctx.summary);
     let s = score;
     s *= decisionBoost;

package/dist/search/breakdown.d.ts

@@ -1,5 +1,5 @@
-import type { MemoryEntry } from '../memory.js';
-import type { ScoreBreakdown } from './types.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { ScoreBreakdown } from '../core/search-types.js';
 /** Whole days since the entry was created, never negative. */
 export declare function ageInDays(entry: MemoryEntry, now: Date): number;
 /** Copies the entry's DAG metadata, and for summaries the multipliers applied, onto an explain breakdown. */

package/dist/search/breakdown.js

@@ -1,7 +1,8 @@
 import { isDagSummary } from './boosts.js';
+import { DAY_MS } from '../util/time.js';
 /** Whole days since the entry was created, never negative. */
 export function ageInDays(entry, now) {
-    return Math.max(0, Math.floor((now.getTime() - new Date(entry.created).getTime()) / 86_400_000));
+    return Math.max(0, Math.floor((now.getTime() - new Date(entry.created).getTime()) / DAY_MS));
 }
 /** Copies the entry's DAG metadata, and for summaries the multipliers applied, onto an explain breakdown. */
 export function addDagFields(breakdown, entry, deboost, freshness) {

package/dist/search/explain.d.ts

@@ -1,4 +1,4 @@
-import type { SearchResult } from './types.js';
+import type { SearchResult } from '../core/search-types.js';
 export interface MatchExplanation {
     /** Human-readable reason string */
     reason: string;

package/dist/search/explain.js

@@ -1,5 +1,6 @@
-import { tokenize } from '../tokenize.js';
+import { tokenize } from '../util/tokenize.js';
 import { matchedQueryTerms } from './bm25.js';
+const COSINE_DECIMALS = 3;
 /** Why a result matched: the overlapping query terms and whether BM25 and/or embedding similarity contributed. */
 export function explainMatch(query, result) {
     const matchedTerms = matchedQueryTerms(new Set(tokenize(query)), result.entry);
@@ -9,7 +10,7 @@ export function explainMatch(query, result) {
     if (hasBm25)
         parts.push(`BM25: matched terms [${matchedTerms.join(', ')}]`);
     if (hasEmbedding)
-        parts.push(`embedding similarity: ${result.cosine.toFixed(3)}`);
+        parts.push(`embedding similarity: ${result.cosine.toFixed(COSINE_DECIMALS)}`);
     if (parts.length === 0)
         parts.push('no direct term or embedding match');
     return {

package/dist/search/finalize.d.ts

@@ -1,5 +1,5 @@
-import type { MemoryEntry } from '../memory.js';
-import type { ResultCost, SearchResult } from './types.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { ResultCost, SearchResult } from '../core/search-types.js';
 /** When an extracted fact and its source both match, keep only the higher-scoring one (usually the fact). */
 export declare function dedupeExtracted(scored: SearchResult[]): SearchResult[];
 /** DAG drill-down: a matched summary pulls its children from `pool` in at 0.9x its score; sorts `results` in place. */

package/dist/search/finalize.js

@@ -1,5 +1,5 @@
-import { estimateTokens } from '../token-ledger.js';
-import { compareScoredResults } from '../compare.js';
+import { estimateTokens } from '../util/token-text.js';
+import { compareScoredResults } from '../core/compare.js';
 import { churnStaleFactor } from './boosts.js';
 /** When an extracted fact and its source both match, keep only the higher-scoring one (usually the fact). */
 export function dedupeExtracted(scored) {
@@ -20,6 +20,7 @@ export function dedupeExtracted(scored) {
     }
     return deduped;
 }
+const DAG_CHILD_SCORE_FACTOR = 0.9;
 /** DAG drill-down: a matched summary pulls its children from `pool` in at 0.9x its score; sorts `results` in place. */
 export function withDagChildren(results, pool) {
     const summaryIds = results.filter((r) => r.entry.tags.includes('dag-summary')).map((r) => r.entry.id);
@@ -30,7 +31,7 @@ export function withDagChildren(results, pool) {
         if (results.some((r) => r.entry.id === child.id))
             continue;
         const parentResult = results.find((r) => r.entry.id === child.dag_parent_id);
-        const childScore = parentResult ? parentResult.score * 0.9 * churnStaleFactor(child) : 0;
+        const childScore = parentResult ? parentResult.score * DAG_CHILD_SCORE_FACTOR * churnStaleFactor(child) : 0;
         results.push({ entry: child, score: childScore, bm25: 0, cosine: 0, tokens: estimateTokens(child.content) });
     }
     results.sort(compareScoredResults);

package/dist/search/fusion.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryEntry } from '../memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 import type { DenseScores } from './vector.js';
 /** Opt-in third RRF list ranking in-pool candidates by graph proximity to the strong lexical seeds. */
 export interface GraphStreamOptions {

package/dist/search/fusion.js

@@ -1,6 +1,6 @@
-import { rrfFuse } from '../rrf.js';
-import { graphRankStream, selectGraphSeeds, DEFAULT_GRAPH_SEED_COUNT } from '../graph-stream.js';
-import { compareEntryIdentity } from '../compare.js';
+import { rrfFuse } from './rrf.js';
+import { graphRankStream, selectGraphSeeds, DEFAULT_GRAPH_SEED_COUNT } from '../graph/stream.js';
+import { compareEntryIdentity } from '../core/compare.js';
 // Score desc, then entry identity, so ties cannot leak fresh-ingest order into graph seeds or RRF ranks.
 function rankBy(eligible, scores, entries) {
     return [...eligible].sort((a, b) => {

package/dist/search/goal-boost.d.ts

@@ -0,0 +1,23 @@
+import type { MemoryEntry } from '../core/memory.js';
+import type { RerankStep } from '../core/search-types.js';
+import type { ActiveGoals, GoalRecallLogRow } from '../store/goals.js';
+/** Options of {@link boostByGoals}. */
+export interface GoalStackBoostOpts {
+    sessionId: string;
+    tenantId: string;
+    limit: number;
+    /** Side-channel: one goal-boost `RerankStep` per boosted row, keyed by `entry.id` (a map because the helper re-spreads rows); only populated when passed. */
+    trace?: Map<string, RerankStep>;
+}
+/** The boosted, re-sorted rows and the `goal_recall_log` rows they earn. */
+export interface GoalStackBoost<R> {
+    results: R[];
+    log: GoalRecallLogRow[];
+}
+/** The goal-stack boost over goals already read, touching no store; a caller skips it under an explicit goal tag. Its log covers the top
+ *  `limit` rows and keeps those whose memory is global, since only the store can tell them apart; {@link localGoalRecallRows} drops those before the write. */
+export declare function boostByGoals<R extends {
+    entry: MemoryEntry;
+    score: number;
+}>(results: R[], active: ActiveGoals, opts: GoalStackBoostOpts): GoalStackBoost<R>;
+//# sourceMappingURL=goal-boost.d.ts.map

package/dist/search/goal-boost.js

@@ -0,0 +1,90 @@
+// src/search/goal-boost.ts: the goal-stack boost over goals already read; it ranks rows and touches no store.
+import { compareScoresDesc } from '../core/compare.js';
+const MAX_FINAL_MULTIPLIER = 3.0;
+/** The capped boost for one row whose tags match `matches` active goals. */
+function goalBoostMultiplier(entry, tags, matches, goalsByTag, policiesByGoalId) {
+    // Base 2.0x for first match, +0.5x per additional, capped at 3.0x.
+    let multiplier = Math.min(2.0 + 0.5 * (matches.length - 1), MAX_FINAL_MULTIPLIER);
+    // Compose per-policy multipliers per matched tag.
+    for (const tag of matches) {
+        const goal = goalsByTag.get(tag);
+        const policy = policiesByGoalId.get(goal.id);
+        if (!policy)
+            continue;
+        if (policy.policyType === 'error-prioritized' && tags.includes('error')) {
+            multiplier *= policy.errorPriority;
+        }
+        else if (policy.policyType === 'schema-fit-biased') {
+            // Linearly weight schema_fit in [0,1] up to (weightSchemaFit)x.
+            // Default 1.0 is a no-op.
+            multiplier *=
+                1.0 +
+                    Math.max(0, policy.weightSchemaFit - 1.0) *
+                        (entry.schema_fit ?? 0.5);
+        }
+        else if (policy.policyType === 'recency-first') {
+            multiplier *= policy.weightRecency;
+        }
+        else if (policy.policyType === 'hybrid') {
+            multiplier *= policy.weightOutcome;
+        }
+    }
+    // Hard cap AFTER all composition.
+    return Math.min(multiplier, MAX_FINAL_MULTIPLIER);
+}
+/** Log rows for the top `limit` boosted rows, one per matched goal. */
+function buildGoalRecallLog(boosted, matchesByEntryId, goalsByTag, opts) {
+    const { sessionId, tenantId, limit } = opts;
+    const recalledAt = new Date().toISOString();
+    const log = [];
+    for (const r of boosted.slice(0, limit)) {
+        const matches = matchesByEntryId.get(r.entry.id);
+        if (!matches || matches.length === 0)
+            continue;
+        for (const tag of matches) {
+            const goal = goalsByTag.get(tag);
+            if (!goal)
+                continue;
+            log.push({ goalId: goal.id, memoryId: r.entry.id, tenantId, sessionId, recalledAt, score: r.score });
+        }
+    }
+    return log;
+}
+/** The goal-stack boost over goals already read, touching no store; a caller skips it under an explicit goal tag. Its log covers the top
+ *  `limit` rows and keeps those whose memory is global, since only the store can tell them apart; {@link localGoalRecallRows} drops those before the write. */
+export function boostByGoals(results, active, opts) {
+    const { trace } = opts;
+    if (active.goals.length === 0)
+        return { results, log: [] };
+    const goalsByTag = new Map(active.goals.map((g) => [g.goalName, g]));
+    const policiesByGoalId = active.policies;
+    // Goal-tag matches per boosted row, keyed by entry id; a side table (not a spread-on marker property) so `boosted` stays exactly R[] with no cast-then-strip.
+    const matchesByEntryId = new Map();
+    const boosted = results
+        .map((r) => {
+        const tags = r.entry.tags ?? [];
+        const matches = tags.filter((t) => goalsByTag.has(t));
+        if (matches.length === 0)
+            return r;
+        const multiplier = goalBoostMultiplier(r.entry, tags, matches, goalsByTag, policiesByGoalId);
+        // Recall-trace side-channel: record the goal-boost step BEFORE the
+        // score is mutated, keyed by entry id; a pure read of r.score.
+        if (trace) {
+            trace.set(r.entry.id, {
+                stage: 'goal-boost',
+                multiplier,
+                scoreBefore: r.score,
+                scoreAfter: r.score * multiplier,
+                note: matches.join(', '),
+            });
+        }
+        matchesByEntryId.set(r.entry.id, matches);
+        // SAFETY: spreading a generic-constrained `r: R` widens to the spread's plain object type; only `score` changes, so the value still satisfies R.
+        return { ...r, score: r.score * multiplier };
+    })
+        // Deliberately a PLAIN stable score sort with no compareEntryIdentity tail: re-sorting an already deterministic ranking inherits its determinism via
+        // stability, and ties keep the prior (meaningful) rank instead of reordering by content.
+        .sort((a, b) => compareScoresDesc(a.score, b.score));
+    return { results: boosted, log: buildGoalRecallLog(boosted, matchesByEntryId, goalsByTag, opts) };
+}
+//# sourceMappingURL=goal-boost.js.map

package/dist/search/hybrid-score.d.ts

@@ -1,7 +1,7 @@
-import type { MemoryEntry } from '../memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 import { type BoostContext } from './boosts.js';
 import type { DenseScores } from './vector.js';
-import type { SearchResult } from './types.js';
+import type { SearchResult } from '../core/search-types.js';
 export interface HybridScoreInput {
     entries: MemoryEntry[];
     queryTerms: string[];

package/dist/search/hybrid-score.js

@@ -1,4 +1,4 @@
-import { estimateTokens } from '../token-ledger.js';
+import { estimateTokens } from '../util/token-text.js';
 import { matchedQueryTerms } from './bm25.js';
 import { applyRankBoosts, strengthRecencyMultipliers } from './boosts.js';
 import { addDagFields, ageInDays } from './breakdown.js';

package/dist/search/hybrid.d.ts

@@ -1,10 +1,10 @@
-import type { MemoryEntry } from '../memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 import type { RerankerFn, RerankerOptions } from '../rerankers/types.js';
 import { type BM25Corpus } from './bm25.js';
 import { type HybridVectorCandidates } from './vector.js';
 import { type GraphStreamOptions } from './fusion.js';
-import { type ResultCost, type SearchResult } from './types.js';
-import type { HippoStore } from '../store-port.js';
+import { type ResultCost, type SearchResult } from '../core/search-types.js';
+import type { HippoStore } from '../store/index.js';
 export interface HybridSearchOptions {
     budget?: number;
     now?: Date;
@@ -37,12 +37,14 @@ export interface HybridSearchOptions {
     summaryDeboost?: number;
     /** 1.05 micro-boost for summaries rebuilt within 7 days. Default true. */
     summaryFreshness?: boolean;
-    /** Graph-proximity third RRF list; active only with `scoring: 'rrf'`, embeddings and a `hippoRoot`. See src/graph-stream.ts. */
+    /** Graph-proximity third RRF list; active only with `scoring: 'rrf'`, embeddings and a `hippoRoot`. See src/graph/stream.ts. */
     graphStream?: GraphStreamOptions;
     /** Add the rows nearest the query vector, not only rescore `entries`; without it a row no query word matches cannot surface. */
     vectorCandidates?: HybridVectorCandidates;
     /** Where vectors are read; hippo.db under `hippoRoot` when unset. */
     store?: HippoStore;
+    /** The deadline a caller already started for this recall's query embedding; a fresh budget when unset. */
+    queryEmbedDeadline?: AbortSignal;
 }
 /** BM25 blended with cosine similarity when stored vectors and a provider are available, BM25 * strength * recency otherwise. */
 export declare function hybridSearch(query: string, entries: MemoryEntry[], options?: HybridSearchOptions): Promise<SearchResult[]>;

package/dist/search/hybrid.js

@@ -1,8 +1,8 @@
-import { tokenize } from '../tokenize.js';
-import { evalNow } from '../ablation.js';
-import { extractPathTags } from '../path-context.js';
-import { detectScope } from '../scope.js';
-import { compareScoredResults } from '../compare.js';
+import { tokenize } from '../util/tokenize.js';
+import { evalNow } from '../core/ablation.js';
+import { extractPathTags } from './path-context.js';
+import { detectScope } from '../sharing/scope.js';
+import { compareScoredResults } from '../core/compare.js';
 import { bm25Score, buildCorpus, entryText } from './bm25.js';
 import { currentEntries } from './as-of.js';
 import { summaryScoring } from './boosts.js';
@@ -12,11 +12,14 @@ import { fuseRanks } from './fusion.js';
 import { scoreHybridPool } from './hybrid-score.js';
 import { applyMmrWindow, applyReranker } from './rerank.js';
 import { dedupeExtracted, fitBudget, withDagChildren } from './finalize.js';
-import { DEFAULT_RECALL_BUDGET } from './types.js';
+import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
+// Share of the blended score that cosine takes, and the relevance side of the MMR relevance-versus-diversity trade.
+const DEFAULT_EMBEDDING_WEIGHT = 0.6;
+const DEFAULT_MMR_LAMBDA = 0.7;
 /** BM25 blended with cosine similarity when stored vectors and a provider are available, BM25 * strength * recency otherwise. */
 export async function hybridSearch(query, entries, options = {}) {
     const now = options.now ?? evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
-    const embeddingWeight = options.embeddingWeight ?? 0.6;
+    const embeddingWeight = options.embeddingWeight ?? DEFAULT_EMBEDDING_WEIGHT;
     const pool = currentEntries(entries, options);
     if (pool.length === 0)
         return [];
@@ -57,7 +60,7 @@ function hybridBoostContext(query, pool, now, options) {
 }
 /** MMR when vectors are loaded, then the optional reranker. */
 async function orderHybrid(query, scored, arm, options) {
-    const mmrLambda = options.mmrLambda ?? 0.7;
+    const mmrLambda = options.mmrLambda ?? DEFAULT_MMR_LAMBDA;
     const applyMmr = (options.mmr ?? true) && arm.useEmbeddings && scored.length > 1 && mmrLambda < 1;
     const ordered = applyMmr ? applyMmrWindow(scored, arm.embeddingIndex, mmrLambda, options.explain ?? false) : scored;
     return options.reranker ? applyReranker(query, ordered, options.reranker, options.rerankerOptions) : ordered;

package/dist/{multihop.d.ts → search/multihop.d.ts}

@@ -1,5 +1,5 @@
-import type { MemoryEntry } from './memory.js';
-import { type ResultCost, type SearchResult } from './search/types.js';
+import type { MemoryEntry } from '../core/memory.js';
+import { type ResultCost, type SearchResult } from '../core/search-types.js';
 export declare function multihopSearch(query: string, entries: MemoryEntry[], options?: {
     budget?: number;
     now?: Date;

package/dist/{multihop.js → search/multihop.js}

@@ -1,12 +1,14 @@
-import { fitBudget } from './search/finalize.js';
-import { search } from './search/bm25-search.js';
-import { DEFAULT_RECALL_BUDGET } from './search/types.js';
+import { compareScoresDesc } from '../core/compare.js';
+import { fitBudget } from './finalize.js';
+import { search } from './bm25-search.js';
+import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
+const PASS1_TOP_K = 10;
 export function multihopSearch(query, entries, options = {}) {
     const budget = options.budget ?? DEFAULT_RECALL_BUDGET;
     // Pass 1 searches wide to find entities, so each return fits the caller's budget, as search() does.
     const fit = (ordered) => fitBudget(ordered, budget, options.minResults ?? 1, options.cost);
     const pass1 = search(query, entries, { ...options, budget: budget * 2 });
-    const topK = pass1.slice(0, 10);
+    const topK = pass1.slice(0, PASS1_TOP_K);
     if (topK.length === 0)
         return [];
     const entityTags = new Set();
@@ -32,9 +34,8 @@ export function multihopSearch(query, entries, options = {}) {
             merged.set(r.entry.id, r);
         }
     }
-    // PLAIN stable score sort on purpose -- pass1/pass2 inputs are
-    // deterministically ordered (search() carries the content tail), stability
-    // inherits that, and ties keep pass-1 results ahead of pass-2 follow-ups.
-    return fit([...merged.values()].sort((a, b) => b.score - a.score));
+    // PLAIN stable score sort on purpose: pass1/pass2 inputs are already deterministically ordered (search() carries the content tail),
+    // stability inherits that, and ties keep pass-1 results ahead of pass-2 follow-ups.
+    return fit([...merged.values()].sort((a, b) => compareScoresDesc(a.score, b.score)));
 }
 //# sourceMappingURL=multihop.js.map

package/dist/search/path-context.d.ts

@@ -0,0 +1,11 @@
+/** Extracts meaningful path segments from a directory as tags like ['path:src', 'path:my-project']; filters noise (node_modules, .git, Users, home dirs,
+ * drive letters). */
+export declare function extractPathTags(dirPath: string): string[];
+/** Path overlap score in 0..1 (1 = perfect match), normalized by the MORE SPECIFIC side (the larger tag set),
+ * so a bare/generic path tag cannot score 1.0 against a deeply nested cwd just because its tiny tag set is contained in the query's. */
+export declare function pathOverlapScore(memoryPathTags: string[], currentPathTags: string[]): number;
+/** Weight applied to path overlap score when computing the recall boost multiplier. */
+export declare const PATH_BOOST_WEIGHT = 0.3;
+/** Multiplier (1.0..1.3) applied to a composite recall score for path locality; filters the memory's tags to path:* itself so call sites cannot drift. */
+export declare function pathBoostMultiplier(memoryTags: string[], currentPathTags: string[]): number;
+//# sourceMappingURL=path-context.d.ts.map

package/dist/{path-context.js → search/path-context.js}

@@ -1,8 +1,7 @@
-/**
- * Extract meaningful path segments from a directory path.
- * Returns tags like ['path:src', 'path:api', 'path:my-project'].
- * Filters out noise (node_modules, .git, Users, home dirs, drive letters).
- */
+// Keeps the last meaningful segments, the most specific ones.
+const PATH_SEGMENTS_KEPT = 4;
+/** Extracts meaningful path segments from a directory as tags like ['path:src', 'path:my-project']; filters noise (node_modules, .git, Users, home dirs,
+ * drive letters). */
 export function extractPathTags(dirPath) {
     const normalized = dirPath.replace(/\\/g, '/');
     const segments = normalized.split('/').filter(Boolean);
@@ -14,17 +13,11 @@ export function extractPathTags(dirPath) {
     ]);
     return segments
         .filter(s => s.length >= 2 && !noise.has(s.toLowerCase()))
-        .slice(-4) // keep last 4 meaningful segments (most specific)
+        .slice(-PATH_SEGMENTS_KEPT)
         .map(s => `path:${s.toLowerCase()}`);
 }
-/**
- * Compute path overlap score between two sets of path tags.
- * Returns 0..1 where 1 = perfect match.
- * Normalizes by the MORE SPECIFIC side (the larger of the two tag sets),
- * so a memory carrying only a bare/generic path tag can no longer score a
- * full 1.0 against a deeply-nested cwd just because its own tiny tag set
- * is fully contained in the query's — genericity is no longer rewarded.
- */
+/** Path overlap score in 0..1 (1 = perfect match), normalized by the MORE SPECIFIC side (the larger tag set),
+ * so a bare/generic path tag cannot score 1.0 against a deeply nested cwd just because its tiny tag set is contained in the query's. */
 export function pathOverlapScore(memoryPathTags, currentPathTags) {
     if (memoryPathTags.length === 0 || currentPathTags.length === 0)
         return 0;
@@ -36,11 +29,7 @@ export function pathOverlapScore(memoryPathTags, currentPathTags) {
 }
 /** Weight applied to path overlap score when computing the recall boost multiplier. */
 export const PATH_BOOST_WEIGHT = 0.3;
-/**
- * Multiplier applied to a composite recall score for path locality.
- * Filters the memory's tags to path:* itself so call sites cannot drift.
- * Returns 1.0..1.3.
- */
+/** Multiplier (1.0..1.3) applied to a composite recall score for path locality; filters the memory's tags to path:* itself so call sites cannot drift. */
 export function pathBoostMultiplier(memoryTags, currentPathTags) {
     const memPathTags = memoryTags.filter(t => t.startsWith('path:'));
     return 1.0 + pathOverlapScore(memPathTags, currentPathTags) * PATH_BOOST_WEIGHT;

package/dist/search/physics-search.d.ts

@@ -1,8 +1,8 @@
-import { type MemoryEntry } from '../memory.js';
-import { type PhysicsConfig } from '../physics-config.js';
-import { type HippoStore } from '../store-port.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { type PhysicsConfig } from '../core/physics-config.js';
+import { type HippoStore } from '../store/index.js';
 import { type HybridVectorCandidates } from './vector.js';
-import { type ResultCost, type SearchResult } from './types.js';
+import { type ResultCost, type SearchResult } from '../core/search-types.js';
 export interface PhysicsSearchOptions {
     budget?: number;
     now?: Date;

package/dist/search/physics-search.js

@@ -1,21 +1,22 @@
-import { calculateStrength } from '../memory.js';
-import { estimateTokens } from '../token-ledger.js';
-import { evalNow, isRecallBoostAblated } from '../ablation.js';
-import { indexedModel, indexNeedsRebuild } from '../embeddings.js';
-import { resolveEmbeddingProvider } from '../embedding-provider.js';
-import { physicsScore as computePhysicsScores, computeMass } from '../physics.js';
-import { DEFAULT_PHYSICS_CONFIG } from '../physics-config.js';
-import { rethrowIfSqliteBlocked } from '../db.js';
-import { compareScoredResults } from '../compare.js';
-import { log } from '../log.js';
-import { sqliteStore } from '../store-port.js';
+import { calculateStrength } from '../core/memory.js';
+import { estimateTokens } from '../util/token-text.js';
+import { evalNow, isRecallBoostAblated } from '../core/ablation.js';
+import { indexNeedsRebuild } from '../store/embeddings/index.js';
+import { indexedModel } from '../store/vector-index.js';
+import { resolveEmbeddingProvider } from '../store/embeddings/provider.js';
+import { physicsScore as computePhysicsScores, computeMass } from '../core/physics.js';
+import { DEFAULT_PHYSICS_CONFIG } from '../core/physics-config.js';
+import { rethrowIfSqliteBlocked } from '../db/index.js';
+import { compareScoredResults } from '../core/compare.js';
+import { errorMessage, log } from '../util/log.js';
+import { sqliteStore } from '../store/index.js';
 import { churnStaleFactor, summaryMultipliers, summaryScoring } from './boosts.js';
 import { addDagFields, ageInDays } from './breakdown.js';
 import { fitBudget } from './finalize.js';
 import { hybridSearch } from './hybrid.js';
 import { currentEntries } from './as-of.js';
-import { requireVectorReads, vectorCandidatesOutside } from './vector.js';
-import { DEFAULT_RECALL_BUDGET } from './types.js';
+import { embedQueryBy, requireVectorReads, startQueryEmbedDeadline, vectorCandidatesOutside } from './vector.js';
+import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
 /** Scores memories by gravity, momentum and cluster amplification; rows without physics state rank through hybridSearch. */
 export async function physicsSearch(query, entries, options = {}) {
     const now = options.now ?? evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
@@ -28,27 +29,29 @@ export async function physicsSearch(query, entries, options = {}) {
         return hybridSearch(query, entries, options);
     const root = options.hippoRoot;
     const store = options.store ?? sqliteStore(root);
-    const queryVector = await physicsQueryVector(query, root, store, options.queryEmbedding);
+    // Shared with every hybrid ranking below, so a provider that stalls here is not waited on a second time.
+    const queryEmbedDeadline = startQueryEmbedDeadline();
+    const queryVector = await physicsQueryVector(query, root, store, queryEmbedDeadline, options.queryEmbedding);
     if (!queryVector)
-        return hybridSearch(query, entries, options);
+        return hybridSearch(query, entries, { ...options, queryEmbedDeadline });
     // Checked here too, since a caller's own query vector skips the check inside physicsQueryVector.
     const reads = requireVectorReads(store);
     const pool = currentEntries(await withVectorCandidates(reads, entries, queryVector, options.vectorCandidates), options);
     const physicsMap = await loadCandidateParticles(reads, pool);
     if (!physicsMap)
-        return hybridSearch(query, pool, options);
+        return hybridSearch(query, pool, { ...options, queryEmbedDeadline });
     const pools = splitByParticle(pool, physicsMap, queryVector, now);
     const config = options.physicsConfig ?? DEFAULT_PHYSICS_CONFIG;
     const physicsResults = scorePhysicsPool(pools, queryVector, config, scoring);
     const classicResults = pools.classic.length > 0
-        ? await hybridSearch(query, pools.classic, { ...options, vectorCandidates: undefined, budget: Infinity, explain })
+        ? await hybridSearch(query, pools.classic, { ...options, queryEmbedDeadline, vectorCandidates: undefined, budget: Infinity, explain })
         : [];
     const merged = mergeScorePools(physicsResults, classicResults);
     merged.sort(compareScoredResults);
     return fitBudget(merged, options.budget ?? DEFAULT_RECALL_BUDGET, options.minResults ?? 1, options.cost);
 }
 /** The caller's vector, else the provider's; null sends the caller to hybridSearch. */
-async function physicsQueryVector(query, root, store, given) {
+async function physicsQueryVector(query, root, store, deadline, given) {
     if (given && given.length > 0)
         return given;
     // Physics scores against particle positions, not the stored vector index, so a pruned index must not block it.
@@ -58,12 +61,12 @@ async function physicsQueryVector(query, root, store, given) {
             return null;
         if (indexNeedsRebuild(indexedModel(await requireVectorReads(store).embeddingIndexState()), provider.id))
             return null;
-        const [vec] = await provider.embed([query], 'query');
+        const vec = await embedQueryBy(deadline, provider, query);
         return vec && vec.length > 0 ? vec : null;
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);
-        log.debug(`physics search: query embed failed, using hybrid: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`physics search: query embed failed, using hybrid: ${errorMessage(err)}`);
         return null;
     }
 }
@@ -75,7 +78,7 @@ async function withVectorCandidates(reads, entries, queryVector, spec) {
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);
-        log.warn(`physics search ranked the lexical pool only; the vector lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+        log.warn(`physics search ranked the lexical pool only; the vector lookup failed: ${errorMessage(err)}`);
         return entries;
     }
 }
@@ -86,7 +89,7 @@ async function loadCandidateParticles(reads, pool) {
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);
-        log.debug(`physics search: state load failed, using hybrid: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`physics search: state load failed, using hybrid: ${errorMessage(err)}`);
         return null;
     }
 }

package/dist/search/rerank.d.ts

@@ -1,10 +1,10 @@
 import type { RerankerFn, RerankerOptions } from '../rerankers/types.js';
-import type { SearchResult } from './types.js';
+import type { SearchResult } from '../core/search-types.js';
 /** MMR: repeatedly picks the candidate maximising lambda * relevance - (1 - lambda) * max(cos(cand, picked)).
  *  Input must be sorted by relevance; strict `>` keeps ties first-wins, so a deterministic input stays deterministic. */
-export declare function mmrRerank(scored: SearchResult[], embeddingIndex: Record<string, number[]>, lambda: number, explain: boolean): SearchResult[];
+export declare function mmrRerank(scored: SearchResult[], embeddingIndex: Record<string, ArrayLike<number>>, lambda: number, explain: boolean): SearchResult[];
 /** MMR over the top window only; the tail keeps its relevance order. */
-export declare function applyMmrWindow(scored: SearchResult[], embeddingIndex: Record<string, number[]>, lambda: number, explain: boolean): SearchResult[];
+export declare function applyMmrWindow(scored: SearchResult[], embeddingIndex: Record<string, ArrayLike<number>>, lambda: number, explain: boolean): SearchResult[];
 /** Runs the reranker over the top `topK` (default 50) and stamps pre and post ranks; see src/rerankers/types.ts. */
 export declare function applyReranker(query: string, ordered: SearchResult[], reranker: RerankerFn, rerankerOptions?: RerankerOptions): Promise<SearchResult[]>;
 //# sourceMappingURL=rerank.d.ts.map