hippo-memory 1.59.0 → 1.61.0

package/dist/search/boosts.js

@@ -0,0 +1,94 @@
+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 { temporalBoost } from './temporal.js';
+export const CHURN_STALE_RANK_MULTIPLIER = 0.5; // SHORTCUT: untuned; measure on real recall before any default.
+const DEFAULT_SUMMARY_DEBOOST = 0.85;
+const DEFAULT_FRESHNESS_BOOST = 1.05;
+const FRESHNESS_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+export function churnStaleFactor(entry) {
+    return entry.tags.includes(CHURN_STALE_TAG) ? CHURN_STALE_RANK_MULTIPLIER : 1.0;
+}
+export 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));
+}
+/** Retrieval-time outcome nudge in [0.85, 1.15]; the bm25-outcome eval baseline ranks with it too. */
+export function outcomeMultiplier(entry) {
+    const pos = entry.outcome_positive ?? 0;
+    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)));
+}
+/** A DAG summary is a topic summary (level 2) or an entity profile (level 3); both take the same deboost. */
+export function isDagSummary(entry) {
+    return entry.dag_level === 2 || entry.dag_level === 3;
+}
+/** Summary deboost: per-call, then HIPPO_SUMMARY_DEBOOST, then 0.85; values outside (0, 1] fall through. */
+export function resolveSummaryDeboost(perCall) {
+    if (perCall !== undefined && Number.isFinite(perCall) && perCall > 0 && perCall <= 1) {
+        return perCall;
+    }
+    const raw = envSummaryDeboost();
+    if (raw !== undefined) {
+        const parsed = parseFloat(raw);
+        if (Number.isFinite(parsed) && parsed > 0 && parsed <= 1) {
+            return parsed;
+        }
+    }
+    return DEFAULT_SUMMARY_DEBOOST;
+}
+/** 1.05 for a summary rebuilt within the window; null, unparseable and future timestamps get 1.0. */
+function summaryFreshnessMultiplier(entry, now) {
+    if (!isDagSummary(entry) || !entry.last_rebuilt_at)
+        return 1.0;
+    const rebuiltMs = new Date(entry.last_rebuilt_at).getTime();
+    if (!Number.isFinite(rebuiltMs))
+        return 1.0;
+    const ageMs = now.getTime() - rebuiltMs;
+    return ageMs >= 0 && ageMs <= FRESHNESS_WINDOW_MS ? DEFAULT_FRESHNESS_BOOST : 1.0;
+}
+/** The sync BM25 path applies no summary scoring; multiplying by exactly 1 keeps its scores bit-identical. */
+export const NO_SUMMARY_SCORING = { deboost: 1, freshness: false };
+export function summaryScoring(options) {
+    return { deboost: resolveSummaryDeboost(options.summaryDeboost), freshness: options.summaryFreshness ?? true };
+}
+export function summaryMultipliers(entry, now, s) {
+    if (!isDagSummary(entry))
+        return { deboost: 1.0, freshness: 1.0 };
+    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) };
+}
+/** Applies every rank multiplier one at a time, in a fixed order, so float rounding matches across paths. */
+export function applyRankBoosts(score, entry, ctx) {
+    const decisionBoost = entry.tags.includes('decision') ? 1.2 : 1.0;
+    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 summary = summaryMultipliers(entry, ctx.now, ctx.summary);
+    let s = score;
+    s *= decisionBoost;
+    s *= churnStaleMultiplier;
+    s *= pathBoost;
+    s *= outcomeBoost;
+    s *= scopeBoost;
+    s *= extractionBoost;
+    s *= temporalBoost(entry, ctx.temporal.direction, ctx.temporal.range);
+    s *= summary.deboost * summary.freshness;
+    return {
+        score: s, decisionBoost, churnStaleMultiplier, pathBoost, outcomeBoost, scopeBoost,
+        summaryDeboost: summary.deboost, summaryFreshnessBoost: summary.freshness,
+    };
+}
+//# sourceMappingURL=boosts.js.map

package/dist/search/breakdown.d.ts

