hippo-memory 1.71.0 → 1.72.0

package/dist/db/migrations/index.js

@@ -52,7 +52,8 @@ import { v51 } from './v51.js';
 import { v52 } from './v52.js';
 import { v53 } from './v53.js';
 import { v54 } from './v54.js';
-export const CURRENT_SCHEMA_VERSION = 54;
+import { v55 } from './v55.js';
+export const CURRENT_SCHEMA_VERSION = 55;
 /** Every schema migration in version order; runMigrations applies each one above the stored version. */
 export const MIGRATIONS = [
     v01,
@@ -109,5 +110,6 @@ export const MIGRATIONS = [
     v52,
     v53,
     v54,
+    v55,
 ];
 //# sourceMappingURL=index.js.map

package/dist/db/migrations/v55.d.ts

@@ -0,0 +1,3 @@
+import type { Migration } from './types.js';
+export declare const v55: Migration;
+//# sourceMappingURL=v55.d.ts.map

package/dist/db/migrations/v55.js

@@ -0,0 +1,17 @@
+import { tableHasColumn, tableExists } from '../tables.js';
+export const v55 = {
+    version: 55,
+    up: (db) => {
+        // No backfill and no floor raise: an older binary names its INSERT columns, so it still writes.
+        if (!tableExists(db, 'delivery_events'))
+            return;
+        if (!tableHasColumn(db, 'delivery_events', 'tool_use_id'))
+            db.exec('ALTER TABLE delivery_events ADD COLUMN tool_use_id TEXT');
+        if (!tableHasColumn(db, 'delivery_events', 'failure_id'))
+            db.exec('ALTER TABLE delivery_events ADD COLUMN failure_id INTEGER');
+        db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_delivery_events_tool_call
+        ON delivery_events(tenant_id, session_id, tool_use_id)
+        WHERE tool_use_id IS NOT NULL AND turn_seq IS NOT NULL`);
+    },
+};
+//# sourceMappingURL=v55.js.map

package/dist/db/open.d.ts

@@ -24,8 +24,6 @@ export declare function withSqliteAllowed<T>(fn: () => T): T;
 export declare function withSqliteOffLoop<T>(fn: () => T): T;
 /** Leaves withSqliteOffLoop's block and nothing else: another store's block and the folder marker still refuse, which withSqliteAllowed would waive. */
 export declare function outsideSqliteOffLoop<T>(fn: () => T): T;
-/** First line of a best-effort catch around a hippo.db open: an unported path must fail closed, not fall back silently. */
-export declare function rethrowIfSqliteBlocked<E>(err: E): void;
 /** store init --db, store copy --db and serve --db write this file in the hippo root; its text is the store kind. */
 export declare const OTHER_STORE_MARKER = "other-store";
 /** Throws where hippo.db must not open; checked on every open, not cached, since the marker can appear while a process runs. */

package/dist/db/open.js

@@ -1,11 +1,12 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { errorMessage, log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { DatabaseSync } from './sqlite.js';
 import { tableExists } from './tables.js';
 import { assertBinaryCompatible } from './migrate.js';
-import { connectWithFacts, DEFAULT_BUSY_WAIT_MS, getHippoDbPath } from './connect.js';
+import { DEFAULT_BUSY_WAIT_MS } from './busy.js';
+import { connectWithFacts, getHippoDbPath } from './connect.js';
 import { currentRequestStores, isScopedHandle, runWithRequestStores } from './request-stores.js';
 import { OtherStoreFolderError, SqliteBlockedError } from '../util/sqlite-blocked.js';
 export { getHippoDbPath };
@@ -49,11 +50,6 @@ export function withSqliteOffLoop(fn) {
 export function outsideSqliteOffLoop(fn) {
     return sqliteBlockedBy.getStore() === OFF_LOOP ? sqliteBlockedBy.exit(fn) : fn();
 }
-/** First line of a best-effort catch around a hippo.db open: an unported path must fail closed, not fall back silently. */
-export function rethrowIfSqliteBlocked(err) {
-    if (err instanceof SqliteBlockedError)
-        throw err;
-}
 /** store init --db, store copy --db and serve --db write this file in the hippo root; its text is the store kind. */
 export const OTHER_STORE_MARKER = 'other-store';
 const markerWaived = new AsyncLocalStorage();
@@ -95,7 +91,7 @@ export function openHippoDbReadOnly(hippoRoot) {
     assertSqliteAllowed(hippoRoot);
     const db = new DatabaseSync(getHippoDbPath(hippoRoot), { readOnly: true });
     try {
-        db.exec('PRAGMA busy_timeout = 5000');
+        db.exec(`PRAGMA busy_timeout = ${DEFAULT_BUSY_WAIT_MS}`);
         if (tableExists(db, 'meta'))
             assertBinaryCompatible(db);
         return db;
@@ -104,8 +100,8 @@ export function openHippoDbReadOnly(hippoRoot) {
         try {
             db.close();
         }
-        catch {
-            // Best effort only.
+        catch (closeErr) {
+            log.error(`openHippoDbReadOnly: closing the handle after a failed open failed: ${errorMessage(closeErr)}`, errorFields(closeErr));
         }
         throw error;
     }

package/dist/db/physics-state.js

@@ -1,5 +1,5 @@
 /** Physics state persistence: particle state (position, velocity, mass, charge, temperature) in SQLite, with BLOB columns for 384-dim vectors. */
-import { evalNow } from '../core/ablation.js';
+import { evalNow, strengthAblation } from '../core/ablation.js';
 import { withWriteScope } from './busy.js';
 import { computeMass, computeCharge, computeTemperature, vecZero } from '../core/physics.js';
 import { calculateStrength } from '../core/memory.js';
@@ -99,7 +99,7 @@ export function savePhysicsState(db, particles) {
 }
 /** Initialize physics state for a memory from its embedding vector; returns the new particle without persisting (the caller must save). */
 export function initializeParticle(entry, embedding, now = evalNow()) {
-    const strength = calculateStrength(entry, now);
+    const strength = calculateStrength(entry, now, { ablation: strengthAblation() });
     const ageDays = (now.getTime() - new Date(entry.created).getTime()) / DAY_MS;
     return {
         memoryId: entry.id,
@@ -141,7 +141,7 @@ export function refreshParticleProperties(particles, entries, now = evalNow()) {
         const entry = entries.get(p.memoryId);
         if (!entry)
             continue;
-        const strength = calculateStrength(entry, now);
+        const strength = calculateStrength(entry, now, { ablation: strengthAblation() });
         const ageDays = (now.getTime() - new Date(entry.created).getTime()) / DAY_MS;
         p.mass = computeMass(strength, entry.retrieval_count);
         p.charge = computeCharge(entry.emotional_valence);

package/dist/db/tables.d.ts

@@ -7,5 +7,7 @@ export declare function tableExists(db: DatabaseSyncLike, tableName: string): bo
 export declare function listTableNames(db: DatabaseSyncLike): string[];
 /** Row count of one table; null when the table is missing or unreadable, which callers show as unknown. */
 export declare function countTableRows(db: DatabaseSyncLike, table: string): number | null;
+/** Sleep runs a store keeps; stats.json lists exactly these, so a recall's stats rewrite reads a fixed number of rows. */
+export declare const CONSOLIDATION_RUNS_KEPT = 50;
 export declare function pruneConsolidationRuns(db: DatabaseSyncLike, keep?: number): void;
 //# sourceMappingURL=tables.d.ts.map

package/dist/db/tables.js

@@ -1,3 +1,4 @@
+import { errorCode, log } from '../util/log.js';
 /** Column names of one table; empty when the table is missing. */
 export function tableColumns(db, tableName) {
     if (!/^[a-z_]+$/i.test(tableName))
@@ -30,12 +31,15 @@ export function countTableRows(db, table) {
         const row = db.prepare(`SELECT COUNT(*) AS n FROM "${table.replace(/"/g, '""')}"`).get();
         return Number(row?.n ?? 0);
     }
