hippo-memory 1.72.0 → 2.1.0

package/dist/rerankers/llm.js

@@ -7,8 +7,12 @@ import { isJsonObject, isJsonString } from '../util/json.js';
 import { errorMessage } from '../util/log.js';
 const DEFAULT_LLM_RERANK_TOP_K = 20;
 const DEFAULT_TIMEOUT_MS = 30_000;
-/** Track 3 reranker (skeleton): listwise LLM rerank on a customer-supplied OpenAI-compatible endpoint, gated on HIPPO_LLM_RERANKER_URL against accidental cost.
- * Timeout is 30s for the whole call, retries included (HIPPO_LLM_RERANKER_TIMEOUT_MS); any failure falls back to identity ordering, so recall never hangs. */
+/**
+ * Track 3 reranker (skeleton): listwise LLM rerank on a customer-supplied OpenAI-compatible endpoint, gated on
+ * HIPPO_LLM_RERANKER_URL against accidental cost.
+ * Timeout is 30s for the whole call, retries included (HIPPO_LLM_RERANKER_TIMEOUT_MS); any failure falls back to
+ * identity ordering, so recall never hangs.
+ */
 export function createLlmReranker() {
     const outage = createOutageWarning('llm', 'keeping the input order');
     return async (query, results, options) => {
@@ -47,7 +51,8 @@ function replyText(body) {
 async function requestPermutation(url, query, head) {
     const key = envLlmRerankerKey();
     const prompt = [
-        `Rerank the candidates below by relevance to the query. Output a JSON array of indices (zero-indexed) in best-first order.`,
+        `Rerank the candidates below by relevance to the query. Output a JSON array of indices (zero-indexed) in ` +
+            `best-first order.`,
         `Query: ${redactSecretsStrict(query)}`,
         ...head.map((r, i) => `[${i}] ${redactSecretsStrict(r.entry.content)}`),
         `Output format: [<int>, <int>, ...] with all ${head.length} indices.`,

package/dist/rerankers/remote.d.ts

@@ -1,4 +1,6 @@
 export declare const RERANKER_MAX_REPLY_BYTES: number;
-/** 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 declare function rerankerPost(url: string, init: RequestInit, budgetMs: number): Promise<Response>;
 //# sourceMappingURL=remote.d.ts.map

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,9 +1,17 @@
 import type { MemoryEntry } from '../core/memory.js';
 import { type EmbeddingProvider } from '../embeddings/provider.js';
 import { type HippoStore } from '../store/port.js';
-/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
-export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model?: string, store?: HippoStore): Promise<void>;
-/** 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. */
+/** `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. */
+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. */
 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

@@ -4,16 +4,17 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
 import { loadConfig } from '../core/config.js';
-import { initializeParticle } from '../db/physics-state.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,15 +188,18 @@ 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 };
-        byTenant.set(entry.tenantId, [...(byTenant.get(entry.tenantId) ?? []), row]);
+        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;
     for (const [tenantId, rows] of byTenant) {
@@ -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);
@@ -237,60 +249,81 @@ function embedMemoryInStore(store, provider, entry) {
                 || (await writeVectorPage(writes, { model, replaceIndex: false }, [entry], await provider.embed([embeddingInputText(entry)], 'passage'), true)).modelMismatch;
             if (refused)
                 warnEmbedFailureOnce('index', OTHER_MODEL_INDEX);
+            return refused ? 'failed' : 'indexed';
         }
         catch (err) {
             warnEmbedFailureOnce(provider.kind, errorMessage(err), err);
+            return 'failed';
         }
     }).catch((err) => {
-        log.warn(`skipped embedding ${entry.id} (${errorMessage(err)})`);
+        log.warn(`skipped embedding ${entry.id} (${errorMessage(err)})`, errorFields(err));
+        return 'failed';
     });
 }
-/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
+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. */
 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;
+        return 'failed';
     }
-    if (!provider.isAvailable())
-        return;
+    if (!available)
+        return 'off';
     if (store)
         return embedMemoryInStore(store, provider, entry);
-    return withEmbedLock(hippoRoot, async () => {
-        // 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.
-        try {
-            const identity = provider.id;
-            if (embeddingModelRequiresReindex(hippoRoot, identity)) {
-                await rebuildIndexForProvider(hippoRoot, provider);
-                return;
+    return withEmbedLock(hippoRoot, () => embedMemoryLocked(hippoRoot, provider, entry)).catch((err) => {
+        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.
+ *  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 (countAllEntries(hippoRoot) > INLINE_REINDEX_MAX_ROWS) {
+                warnEmbedFailureOnce('index', OTHER_MODEL_INDEX);
+                return 'failed';
             }
-            const text = embeddingInputText(entry);
-            const [vector] = await provider.embed([text], 'passage');
-            if (!vector || vector.length === 0)
-                return;
-            saveStoredVectors(hippoRoot, [[entry.id, vector]], embeddingIndexIdentity(identity));
-            saveStoredEmbeddingModel(hippoRoot, identity);
-            // Initialize physics state for this memory
-            initializePhysicsIfMissing(hippoRoot, entry, vector);
+            await rebuildIndexForProvider(hippoRoot, provider);
+            return 'indexed';
         }
-        catch (err) {
-            // Provider failure (API down / bad key). Best-effort: leave the index as-is, but say so once.
-            warnEmbedFailureOnce(provider.kind, errorMessage(err), err);
-        }
-    }).catch((err) => {
-        log.warn(`skipped embedding ${entry.id} (${errorMessage(err)}); run 'hippo embed' to backfill`);
-    });
+        const [vector] = await provider.embed([embeddingInputText(entry)], 'passage');
+        if (!vector || vector.length === 0)
+            return 'failed';
+        saveStoredVectors(hippoRoot, [[entry.id, vector]], embeddingIndexIdentity(identity));
+        saveStoredEmbeddingModel(hippoRoot, identity);
+        initializePhysicsIfMissing(hippoRoot, entry, vector);
+        return 'indexed';
+    }
+    catch (err) {
+        // Provider failure (API down / bad key). Best-effort: leave the index as-is, but say so once.
+        warnEmbedFailureOnce(provider.kind, errorMessage(err), err);
+        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));
@@ -304,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' &&
@@ -319,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.
@@ -348,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);
@@ -361,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

@@ -0,0 +1,11 @@
+import type { MemoryEntry } from '../core/memory.js';
+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.
+ */
+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

@@ -0,0 +1,14 @@
+// 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.
+ */
+export function searchByEngine(source, query, pool, physics, options) {
+    return physics
+        ? physicsSearchIn(source, query, pool, { ...options, physicsConfig: physics })
+        : hybridSearch(query, pool, { ...options, hippoRoot: source.root, store: source.store });
+}
+//# sourceMappingURL=engine.js.map

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);