hippo-memory 0.27.0 → 0.29.0

package/dist/refine-llm.d.ts

@@ -0,0 +1,53 @@
+/**
+ * LLM-powered refinement of consolidated semantic memories.
+ *
+ * The rule-based `mergeContents` in consolidate.ts produces functional but
+ * ugly semantic memories — typically "[Consolidated from N related memories]"
+ * prepended to the longest source, or a bulleted list. `hippo refine` takes
+ * those and asks Claude to synthesize a clean, generalized principle.
+ *
+ * Design choices:
+ * - Separate command (not baked into `hippo sleep`) so API-key users opt in.
+ * - Idempotent via the `llm-refined` tag — re-running skips already-refined.
+ * - Uses fetch directly so no SDK dependency.
+ * - On failure (API error, bad response), the original memory is untouched.
+ */
+import { MemoryEntry } from './memory.js';
+export interface RefineOptions {
+    apiKey: string;
+    model?: string;
+    limit?: number;
+    dryRun?: boolean;
+    /** Ignore the llm-refined tag and re-refine everything eligible. */
+    all?: boolean;
+    /** Injected for testing — defaults to the real fetch. */
+    fetcher?: typeof fetch;
+}
+export interface RefineResult {
+    scanned: number;
+    refined: number;
+    skipped: number;
+    failed: number;
+    details: Array<{
+        id: string;
+        status: 'refined' | 'skipped' | 'failed';
+        reason?: string;
+    }>;
+}
+/**
+ * Ask Claude to synthesize a clean semantic memory from the merged content
+ * plus the original source memories. Returns the refined content string or
+ * `null` when the API call failed.
+ */
+export declare function refineSemanticMemory(merged: string, sources: MemoryEntry[], opts: {
+    apiKey: string;
+    model?: string;
+    fetcher?: typeof fetch;
+}): Promise<string | null>;
+/**
+ * Scan the store for consolidated semantic memories, refine each with the
+ * LLM, and write the refined content back. Tags with `llm-refined` so
+ * repeated runs are idempotent (unless `all` is set).
+ */
+export declare function refineStore(hippoRoot: string, opts: RefineOptions): Promise<RefineResult>;
+//# sourceMappingURL=refine-llm.d.ts.map

package/dist/refine-llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine-llm.d.ts","sourceRoot":"","sources":["../src/refine-llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAS,MAAM,aAAa,CAAC;AASjD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3F;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EAAE,EACtB,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;CAAE,GAC/D,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqDxB;AAOD;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,YAAY,CAAC,CA+DvB"}

package/dist/refine-llm.js

