hippo-memory 1.70.0 → 1.72.0

package/dist/db/physics-state.js

@@ -1,16 +1,10 @@
-/**
- * Physics state persistence for Hippo.
- * Stores and loads particle state (position, velocity, mass, charge, temperature)
- * in SQLite using BLOB columns for 384-dim vectors.
- */
-import { evalNow } from '../core/ablation.js';
+/** Physics state persistence: particle state (position, velocity, mass, charge, temperature) in SQLite, with BLOB columns for 384-dim vectors. */
+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';
 import { DAY_MS } from '../util/time.js';
-// ---------------------------------------------------------------------------
 // Float32Array <-> Buffer serialization
-// ---------------------------------------------------------------------------
 export function float32ToBuffer(arr) {
     const f32 = new Float32Array(arr);
     return Buffer.from(f32.buffer);
@@ -24,13 +18,8 @@ export function bufferToFloat32(buf) {
     new Uint8Array(aligned).set(bytes);
     return Array.from(new Float32Array(aligned));
 }
-// ---------------------------------------------------------------------------
 // Schema migration
-// ---------------------------------------------------------------------------
-/**
- * Create the memory_physics table (migration v8).
- * Call this from db.ts MIGRATIONS array.
- */
+/** Create the memory_physics table (migration v8). */
 export function createPhysicsTable(db) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS memory_physics (
@@ -108,12 +97,9 @@ export function savePhysicsState(db, particles) {
         }
     });
 }
-/**
- * Initialize physics state for a memory from its embedding vector.
- * Returns the new particle (does not persist — caller must save).
- */
+/** 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,
@@ -125,34 +111,37 @@ export function initializeParticle(entry, embedding, now = evalNow()) {
         lastSimulation: now.toISOString(),
     };
 }
-/**
- * Reset all physics states from original embeddings.
- * Drops existing physics data and re-initializes from the embedding index.
- */
+const RESET_BATCH = 64;
+/** Drops every particle, then seeds one per entry that has an embedding; `entries` may be read lazily, as each batch is written before the next is read. */
 export function resetAllPhysicsState(db, entries, embeddingIndex, now = evalNow()) {
     db.exec('DELETE FROM memory_physics');
-    const particles = [];
-    for (const entry of entries) {
-        const embedding = embeddingIndex[entry.id];
-        if (!embedding || embedding.length === 0)
-            continue;
-        particles.push(initializeParticle(entry, embedding, now));
-    }
-    if (particles.length > 0) {
-        savePhysicsState(db, particles);
-    }
-    return particles.length;
+    // One transaction for every batch, so a failure part way leaves no particles rather than some.
+    return withWriteScope(db, 'reset_particles', () => {
+        let count = 0;
+        let batch = [];
+        const flush = () => {
+            savePhysicsState(db, batch);
+            count += batch.length;
+            batch = [];
+        };
+        for (const entry of entries) {
+            const embedding = embeddingIndex[entry.id];
+            if (!embedding || embedding.length === 0)
+                continue;
+            if (batch.push(initializeParticle(entry, embedding, now)) === RESET_BATCH)
+                flush();
+        }
+        flush();
+        return count;
+    });
 }