-    catch {
+    catch (err) {
         // Callers treat an uncountable table as unknown; the bundle and doctor still finish.
+        log.warn(`could not count rows in table ${table}`, { table, code: errorCode(err) || 'unknown' });
         return null;
     }
 }
-export function pruneConsolidationRuns(db, keep = 50) {
+/** Sleep runs a store keeps; stats.json lists exactly these, so a recall's stats rewrite reads a fixed number of rows. */
+export const CONSOLIDATION_RUNS_KEPT = 50;
+export function pruneConsolidationRuns(db, keep = CONSOLIDATION_RUNS_KEPT) {
     db.prepare(`
     DELETE FROM consolidation_runs
     WHERE id NOT IN (

package/dist/db/vector-store.js

@@ -2,7 +2,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { withWriteScope } from './busy.js';
-import { log } from '../util/log.js';
+import { errorCode, errorFields, log } from '../util/log.js';
 /** Legacy whole-file index; imported once into `memory_vectors`, then kept beside the store as a renamed backup. */
 const LEGACY_EMBEDDINGS_FILE = 'embeddings.json';
 export const EMBEDDING_MODEL_META_KEY = 'embedding_model';
@@ -188,17 +188,30 @@ function insertSorted(top, m, k) {
 function stamp() {
     return `${new Date().toISOString().replace(/[:.]/g, '-')}-${process.pid}`;
 }
-/** Rename `fp` to `aside`; a rename blocked by an open handle (Windows) falls back to a copy, so the bytes are kept either way. */
+// The codes a rename gets when another process holds the file open (Windows); any other failure would fail a copy too.
+const RENAME_BLOCKED_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+/** Rename `fp` to `aside`; a rename blocked by an open handle falls back to a copy, so the bytes are kept either way. */
 function moveAside(fp, aside) {
     try {
         fs.renameSync(fp, aside);
         return true;
     }
     catch (err) {
-        if (err instanceof Error && 'code' in err && err.code === 'ENOENT')
+        const code = errorCode(err);
+        if (code === 'ENOENT')
             return false;
+        if (!RENAME_BLOCKED_CODES.has(code))
+            throw err;
+        log.warn(`could not rename ${path.basename(fp)} aside (${code}); copying it instead`, { path: fp, ...errorFields(err) });
         fs.copyFileSync(fp, aside, fs.constants.COPYFILE_EXCL);
-        fs.rmSync(fp, { force: true });
+        try {
+            fs.rmSync(fp, { force: true });
+        }
+        catch (rmErr) {
+            // The original stays for the next open to retry, so a copy left beside it would pile up one per open.
+            fs.rmSync(aside, { force: true });
+            throw rmErr;
+        }
         return true;
     }
 }

package/dist/db/wal-checkpointer.js

@@ -2,6 +2,7 @@
 import * as path from 'node:path';
 import { Worker } from 'node:worker_threads';
 import { errorMessage, log } from '../util/log.js';
+import { DEFAULT_BUSY_WAIT_MS } from './busy.js';
 // WAL pages at which a connection checkpoints inside its own commit.
 const INLINE_CHECKPOINT_PAGES = 100;
 // The same limit while a worker checkpoints the store: SQLite still bounds the WAL when the worker falls behind.
@@ -17,7 +18,7 @@ const WORKER_SOURCE = `
 const { parentPort, workerData } = require('node:worker_threads');
 const { DatabaseSync } = require('node:sqlite');
 const db = new DatabaseSync(workerData.dbPath);
-db.exec('PRAGMA busy_timeout = 5000');
+db.exec('PRAGMA busy_timeout = ${DEFAULT_BUSY_WAIT_MS}');
 db.exec('PRAGMA synchronous = NORMAL');
 const pass = db.prepare('PRAGMA wal_checkpoint(PASSIVE)');
 parentPort.on('message', (message) => {

package/dist/doctor.js

@@ -3,17 +3,18 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { findHippoStoreDir } from './core/project-identity.js';
+import { findHippoStoreDir, isInitialized } from './core/project-identity.js';
 import { getGlobalRoot } from './sharing/global-store.js';
-import { isInitialized } from './store/open.js';
 import { readStoreHealth } from './store/diagnostics.js';
 import { loadConfig } from './core/config.js';
 import { openHippoDbReadOnly, closeHippoDb, getCurrentSchemaVersion, IncompatibleBinaryError } from './db/index.js';
-import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './capture/compaction-record.js';
+import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './core/compaction-timing.js';
 import { SPOOL_DIR, spoolCounts } from './capture/compaction-spool.js';
-import { isEmbeddingAvailable } from './store/embeddings/local.js';
-import { CODEX_TRUST_LINE, claudeConfigDir, codexHomeDir, isCodexPresent } from './hooks/shared.js';
+import { isEmbeddingAvailable } from './embeddings/local.js';
+import { CODEX_TRUST_LINE, isCodexPresent } from './hooks/shared.js';
+import { claudeConfigDir, codexHomeDir } from './util/agent-homes.js';
 import { planProjectRepair } from './sharing/project-merge.js';
+import { projectTagReads } from './store/project-tags.js';
 import { resolveTenantId } from './store/tenant.js';
 import { errorMessage, log } from './util/log.js';
 import { readJsonFile, isJsonObjectLiteral } from './util/json.js';
@@ -132,7 +133,8 @@ function compactionsCheck(compactions, store, now) {
     ].filter((s) => s !== '');
     const unfinished = stuck === 0
         ? `${recorded} in the store`
-        : `${stuck} compaction${stuck === 1 ? '' : 's'} unfinished after 10 minutes (${summarised} with a summary whose memories are not saved yet, ${started} with no summary yet)`;
+        : `${stuck} compaction${stuck === 1 ? '' : 's'} unfinished after 10 minutes ` +
+            `(${summarised} with a summary whose memories are not saved yet, ${started} with no summary yet)`;
     const note = spooled ? `; spool: ${spool.waiting} waiting, ${spool.stale} left by a replay that stopped, ${spool.bad} .bad` : '';
     return { id: 'compactions', status: 'warn', detail: `${unfinished}${note}${unread}`, fix: fix.join('; ') };
 }
@@ -141,7 +143,7 @@ function projectsCheck(globalRoot) {
     let db = null;
     try {
         db = openHippoDbReadOnly(globalRoot);
-        const r = planProjectRepair(db, globalRoot, resolveTenantId({}));
+        const r = planProjectRepair(projectTagReads(db, resolveTenantId({})), globalRoot);
         const found = [
             r.copies.length > 0 ? `${r.copies.length} imported notes copied under the wrong project` : '',
             r.folds.length > 0 ? `old project names that now resolve to another project: ${r.folds.map((f) => `${f.from} -> ${f.into}`).join(', ')}` : '',
@@ -253,7 +255,8 @@ function tokensCheck(tokens) {
     return {
         id: 'tokens',
         status: 'info',
-        detail: `${tally.injected} memory blocks sent to agents in 7 days, about ${tally.tokensSent} tokens sent and ${tally.tokensReread} re-read by later model calls (hippo tokens for detail)`,
+        detail: `${tally.injected} memory blocks sent to agents in 7 days, about ${tally.tokensSent} tokens sent ` +
+            `and ${tally.tokensReread} re-read by later model calls (hippo tokens for detail)`,
     };
 }
 /** Checks that read the store's database; a store that cannot be opened becomes one failed schema check. */

package/dist/embeddings/local.d.ts

@@ -0,0 +1,62 @@
+/** The one call this file makes on a Transformers.js feature-extraction pipeline, and the part of its tensor it reads. */
+interface EmbeddingPipeline {
+    (input: string, options: {
+        pooling: 'cls' | 'mean';
+        normalize: boolean;
+    }): Promise<{
+        data: ArrayLike<number>;
+    }>;
+}
+type PipelineFactory = (task: 'feature-extraction', model: string, options: {
+    quantized: boolean;
+}) => Promise<EmbeddingPipeline>;
+/** The settings written on the package's `env` object. */
+interface TransformersEnv {
+    cacheDir?: string;
+    localModelPath?: string;
+    allowRemoteModels?: boolean;
+}
+/** The parts of the optional package's module this file reads; either export spelling may carry `pipeline`. */
+interface TransformersModule {
+    env?: TransformersEnv;
+    pipeline?: PipelineFactory;
+    default?: {
+        pipeline?: PipelineFactory;
+    };
+}
+export declare const DEFAULT_EMBEDDING_MODEL = "Xenova/all-MiniLM-L6-v2";
+/** BGE was trained with CLS pooling; everything else gets mean, the sentence-transformers default, since CLS degrades mean-trained models. */
+export declare function poolingFor(model: string): 'cls' | 'mean';
+/** `query` is search input, `passage` is a document being indexed; no role means no prefix on any model. */
+export type EmbeddingRole = 'query' | 'passage';
+/** e5 models only match a query to a passage when each side carries its trained prefix. */
+export declare function prefixFor(model: string, role?: EmbeddingRole): string;
+/** The optional package as the local embedder reaches it; tests hand in a stand-in. */
+export interface LocalTransformers {
+    /** Whether a package is installed, answered without importing it. */
+    installed(): boolean;
+    /** The package's module, or null when neither package is installed. */
+    load(): Promise<{
+        readonly name: string;
+        readonly mod: TransformersModule;
+    } | null>;
+}
+export interface LocalEmbedder {
+    isAvailable(): boolean;
+    /** Throws, with the reason, when the model's pipeline cannot load: a provider-level failure, not a per-item skip.
+     * `signal` ends the wait, never the load, and only once the load is downloading: a load from disk ends soon on its own, a download may not. */
+    requirePipeline(model: string, signal?: AbortSignal): Promise<void>;
+    /** `text`'s vector, or `[]` when the model is missing or fails; `role` adds e5-style prefixes. */
+    embed(text: string, model: string, role?: EmbeddingRole): Promise<number[]>;
+}
+/** One pipeline per model for the embedder's life, since a pipeline is expensive to load. */
+export declare function createLocalEmbedder(transformers?: LocalTransformers): LocalEmbedder;
+/** The process's embedder, shared by every provider and caller so each model loads once. */
+export declare const sharedLocalEmbedder: LocalEmbedder;
+/** Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed. */
+export declare function isEmbeddingAvailable(): boolean;
+export declare function resolveEmbeddingModel(hippoRoot: string, explicitModel?: string): string;
+/** Embeds `text` with the local model, or returns `[]` when Transformers.js is missing or fails; `role` adds e5-style prefixes. */
+export declare function getEmbedding(text: string, model?: string, role?: EmbeddingRole): Promise<number[]>;
+export {};
+//# sourceMappingURL=local.d.ts.map

package/dist/embeddings/local.js

@@ -0,0 +1,146 @@
+// The local Transformers.js embedder, a leaf so provider.ts can wrap it without importing index.ts.
+import { MINUTE_MS } from '../util/time.js';
+import { envModelCache } from '../util/env.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadConfig } from '../core/config.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+import { createModelLoads, importTransformers, MODEL_LOAD_POLICY, resolveTransformersPackage } from './transformers.js';
+export const DEFAULT_EMBEDDING_MODEL = 'Xenova/all-MiniLM-L6-v2';
+/** BGE was trained with CLS pooling; everything else gets mean, the sentence-transformers default, since CLS degrades mean-trained models. */
+export function poolingFor(model) {
+    return /\bbge\b/i.test(model) ? 'cls' : 'mean';
+}
+/** e5 models only match a query to a passage when each side carries its trained prefix. */
+export function prefixFor(model, role) {
+    if (!role)
+        return '';
+    if (/\be5\b/i.test(model)) {
+        return role === 'query' ? 'query: ' : 'passage: ';
+    }
+    return '';
+}
+const INSTALLED_TRANSFORMERS = {
+    installed: () => resolveTransformersPackage() !== null,
+    load: () => importTransformers(),
+};
+/** One pipeline per model for the embedder's life, since a pipeline is expensive to load. */
+export function createLocalEmbedder(transformers = INSTALLED_TRANSFORMERS) {
+    let available = null;
+    const gates = new Map();
+    const pipelines = createModelLoads(MODEL_LOAD_POLICY, warnLoadFailure);
+    const load = (model) => pipelines.load(model, () => createPipeline(transformers, model, gates));
+    const isAvailable = () => (available ??= transformers.installed());
+    return {
+        isAvailable,
+        requirePipeline: (model, signal) => waitForPipeline(load(model), signal && gateOf(gates, model).opened, signal),
+        async embed(text, model, role) {
+            if (!isAvailable())
+                return [];
+            try {
+                const pipe = await load(model);
+                const prefix = prefixFor(model, role);
+                const output = await pipe(prefix ? `${prefix}${text}` : text, { pooling: poolingFor(model), normalize: true });
+                return Array.from(output.data);
+            }
+            catch (err) {
+                // The caller sees `[]` and names the memory; a failed load already warned once for its backoff window.
+                log.debug(`local embedding failed: ${errorMessage(err)}`);
+                return [];
+            }
+        },
+    };
+}
+function warnLoadFailure(model, err) {
+    const retry = `the next try is in ${MODEL_LOAD_POLICY.backoffMs / MINUTE_MS} minutes`;
+    log.warn(`local embedding model ${model} did not load (${errorMessage(err)}); embeddings stay off and ${retry}`, errorFields(err));
+}
+/** The model's pipeline; throws the reason it cannot load. */
+async function createPipeline(transformers, model, gates) {
+    // The package is an optional peer, so the dynamic import is typed by what this file reads; a missing export throws below.
+    const imported = await transformers.load();
+    if (!imported)
+        throw new Error('no transformers package is installed');
+    const { name, mod } = imported;
+    const cache = envModelCache();
+    if (cache && mod.env) {
+        mod.env.cacheDir = cache;
+        mod.env.localModelPath = cache;
+        mod.env.allowRemoteModels = false;
+    }
+    const pipelineFn = mod.pipeline ?? mod.default?.pipeline;
+    if (!pipelineFn)
+        throw new Error(`${name} exports no pipeline function`);
+    // The offline bundle used in egress-blocked sandboxes ships only the FP32 model, so use whichever file is on disk.
+    const quantized = !cache || fs.existsSync(path.join(cache, model, 'onnx', 'model_quantized.onnx'));
+    if (fetchesWeights(mod.env, model))
+        gateOf(gates, model).open();
+    try {
+        return await pipelineFn('feature-extraction', model, { quantized });
+    }
+    finally {
+        gates.delete(model);
+    }
+}
+/** Whether the load will download: remote models are allowed and no folder the package reads holds the model's ONNX files. */
+function fetchesWeights(env, model) {
+    if (env?.allowRemoteModels === false)
+        return false;
+    return ![env?.localModelPath, env?.cacheDir].some((dir) => dir !== undefined && fs.existsSync(path.join(dir, model, 'onnx')));
+}
+function gateOf(gates, model) {
+    let gate = gates.get(model);
+    if (!gate) {
+        let open;
+        const opened = new Promise((resolve) => {
+            open = resolve;
+        });
+        gate = { opened, open };
+        gates.set(model, gate);
+    }
+    return gate;
+}
+function rejectOnAbort(signal) {
+    return new Promise((_resolve, reject) => {
+        if (signal.aborted)
+            reject(signal.reason);
+        else
+            signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+    });
+}
+async function waitForPipeline(loading, downloading, signal) {
+    try {
+        await (downloading && signal ? Promise.race([loading, downloading.then(() => rejectOnAbort(signal))]) : loading);
+    }
+    catch (err) {
+        // The download goes on, and the first call after it lands gets the model.
+        if (signal?.aborted && err === signal.reason)
+            throw err;
+        throw new Error(`local embedding model did not load: ${errorMessage(err)}`, { cause: err });
+    }
+}
+/** The process's embedder, shared by every provider and caller so each model loads once. */
+export const sharedLocalEmbedder = createLocalEmbedder();
+/** Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed. */
+export function isEmbeddingAvailable() {
+    return sharedLocalEmbedder.isAvailable();
+}
+export function resolveEmbeddingModel(hippoRoot, explicitModel) {
+    const direct = explicitModel?.trim();
+    if (direct)
+        return direct;
+    try {
+        const configured = loadConfig(hippoRoot).embeddings.model?.trim();
+        if (configured)
+            return configured;
+    }
+    catch (err) {
+        log.warn(`embedding model config unreadable, using the default model: ${errorMessage(err)}`);
+    }
+    return DEFAULT_EMBEDDING_MODEL;
+}
+/** Embeds `text` with the local model, or returns `[]` when Transformers.js is missing or fails; `role` adds e5-style prefixes. */
+export function getEmbedding(text, model = DEFAULT_EMBEDDING_MODEL, role) {
+    return sharedLocalEmbedder.embed(text, model, role);
+}
+//# sourceMappingURL=local.js.map

package/dist/{store/embeddings → embeddings}/provider.d.ts

@@ -1,11 +1,12 @@
 /** Pluggable embedding providers; local `@huggingface/transformers` is the zero-dependency default, OpenAI / Voyage / Cohere are opt-in via native `fetch`.
  * Local `id` is the bare model string, API `id` is `${kind}:${model}`; the stored identity adds `#t<N>` (`embeddingIndexIdentity`), so changes reindex.
  * `embed()` MAY throw on hard transport/auth failure so a reindex aborts atomically; hot paths wrap it and fall back to BM25. */
-import { type EmbeddingRole } from './local.js';
+import { type EmbeddingRole, type LocalTransformers } from './local.js';
 export type EmbeddingProviderKind = 'local' | 'openai' | 'voyage' | 'cohere';
 export declare const API_PROVIDER_KINDS: readonly EmbeddingProviderKind[];
 export interface EmbedCallOptions {
-    /** Ends the whole call when it aborts, every batch and retry included. The local provider runs in process and ignores it. */
+    /** Ends the whole call when it aborts, every batch and retry included. The local provider stops waiting only on a model download,
+     * since nothing stops a load from disk or an in-process inference. */
     signal?: AbortSignal;
 }
 export interface EmbeddingProvider {
@@ -28,6 +29,8 @@ export interface ResolveProviderOptions {
     model?: string;
     /** Explicit provider override (mainly for tests). */
     provider?: EmbeddingProviderKind;
+    /** The Transformers.js package a local provider loads from, with its own models; the process's shared embedder when unset. */
+    transformers?: LocalTransformers;
 }
 /** Build the active embedding provider from config (or an explicit override). A missing key never throws here (it surfaces via `isAvailable()`);
  * only an invalid config (e.g. insecure apiBaseUrl) throws, deliberately loud, so hot-path callers wrap it. */

package/dist/{store/embeddings → embeddings}/provider.js

@@ -1,13 +1,13 @@
 /** Pluggable embedding providers; local `@huggingface/transformers` is the zero-dependency default, OpenAI / Voyage / Cohere are opt-in via native `fetch`.
  * Local `id` is the bare model string, API `id` is `${kind}:${model}`; the stored identity adds `#t<N>` (`embeddingIndexIdentity`), so changes reindex.
  * `embed()` MAY throw on hard transport/auth failure so a reindex aborts atomically; hot paths wrap it and fall back to BM25. */
-import { envByName } from '../../util/env.js';
-import { getEmbedding, isEmbeddingAvailable, requireLocalPipeline, resolveEmbeddingModel, DEFAULT_EMBEDDING_MODEL, } from './local.js';
-import { loadConfig } from '../../core/config.js';
-import { errorMessage, log } from '../../util/log.js';
-import { redactSecretsStrict } from '../../util/secret-detect.js';
-import { fetchWithRetry } from '../../util/http-retry.js';
-import { readCappedJson, readCappedText } from '../../util/capped-json.js';
+import { envByName } from '../util/env.js';
+import { createLocalEmbedder, resolveEmbeddingModel, sharedLocalEmbedder, DEFAULT_EMBEDDING_MODEL, } from './local.js';
+import { loadConfig } from '../core/config.js';
+import { errorMessage, log } from '../util/log.js';
+import { redactSecretsStrict } from '../util/secret-detect.js';
+import { fetchWithRetry } from '../util/http-retry.js';
+import { readCappedJson, readCappedText } from '../util/capped-json.js';
 const ERROR_DETAIL_CHARS = 300;
 // An error body is read for its first lines only; 4x leaves room for multi-byte text.
 const ERROR_BODY_MAX_BYTES = ERROR_DETAIL_CHARS * 4;
@@ -27,24 +27,26 @@ const DEADLINE_RETRY_WAIT_CAP_MS = 2_000;
 class LocalEmbeddingProvider {
     model;
     enabled;
+    embedder;
     kind = 'local';
-    constructor(model, enabled = true) {
+    constructor(model, enabled, embedder) {
         this.model = model;
         this.enabled = enabled;
+        this.embedder = embedder;
     }
     get id() {
         return this.model;
     }
     isAvailable() {
-        return this.enabled && isEmbeddingAvailable();
+        return this.enabled && this.embedder.isAvailable();
     }
-    async embed(texts, role) {
+    async embed(texts, role, call = {}) {
         // A model that cannot load fails the call, as an API outage does; items then run one at a time on the shared pipeline.
         if (texts.length > 0)
-            await requireLocalPipeline(this.model);
+            await this.embedder.requirePipeline(this.model, call.signal);
         const out = [];
         for (const text of texts) {
-            out.push(await getEmbedding(text, this.model, role));
+            out.push(await this.embedder.embed(text, this.model, role));
         }
         return out;
     }
@@ -211,8 +213,8 @@ class ApiEmbeddingProvider {
             try {
                 detail = await readCappedText(resp, ERROR_BODY_MAX_BYTES);
             }
-            catch {
-                /* ignore body read error */
+            catch (err) {
+                log.debug(`${this.kind} embeddings error body unreadable: ${errorMessage(err)}`);
             }
             throw new Error(redact(`${this.kind} embeddings HTTP ${resp.status}: ${detail.slice(0, ERROR_DETAIL_CHARS)}`, key));
         }
@@ -264,7 +266,8 @@ export function resolveEmbeddingProvider(hippoRoot, opts = {}) {
     // and API providers — for API this prevents unwanted paid off-box calls.
     const enabled = cfg.enabled !== false;
     if (requested === 'local') {
-        return new LocalEmbeddingProvider(resolveEmbeddingModel(hippoRoot, opts.model), enabled);
+        const embedder = opts.transformers ? createLocalEmbedder(opts.transformers) : sharedLocalEmbedder;
+        return new LocalEmbeddingProvider(resolveEmbeddingModel(hippoRoot, opts.model), enabled, embedder);
     }
     if (!isApiProviderKind(requested)) {
         // Fail loud on a typo'd provider rather than silently using local (which

package/dist/embeddings/transformers.d.ts

@@ -0,0 +1,26 @@
+export interface TransformersPackage {
+    readonly name: string;
+    /** The ESM entry; a require-style import picks the CommonJS build and puts a second copy of the library, with its own ONNX sessions, in the process. */
+    readonly url: string;
+}
+/** The installed package to import, or null when neither is installed. */
+export declare function resolveTransformersPackage(): TransformersPackage | null;
+/** The package's module namespace, typed by the parts the caller reads; null when neither package is installed. */
+export declare function importTransformers<M>(): Promise<{
+    readonly name: string;
+    readonly mod: M;
+} | null>;
+export interface ModelLoadPolicy {
+    /** How long one load may run before it counts as failed; nothing can cancel it, so it keeps running and a late model is still kept. */
+    readonly timeoutMs: number;
+    /** How long a failure is answered from memory before the next call loads again. */
+    readonly backoffMs: number;
+}
+export declare const MODEL_LOAD_POLICY: ModelLoadPolicy;
+export interface ModelLoads<T> {
+    /** The model under `key`: the loaded one, the load in flight, the failure inside its backoff window, or a new `start()`. */
+    load(key: string, start: () => Promise<T>): Promise<T>;
+}
+/** One load per key at a time, bounded by the policy's timeout; `onFailure` hears each failed attempt, so once per backoff window. */
+export declare function createModelLoads<T>(policy: ModelLoadPolicy, onFailure?: (key: string, err: Error) => void): ModelLoads<T>;
+//# sourceMappingURL=transformers.d.ts.map