@@ -0,0 +1,7 @@
+import type { MemoryEntry } from '../memory.js';
+import type { ScoreBreakdown } from './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. */
+export declare function addDagFields(breakdown: ScoreBreakdown, entry: MemoryEntry, deboost: number, freshness: number): ScoreBreakdown;
+//# sourceMappingURL=breakdown.d.ts.map

package/dist/search/breakdown.js

@@ -0,0 +1,20 @@
+import { isDagSummary } from './boosts.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));
+}
+/** Copies the entry's DAG metadata, and for summaries the multipliers applied, onto an explain breakdown. */
+export function addDagFields(breakdown, entry, deboost, freshness) {
+    if (entry.dag_level !== undefined)
+        breakdown.dagLevel = entry.dag_level;
+    if (entry.descendant_count !== undefined)
+        breakdown.descendantCount = entry.descendant_count;
+    if (isDagSummary(entry)) {
+        breakdown.lastRebuiltAt = entry.last_rebuilt_at ?? null;
+        breakdown.rebuildCount = entry.rebuild_count ?? 0;
+        breakdown.summaryDeboost = deboost;
+        breakdown.summaryFreshnessBoost = freshness;
+    }
+    return breakdown;
+}
+//# sourceMappingURL=breakdown.js.map

package/dist/search/explain.d.ts

@@ -0,0 +1,25 @@
+import type { SearchResult } from './types.js';
+export interface MatchExplanation {
+    /** Human-readable reason string */
+    reason: string;
+    /** Which query terms matched in the document (BM25 component) */
+    matchedTerms: string[];
+    /** Whether BM25 contributed to the score */
+    hasBm25: boolean;
+    /** Whether embedding similarity contributed to the score */
+    hasEmbedding: boolean;
+    /** Raw cosine similarity (0 when embeddings not used) */
+    cosineSimilarity: number;
+    /** Provenance envelope (kind, scope, owner, artifact_ref, session_id, confidence) */
+    envelope?: {
+        kind: string;
+        scope: string | null;
+        owner: string | null;
+        artifact_ref: string | null;
+        session_id: string | null;
+        confidence: string;
+    };
+}
+/** Why a result matched: the overlapping query terms and whether BM25 and/or embedding similarity contributed. */
+export declare function explainMatch(query: string, result: SearchResult): MatchExplanation;
+//# sourceMappingURL=explain.d.ts.map

package/dist/search/explain.js

@@ -0,0 +1,31 @@
+import { tokenize } from '../tokenize.js';
+import { matchedQueryTerms } from './bm25.js';
+/** 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);
+    const hasBm25 = result.bm25 > 0;
+    const hasEmbedding = result.cosine > 0;
+    const parts = [];
+    if (hasBm25)
+        parts.push(`BM25: matched terms [${matchedTerms.join(', ')}]`);
+    if (hasEmbedding)
+        parts.push(`embedding similarity: ${result.cosine.toFixed(3)}`);
+    if (parts.length === 0)
+        parts.push('no direct term or embedding match');
+    return {
+        reason: parts.join('; '),
+        matchedTerms,
+        hasBm25,
+        hasEmbedding,
+        cosineSimilarity: result.cosine,
+        envelope: {
+            kind: result.entry.kind ?? 'distilled',
+            scope: result.entry.scope ?? null,
+            owner: result.entry.owner ?? null,
+            artifact_ref: result.entry.artifact_ref ?? null,
+            session_id: result.entry.source_session_id ?? null,
+            confidence: result.entry.confidence ?? 'observed',
+        },
+    };
+}
+//# sourceMappingURL=explain.js.map

package/dist/search/finalize.d.ts

@@ -0,0 +1,8 @@
+import type { MemoryEntry } from '../memory.js';
+import type { ResultCost, SearchResult } from './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. */
+export declare function withDagChildren(results: SearchResult[], pool: MemoryEntry[]): SearchResult[];
+export declare function fitBudget<T extends SearchResult>(ordered: T[], budget: number, minResults: number, cost?: ResultCost): T[];
+//# sourceMappingURL=finalize.d.ts.map