-/**
- * Refresh mass, charge, and temperature for existing particles
- * based on current memory attributes (called during consolidation).
- */
+/** Refresh mass, charge and temperature for existing particles from current memory attributes (called during consolidation). */
 export function refreshParticleProperties(particles, entries, now = evalNow()) {
     for (const p of particles) {
         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/raw-archive-mirror-cleanup.d.ts

@@ -1,20 +1,5 @@
 import type { DatabaseSyncLike } from './index.js';
-/**
- * Path A backfill cleanup: existing raw_archive rows that were archived BEFORE
- * commit 70180b5 left their markdown mirrors at <hippoRoot>/<layer>/<id>.md
- * with original content intact. The DB is already redacted via migration v20;
- * this function deletes those filesystem mirrors so RTBF holds for historical
- * archives too.
- *
- * Per-row tracking via raw_archive.mirror_cleaned_at (added in v21):
- *   - SELECT only rows WHERE mirror_cleaned_at IS NULL.
- *   - On success (every layer either deleted or didn't exist), UPDATE the row
- *     with the cleanup timestamp.
- *   - On any unlink failure, leave mirror_cleaned_at NULL so the next
- *     connection retries. Warn (capped at MAX_WARN_LOGS rows per call).
- *
- * Returns whether every pending row was cleaned; the SELECT has no index to
- * use, so a connection runs it only when the archive has changed since.
- */
+/** Path A backfill cleanup: delete markdown mirrors (<hippoRoot>/<layer>/<id>.md) of rows archived before redaction, so RTBF holds for historical archives.
+ * Tracked by raw_archive.mirror_cleaned_at: set only on success, so a failed unlink retries next connection. Returns whether all pending rows were cleaned. */
 export declare function cleanupArchivedMirrors(hippoRoot: string, db: DatabaseSyncLike): boolean;
 //# sourceMappingURL=raw-archive-mirror-cleanup.d.ts.map

package/dist/db/raw-archive-mirror-cleanup.js

@@ -3,23 +3,8 @@ import * as path from 'path';
 import { errorMessage, log } from '../util/log.js';
 const LAYERS = ['episodic', 'buffer', 'semantic'];
 const MAX_WARN_LOGS = 5;
-/**
- * Path A backfill cleanup: existing raw_archive rows that were archived BEFORE
- * commit 70180b5 left their markdown mirrors at <hippoRoot>/<layer>/<id>.md
- * with original content intact. The DB is already redacted via migration v20;
- * this function deletes those filesystem mirrors so RTBF holds for historical
- * archives too.
- *
- * Per-row tracking via raw_archive.mirror_cleaned_at (added in v21):
- *   - SELECT only rows WHERE mirror_cleaned_at IS NULL.
- *   - On success (every layer either deleted or didn't exist), UPDATE the row
- *     with the cleanup timestamp.
- *   - On any unlink failure, leave mirror_cleaned_at NULL so the next
- *     connection retries. Warn (capped at MAX_WARN_LOGS rows per call).
- *
- * Returns whether every pending row was cleaned; the SELECT has no index to
- * use, so a connection runs it only when the archive has changed since.
- */
+/** Path A backfill cleanup: delete markdown mirrors (<hippoRoot>/<layer>/<id>.md) of rows archived before redaction, so RTBF holds for historical archives.
+ * Tracked by raw_archive.mirror_cleaned_at: set only on success, so a failed unlink retries next connection. Returns whether all pending rows were cleaned. */
 export function cleanupArchivedMirrors(hippoRoot, db) {
     // SAFETY: the SELECT above names exactly one column, memory_id (raw_archive.memory_id
     // is NOT NULL TEXT), so the row shape matches this assertion.

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.d.ts

@@ -15,6 +15,8 @@ export declare function loadVectors(db: DatabaseSyncLike, ids?: readonly string[
 /** `loadVectors` for `ids` with no copy: each value views the bytes the store returned for that row. */
 export declare function loadVectorViews(db: DatabaseSyncLike, ids: readonly string[]): Map<string, Float32Array>;
 export declare function storedVectorIds(db: DatabaseSyncLike): Set<string>;
+/** Float count of the first stored row, from its blob length; the vector is never read. */
+export declare function storedVectorDims(db: DatabaseSyncLike): number | undefined;
 export declare function hasStoredVectors(db: DatabaseSyncLike): boolean;
 export interface VectorMatch {
     id: string;

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';
@@ -85,6 +85,12 @@ export function storedVectorIds(db) {
     // SAFETY: the SELECT names exactly the one column read.
     return new Set(db.prepare('SELECT memory_id FROM memory_vectors').all().map((r) => r.memory_id));
 }
+/** Float count of the first stored row, from its blob length; the vector is never read. */
+export function storedVectorDims(db) {
+    // SAFETY: the SELECT names exactly the one column read.
+    const row = db.prepare('SELECT length(vector) AS bytes FROM memory_vectors LIMIT 1').get();
+    return row === undefined ? undefined : Math.floor(row.bytes / 4);
+}
 export function hasStoredVectors(db) {
     return db.prepare('SELECT 1 FROM memory_vectors LIMIT 1').get() !== undefined;
 }
@@ -141,7 +147,8 @@ export async function topVectorMatches(db, query, k, where, params) {
     const best = bestMatches(query, k);
     if (!best)
         return [];
-    // SHORTCUT: brute-force cosine over every admitted vector, a chunk per event-loop turn; latency still grows with rows, fine to ~100k, and an ANN index (sqlite-vec, HNSW) is the upgrade.
+    // SHORTCUT: brute-force cosine over every admitted vector, a chunk per event-loop turn; latency
+    // still grows with rows, fine to ~100k, and an ANN index (sqlite-vec, HNSW) is the upgrade.
     // SAFETY: the SELECT names exactly these two columns; node:sqlite returns BLOBs as Uint8Array.
     const rows = db.prepare(`
     SELECT v.memory_id AS id, v.vector AS vector
@@ -181,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

@@ -1,23 +1,20 @@
-/**
- * `hippo doctor`: a health check people and agents can run after installing
- * hippo, or when something seems off. Read-only: it never creates a store,
- * installs a hook or migrates a database. Every non-passing check names the
- * command that fixes it, so an agent can act on the `--json` output.
- */
+/** `hippo doctor`: a read-only health check (never creates a store, installs a hook or migrates a database).
+ * Every non-passing check names the command that fixes it, so an agent can act on the `--json` output. */
 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 { getGlobalRoot } from './sharing/shared.js';
-import { isInitialized } from './store/open.js';
+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 { 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';
@@ -50,7 +47,12 @@ function codexCheck(home) {
     const parsed = readJson(file);
     // Codex drops every hook in a hooks.json it cannot parse, hippo's included.
     if (fs.existsSync(file) && !isJsonObjectLiteral(parsed)) {
-        return { id: 'codex', status: 'warn', detail: "Codex's hooks.json is not a JSON object, so Codex runs no hook from it", fix: 'repair hooks.json, then run: hippo hook install codex' };
+        return {
+            id: 'codex',
+            status: 'warn',
+            detail: "Codex's hooks.json is not a JSON object, so Codex runs no hook from it",
+            fix: 'repair hooks.json, then run: hippo hook install codex'
+        };
     }
     const text = JSON.stringify(parsed ?? '');
     const codexHooks = [
@@ -63,7 +65,9 @@ function codexCheck(home) {
     return {
         id: 'codex',
         status: 'warn',
-        detail: missing.length === codexHooks.length ? "Codex found, but hippo's memory hooks are not installed" : `Codex: hippo hooks missing for ${missing.join(', ')}`,
+        detail: missing.length === codexHooks.length
+            ? "Codex found, but hippo's memory hooks are not installed"
+            : `Codex: hippo hooks missing for ${missing.join(', ')}`,
         fix: 'hippo hook install codex   (then trust the hooks once in /hooks)',
     };
 }
@@ -88,7 +92,12 @@ function sleepCheck(lastSleep, now) {
     const last = lastSleep.value;
     const when = last !== undefined ? Date.parse(last) : Number.NaN;
     if (Number.isNaN(when)) {
-        return { id: 'sleep', status: 'warn', detail: 'hippo has never slept (consolidated) in this store', fix: 'hippo sleep   (the session-end hook runs it automatically)' };
+        return {
+            id: 'sleep',
+            status: 'warn',
+            detail: 'hippo has never slept (consolidated) in this store',
+            fix: 'hippo sleep   (the session-end hook runs it automatically)'
+        };
     }
     const days = Math.floor((now.getTime() - when) / DAY_MS);
     return days > 7
@@ -124,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('; ') };
 }
@@ -133,16 +143,23 @@ 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(', ')}` : '',
-            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('; ')}` : '',
+            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('; ')}`
+                : '',
             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' }
-            : { id: 'projects', status: 'warn', detail: `global store: ${found.join('; ')}`, fix: 'hippo projects repair --global   (dry run; add --apply to write)' };
+            : {
+                id: 'projects',
+                status: 'warn',
+                detail: `global store: ${found.join('; ')}`,
+                fix: 'hippo projects repair --global   (dry run; add --apply to write)'
+            };
     }
     catch (err) {
         return { id: 'projects', status: 'info', detail: `project tags not checked (${errorMessage(err)})` };
@@ -160,16 +177,43 @@ function nodeCheck(node) {
 /** 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)` : ''}` } };
+        return {
+            store: local,
+            check: { id: 'store', status: 'pass', detail: `project store at ${local}${hasGlobal ? ` (global store at ${globalRoot} too)` : ''}` }
+        };
     }
     if (local !== null) {
         // The walk stops at the first .hippo it finds, so a bare one (no hippo.db) blocks a parent or global store too.
-        return { store: null, check: { id: 'store', status: 'fail', detail: `${local} has no hippo.db, so hippo commands run here stop at it`, fix: `run hippo init in ${path.dirname(local)}, or remove that .hippo folder` } };
+        return {
+            store: null,
+            check: {
+                id: 'store',
+                status: 'fail',
+                detail: `${local} has no hippo.db, so hippo commands run here stop at it`,
+                fix: `run hippo init in ${path.dirname(local)}, or remove that .hippo folder`
+            }
+        };
     }
     if (hasGlobal) {
-        return { store: globalRoot, check: { id: 'store', status: 'warn', detail: `no project store here; using the global store at ${globalRoot}`, fix: 'hippo init   (in the project root)' } };
+        return {
+            store: globalRoot,
+            check: {
+                id: 'store',
+                status: 'warn',
+                detail: `no project store here; using the global store at ${globalRoot}`,
+                fix: 'hippo init   (in the project root)'
+            }
+        };
     }
-    return { store: null, check: { id: 'store', status: 'fail', detail: 'no hippo store found (project or global)', fix: 'hippo init   (in the project root), or hippo init --global' } };
+    return {
+        store: null,
+        check: {
+            id: 'store',
+            status: 'fail',
+            detail: 'no hippo store found (project or global)',
+            fix: 'hippo init   (in the project root), or hippo init --global'
+        }
+    };
 }
 function schemaCheck(have, want) {
     return have === want
@@ -211,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. */
@@ -269,7 +314,12 @@ function claudeCodeCheck(home) {
     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: hippo hooks missing for ${missing.join(', ')}`, fix: 'hippo hook install claude-code   (adds only what is missing)' };
+    return {
+        id: 'claude-code',
+        status: 'warn',
+        detail: `Claude Code: hippo hooks missing for ${missing.join(', ')}`,
+        fix: 'hippo hook install claude-code   (adds only what is missing)'
+    };
 }
 /** Run every check. Never throws for a broken install; broken parts become failed checks. */
 export function runDoctor(opts) {
@@ -287,14 +337,22 @@ export function runDoctor(opts) {
         checks.push(...databaseChecks(store, now));
     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})` });
+        checks.push({
+            id: 'pilot',
+            status: 'info',
+            detail: `pilot holdout on: about ${holdoutRateBp / 100}% of sessions get no memories pushed by hippo (pilot.holdoutRateBp=${holdoutRateBp})`
+        });
     }
     if (hasGlobal)
         checks.push(projectsCheck(globalRoot));
     checks.push(claudeCodeCheck(home));
     if (isCodexPresent(home))
         checks.push(codexCheck(home));
-    checks.push({ id: 'embeddings', status: 'info', detail: isEmbeddingAvailable() ? 'local embeddings available (hybrid search)' : 'embeddings not installed; recall uses BM25 (optional: hippo embed --help)' });
+    checks.push({
+        id: 'embeddings',
+        status: 'info',
+        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 };
 }
 /** Human-readable rendering of a {@link DoctorReport}. */

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