hippo-memory 2.0.0 → 2.1.0

package/dist/rerankers/remote.js

@@ -2,9 +2,12 @@
 import { fetchWithRetry } from '../util/http-retry.js';
 // A Retry-After longer than this would outlast most budgets, so the answer is handed back and the reranker falls back.
 const RETRY_WAIT_CAP_MS = 2_000;
-// Every reranker reads its reply through this cap; the largest honest reply is a few KB, and 1 MiB leaves room for a verbose envelope.
+// Every reranker reads its reply through this cap; the largest honest reply is a few KB, and 1 MiB leaves room for a
+// verbose envelope.
 export const RERANKER_MAX_REPLY_BYTES = 1024 * 1024;
-/** POST a scoring request. A dropped connection, 429 or 5xx is retried, since scoring changes nothing on the far side. */
+/**
+ * POST a scoring request. A dropped connection, 429 or 5xx is retried, since scoring changes nothing on the far side.
+ */
 export async function rerankerPost(url, init, budgetMs) {
     // The budget bounds the whole call, retries included, so recall never waits past the configured timeout.
     const budget = AbortSignal.timeout(budgetMs);

package/dist/rerankers/types.d.ts

@@ -1,6 +1,10 @@
 import type { SearchResult } from '../core/search-types.js';
-/** Reorders hybridSearch's candidates AFTER MMR de-duplication and BEFORE token-budget filtering, so it sees the full diverse pool.
- * MUST be deterministic for a given (query, results) unless documented stochastic (LLM track, hosted jev): paired A/B and the validity gate need it. */
+/**
+ * Reorders hybridSearch's candidates AFTER MMR de-duplication and BEFORE token-budget filtering, so it sees the full
+ * diverse pool.
+ * MUST be deterministic for a given (query, results) unless documented stochastic (LLM track, hosted jev): paired A/B
+ * and the validity gate need it.
+ */
 export type RerankerFn = (query: string, results: SearchResult[], options?: RerankerOptions) => Promise<RerankResult[]>;
 /** JSON-serializable value. Per-track reranker config is opaque to the seam
  *  but must still be a concrete, serializable shape rather than `unknown`. */

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

@@ -9,6 +9,8 @@ export interface SearchOptions {
     includeSuperseded?: boolean;
     asOf?: string;
 }
-/** Synchronous BM25 search: relevance * strength * recency and the rank boosts, without embeddings or the outcome nudge. */
+/**
+ * Synchronous BM25 search: relevance * strength * recency and the rank boosts, without embeddings or the outcome nudge.
+ */
 export declare function search(query: string, entries: MemoryEntry[], options?: SearchOptions): SearchResult[];
 //# sourceMappingURL=bm25-search.d.ts.map

package/dist/search/bm25-search.js

@@ -10,7 +10,20 @@ import { applyRankBoosts, strengthRecencyMultipliers, NO_SUMMARY_SCORING } from
 import { temporalContext } from './temporal.js';
 import { dedupeExtracted, fitBudget, withDagChildren } from './finalize.js';
 import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
-/** Synchronous BM25 search: relevance * strength * recency and the rank boosts, without embeddings or the outcome nudge. */
+// Keyed on the caller's array so multihop's two passes share one build;
+// the pool identity check keeps a mutated array honest.
+const corpusCache = new WeakMap();
+function corpusFor(entries, pool) {
+    const hit = corpusCache.get(entries);
+    if (hit && hit.pool.length === pool.length && hit.pool.every((e, i) => e === pool[i]))
+        return hit.corpus;
+    const corpus = buildCorpus(pool.map(entryText));
+    corpusCache.set(entries, { pool: pool.slice(), corpus });
+    return corpus;
+}
+/**
+ * Synchronous BM25 search: relevance * strength * recency and the rank boosts, without embeddings or the outcome nudge.
+ */
 export function search(query, entries, options = {}) {
     const now = options.now ?? evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
     const pool = currentEntries(entries, options);
@@ -19,7 +32,7 @@ export function search(query, entries, options = {}) {
     const queryTerms = tokenize(query);
     if (queryTerms.length === 0)
         return [];
-    const corpus = buildCorpus(pool.map(entryText));
+    const corpus = corpusFor(entries, pool);
     const ctx = {
         now,
         pathTags: extractPathTags(process.cwd()),

package/dist/search/boosts.js

@@ -1,5 +1,5 @@
 import { envSummaryDeboost } from '../util/env.js';
-import { calculateStrength, CHURN_STALE_TAG } from '../core/memory.js';
+import { calculateStrength, CHURN_STALE_TAG, DAG_LEVEL } from '../core/memory.js';
 import { isOutcomeFastAblated, isRecencyAblated, evalRecencyScaleDays } from '../core/ablation.js';
 import { pathBoostMultiplier } from './path-context.js';
 import { scopeMatch } from '../core/active-scope.js';
@@ -15,7 +15,8 @@ const EXTRACTION_TAG_BOOST = 1.3;
 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.
+// 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;
@@ -44,7 +45,7 @@ export function outcomeMultiplier(entry) {
 }
 /** 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;
+    return entry.dag_level === DAG_LEVEL.topic || entry.dag_level === DAG_LEVEL.entity;
 }
 /** Summary deboost: per-call, then HIPPO_SUMMARY_DEBOOST, then 0.85; values outside (0, 1] fall through. */
 export function resolveSummaryDeboost(perCall) {

package/dist/search/embed-memories.d.ts

@@ -1,12 +1,17 @@
 import type { MemoryEntry } from '../core/memory.js';
 import { type EmbeddingProvider } from '../embeddings/provider.js';
 import { type HippoStore } from '../store/port.js';
-/** `off` is a provider that is disabled or not installed, which is a choice; `failed` is a memory that stays out of the vector index. */
+/** `off` is a provider that is disabled or not installed, which is a choice; `failed` is a memory that stays out of
+ * the vector index. */
 export type EmbedOutcome = 'indexed' | 'off' | 'failed';
-/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db.
- *  Resolves whatever fails, so a caller that fires and forgets stays safe; the outcome says whether the memory reached the index. */
+/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites,
+ * never opening hippo.db.
+ * Resolves whatever fails, so a caller that fires and forgets stays safe; the outcome says whether the memory
+ * reached the index. */
 export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model?: string, store?: HippoStore): Promise<EmbedOutcome>;
-/** Embeds every entry with no cached vector, prunes vectors of deleted memories, and returns how many it embedded; `provider` defaults to the
- *  configured one. With `store`, every tenant's memories with no vector for the provider's model go through its `vectorWrites`, never hippo.db. */
+/** Embeds every entry with no cached vector, prunes vectors of deleted memories, and returns how many it embedded;
+ * `provider` defaults to the
+ * configured one. With `store`, every tenant's memories with no vector for the provider's model go through its
+ * `vectorWrites`, never hippo.db. */
 export declare function embedAll(hippoRoot: string, model?: string, provider?: EmbeddingProvider, store?: HippoStore): Promise<number>;
 //# sourceMappingURL=embed-memories.d.ts.map

package/dist/search/embed-memories.js

@@ -7,13 +7,14 @@ import { loadConfig } from '../core/config.js';
 import { initializeParticle } from '../core/physics.js';
 import { resolveEmbeddingProvider } from '../embeddings/provider.js';
 import { embeddingIndexIdentity, embeddingInputText, embeddingModelRequiresReindex, indexNeedsRebuild, saveStoredEmbeddingModel, } from '../store/embeddings/index.js';
-import { loadAllEntryIds, loadEntriesByIds } from '../store/entry-reads.js';
+import { countAllEntries, loadAllEntryIds, loadEntriesByIds } from '../store/entry-reads.js';
 import { requireGroup, } from '../store/port.js';
-import { indexedModel, pruneStoredVectors, replacesIndex, resetStoredParticles, saveEmbeddingIndex, saveStoredVectors, seedStoredParticle, } from '../store/vector-index.js';
+import { indexedModel, pruneStoredVectorsListPending, replacesIndex, resetStoredParticles, saveEmbeddingIndex, saveStoredVectors, seedStoredParticle, } from '../store/vector-index.js';
 import { chunked } from '../util/chunked.js';
 import { envByName } from '../util/env.js';
-import { errorCode, errorMessage, log } from '../util/log.js';
+import { errorCode, errorMessage, log, errorFields } from '../util/log.js';
 import { redactSecretsStrict } from '../util/secret-detect.js';
+import { MINUTE_MS } from '../util/time.js';
 const STORE_PAGE = 64;
 /** The rows for `ids`, a page at a time and in that order; an id deleted since it was listed is skipped. */
 function* entryPages(hippoRoot, ids) {
@@ -48,7 +49,7 @@ function resetPhysicsFromIndex(hippoRoot, ids, index) {
     }
     catch (err) {
         // Best effort: retrieval still falls back without physics state.
-        log.warn(`physics reset after reindex failed: ${errorMessage(err)}`);
+        log.warn(`physics reset after reindex failed: ${errorMessage(err)}`, errorFields(err));
     }
 }
 /** A provider's `[]` row is a swallowed per-item failure; name the memory so the gap can be traced. */
@@ -112,7 +113,8 @@ async function acquireEmbedFileLock(hippoRoot) {
             if (!(err instanceof Error && 'code' in err && err.code === 'EEXIST'))
                 throw err;
         }
-        // SHORTCUT: two waiters can both break one dead holder's lock; a vector lost that way is backfilled by the next `hippo embed`.
+        // SHORTCUT: two waiters can both break one dead holder's lock; a vector lost that way is backfilled by the next
+        // `hippo embed`.
         if (!embedLockHolderAlive(lockPath)) {
             fs.rmSync(lockPath, { force: true });
             continue;
@@ -133,7 +135,8 @@ async function withEmbedLock(hippoRoot, fn) {
         }
     });
 }
-// A store keeps each write whole in its own transaction, and a lock file in hippoRoot would not reach a worker on another host.
+// A store keeps each write whole in its own transaction, and a
+// lock file in hippoRoot would not reach a worker on another host.
 async function withProcessEmbedLock(fn) {
     let resolve;
     const next = new Promise(r => { resolve = r; });
@@ -147,9 +150,10 @@ async function withProcessEmbedLock(fn) {
         resolve();
     }
 }
-// A bad key fails every write; one full warning per distinct failure tells the user, and a count of the repeats follows at most once per interval.
+// A bad key fails every write; one full warning per distinct failure tells the user, and a count of the repeats follows
+// at most once per interval.
 const EMBED_WARN_KEY_CAP = 64;
-const EMBED_SUPPRESSED_SUMMARY_INTERVAL_MS = 60_000;
+const EMBED_SUPPRESSED_SUMMARY_INTERVAL_MS = MINUTE_MS;
 const embedFailureSeen = new Map();
 function embedFailureKey(source, cause) {
     const kind = errorCode(cause) || (cause instanceof Error ? cause.constructor.name : 'NonError');
@@ -162,7 +166,8 @@ function warnEmbedFailureOnce(source, rawMessage, cause) {
     if (seen) {
         seen.suppressed += 1;
         if (now - seen.lastNoticeAt >= EMBED_SUPPRESSED_SUMMARY_INTERVAL_MS) {
-            log.warn(`${seen.suppressed} more embedding errors from ${source} since the last notice; memories are still stored without embeddings.`);
+            log.warn(`${seen.suppressed} more embedding errors from ${source} since ` +
+                `the last notice; memories are still stored without embeddings.`);
             seen.suppressed = 0;
             seen.lastNoticeAt = now;
         }
@@ -183,14 +188,17 @@ function warnEmbedFailureOnce(source, rawMessage, cause) {
 function vectorGroups(store) {
     return [requireGroup(store, 'vectors'), requireGroup(store, 'vectorWrites')];
 }
-/** Writes one page's vectors, one writeVectors per tenant, and stops at the first refused write; `withParticles` seeds each memory's particle. */
+/** Writes one page's vectors, one writeVectors per tenant, and stops at the first refused write; `withParticles`
+ * seeds each memory's particle. */
 async function writeVectorPage(writes, write, page, vectors, withParticles) {
     const byTenant = new Map();
     page.forEach((entry, i) => {
         const vector = vectors[i];
         if (!vector || vector.length === 0)
             return noteSkippedEmbedding(entry.id);
-        const row = withParticles ? { memoryId: entry.id, vector, particle: initializeParticle(entry, vector) } : { memoryId: entry.id, vector };
+        const row = withParticles
+            ? { memoryId: entry.id, vector, particle: initializeParticle(entry, vector) }
+            : { memoryId: entry.id, vector };
         byTenant.set(entry.tenant_id, [...(byTenant.get(entry.tenant_id) ?? []), row]);
     });
     let written = 0;
@@ -203,7 +211,8 @@ async function writeVectorPage(writes, write, page, vectors, withParticles) {
     return { written, modelMismatch: false };
 }
 const OTHER_MODEL_INDEX = "the vector index was built by another embedding model; run 'hippo embed' to rebuild it";
-/** Embeds every memory with no vector under `model`, page by page, so a provider failure keeps the pages written; a rebuild reseeds the particles it drops. */
+/** Embeds every memory with no vector under `model`, page by page, so a provider failure keeps the pages written; a
+ * rebuild reseeds the particles it drops. */
 async function backfillInStore(writes, provider, model, rebuild) {
     let count = 0;
     let afterId;
@@ -214,7 +223,8 @@ async function backfillInStore(writes, provider, model, rebuild) {
         afterId = page[page.length - 1].id;
         const vectors = await provider.embed(page.map((e) => embeddingInputText(e)), 'passage');
         const result = await writeVectorPage(writes, { model, replaceIndex: rebuild }, page, vectors, rebuild);
-        // Another process rebuilt the index mid-run; every later page would be refused too, after paying the provider for it.
+        // Another process rebuilt the index mid-run; every later page
+        // would be refused too, after paying the provider for it.
         if (result.modelMismatch)
             throw new Error(OTHER_MODEL_INDEX);
         count += result.written;
@@ -226,8 +236,10 @@ async function embedAllInStore(store, provider) {
     const rebuild = indexNeedsRebuild(indexedModel(await reads.embeddingIndexState()), provider.id);
     return backfillInStore(writes, provider, embeddingIndexIdentity(provider.id), rebuild);
 }
-/** embedMemory on a store; like the hippo.db path it resolves whatever fails. Unlike it, it leaves a model change to embedAll, so a stale
- *  read here never drops another process's rebuild; the read only saves a paid embed call, as the write refuses another model itself. */
+/** embedMemory on a store; like the hippo.db path it resolves whatever fails. Unlike it, it leaves a model change to
+ * embedAll, so a stale
+ * read here never drops another process's rebuild; the read only saves a paid embed call, as the write refuses
+ * another model itself. */
 function embedMemoryInStore(store, provider, entry) {
     return withProcessEmbedLock(async () => {
         const [reads, writes] = vectorGroups(store);
@@ -244,40 +256,46 @@ function embedMemoryInStore(store, provider, entry) {
             return 'failed';
         }
     }).catch((err) => {
-        log.warn(`skipped embedding ${entry.id} (${errorMessage(err)})`);
+        log.warn(`skipped embedding ${entry.id} (${errorMessage(err)})`, errorFields(err));
         return 'failed';
     });
 }
 const INLINE_REINDEX_MAX_ROWS = 256;
-/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db.
- *  Resolves whatever fails, so a caller that fires and forgets stays safe; the outcome says whether the memory reached the index. */
+/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites,
+ * never opening hippo.db.
+ * Resolves whatever fails, so a caller that fires and forgets stays safe; the outcome says whether the memory
+ * reached the index. */
 export async function embedMemory(hippoRoot, entry, model, store) {
     let provider;
+    let available;
     try {
         provider = resolveEmbeddingProvider(hippoRoot, { model });
+        available = provider.isAvailable();
     }
     catch (err) {
         // Callers fire and forget, so this must resolve: a bad config warns once instead of rejecting.
         warnEmbedFailureOnce('config', errorMessage(err), err);
         return 'failed';
     }
-    if (!provider.isAvailable())
+    if (!available)
         return 'off';
     if (store)
         return embedMemoryInStore(store, provider, entry);
     return withEmbedLock(hippoRoot, () => embedMemoryLocked(hippoRoot, provider, entry)).catch((err) => {
-        log.warn(`skipped embedding ${entry.id} (${errorMessage(err)}); run 'hippo embed' to backfill`);
+        log.warn(`skipped embedding ${entry.id} (${errorMessage(err)}); run 'hippo embed' to backfill`, errorFields(err));
         return 'failed';
     });
 }
-/** Best-effort: an embedding failure (API down, bad key, 5xx) must not reject the caller's write; the existing index is left as-is.
+/** Best-effort: an embedding failure (API down, bad key, 5xx) must not reject the caller's write; the existing index is
+ * left as-is.
  *  Failures surface on the explicit `hippo embed` / `embedAll` path. */
 async function embedMemoryLocked(hippoRoot, provider, entry) {
     try {
         const identity = provider.id;
         if (embeddingModelRequiresReindex(hippoRoot, identity)) {
-            // A fire-and-forget write heals a small index inline; a large one is left to `hippo embed`, so no write holds the lock for a whole-store embed.
-            if (loadAllEntryIds(hippoRoot).length > INLINE_REINDEX_MAX_ROWS) {
+            // A fire-and-forget write heals a small index inline; a large one is left to `hippo embed`, so no write holds the
+            // lock for a whole-store embed.
+            if (countAllEntries(hippoRoot) > INLINE_REINDEX_MAX_ROWS) {
                 warnEmbedFailureOnce('index', OTHER_MODEL_INDEX);
                 return 'failed';
             }
@@ -298,11 +316,14 @@ async function embedMemoryLocked(hippoRoot, provider, entry) {
         return 'failed';
     }
 }
-// Every page is embedded before one transaction replaces the index, and the identity is saved only after that: a provider failure or a crash
-// at any earlier point leaves the old identity, so embeddingModelRequiresReindex has the next run rebuild from the start.
+// Every page is embedded before one transaction replaces the index, and
+// the identity is saved only after that: a provider failure or a crash
+// at any earlier point leaves the old identity, so
+// embeddingModelRequiresReindex has the next run rebuild from the start.
 async function rebuildIndexForProvider(hippoRoot, provider) {
     const identity = provider.id;
-    // Host-wide rebuild: one embedding index per hippoRoot, keyed by tenant-scoped entry.id; per-tenant indices would be a larger architecture change.
+    // Host-wide rebuild: one embedding index per hippoRoot, keyed by tenant-scoped entry.id; per-tenant indices would be
+    // a larger architecture change.
     const ids = loadAllEntryIds(hippoRoot);
     const rebuiltIndex = await rebuildEmbeddingIndex(hippoRoot, ids, provider);
     saveEmbeddingIndex(hippoRoot, rebuiltIndex, embeddingIndexIdentity(identity));
@@ -316,12 +337,13 @@ function initializePhysicsIfMissing(hippoRoot, entry, vector) {
     }
     catch (err) {
         // Physics init is best-effort and must not fail the embedding that just landed.
-        log.debug(`physics state not initialised for ${entry.id}: ${errorMessage(err)}`);
+        log.warnThenDebug('physics-state-seed', `physics state not initialised for ${entry.id}: ${errorMessage(err)}`, errorFields(err));
     }
 }
 /** Throws when an unavailable provider is a misconfiguration rather than an intentional no-op. */
 function throwIfProviderKeyMissing(hippoRoot, provider) {
-    // A configured API provider with a missing key is a misconfiguration: surface it so callers of the exported embedAll() learn nothing was written.
+    // A configured API provider with a missing key is a misconfiguration: surface it so callers of the exported
+    // embedAll() learn nothing was written.
     // Local-not-installed and an explicit enabled=false stay silent no-ops.
     const cfg = loadConfig(hippoRoot).embeddings;
     if (provider.kind !== 'local' &&
@@ -331,8 +353,10 @@ function throwIfProviderKeyMissing(hippoRoot, provider) {
         throw new Error(`Embedding provider '${provider.kind}' is configured but ${provider.keyEnv} is not set.`);
     }
 }
-// Embeds entries without a cached vector in save-checkpointed chunks; a `[]` row means that item could not be embedded and is retried next run.
-// On a hard provider failure mid-backfill the chunks already embedded are persisted (paid progress), then it stops and resumes next run.
+// Embeds entries without a cached vector in save-checkpointed chunks; a `[]` row means that item could not be embedded
+// and is retried next run.
+// On a hard provider failure mid-backfill the chunks already embedded are persisted (paid progress), then it stops and
+// resumes next run.
 async function backfillPending(hippoRoot, provider, pending, model) {
     let count = 0;
     // Initialized to `undefined` so it stays a plain `unknown` binding for the arbitrary caught value; falsy either way.
@@ -360,8 +384,10 @@ async function backfillPending(hippoRoot, provider, pending, model) {
     }
     return { count, backfillError };
 }
-/** Embeds every entry with no cached vector, prunes vectors of deleted memories, and returns how many it embedded; `provider` defaults to the
- *  configured one. With `store`, every tenant's memories with no vector for the provider's model go through its `vectorWrites`, never hippo.db. */
+/** Embeds every entry with no cached vector, prunes vectors of deleted memories, and returns how many it embedded;
+ * `provider` defaults to the
+ * configured one. With `store`, every tenant's memories with no vector for the provider's model go through its
+ * `vectorWrites`, never hippo.db. */
 export async function embedAll(hippoRoot, model, provider = resolveEmbeddingProvider(hippoRoot, { model }), store) {
     if (!provider.isAvailable()) {
         throwIfProviderKeyMissing(hippoRoot, provider);
@@ -373,10 +399,10 @@ export async function embedAll(hippoRoot, model, provider = resolveEmbeddingProv
         const identity = provider.id;
         if (embeddingModelRequiresReindex(hippoRoot, identity))
             return rebuildIndexForProvider(hippoRoot, provider);
-        // Host-wide by design: embedAll backfills all tenants' entries into the per-host index; per-tenant filtering would produce partial indices and break
-        // recall.
-        const embedded = pruneStoredVectors(hippoRoot);
-        const pending = loadAllEntryIds(hippoRoot).filter((id) => !embedded.has(id));
+        // Host-wide by design: embedAll backfills all tenants'
+        // entries into the per-host index; per-tenant filtering
+        // would produce partial indices and break recall.
+        const pending = pruneStoredVectorsListPending(hippoRoot);
         const { count, backfillError } = await backfillPending(hippoRoot, provider, pending, embeddingIndexIdentity(identity));
         saveStoredEmbeddingModel(hippoRoot, identity);
         // Partial progress is now persisted; surface a hard backfill failure so the

package/dist/search/engine.d.ts

@@ -3,6 +3,9 @@ import type { PhysicsConfig } from '../core/physics-config.js';
 import type { SearchResult } from '../core/search-types.js';
 import { type HybridSearchOptions } from './hybrid.js';
 import type { VectorSource } from './vector.js';
-/** Physics scoring when `physics` holds its config, hybrid otherwise, both on the store `source` names; each caller keeps its own options. */
+/**
+ * Physics scoring when `physics` holds its config, hybrid otherwise, both on the store `source` names; each caller
+ * keeps its own options.
+ */
 export declare function searchByEngine(source: VectorSource, query: string, pool: MemoryEntry[], physics: PhysicsConfig | null, options: Omit<HybridSearchOptions, 'hippoRoot' | 'store'>): Promise<SearchResult[]>;
 //# sourceMappingURL=engine.d.ts.map

package/dist/search/engine.js

@@ -1,7 +1,11 @@
-// The one search-engine choice every ranker over a candidate pool makes: recall's band, MCP's wide list, the CLI core and context.
+// The one search-engine choice every ranker over a candidate pool makes: recall's band, MCP's wide list, the CLI core
+// and context.
 import { hybridSearch } from './hybrid.js';
 import { physicsSearchIn } from './physics-search.js';
-/** Physics scoring when `physics` holds its config, hybrid otherwise, both on the store `source` names; each caller keeps its own options. */
+/**
+ * Physics scoring when `physics` holds its config, hybrid otherwise, both on the store `source` names; each caller
+ * keeps its own options.
+ */
 export function searchByEngine(source, query, pool, physics, options) {
     return physics
         ? physicsSearchIn(source, query, pool, { ...options, physicsConfig: physics })

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

@@ -6,7 +6,10 @@ 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. */
+    /**
+     * 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. */
@@ -14,8 +17,12 @@ 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. */
+/**
+ * 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;

package/dist/search/goal-boost.js

@@ -53,15 +53,20 @@ function buildGoalRecallLog(boosted, matchesByEntryId, goalsByTag, opts) {
     }
     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. */
+/**
+ * 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.
+    // 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) => {
@@ -82,11 +87,13 @@ export function boostByGoals(results, active, opts) {
             });
         }
         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.
+        // 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.
+        // 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) };
 }

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

@@ -15,6 +15,9 @@ export interface HybridScoreInput {
     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. */
+/**
+ * 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

@@ -2,7 +2,10 @@ import { estimateTokens } from '../util/token-text.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. */
+/**
+ * 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);

package/dist/search/hybrid.d.ts

@@ -17,7 +17,9 @@ export interface HybridSearchOptions {
     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. */
+    /**
+     * 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;
@@ -33,13 +35,21 @@ export interface HybridSearchOptions {
     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. */
+    /**
+     * 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. */
+    /**
+     * 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. */
+    /**
+     * 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;
@@ -47,11 +57,16 @@ export interface HybridSearchOptions {
     queryEmbedDeadline?: AbortSignal;
 }
 export declare const DEFAULT_EMBEDDING_WEIGHT = 0.6;
-export declare const DEFAULT_MMR_LAMBDA = 0.7;
-/** BM25 blended with cosine similarity when stored vectors and a provider are available, BM25 * strength * recency otherwise. */
+/**
+ * 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[]>;
-/** hippo.db under `hippoRoot` when the caller passed no store: the default lives on this exported entry, never inside the vector arm. */
-export declare function vectorSourceOf({ hippoRoot, store }: {
+/**
+ * hippo.db under `hippoRoot` when the caller passed no store: the default lives on this exported entry, never inside
+ * the vector arm.
+ */
+export declare function vectorSourceOf({ hippoRoot, store, }: {
     hippoRoot?: string;
     store?: HippoStore;
 }): VectorSource | undefined;

package/dist/search/hybrid.js

@@ -7,17 +7,19 @@ 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 { 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';
-import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
+import { DEFAULT_MMR_LAMBDA, DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
 import { sqliteStore } from '../store/index.js';
-// Share of the blended score that cosine takes, and the relevance side of the MMR relevance-versus-diversity trade.
+// Share of the blended score that cosine takes.
 export const DEFAULT_EMBEDDING_WEIGHT = 0.6;
-export const DEFAULT_MMR_LAMBDA = 0.7;
-/** BM25 blended with cosine similarity when stored vectors and a provider are available, BM25 * strength * recency otherwise. */
+/**
+ * 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 ?? DEFAULT_EMBEDDING_WEIGHT;
@@ -49,8 +51,11 @@ export async function hybridSearch(query, entries, options = {}) {
     const ordered = await orderHybrid(query, withDagChildren(dedupeExtracted(scored), arm.entries), arm, options);
     return fitBudget(ordered, options.budget ?? DEFAULT_RECALL_BUDGET, options.minResults ?? 1, options.cost);
 }
-/** hippo.db under `hippoRoot` when the caller passed no store: the default lives on this exported entry, never inside the vector arm. */
-export function vectorSourceOf({ hippoRoot, store }) {
+/**
+ * hippo.db under `hippoRoot` when the caller passed no store: the default lives on this exported entry, never inside
+ * the vector arm.
+ */
+export function vectorSourceOf({ hippoRoot, store, }) {
     return hippoRoot ? { root: hippoRoot, store: store ?? sqliteStore(hippoRoot) } : undefined;
 }
 function hybridBoostContext(query, pool, now, options) {