@@ -0,0 +1,147 @@
+/**
+ * LLM-powered refinement of consolidated semantic memories.
+ *
+ * The rule-based `mergeContents` in consolidate.ts produces functional but
+ * ugly semantic memories — typically "[Consolidated from N related memories]"
+ * prepended to the longest source, or a bulleted list. `hippo refine` takes
+ * those and asks Claude to synthesize a clean, generalized principle.
+ *
+ * Design choices:
+ * - Separate command (not baked into `hippo sleep`) so API-key users opt in.
+ * - Idempotent via the `llm-refined` tag — re-running skips already-refined.
+ * - Uses fetch directly so no SDK dependency.
+ * - On failure (API error, bad response), the original memory is untouched.
+ */
+import { Layer } from './memory.js';
+import { loadAllEntries, readEntry, writeEntry } from './store.js';
+const REFINED_TAG = 'llm-refined';
+const CONSOLIDATED_MARKERS = [
+    '[Consolidated from',
+    '[Consolidated pattern from',
+];
+/**
+ * Ask Claude to synthesize a clean semantic memory from the merged content
+ * plus the original source memories. Returns the refined content string or
+ * `null` when the API call failed.
+ */
+export async function refineSemanticMemory(merged, sources, opts) {
+    const model = opts.model ?? 'claude-sonnet-4-6';
+    const fetchFn = opts.fetcher ?? fetch;
+    const sourceBlock = sources
+        .slice(0, 8)
+        .map((s, i) => `[source ${i + 1}] ${s.content.slice(0, 400)}`)
+        .join('\n\n');
+    const prompt = `You are refining a semantic memory in an agent's memory store. The rule-based consolidator merged several related episodic memories into one, but the output is clumsy. Produce a single coherent semantic memory that captures the underlying principle.
+
+Rules:
+- Output ONLY the refined content — no preamble, no quote marks, no "Here is...".
+- Keep it concise: one paragraph, no headers, no bullet lists unless the sources are inherently a list.
+- Preserve specific facts (names, numbers, paths, IDs) from the sources.
+- Generalize: state the pattern, not each instance.
+- Do NOT include the "[Consolidated from N ...]" marker.
+
+Current merged content:
+${merged}
+
+Source memories (up to 8 shown):
+${sourceBlock}`;
+    let res;
+    try {
+        res = await fetchFn('https://api.anthropic.com/v1/messages', {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-api-key': opts.apiKey,
+                'anthropic-version': '2023-06-01',
+            },
+            body: JSON.stringify({
+                model,
+                max_tokens: 800,
+                messages: [{ role: 'user', content: prompt }],
+            }),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!res.ok)
+        return null;
+    try {
+        const data = await res.json();
+        const text = data.content?.[0]?.text?.trim() ?? '';
+        if (text.length < 10)
+            return null;
+        return text;
+    }
+    catch {
+        return null;
+    }
+}
+function isConsolidated(entry) {
+    if (entry.layer !== Layer.Semantic)
+        return false;
+    return CONSOLIDATED_MARKERS.some((m) => entry.content.startsWith(m));
+}
+/**
+ * Scan the store for consolidated semantic memories, refine each with the
+ * LLM, and write the refined content back. Tags with `llm-refined` so
+ * repeated runs are idempotent (unless `all` is set).
+ */
+export async function refineStore(hippoRoot, opts) {
+    const result = {
+        scanned: 0,
+        refined: 0,
+        skipped: 0,
+        failed: 0,
+        details: [],
+    };
+    const entries = loadAllEntries(hippoRoot);
+    let processed = 0;
+    for (const entry of entries) {
+        if (!isConsolidated(entry))
+            continue;
+        result.scanned++;
+        if (!opts.all && entry.tags.includes(REFINED_TAG)) {
+            result.skipped++;
+            result.details.push({ id: entry.id, status: 'skipped', reason: 'already refined' });
+            continue;
+        }
+        if (opts.limit !== undefined && processed >= opts.limit)
+            break;
+        processed++;
+        // Best-effort: walk parents_json (schema v9) to fetch originals. When
+        // parents aren't recorded we still refine using just the merged content.
+        const sources = [];
+        const parentIds = Array.isArray(entry.parents) ? entry.parents : [];
+        for (const pid of parentIds) {
+            const p = readEntry(hippoRoot, pid);
+            if (p)
+                sources.push(p);
+        }
+        const refined = await refineSemanticMemory(entry.content, sources, {
+            apiKey: opts.apiKey,
+            model: opts.model,
+            fetcher: opts.fetcher,
+        });
+        if (refined === null) {
+            result.failed++;
+            result.details.push({ id: entry.id, status: 'failed', reason: 'api error or empty response' });
+            continue;
+        }
+        if (opts.dryRun) {
+            result.refined++;
+            result.details.push({ id: entry.id, status: 'refined', reason: 'dry-run (no write)' });
+            continue;
+        }
+        const updated = {
+            ...entry,
+            content: refined,
+            tags: entry.tags.includes(REFINED_TAG) ? entry.tags : [...entry.tags, REFINED_TAG],
+        };
+        writeEntry(hippoRoot, updated);
+        result.refined++;
+        result.details.push({ id: entry.id, status: 'refined' });
+    }
+    return result;
+}
+//# sourceMappingURL=refine-llm.js.map

package/dist/refine-llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine-llm.js","sourceRoot":"","sources":["../src/refine-llm.ts"],"names":[],"mappings":"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"}

package/dist/replay.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Replay — biologically-inspired rehearsal during consolidation.
+ *
+ * Hippocampal replay is internally-driven reactivation of memories during
+ * slow-wave sleep: the brain picks important recent experiences and "plays
+ * them back" without external input, strengthening them before they decay.
+ * In McClelland's complementary-learning-systems framing, replay is also
+ * how episodic memories train the neocortex (interleaved rehearsal); in
+ * reward-modulated STDP, replay is gated by dopamine so rewarded
+ * experiences get preferentially consolidated.
+ *
+ * This module implements a lightweight, deterministic analog. During each
+ * `hippo sleep`, we sample N surviving memories by a priority score that
+ * weighs reward feedback, emotional valence, under-rehearsal, and age —
+ * then apply the same retrieval-strengthening dynamics `markRetrieved`
+ * applies to real queries. The effect is that important memories stay
+ * strong even when the user hasn't explicitly queried them recently.
+ *
+ * Distinct from the other consolidation passes:
+ *   - decay: removes what's too weak
+ *   - physics: moves particles in embedding space
+ *   - merge: collapses near-duplicate episodics into semantics
+ *   - REPLAY: picks winners and rehearses them (this file)
+ */
+import type { MemoryEntry } from './memory.js';
+/**
+ * Priority score used to rank survivors for replay. Higher = more likely
+ * to be sampled. Pure function of the entry and current time.
+ */
+export declare function replayPriority(entry: MemoryEntry, now: Date): number;
+/**
+ * Pick `count` memories for replay, weighted by `replayPriority`, without
+ * replacement. Deterministic given the same seed.
+ *
+ * The sampler is weighted but not greedy — picking by priority alone would
+ * always pick the top-N, which overfits. Biological replay shows both
+ * preferential-for-reward AND stochastic-exploration characteristics; we
+ * keep the stochastic element so adjacent survivors aren't always ignored.
+ */
+export declare function sampleForReplay(survivors: MemoryEntry[], count: number, now: Date, seed?: number): MemoryEntry[];
+//# sourceMappingURL=replay.d.ts.map

package/dist/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAoB,MAAM,aAAa,CAAC;AASjE;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,CAyBpE;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,WAAW,EAAE,EACxB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,IAAI,EACT,IAAI,GAAE,MAAyB,GAC9B,WAAW,EAAE,CAoCf"}

package/dist/replay.js

@@ -0,0 +1,117 @@
+/**
+ * Replay — biologically-inspired rehearsal during consolidation.
+ *
+ * Hippocampal replay is internally-driven reactivation of memories during
+ * slow-wave sleep: the brain picks important recent experiences and "plays
+ * them back" without external input, strengthening them before they decay.
+ * In McClelland's complementary-learning-systems framing, replay is also
+ * how episodic memories train the neocortex (interleaved rehearsal); in
+ * reward-modulated STDP, replay is gated by dopamine so rewarded
+ * experiences get preferentially consolidated.
+ *
+ * This module implements a lightweight, deterministic analog. During each
+ * `hippo sleep`, we sample N surviving memories by a priority score that
+ * weighs reward feedback, emotional valence, under-rehearsal, and age —
+ * then apply the same retrieval-strengthening dynamics `markRetrieved`
+ * applies to real queries. The effect is that important memories stay
+ * strong even when the user hasn't explicitly queried them recently.
+ *
+ * Distinct from the other consolidation passes:
+ *   - decay: removes what's too weak
+ *   - physics: moves particles in embedding space
+ *   - merge: collapses near-duplicate episodics into semantics
+ *   - REPLAY: picks winners and rehearses them (this file)
+ */
+const VALENCE_WEIGHT = {
+    neutral: 1.0,
+    positive: 1.3,
+    negative: 1.5,
+    critical: 2.0,
+};
+/**
+ * Priority score used to rank survivors for replay. Higher = more likely
+ * to be sampled. Pure function of the entry and current time.
+ */
+export function replayPriority(entry, now) {
+    const pos = entry.outcome_positive ?? 0;
+    const neg = entry.outcome_negative ?? 0;
+    // Reward signal: neutral memories get 1, strongly-rewarded memories > 1,
+    // negative-dominated memories floor at 0.1 (so they're still eligible, just
+    // much less likely to be sampled than neutral peers). Clamp is required
+    // because sampleForReplay depends on all weights being positive.
+    const rewardSignal = Math.max(0.1, 1 + pos * 0.5 + (pos - neg) * 0.25);
+    const valence = VALENCE_WEIGHT[entry.emotional_valence] ?? 1.0;
+    // Under-rehearsed memories benefit most from replay.
+    const underRehearsed = 1 / (1 + (entry.retrieval_count ?? 0));
+    // Idle-time boost: memories that haven't been touched recently need rehearsal more.
+    const lastRetrieved = new Date(entry.last_retrieved);
+    const deltaMs = now.getTime() - lastRetrieved.getTime();
+    const ageHours = Number.isFinite(deltaMs) ? Math.max(0, deltaMs / 3_600_000) : 0;
+    const idleBoost = 1 + Math.log1p(ageHours) * 0.1;
+    // Weight by current strength so dead-and-decaying memories don't waste replay slots.
+    const rawStrength = Number.isFinite(entry.strength) ? entry.strength : 0;
+    const strengthFloor = Math.max(0.1, rawStrength);
+    return rewardSignal * valence * underRehearsed * idleBoost * strengthFloor;
+}
+/**
+ * Deterministic 32-bit RNG (Mulberry32). Same seed → same sequence.
+ * Keeps replay reproducible for tests and audit runs without bringing
+ * in a random-number dependency.
+ */
+function mulberry32(seed) {
+    let s = seed >>> 0;
+    return () => {
+        let t = (s += 0x6D2B79F5);
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Pick `count` memories for replay, weighted by `replayPriority`, without
+ * replacement. Deterministic given the same seed.
+ *
+ * The sampler is weighted but not greedy — picking by priority alone would
+ * always pick the top-N, which overfits. Biological replay shows both
+ * preferential-for-reward AND stochastic-exploration characteristics; we
+ * keep the stochastic element so adjacent survivors aren't always ignored.
+ */
+export function sampleForReplay(survivors, count, now, seed = Date.now() >>> 0) {
+    if (count <= 0 || survivors.length === 0)
+        return [];
+    const rng = mulberry32(seed);
+    // Stale memories have been deliberately marked as untrusted; rehearsing
+    // them would defeat the purpose of staleness. Skip them entirely.
+    const eligible = survivors.filter((e) => e.confidence !== 'stale');
+    if (eligible.length === 0)
+        return [];
+    const pool = eligible.map((entry, idx) => ({
+        entry,
+        idx,
+        weight: replayPriority(entry, now),
+    }));
+    const want = Math.min(count, pool.length);
+    const chosen = [];
+    const taken = new Set();
+    for (let k = 0; k < want; k++) {
+        let totalW = 0;
+        for (const p of pool)
+            if (!taken.has(p.idx))
+                totalW += p.weight;
+        if (totalW <= 0)
+            break;
+        let r = rng() * totalW;
+        for (const p of pool) {
+            if (taken.has(p.idx))
+                continue;
+            r -= p.weight;
+            if (r <= 0) {
+                chosen.push(p.entry);
+                taken.add(p.idx);
+                break;
+            }
+        }
+    }
+    return chosen;
+}
+//# sourceMappingURL=replay.js.map

package/dist/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"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"}

package/dist/search.d.ts

@@ -5,6 +5,18 @@
 import { MemoryEntry } from './memory.js';
 import type { PhysicsConfig } from './physics-config.js';
 export declare function tokenize(text: string): string[];
+/**
+ * Tokenized BM25 corpus. Callers can pre-build this with `buildCorpus` once
+ * and reuse across many `hybridSearch` calls on the same entry set — the
+ * tokenization work is the bulk of per-query cost on large stores.
+ */
+export interface BM25Corpus {
+    docs: string[][];
+    avgLen: number;
+    df: Map<string, number>;
+    N: number;
+}
+export declare function buildCorpus(texts: string[]): BM25Corpus;
 /**
  * Rough token estimate: characters / 4 (works well for English text).
  */
@@ -81,6 +93,18 @@ export declare function hybridSearch(query: string, entries: MemoryEntry[], opti
     mmr?: boolean;
     /** MMR balance: 1.0 = pure relevance, 0.0 = pure diversity. Default 0.7. */
     mmrLambda?: number;
+    /** Scoring mode: 'blend' (weighted sum of BM25+cosine, default) or
+     *  'rrf' (reciprocal rank fusion - combines BM25 and cosine ranks
+     *  instead of scores, more robust for long documents). */
+    scoring?: 'blend' | 'rrf';
+    /** Pre-built BM25 corpus from `buildCorpus`. Pass this across many
+     *  queries on the same entry set to skip ~O(N*docLen) tokenization
+     *  work per call. Must be built from the same `entries` in the same
+     *  order (content + tags.join(' ')). */
+    preparedCorpus?: BM25Corpus;
+    /** Minimum number of results to return regardless of budget.
+     *  Prevents budget saturation when memories are large. Default 1. */
+    minResults?: number;
 }): Promise<SearchResult[]>;
 /**
  * MMR (Maximal Marginal Relevance) re-ranking.
@@ -105,6 +129,7 @@ export declare function physicsSearch(query: string, entries: MemoryEntry[], opt
     physicsConfig?: PhysicsConfig;
     queryEmbedding?: number[];
     explain?: boolean;
+    minResults?: number;
 }): Promise<SearchResult[]>;
 /**
  * Search entries using BM25 + strength + recency composite score.
@@ -118,6 +143,7 @@ export declare function search(query: string, entries: MemoryEntry[], options?:
     budget?: number;
     now?: Date;
     hippoRoot?: string;
+    minResults?: number;
 }): SearchResult[];
 /**
  * Update retrieval metadata on entries that were returned by a search.

package/dist/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAqB,MAAM,aAAa,CAAC;AAY7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AASzD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAM/C;AAMD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxB,CAAC,EAAE,MAAM,CAAC;CACX;AAKD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,UAAU,CAmBvD;AA6BD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAiBD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,IAAI,EAAE,QAAQ,GAAG,eAAe,GAAG,WAAW,GAAG,SAAS,CAAC;IAC3D,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB;gEAC4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB;;kEAE8D;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;8DAE0D;IAC1D,OAAO,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAC1B;;;4CAGwC;IACxC,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B;yEACqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CAChB,GACL,OAAO,CAAC,YAAY,EAAE,CAAC,CAmNzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,YAAY,EAAE,EACtB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EACxC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,GACf,YAAY,EAAE,CAgDhB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CAChB,GACL,OAAO,CAAC,YAAY,EAAE,CAAC,CA2HzB;AAiBD;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACrF,YAAY,EAAE,CA4DhB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,GAAG,GAAE,IAAiB,GAAG,WAAW,EAAE,CAc3F;AAMD,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,YAAY,EAAE,OAAO,CAAC;IACtB,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,gBAAgB,CAgClF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAaxD"}

package/dist/search.js

@@ -21,7 +21,7 @@ export function tokenize(text) {
 }
 const BM25_K1 = 1.5;
 const BM25_B = 0.75;
-function buildCorpus(texts) {
+export function buildCorpus(texts) {
     const docs = texts.map(tokenize);
     const N = docs.length;
     const df = new Map();
@@ -87,8 +87,10 @@ function recencyBoost(entry, now) {
 export async function hybridSearch(query, entries, options = {}) {
     const now = options.now ?? new Date();
     const budget = options.budget ?? 4000;
+    const minResults = options.minResults ?? 1;
     const embeddingWeight = options.embeddingWeight ?? 0.6;
     const bm25Weight = 1 - embeddingWeight;
+    const scoringMode = options.scoring ?? 'blend';
     const explain = options.explain ?? false;
     const mmrEnabled = options.mmr ?? true;
     const mmrLambda = options.mmrLambda ?? 0.7;
@@ -97,9 +99,9 @@ export async function hybridSearch(query, entries, options = {}) {
     const queryTerms = tokenize(query);
     if (queryTerms.length === 0)
         return [];
-    // Build BM25 corpus
-    const texts = entries.map((e) => `${e.content} ${e.tags.join(' ')}`);
-    const corpus = buildCorpus(texts);
+    // Build BM25 corpus (or reuse one the caller already built).
+    const corpus = options.preparedCorpus
+        ?? buildCorpus(entries.map((e) => `${e.content} ${e.tags.join(' ')}`));
     // Score all entries with BM25
     const bm25Scores = entries.map((_, i) => bm25Score(corpus, i, queryTerms));
     const maxBm25 = bm25Scores.reduce((a, b) => Math.max(a, b), 1e-9);
@@ -122,12 +124,46 @@ export async function hybridSearch(query, entries, options = {}) {
             // Fall through to BM25-only
         }
     }
+    // Compute cosine similarities for RRF ranking (need all before scoring)
+    const cosineScores = new Array(entries.length).fill(0);
+    const hadCachedVecs = new Array(entries.length).fill(false);
+    if (useEmbeddings) {
+        for (let i = 0; i < entries.length; i++) {
+            const cached = embeddingIndex[entries[i].id];
+            hadCachedVecs[i] = Boolean(cached && queryVector.length > 0);
+            cosineScores[i] = hadCachedVecs[i]
+                ? Math.max(0, cosineSimilarity(queryVector, cached))
+                : 0;
+        }
+    }
+    // For RRF: build rank maps from BM25 and cosine orderings
+    let rrfScores = null;
+    if (useEmbeddings && scoringMode === 'rrf') {
+        const RRF_K = 60;
+        const bm25Ranked = entries.map((_, i) => i).filter(i => bm25Scores[i] > 0 || cosineScores[i] > 0);
+        bm25Ranked.sort((a, b) => bm25Scores[b] - bm25Scores[a]);
+        const cosineRanked = entries.map((_, i) => i).filter(i => bm25Scores[i] > 0 || cosineScores[i] > 0);
+        cosineRanked.sort((a, b) => cosineScores[b] - cosineScores[a]);
+        const bm25RankMap = new Map();
+        bm25Ranked.forEach((idx, rank) => bm25RankMap.set(idx, rank + 1));
+        const cosineRankMap = new Map();
+        cosineRanked.forEach((idx, rank) => cosineRankMap.set(idx, rank + 1));
+        rrfScores = new Map();
+        const allCandidates = new Set([...bm25Ranked, ...cosineRanked]);
+        for (const idx of allCandidates) {
+            const bm25Rank = bm25RankMap.get(idx) ?? (entries.length + 1);
+            const cosineRank = cosineRankMap.get(idx) ?? (entries.length + 1);
+            rrfScores.set(idx, bm25Weight / (RRF_K + bm25Rank) + embeddingWeight / (RRF_K + cosineRank));
+        }
+    }
     // Score each entry
     const scored = [];
     const currentPathTags = extractPathTags(process.cwd());
     const queryTermSet = new Set(queryTerms);
     for (let i = 0; i < entries.length; i++) {
         const rawBm25 = bm25Scores[i];
+        const cosineScore = cosineScores[i];
+        const hadCachedVec = hadCachedVecs[i];
         if (!useEmbeddings && rawBm25 <= 0)
             continue;
         const normBm25 = rawBm25 / maxBm25;
@@ -136,25 +172,19 @@ export async function hybridSearch(query, entries, options = {}) {
         const strengthMultiplier = 0.5 + 0.5 * strength;
         const recencyMultiplier = 0.8 + 0.2 * recency;
         let compositeScore;
-        let cosineScore = 0;
         let base;
         let modeLabel;
-        let hadCachedVec = false;
         if (useEmbeddings) {
-            const cached = embeddingIndex[entries[i].id];
-            hadCachedVec = Boolean(cached && queryVector.length > 0);
-            cosineScore = hadCachedVec
-                ? Math.max(0, cosineSimilarity(queryVector, cached))
-                : 0;
-            base = bm25Weight * normBm25 + embeddingWeight * cosineScore;
+            if (rrfScores) {
+                base = rrfScores.get(i) ?? 0;
+            }
+            else {
+                base = bm25Weight * normBm25 + embeddingWeight * cosineScore;
+            }
             compositeScore = base * strengthMultiplier * recencyMultiplier;
-            // Distinguish "real hybrid" from "query embedded but doc has no cached
-            // vector" so explain can tell users their index is stale without lying
-            // that the search actually used embeddings.
             modeLabel = hadCachedVec ? 'hybrid' : 'hybrid-no-vec';
         }
         else {
-            // Pure BM25 path: identical to original behavior
             base = queryTerms.length > 0 ? rawBm25 / queryTerms.length : rawBm25;
             compositeScore = base * strengthMultiplier * recencyMultiplier;
             modeLabel = 'bm25-only';
@@ -218,17 +248,29 @@ export async function hybridSearch(query, entries, options = {}) {
     // diversity. Only applies when embeddings are loaded (doc-to-doc similarity
     // is via cosine of cached vectors); otherwise we return the pure-relevance
     // ordering unchanged.
+    //
+    // MMR is O(K^2) in cosine similarity ops, which on large corpora (1000+
+    // candidates) dominates query time. Cap the re-ranking window to the top
+    // relevance-scored candidates — anything below top-K was never going to
+    // surface anyway after budget filtering.
+    const MMR_CANDIDATE_CAP = 100;
     const applyMmr = mmrEnabled && useEmbeddings && scored.length > 1 && mmrLambda < 1;
-    const ordered = applyMmr
-        ? mmrRerank(scored, embeddingIndex, mmrLambda, explain)
-        : scored;
-    // Apply token budget
+    let ordered;
+    if (applyMmr) {
+        const head = scored.slice(0, MMR_CANDIDATE_CAP);
+        const tail = scored.slice(MMR_CANDIDATE_CAP);
+        ordered = [...mmrRerank(head, embeddingIndex, mmrLambda, explain), ...tail];
+    }
+    else {
+        ordered = scored;
+    }
+    // Apply token budget (guarantee at least minResults items)
     const results = [];
     let usedTokens = 0;
     for (let i = 0; i < ordered.length; i++) {
         const tokens = ordered[i].tokens;
-        if (i > 0 && usedTokens + tokens > budget)
-            continue; // always include first result
+        if (results.length >= minResults && usedTokens + tokens > budget)
+            continue;
         usedTokens += tokens;
         results.push(ordered[i]);
     }
@@ -300,6 +342,7 @@ export function mmrRerank(scored, embeddingIndex, lambda, explain) {
 export async function physicsSearch(query, entries, options = {}) {
     const now = options.now ?? new Date();
     const budget = options.budget ?? 4000;
+    const minResults = options.minResults ?? 1;
     const config = options.physicsConfig ?? DEFAULT_PHYSICS_CONFIG;
     const explain = options.explain ?? false;
     if (entries.length === 0 || !options.hippoRoot)
@@ -403,8 +446,8 @@ export async function physicsSearch(query, entries, options = {}) {
     let usedTokens = 0;
     for (let i = 0; i < merged.length; i++) {
         const tokens = merged[i].tokens;
-        if (i > 0 && usedTokens + tokens > budget)
-            continue; // always include first result
+        if (results.length >= minResults && usedTokens + tokens > budget)
+            continue;
         usedTokens += tokens;
         results.push(merged[i]);
     }
@@ -435,6 +478,7 @@ export function search(query, entries, options = {}) {
     // Synchronous path: BM25 only (no async hybrid)
     const now = options.now ?? new Date();
     const budget = options.budget ?? 4000;
+    const minResults = options.minResults ?? 1;
     if (entries.length === 0)
         return [];
     const queryTerms = tokenize(query);
@@ -474,8 +518,8 @@ export function search(query, entries, options = {}) {
     let usedTokens = 0;
     for (let i = 0; i < scored.length; i++) {
         const tokens = scored[i].tokens;
-        if (i > 0 && usedTokens + tokens > budget)
-            continue; // always include first result
+        if (results.length >= minResults && usedTokens + tokens > budget)
+            continue;
         usedTokens += tokens;
         results.push(scored[i]);
     }