hippo-memory 1.72.0 → 2.1.0

package/dist/doctor.js

@@ -7,14 +7,14 @@ import { findHippoStoreDir, isInitialized } from './core/project-identity.js';
 import { getGlobalRoot } from './sharing/global-store.js';
 import { readStoreHealth } from './store/diagnostics.js';
 import { loadConfig } from './core/config.js';
-import { openHippoDbReadOnly, closeHippoDb, getCurrentSchemaVersion, IncompatibleBinaryError } from './db/index.js';
+import { getCurrentSchemaVersion, IncompatibleBinaryError, } from './db/index.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 './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 { readProjectTags } 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';
@@ -60,8 +60,9 @@ function codexCheck(home) {
         ['hippo compact-resume', 'resume after compaction'],
     ];
     const missing = codexHooks.filter(([marker]) => !text.includes(marker)).map(([, what]) => what);
-    if (missing.length === 0)
+    if (missing.length === 0) {
         return { id: 'codex', status: 'pass', detail: `Codex: hippo memory hooks installed. ${CODEX_TRUST_LINE}` };
+    }
     return {
         id: 'codex',
         status: 'warn',
@@ -76,14 +77,22 @@ const FAILURE_LOG_SCHEMA = 46;
 /** The failed-tool-call count over the last 7 days, or why it could not be read. */
 function failuresCheck(failures, schemaVersion) {
     if (failures.ok) {
-        return { id: 'failures', status: 'info', detail: `${failures.value} failed tool calls logged in 7 days (hippo failures for detail)` };
+        return {
+            id: 'failures',
+            status: 'info',
+            detail: `${failures.value} failed tool calls logged in 7 days (hippo failures for detail)`,
+        };
     }
     if (!failures.message.includes('no such table')) {
         return { id: 'failures', status: 'warn', detail: `cannot read the failure log: ${failures.message}` };
     }
     return schemaVersion < FAILURE_LOG_SCHEMA
         ? { id: 'failures', status: 'info', detail: 'no failure log yet (hippo creates it on the next write)' }
-        : { id: 'failures', status: 'warn', detail: 'the failure_log table is missing, so failed tool calls are not being logged' };
+        : {
+            id: 'failures',
+            status: 'warn',
+            detail: 'the failure_log table is missing, so failed tool calls are not being logged',
+        };
 }
 /** How long ago the store last slept (consolidated), or why that history could not be read. */
 function sleepCheck(lastSleep, now) {
@@ -101,56 +110,81 @@ function sleepCheck(lastSleep, now) {
     }
     const days = Math.floor((now.getTime() - when) / DAY_MS);
     return days > 7
-        ? { id: 'sleep', status: 'warn', detail: `last sleep ${days} days ago`, fix: 'hippo sleep, and check the session-end hook is installed' }
-        : { id: 'sleep', status: 'pass', detail: `last sleep ${days === 0 ? 'today' : `${days} day${days === 1 ? '' : 's'} ago`}` };
+        ? {
+            id: 'sleep',
+            status: 'warn',
+            detail: `last sleep ${days} days ago`,
+            fix: 'hippo sleep, and check the session-end hook is installed',
+        }
+        : {
+            id: 'sleep',
+            status: 'pass',
+            detail: `last sleep ${days === 0 ? 'today' : `${days} day${days === 1 ? '' : 's'} ago`}`,
+        };
 }
 /** Spool counts in their own try, so a spool that cannot be read never hides the database counts. */
-function readSpool(store, now) {
+function readSpool(store, now, spoolFs) {
     try {
-        return { counts: spoolCounts(store, now, REPLAY_AFTER_MS), unread: '' };
+        return { counts: spoolCounts(store, now, REPLAY_AFTER_MS, spoolFs), unread: '' };
     }
     catch (err) {
         return { counts: { waiting: 0, stale: 0, bad: 0 }, unread: `; spool not read: ${errorMessage(err)}` };
     }
 }
-/** Compaction records the PostCompact hook left unfinished and spool files a replay has not finished, which `hippo sleep` replays. */
-function compactionsCheck(compactions, store, now) {
+/**
+ * Compaction records the PostCompact hook left unfinished and spool files a replay has not finished, which `hippo
+ * sleep` replays.
+ */
+function compactionsCheck(compactions, store, now, spoolFs) {
     if (!compactions.ok) {
         return compactions.message.includes('no such table')
-            ? { id: 'compactions', status: 'info', detail: 'no compaction records yet (hippo creates them on the next write)' }
+            ? {
+                id: 'compactions',
+                status: 'info',
+                detail: 'no compaction records yet (hippo creates them on the next write)',
+            }
             : { id: 'compactions', status: 'warn', detail: `cannot read the compaction records: ${compactions.message}` };
     }
     const { total, summarised, started } = compactions.value;
     const stuck = summarised + started;
-    const { counts: spool, unread } = readSpool(store, now);
+    const { counts: spool, unread } = readSpool(store, now, spoolFs);
     const spooled = spool.waiting + spool.stale + spool.bad > 0;
     const recorded = `${total} compaction${total === 1 ? '' : 's'} recorded, none stuck`;
     if (stuck === 0 && !spooled && unread === '')
         return { id: 'compactions', status: 'pass', detail: recorded };
     const fix = [
         stuck + spool.waiting + spool.stale > 0 ? 'hippo sleep   (replays them)' : '',
-        spool.bad > 0 ? `open the .bad files in ${path.join(store, SPOOL_DIR)}, save what you still need with hippo remember, then delete them` : '',
+        spool.bad > 0
+            ? `open the .bad files in ${path.join(store, SPOOL_DIR)}, save what you still need with hippo remember, then ` +
+                `delete them`
+            : '',
     ].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)`;
-    const note = spooled ? `; spool: ${spool.waiting} waiting, ${spool.stale} left by a replay that stopped, ${spool.bad} .bad` : '';
+    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('; ') };
 }
 /** Old project tags in the global store, counted by the repair's own plan so a truly user-global merge never warns. */
 function projectsCheck(globalRoot) {
-    let db = null;
     try {
-        db = openHippoDbReadOnly(globalRoot);
-        const r = planProjectRepair(projectTagReads(db, resolveTenantId({})), globalRoot);
+        const r = readProjectTags(globalRoot, resolveTenantId({}), (reads) => planProjectRepair(reads, 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(', ')}` : '',
+            r.folds.length > 0
+                ? `old project names that now resolve to another project: ` +
+                    `${r.folds.map((f) => `${f.from} -> ${f.into}`).join(', ')}`
+                : '',
             r.collisions.length > 0
-                ? `old project names shared by several projects, folded by hand only: ${r.collisions.map((c) => `${c.name} (${c.ids.join(', ')})`).join('; ')}`
+                ? `old project names shared by several projects, folded by hand only: ` +
+                    `${r.collisions.map((c) => `${c.name} (${c.ids.join(', ')})`).join('; ')}`
+                : '',
+            r.toProject.length + r.setAside.length > 0
+                ? `${r.toProject.length + r.setAside.length} merged memories tagged user-global`
                 : '',
-            r.toProject.length + r.setAside.length > 0 ? `${r.toProject.length + r.setAside.length} merged memories tagged user-global` : '',
         ].filter((s) => s !== '');
         return found.length === 0
             ? { id: 'projects', status: 'pass', detail: 'no duplicate or out-of-date project tags in the global store' }
@@ -164,22 +198,27 @@ function projectsCheck(globalRoot) {
     catch (err) {
         return { id: 'projects', status: 'info', detail: `project tags not checked (${errorMessage(err)})` };
     }
-    finally {
-        if (db !== null)
-            closeHippoDb(db);
-    }
 }
 function nodeCheck(node) {
     return versionAtLeast(node, MIN_NODE)
         ? { id: 'node', status: 'pass', detail: `Node.js ${node}` }
-        : { id: 'node', status: 'fail', detail: `Node.js ${node} is older than ${MIN_NODE}`, fix: `Install Node.js ${MIN_NODE} or newer` };
+        : {
+            id: 'node',
+            status: 'fail',
+            detail: `Node.js ${node} is older than ${MIN_NODE}`,
+            fix: `Install Node.js ${MIN_NODE} or newer`,
+        };
 }
 /** The store the checks run against (project first, then global), and the check that says which. */
 function storeCheck(local, globalRoot, hasGlobal) {
     if (local !== null && isInitialized(local)) {
         return {
             store: local,
-            check: { id: 'store', status: 'pass', detail: `project store at ${local}${hasGlobal ? ` (global store at ${globalRoot} too)` : ''}` }
+            check: {
+                id: 'store',
+                status: 'pass',
+                detail: `project store at ${local}${hasGlobal ? ` (global store at ${globalRoot} too)` : ''}`,
+            },
         };
     }
     if (local !== null) {
@@ -219,30 +258,49 @@ function schemaCheck(have, want) {
     return have === want
         ? { id: 'schema', status: 'pass', detail: `database schema v${have}` }
         : have > want
-            ? { id: 'schema', status: 'fail', detail: `database schema v${have} is newer than this hippo (v${want})`, fix: 'npm install -g hippo-memory@latest' }
-            : { id: 'schema', status: 'info', detail: `database schema v${have}; hippo migrates it to v${want} on the next write` };
+            ? {
+                id: 'schema',
+                status: 'fail',
+                detail: `database schema v${have} is newer than this hippo (v${want})`,
+                fix: 'npm install -g hippo-memory@latest',
+            }
+            : {
+                id: 'schema',
+                status: 'info',
+                detail: `database schema v${have}; hippo migrates it to v${want} on the next write`,
+            };
 }
 function memoriesCheck(memories, dormant) {
-    const memoryCheck = { id: 'memories', status: 'info', detail: `${memories ?? '?'} memories${dormant !== null ? `, ${dormant} dormant` : ''}` };
+    const memoryCheck = {
+        id: 'memories',
+        status: 'info',
+        detail: `${memories ?? '?'} memories${dormant !== null ? `, ${dormant} dormant` : ''}`,
+    };
     if (memories === 0) {
         memoryCheck.status = 'warn';
         memoryCheck.fix = 'hippo learn --git   (seed lessons from git history)';
     }
     return memoryCheck;
 }
-/** Whether the full-text index still matches `memories`; opening a current store no longer checks, so doctor reports and sleep repairs. */
+/**
+ * Whether the full-text index still matches `memories`; opening a current store no longer checks, so doctor reports and
+ * sleep repairs.
+ */
 function ftsCheck(fts) {
     if (!fts.ok)
         return { id: 'fts', status: 'warn', detail: `cannot read the full-text index: ${fts.message}` };
     const counts = fts.value;
-    if (counts === null)
+    if (counts === null) {
         return { id: 'fts', status: 'info', detail: 'no full-text index; search uses slower LIKE matching' };
-    if (counts.memories === counts.fts)
+    }
+    if (counts.memories === counts.fts) {
         return { id: 'fts', status: 'pass', detail: `full-text index in sync (${counts.fts} rows)` };
+    }
     return {
         id: 'fts',
         status: 'warn',
-        detail: `full-text index out of sync: ${counts.fts} indexed rows for ${counts.memories} memories, so search can miss memories or match removed ones`,
+        detail: `full-text index out of sync: ${counts.fts} indexed rows for ${counts.memories} memories, so search can ` +
+            `miss memories or match removed ones`,
         fix: 'hippo sleep   (re-syncs the index)',
     };
 }
@@ -260,7 +318,7 @@ function tokensCheck(tokens) {
     };
 }
 /** Checks that read the store's database; a store that cannot be opened becomes one failed schema check. */
-function databaseChecks(store, now) {
+function databaseChecks(store, now, spoolFs) {
     let health;
     try {
         health = readStoreHealth(store, {
@@ -270,12 +328,16 @@ function databaseChecks(store, now) {
         });
     }
     catch (err) {
-        return [{
+        return [
+            {
                 id: 'schema',
                 status: 'fail',
                 detail: `cannot open the database: ${errorMessage(err)}`,
-                fix: err instanceof IncompatibleBinaryError ? 'npm install -g hippo-memory@latest' : 'check file permissions on the .hippo folder',
-            }];
+                fix: err instanceof IncompatibleBinaryError
+                    ? 'npm install -g hippo-memory@latest'
+                    : 'check file permissions on the .hippo folder',
+            },
+        ];
     }
     return [
         schemaCheck(health.schemaVersion, getCurrentSchemaVersion()),
@@ -284,7 +346,7 @@ function databaseChecks(store, now) {
         tokensCheck(health.tokens),
         failuresCheck(health.failures, health.schemaVersion),
         sleepCheck(health.lastSleep, now),
-        compactionsCheck(health.compactions, store, now),
+        compactionsCheck(health.compactions, store, now, spoolFs),
     ];
 }
 // Each hook and what it does, so a partial install says what is missing.
@@ -299,20 +361,37 @@ const CLAUDE_CODE_HOOKS = [
 function claudeCodeCheck(home) {
     const claudeDir = claudeConfigDir(home);
     if (!fs.existsSync(claudeDir)) {
-        return { id: 'claude-code', status: 'info', detail: 'Claude Code not found; other agents can use hippo over MCP (hippo mcp)' };
+        return {
+            id: 'claude-code',
+            status: 'info',
+            detail: 'Claude Code not found; other agents can use hippo over MCP (hippo mcp)',
+        };
     }
     const settings = readJson(path.join(claudeDir, 'settings.json'));
     const text = settings === null ? '' : JSON.stringify(settings);
     const viaPlugin = /hippo-memory@/.test(text);
     const missing = CLAUDE_CODE_HOOKS.filter(([marker]) => !text.includes(marker)).map(([, what]) => what);
     if (viaPlugin) {
-        return { id: 'claude-code', status: 'pass', detail: 'Claude Code: hippo plugin enabled (all hooks, including compaction and failed-tool capture)' };
+        return {
+            id: 'claude-code',
+            status: 'pass',
+            detail: 'Claude Code: hippo plugin enabled (all hooks, including compaction and failed-tool capture)',
+        };
     }
     if (missing.length === 0) {
-        return { id: 'claude-code', status: 'pass', detail: 'Claude Code: all hippo hooks installed, including compaction and failed-tool capture' };
+        return {
+            id: 'claude-code',
+            status: 'pass',
+            detail: 'Claude Code: all hippo hooks installed, including compaction and failed-tool capture',
+        };
     }
     if (missing.length === CLAUDE_CODE_HOOKS.length) {
-        return { id: 'claude-code', status: 'warn', detail: 'Claude Code found, but no hippo hooks are installed', fix: 'hippo hook install claude-code' };
+        return {
+            id: 'claude-code',
+            status: 'warn',
+            detail: 'Claude Code found, but no hippo hooks are installed',
+            fix: 'hippo hook install claude-code',
+        };
     }
     return {
         id: 'claude-code',
@@ -334,13 +413,14 @@ export function runDoctor(opts) {
     const { store, check } = storeCheck(local, globalRoot, hasGlobal);
     checks.push(check);
     if (store !== null)
-        checks.push(...databaseChecks(store, now));
+        checks.push(...databaseChecks(store, now, opts.spoolFs));
     const holdoutRateBp = store === null ? 0 : loadConfig(store).pilot.holdoutRateBp;
     if (holdoutRateBp > 0) {
         checks.push({
             id: 'pilot',
             status: 'info',
-            detail: `pilot holdout on: about ${holdoutRateBp / 100}% of sessions get no memories pushed by hippo (pilot.holdoutRateBp=${holdoutRateBp})`
+            detail: `pilot holdout on: about ${holdoutRateBp / 100}% of sessions get no memories pushed by hippo ` +
+                `(pilot.holdoutRateBp=${holdoutRateBp})`,
         });
     }
     if (hasGlobal)
@@ -351,7 +431,9 @@ export function runDoctor(opts) {
     checks.push({
         id: 'embeddings',
         status: 'info',
-        detail: isEmbeddingAvailable() ? 'local embeddings available (hybrid search)' : 'embeddings not installed; recall uses BM25 (optional: hippo embed --help)'
+        detail: isEmbeddingAvailable()
+            ? 'local embeddings available (hybrid search)'
+            : 'embeddings not installed; recall uses BM25 (optional: hippo embed --help)',
     });
     return { ok: !checks.some((c) => c.status === 'fail'), version: opts.version, store, checks };
 }

package/dist/embeddings/local.d.ts

@@ -1,4 +1,5 @@
-/** The one call this file makes on a Transformers.js feature-extraction pipeline, and the part of its tensor it reads. */
+/** 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';
@@ -25,7 +26,8 @@ interface TransformersModule {
     };
 }
 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. */
+/** 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';
@@ -44,7 +46,8 @@ export interface LocalTransformers {
 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. */
+     * `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[]>;
@@ -56,7 +59,8 @@ 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. */
+/** 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

@@ -7,7 +7,8 @@ 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. */
+/** 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';
 }
@@ -44,8 +45,8 @@ export function createLocalEmbedder(transformers = INSTALLED_TRANSFORMERS) {
                 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)}`);
+                // The caller sees `[]` and names the memory; the first failure per model is told, the repeats go to debug.
+                log.warnThenDebug(`local-embed:${model}`, `local embedding with ${model} failed: ${errorMessage(err)}`, errorFields(err));
                 return [];
             }
         },
@@ -57,7 +58,8 @@ function warnLoadFailure(model, 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.
+    // 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');
@@ -82,7 +84,8 @@ async function createPipeline(transformers, model, gates) {
         gates.delete(model);
     }
 }
-/** Whether the load will download: remote models are allowed and no folder the package reads holds the model's ONNX files. */
+/** 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;
@@ -135,11 +138,12 @@ export function resolveEmbeddingModel(hippoRoot, explicitModel) {
             return configured;
     }
     catch (err) {
-        log.warn(`embedding model config unreadable, using the default model: ${errorMessage(err)}`);
+        log.warn(`embedding model config unreadable, using the default model: ${errorMessage(err)}`, errorFields(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. */
+/** 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);
 }

package/dist/embeddings/provider.d.ts

@@ -1,18 +1,23 @@
-/** 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. */
+/** 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, 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 stops waiting only on a model download,
+    /** 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 {
     readonly kind: EmbeddingProviderKind;
     readonly model: string;
-    /** Identity recorded in DB meta to drive reindex-on-change: bare model string for local, `${kind}:${model}` for api. */
+    /** Identity recorded in DB meta to drive reindex-on-change:
+     * bare model string for local, `${kind}:${model}` for api. */
     readonly id: string;
     /** Known fixed output dimension, if any (undefined for local / unknown). */
     readonly dimensions?: number;
@@ -29,15 +34,19 @@ 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. */
+    /** 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()`);
+/** 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. */
 export declare function resolveEmbeddingProvider(hippoRoot: string, opts?: ResolveProviderOptions): EmbeddingProvider;
-/** The reindex identity for the active provider; use it, NOT resolveEmbeddingModel, wherever `embeddingModelRequiresReindex` / stored-model comparisons
- * happen. */
+/** The reindex identity for the active provider; use it, NOT
+ * resolveEmbeddingModel, wherever `embeddingModelRequiresReindex`
+ * / stored-model comparisons happen. */
 export declare function resolveEmbeddingIdentity(hippoRoot: string, opts?: ResolveProviderOptions): string;
-/** Provider-aware availability for a store (local: dependency installed; api: key present); use where the decision to embed is made. */
+/** Provider-aware availability for a store (local: dependency installed; api: key present); use where the decision
+ * to embed is made. */
 export declare function isEmbeddingConfigured(hippoRoot: string): boolean;
 //# sourceMappingURL=provider.d.ts.map

package/dist/embeddings/provider.js

@@ -1,10 +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. */
+/** 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 { createLocalEmbedder, resolveEmbeddingModel, sharedLocalEmbedder, DEFAULT_EMBEDDING_MODEL, } from './local.js';
 import { loadConfig } from '../core/config.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorMessage, log, errorFields } 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';
@@ -41,7 +44,8 @@ class LocalEmbeddingProvider {
         return this.enabled && this.embedder.isAvailable();
     }
     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.
+        // 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 this.embedder.requirePipeline(this.model, call.signal);
         const out = [];
@@ -97,7 +101,8 @@ const API_PROVIDER_SPECS = {
         }),
         extractVectors: (json) => {
             // Cohere v2 shape: { embeddings: { float: number[][] } }
-            // SAFETY: documented v2 envelope; embedChunk validates the vectors afterward, so a malformed response degrades to [] here and throws there.
+            // SAFETY: documented v2 envelope; embedChunk validates the vectors afterward, so a malformed response degrades to
+            // [] here and throws there.
             const emb = json.embeddings;
             return emb?.float ?? [];
         },
@@ -170,7 +175,8 @@ class ApiEmbeddingProvider {
         const resp = await this.postChunk(chunk, key, role, signal);
         const json = await this.responseJson(resp, key, chunk.length);
         const vectors = spec.extractVectors(json);
-        // A 200 with the wrong vector count (or any empty/malformed vector) is a provider contract violation, not a per-item miss:
+        // A 200 with the wrong vector count (or any empty/malformed vector) is a provider contract violation, not a
+        // per-item miss:
         // throw so a reindex aborts atomically and the explicit backfill surfaces it, instead of saving []-padded rows.
         if (vectors.length !== chunk.length) {
             throw new Error(redact(`${this.kind} embeddings returned ${vectors.length} vectors for ${chunk.length} inputs`, key));
@@ -196,14 +202,17 @@ class ApiEmbeddingProvider {
                 signal,
             }, {
                 timeoutMs: REQUEST_TIMEOUT_MS,
-                // Embedding the same text twice changes nothing on the far side, so a dropped connection or a stalled attempt is replayed.
+                // Embedding the same text twice changes nothing on the far side,
+                // so a dropped connection or a stalled attempt is replayed.
                 retryTransport: true,
                 maxDelayMs: signal ? DEADLINE_RETRY_WAIT_CAP_MS : undefined,
             });
         }
         catch (err) {
             const msg = errorMessage(err);
-            throw new Error(redact(`embedding request to ${this.kind} failed: ${msg}`, key), { cause: redactedCause(err, key) });
+            throw new Error(redact(`embedding request to ${this.kind} failed: ${msg}`, key), {
+                cause: redactedCause(err, key),
+            });
         }
     }
     /** The body of an OK reply; any other status, or a body that is not JSON, throws with the key cut out. */
@@ -214,7 +223,8 @@ class ApiEmbeddingProvider {
                 detail = await readCappedText(resp, ERROR_BODY_MAX_BYTES);
             }
             catch (err) {
-                log.debug(`${this.kind} embeddings error body unreadable: ${errorMessage(err)}`);
+                // The error thrown below already carries the status; the body is only extra detail.
+                log.debug(`${this.kind} embeddings error body unreadable: ${errorMessage(err)}`, errorFields(err));
             }
             throw new Error(redact(`${this.kind} embeddings HTTP ${resp.status}: ${detail.slice(0, ERROR_DETAIL_CHARS)}`, key));
         }
@@ -224,20 +234,11 @@ class ApiEmbeddingProvider {
         catch (err) {
             const msg = errorMessage(err);
             throw new Error(redact(`${this.kind} embeddings returned invalid JSON: ${msg}`, key), {
-                cause: redactedCause(err instanceof Error && err.cause ? err.cause : err, key)
+                cause: redactedCause(err instanceof Error && err.cause ? err.cause : err, key),
             });
         }
     }
 }
-function readEmbeddingsConfig(hippoRoot) {
-    try {
-        return loadConfig(hippoRoot).embeddings;
-    }
-    catch {
-        // An unreadable config falls back to provider defaults; loadConfig warns on a bad parse.
-        return {};
-    }
-}
 /** Validate a user-supplied API base URL: HTTPS only (or explicit localhost). */
 function validateBaseUrl(url, fallback) {
     const candidate = url?.trim();
@@ -257,10 +258,11 @@ function validateBaseUrl(url, fallback) {
     }
     return candidate;
 }
-/** Build the active embedding provider from config (or an explicit override). A missing key never throws here (it surfaces via `isAvailable()`);
+/** 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. */
 export function resolveEmbeddingProvider(hippoRoot, opts = {}) {
-    const cfg = readEmbeddingsConfig(hippoRoot);
+    const cfg = loadConfig(hippoRoot).embeddings;
     const requested = opts.provider ?? cfg.provider ?? 'local';
     // An explicit embeddings.enabled=false hard-disables embedding for BOTH local
     // and API providers — for API this prevents unwanted paid off-box calls.
@@ -272,7 +274,8 @@ export function resolveEmbeddingProvider(hippoRoot, opts = {}) {
     if (!isApiProviderKind(requested)) {
         // Fail loud on a typo'd provider rather than silently using local (which
         // would reindex with the local model and clobber the intended identity).
-        throw new Error(`Unknown embeddings.provider '${requested}'. Valid values: local, ${API_PROVIDER_KINDS.filter((k) => k !== 'local').join(', ')}.`);
+        throw new Error(`Unknown embeddings.provider '${requested}'. Valid values: local, ` +
+            `${API_PROVIDER_KINDS.filter((k) => k !== 'local').join(', ')}.`);
     }
     const kind = requested;
     const spec = API_PROVIDER_SPECS[kind];
@@ -286,19 +289,21 @@ export function resolveEmbeddingProvider(hippoRoot, opts = {}) {
         : DEFAULT_API_BATCH_SIZE;
     return new ApiEmbeddingProvider(kind, model, baseUrl, batchSize, enabled);
 }
-/** The reindex identity for the active provider; use it, NOT resolveEmbeddingModel, wherever `embeddingModelRequiresReindex` / stored-model comparisons
- * happen. */
+/** The reindex identity for the active provider; use it, NOT
+ * resolveEmbeddingModel, wherever `embeddingModelRequiresReindex`
+ * / stored-model comparisons happen. */
 export function resolveEmbeddingIdentity(hippoRoot, opts = {}) {
     return resolveEmbeddingProvider(hippoRoot, opts).id;
 }
-/** Provider-aware availability for a store (local: dependency installed; api: key present); use where the decision to embed is made. */
+/** Provider-aware availability for a store (local: dependency installed; api: key present); use where the decision
+ * to embed is made. */
 export function isEmbeddingConfigured(hippoRoot) {
     try {
         return resolveEmbeddingProvider(hippoRoot).isAvailable();
     }
     catch (err) {
         // An invalid embedding config must not crash the best-effort ingestion guard, so it reads as not configured.
-        log.debug(`embedding config unusable: ${errorMessage(err)}`);
+        log.warnThenDebug(`embedding-config-unusable:${hippoRoot}`, `embedding config unusable: ${errorMessage(err)}`, errorFields(err));
         return false;
     }
 }