package/dist/search/finalize.js

@@ -0,0 +1,52 @@
+import { estimateTokens } from '../token-ledger.js';
+import { compareScoredResults } from '../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) {
+    const seenExtractedFrom = new Set();
+    const deduped = [];
+    for (const result of scored) {
+        const entry = result.entry;
+        if (entry.extracted_from) {
+            seenExtractedFrom.add(entry.extracted_from);
+            const sourceIdx = deduped.findIndex((d) => d.entry.id === entry.extracted_from);
+            if (sourceIdx >= 0)
+                deduped.splice(sourceIdx, 1);
+            deduped.push(result);
+        }
+        else if (!seenExtractedFrom.has(entry.id)) {
+            deduped.push(result);
+        }
+    }
+    return deduped;
+}
+/** 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);
+    if (summaryIds.length === 0)
+        return results;
+    const children = pool.filter((e) => e.dag_parent_id && summaryIds.includes(e.dag_parent_id));
+    for (const child of children) {
+        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;
+        results.push({ entry: child, score: childScore, bm25: 0, cosine: 0, tokens: estimateTokens(child.content) });
+    }
+    results.sort(compareScoredResults);
+    return results;
+}
+// Skip-and-continue, with the first minResults kept whatever they cost; one loop so every engine spends alike.
+export function fitBudget(ordered, budget, minResults, cost) {
+    const results = [];
+    let used = 0;
+    for (const r of ordered) {
+        const tokens = cost ? cost(r) : r.tokens;
+        if (results.length >= minResults && used + tokens > budget)
+            continue;
+        used += tokens;
+        results.push(r);
+    }
+    return results;
+}
+//# sourceMappingURL=finalize.js.map

package/dist/search/fusion.d.ts

@@ -0,0 +1,27 @@
+import type { MemoryEntry } from '../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 {
+    /** RRF weight for the graph list. Required (opt-in is explicit; no implicit default). */
+    weight: number;
+    tenantId: string;
+    /** Global store root, when distinct (where global seeds' graph lives). */
+    globalRoot?: string;
+    hops?: number;
+    decay?: number;
+    maxNeighbors?: number;
+    /** # of top lexical seeds to expand from. Default DEFAULT_GRAPH_SEED_COUNT. */
+    seedCount?: number;
+}
+export interface FusionInput {
+    entries: MemoryEntry[];
+    bm25Scores: number[];
+    dense: DenseScores;
+    bm25Weight: number;
+    embeddingWeight: number;
+    hippoRoot?: string;
+    graphStream?: GraphStreamOptions;
+}
+/** Reciprocal rank fusion of the BM25 and dense rankings, plus the graph list when it ranks anything. */
+export declare function fuseRanks(input: FusionInput): Map<number, number>;
+//# sourceMappingURL=fusion.d.ts.map

package/dist/search/fusion.js

@@ -0,0 +1,42 @@
+import { rrfFuse } from '../rrf.js';
+import { graphRankStream, selectGraphSeeds, DEFAULT_GRAPH_SEED_COUNT } from '../graph-stream.js';
+import { compareEntryIdentity } from '../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) => {
+        const d = scores[b] - scores[a];
+        return d !== 0 ? d : compareEntryIdentity(entries[a], entries[b]);
+    });
+}
+/** Reciprocal rank fusion of the BM25 and dense rankings, plus the graph list when it ranks anything. */
+export function fuseRanks(input) {
+    const { entries, bm25Scores, dense } = input;
+    const eligible = entries.map((_, i) => i).filter((i) => bm25Scores[i] > 0 || dense.cosine[i] > 0);
+    const bm25Ranked = rankBy(eligible, bm25Scores, entries);
+    const cosineRanked = rankBy(eligible, dense.cosine, entries);
+    const graphRanked = graphRanking(input, eligible.length, bm25Ranked, cosineRanked);
+    // absentRank stays entries.length + 1 rather than rrfFuse's longest-list default.
+    const opts = { absentRank: entries.length + 1 };
+    // An all-absent third list would add a constant the later multipliers make non-uniform, so an empty one is skipped.
+    return graphRanked.length > 0
+        ? rrfFuse([bm25Ranked, cosineRanked, graphRanked], [input.bm25Weight, input.embeddingWeight, input.graphStream?.weight ?? 0], opts)
+        : rrfFuse([bm25Ranked, cosineRanked], [input.bm25Weight, input.embeddingWeight], opts);
+}
+function graphRanking(input, eligibleCount, bm25Ranked, cosineRanked) {
+    const gs = input.graphStream;
+    // Without doc vectors the dense ranking is just entry order, so seeds drawn from it would mean nothing.
+    const hasDocVectors = input.dense.hadVec.some(Boolean);
+    if (!gs || gs.weight <= 0 || !input.hippoRoot || !hasDocVectors)
+        return [];
+    const seedCount = Math.min(gs.seedCount ?? DEFAULT_GRAPH_SEED_COUNT, eligibleCount);
+    const seeds = selectGraphSeeds(bm25Ranked, cosineRanked, seedCount);
+    return graphRankStream(input.entries, seeds, {
+        hippoRoot: input.hippoRoot,
+        tenantId: gs.tenantId,
+        globalRoot: gs.globalRoot,
+        hops: gs.hops,
+        decay: gs.decay,
+        maxNeighbors: gs.maxNeighbors,
+    });
+}
+//# sourceMappingURL=fusion.js.map

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

@@ -0,0 +1,20 @@
+import type { MemoryEntry } from '../memory.js';
+import { type BoostContext } from './boosts.js';
+import type { DenseScores } from './vector.js';
+import type { SearchResult } from './types.js';
+export interface HybridScoreInput {
+    entries: MemoryEntry[];
+    queryTerms: string[];
+    bm25Scores: number[];
+    maxBm25: number;
+    dense: DenseScores;
+    useEmbeddings: boolean;
+    rrfScores: Map<number, number> | null;
+    bm25Weight: number;
+    embeddingWeight: number;
+    explain: boolean;
+    boosts: BoostContext;
+}
+/** Scores every pool entry; rows with no lexical hit drop out unless vectors are in play, and non-positive scores always do. */
+export declare function scoreHybridPool(input: HybridScoreInput): SearchResult[];
+//# sourceMappingURL=hybrid-score.d.ts.map

package/dist/search/hybrid-score.js

@@ -0,0 +1,73 @@
+import { estimateTokens } from '../token-ledger.js';
+import { matchedQueryTerms } from './bm25.js';
+import { applyRankBoosts, strengthRecencyMultipliers } from './boosts.js';
+import { addDagFields, ageInDays } from './breakdown.js';
+/** Scores every pool entry; rows with no lexical hit drop out unless vectors are in play, and non-positive scores always do. */
+export function scoreHybridPool(input) {
+    const scored = [];
+    const queryTermSet = new Set(input.queryTerms);
+    for (let i = 0; i < input.entries.length; i++) {
+        if (!input.useEmbeddings && input.bm25Scores[i] <= 0)
+            continue;
+        const s = scoreEntry(i, input);
+        if (s.boosts.score <= 0)
+            continue;
+        const entry = input.entries[i];
+        const result = {
+            entry,
+            score: s.boosts.score,
+            bm25: input.bm25Scores[i],
+            cosine: input.dense.cosine[i],
+            tokens: estimateTokens(entry.content),
+        };
+        if (input.explain)
+            result.breakdown = hybridBreakdown(i, s, input, queryTermSet);
+        scored.push(result);
+    }
+    return scored;
+}
+function scoreEntry(i, input) {
+    const entry = input.entries[i];
+    const rawBm25 = input.bm25Scores[i];
+    const normBm25 = rawBm25 / input.maxBm25;
+    const { strength, recency } = strengthRecencyMultipliers(entry, input.boosts.now);
+    let base;
+    let mode;
+    if (input.useEmbeddings) {
+        base = input.rrfScores
+            ? input.rrfScores.get(i) ?? 0
+            : input.bm25Weight * normBm25 + input.embeddingWeight * input.dense.cosine[i];
+        mode = input.dense.hadVec[i] ? 'hybrid' : 'hybrid-no-vec';
+    }
+    else {
+        base = input.queryTerms.length > 0 ? rawBm25 / input.queryTerms.length : rawBm25;
+        mode = 'bm25-only';
+    }
+    const boosts = applyRankBoosts(base * strength * recency, entry, input.boosts);
+    return { base, mode, normBm25, strength, recency, boosts };
+}
+function hybridBreakdown(i, s, input, queryTermSet) {
+    const entry = input.entries[i];
+    const b = s.boosts;
+    const breakdown = {
+        mode: s.mode,
+        normBm25: s.normBm25,
+        bm25Weight: input.useEmbeddings ? input.bm25Weight : 1,
+        embeddingWeight: input.useEmbeddings ? input.embeddingWeight : 0,
+        cosine: input.dense.cosine[i],
+        base: s.base,
+        strengthMultiplier: s.strength,
+        recencyMultiplier: s.recency,
+        decisionBoost: b.decisionBoost,
+        pathBoost: b.pathBoost,
+        scopeBoost: b.scopeBoost,
+        sourceBump: 1,
+        outcomeBoost: b.outcomeBoost,
+        churnStaleMultiplier: b.churnStaleMultiplier,
+        matchedTerms: matchedQueryTerms(queryTermSet, entry),
+        final: b.score,
+        ageDays: ageInDays(entry, input.boosts.now),
+    };
+    return addDagFields(breakdown, entry, b.summaryDeboost, b.summaryFreshnessBoost);
+}
+//# sourceMappingURL=hybrid-score.js.map

package/dist/search/hybrid.d.ts

@@ -0,0 +1,46 @@
+import type { MemoryEntry } from '../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, SearchResult } from './types.js';
+export interface HybridSearchOptions {
+    budget?: number;
+    now?: Date;
+    hippoRoot?: string;
+    embeddingWeight?: number;
+    explain?: boolean;
+    /** Disable MMR re-ranking even when embeddings are available. */
+    mmr?: boolean;
+    /** MMR balance: 1.0 = pure relevance, 0.0 = pure diversity. Default 0.7. */
+    mmrLambda?: number;
+    /** 'blend' (weighted sum of BM25 and cosine, default) or 'rrf' (reciprocal rank fusion of their ranks). */
+    scoring?: 'blend' | 'rrf';
+    /** Corpus from `buildCorpus` over the same `entries` in the same order (content + tags), reused to skip tokenizing. */
+    preparedCorpus?: BM25Corpus;
+    /** Minimum number of results to return regardless of budget. Default 1. */
+    minResults?: number;
+    /** Budget cost per result; the caller that prints passes the cost of its printed text. */
+    cost?: ResultCost;
+    /** Active scope for scope-boost scoring. Auto-detected if not provided. */
+    scope?: string | null;
+    /** Include superseded memories in results. Default false. */
+    includeSuperseded?: boolean;
+    /** Filter to memories current at this ISO date string. */
+    asOf?: string;
+    /** Optional reranker. Runs after MMR, before budget filtering. See src/rerankers/types.ts. */
+    reranker?: RerankerFn;
+    /** Options passed through to the reranker. */
+    rerankerOptions?: RerankerOptions;
+    /** Multiplier on DAG summary scores. Default 0.85 (env HIPPO_SUMMARY_DEBOOST overrides; per-call wins). 1.0 disables. */
+    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. */
+    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;
+}
+/** 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[]>;
+//# sourceMappingURL=hybrid.d.ts.map

package/dist/search/hybrid.js

@@ -0,0 +1,64 @@
+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 { bm25Score, buildCorpus, entryText } from './bm25.js';
+import { currentEntries } from './as-of.js';
+import { summaryScoring } from './boosts.js';
+import { temporalContext } from './temporal.js';
+import { denseScores, resolveVectorArm } from './vector.js';
+import { fuseRanks } from './fusion.js';
+import { scoreHybridPool } from './hybrid-score.js';
+import { applyMmrWindow, applyReranker } from './rerank.js';
+import { dedupeExtracted, fitBudget, withDagChildren } from './finalize.js';
+/** 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 pool = currentEntries(entries, options);
+    if (pool.length === 0)
+        return [];
+    const queryTerms = tokenize(query);
+    if (queryTerms.length === 0)
+        return [];
+    const arm = await resolveVectorArm(query, pool, options);
+    // A prepared corpus covers the caller's entries only, so rows the vector arm added force a rebuild.
+    const corpus = (arm.addedRows ? undefined : options.preparedCorpus) ?? buildCorpus(arm.entries.map(entryText));
+    const bm25Scores = arm.entries.map((_, i) => bm25Score(corpus, i, queryTerms));
+    const dense = denseScores(arm);
+    const fusion = { entries: arm.entries, bm25Scores, dense, bm25Weight: 1 - embeddingWeight, embeddingWeight };
+    const rrfScores = arm.useEmbeddings && options.scoring === 'rrf'
+        ? fuseRanks({ ...fusion, hippoRoot: options.hippoRoot, graphStream: options.graphStream })
+        : null;
+    const scored = scoreHybridPool({
+        ...fusion,
+        queryTerms,
+        maxBm25: bm25Scores.reduce((a, b) => Math.max(a, b), 1e-9),
+        useEmbeddings: arm.useEmbeddings,
+        rrfScores,
+        explain: options.explain ?? false,
+        boosts: hybridBoostContext(query, arm.entries, now, options),
+    });
+    scored.sort(compareScoredResults);
+    const ordered = await orderHybrid(query, withDagChildren(dedupeExtracted(scored), arm.entries), arm, options);
+    return fitBudget(ordered, options.budget ?? 4000, options.minResults ?? 1, options.cost);
+}
+function hybridBoostContext(query, pool, now, options) {
+    return {
+        now,
+        pathTags: extractPathTags(process.cwd()),
+        scope: options.scope !== undefined ? options.scope : detectScope(),
+        temporal: temporalContext(query, pool),
+        outcome: true,
+        summary: summaryScoring(options),
+    };
+}
+/** MMR when vectors are loaded, then the optional reranker. */
+async function orderHybrid(query, scored, arm, options) {
+    const mmrLambda = options.mmrLambda ?? 0.7;
+    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;
+}
+//# sourceMappingURL=hybrid.js.map

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

@@ -0,0 +1,29 @@
+import { type MemoryEntry } from '../memory.js';
+import { type PhysicsConfig } from '../physics-config.js';
+import { type HybridVectorCandidates } from './vector.js';
+import type { ResultCost, SearchResult } from './types.js';
+export interface PhysicsSearchOptions {
+    budget?: number;
+    now?: Date;
+    hippoRoot?: string;
+    physicsConfig?: PhysicsConfig;
+    queryEmbedding?: number[];
+    explain?: boolean;
+    minResults?: number;
+    cost?: ResultCost;
+    /** Active scope for scope-boost scoring. Auto-detected if not provided. */
+    scope?: string | null;
+    /** Include superseded memories; must reach the inner hybrid filter or `recall --include-superseded` rows drop out here. */
+    includeSuperseded?: boolean;
+    /** Bi-temporal filter: memories current at this ISO date string, ranked by hybridSearch. */
+    asOf?: string;
+    /** Same summary deboost as hybridSearch, which also inherits it on every fallback. */
+    summaryDeboost?: number;
+    /** Same freshness boost as hybridSearch. */
+    summaryFreshness?: boolean;
+    /** Same as hybridSearch's: rows nearest the query join the pool before physics scoring. */
+    vectorCandidates?: HybridVectorCandidates;
+}
+/** Scores memories by gravity, momentum and cluster amplification; rows without physics state rank through hybridSearch. */
+export declare function physicsSearch(query: string, entries: MemoryEntry[], options?: PhysicsSearchOptions): Promise<SearchResult[]>;
+//# sourceMappingURL=physics-search.d.ts.map