hippo-memory 1.69.0 → 1.70.0

package/dist/store/doctor-reads.js

@@ -0,0 +1,19 @@
+/** Compaction records in all, those with a summary whose memories never got saved, and those still without a summary; each cutoff is an ISO time. */
+export function compactionCountsAt(db, stuckBefore, transcriptFloor) {
+    // SAFETY: COUNT aggregate row.
+    const row = db.prepare(`SELECT COUNT(*) AS total,
+              COUNT(CASE WHEN status = 'summarised' AND summarised_at < ? THEN 1 END) AS summarised,
+              COUNT(CASE WHEN status = 'started' AND started_at < ? AND started_at > ? AND transcript_path IS NOT NULL THEN 1 END) AS started
+       FROM compactions`).get(stuckBefore, stuckBefore, transcriptFloor);
+    return { total: Number(row?.total ?? 0), summarised: Number(row?.summarised ?? 0), started: Number(row?.started ?? 0) };
+}
+/** Memory blocks injected since `sinceIso`, the tokens they sent and the tokens later model calls re-read. */
+export function tokenTallySince(db, sinceIso) {
+    // SAFETY: COUNT/SUM aggregate row.
+    const row = db.prepare(`SELECT COUNT(CASE WHEN event = 'inject' THEN 1 END) AS n,
+              COALESCE(SUM(CASE WHEN event = 'inject' THEN tokens END), 0) AS t,
+              COALESCE(SUM(CASE WHEN event = 'reread' THEN tokens END), 0) AS r
+       FROM token_ledger WHERE ts >= ?`).get(sinceIso);
+    return { injected: Number(row?.n ?? 0), tokensSent: Number(row?.t ?? 0), tokensReread: Number(row?.r ?? 0) };
+}
+//# sourceMappingURL=doctor-reads.js.map

package/dist/{dormant.d.ts → store/dormant.d.ts}

@@ -13,13 +13,14 @@
  * `hippo forget --archive`): that path removes a raw receipt's content and
  * keeps only its metadata. A dormant memory keeps its content.
  *
- * DB-only helpers: the caller owns the handle and any transaction. The
- * tenant-scoped entry points are api.listDormant / restoreDormant /
- * forgetDormant.
+ * The db-taking helpers leave the handle and any transaction to the caller.
+ * The hippoRoot-taking functions at the end open one of their own, for
+ * api.listDormant / restoreDormant / forgetDormant / isDormant.
  */
-import type { DatabaseSyncLike } from './db.js';
-import type { MemoryEntry } from './memory.js';
+import { type DatabaseSyncLike } from '../db/index.js';
+import type { MemoryEntry } from '../core/memory.js';
 import type { SqlFragment } from './recall-scope.js';
+import type { WriteBudget } from '../util/write-budget.js';
 /** Why a memory went dormant: sleep's decay pass, an imported agent memory whose note was deleted, `hippo projects repair` splitting a two-project merge, or `hippo audit repair` setting aside an automatic memory with a certain defect. */
 export type DormantReason = 'decay' | 'source-deleted' | 'project-repair' | 'quality-repair';
 /** One memory that sleep is moving out of active memory into the dormant store. */
@@ -58,8 +59,6 @@ export interface ListDormantOpts {
  * memory is never in both places or in neither.
  */
 export declare function insertDormantRow(db: DatabaseSyncLike, move: DormantMove): void;
-/** A tenant's dormant memories whose scope `admit` passes, newest first, optionally filtered by search terms. */
-export declare function listDormantRows(db: DatabaseSyncLike, tenantId: string, opts?: ListDormantOpts, admit?: SqlFragment): DormantMemory[];
 /** A dormant memory's stored snapshot plus when and why it went dormant. */
 export interface DormantSnapshot {
     entry: MemoryEntry;
@@ -78,16 +77,51 @@ export declare function listDormantSnapshots(db: DatabaseSyncLike, tenantId: str
 export declare function dormantSnapshotsBySourcePrefix(db: DatabaseSyncLike, tenantId: string, prefix: string): DormantSnapshot[];
 /** Put `entry` in place of a tenant's dormant memory `id`, keeping when and why that one went dormant. */
 export declare function replaceDormantEntry(db: DatabaseSyncLike, tenantId: string, id: string, entry: MemoryEntry): void;
-/** Whether a tenant has a dormant memory with this id whose scope `admit` passes (snapshot readable or not). */
-export declare function hasDormantRow(db: DatabaseSyncLike, tenantId: string, id: string, admit?: SqlFragment): boolean;
 /** Delete a tenant's dormant memory. Returns false when there was none. */
 export declare function deleteDormantRow(db: DatabaseSyncLike, tenantId: string, id: string): boolean;
 /** Deletes the tenant's dormant copies of a rejected digest whose snapshot scope `inReach` admits, so the value cannot linger; returns their ids. */
 export declare function purgeDormantByDigest(db: DatabaseSyncLike, tenantId: string, digest: string, inReach: (scope: string | null) => boolean): string[];
-export interface DormantKey {
+/** Deletes for good every memory that went dormant before `cutoffIso`, on one handle; returns how many went, or under `dryRun` how many would. */
+export declare function expireDormantBefore(hippoRoot: string, cutoffIso: string, opts: {
+    dryRun: boolean;
+    budget: WriteBudget;
+    busyWaitMs: number;
+}): Promise<number>;
+/** A tenant's dormant memories whose scope `admit` passes, newest first, read on a handle of its own. */
+export declare function loadDormantMemories(hippoRoot: string, tenantId: string, opts?: ListDormantOpts, admit?: SqlFragment): DormantMemory[];
+/** Whether a tenant holds a dormant memory with this id whose scope `admit` passes, read on a handle of its own. */
+export declare function holdsDormantMemory(hippoRoot: string, tenantId: string, id: string, admit?: SqlFragment): boolean;
+/** One restore as the store applies it. The two functions are the caller's policy over plain rows; neither is handed the handle. */
+export interface DormantRestore {
     readonly tenantId: string;
     readonly id: string;
+    /** Who restores, for the audit rows. */
+    readonly actor: string;
+    /** False for a snapshot this caller may not touch, which then reads as missing. */
+    readonly inReach: (scope: string | null) => boolean;
+    /** The live memory the snapshot comes back as at `now`; a throw refuses before any write. */
+    readonly revive: (snapshot: DormantSnapshot, now: Date) => MemoryEntry;
 }
-export declare function expiredDormantKeys(db: DatabaseSyncLike, cutoffIso: string): DormantKey[];
-export declare function deleteExpiredDormantRow(db: DatabaseSyncLike, key: DormantKey, cutoffIso: string): number;
+/** The restored memory, or why nothing was written: no dormant copy in reach, or a live memory already holds the id. */
+export type DormantRestoreOutcome = {
+    readonly status: 'restored';
+    readonly entry: MemoryEntry;
+} | {
+    readonly status: 'missing';
+} | {
+    readonly status: 'active';
+};
+/** Brings one dormant memory back on a single handle: the live row, the dormant delete and the audit row commit together, then its mirrors are written. */
+export declare function restoreDormantMemory(hippoRoot: string, restore: DormantRestore): DormantRestoreOutcome;
+/** One permanent delete of a dormant memory. */
+export interface DormantForget {
+    readonly tenantId: string;
+    readonly id: string;
+    /** Who forgets, for the audit row. */
+    readonly actor: string;
+    /** The scopes this caller may touch; a row outside them reads as missing. */
+    readonly admit: SqlFragment;
+}
+/** Deletes a tenant's dormant memory for good and writes its `forget` audit row, on a single handle; false when it holds none `admit` passes. */
+export declare function forgetDormantMemory(hippoRoot: string, forget: DormantForget): boolean;
 //# sourceMappingURL=dormant.d.ts.map

package/dist/{dormant.js → store/dormant.js}

@@ -1,5 +1,31 @@
-import { rejectionDigest } from './rejection.js';
-import { escapeLike } from './escape.js';
+/**
+ * Dormant memories: what sleep does with a faded memory instead of deleting
+ * it (config `dormant.enabled`, on by default; `retentionDays` bounds how
+ * long one is kept).
+ *
+ * A dormant memory keeps its full content in `dormant_memories` (schema v44)
+ * but is no longer a `memories` row, so recall, context, every sleep pass and
+ * every other reader of `memories` stop seeing it exactly as if it had been
+ * deleted. `hippo dormant` lists and searches them, `hippo dormant restore`
+ * brings one back, `hippo dormant forget` deletes one for good.
+ *
+ * Not to be confused with the raw archive (`raw_archive`, `archiveRawMemory`,
+ * `hippo forget --archive`): that path removes a raw receipt's content and
+ * keeps only its metadata. A dormant memory keeps its content.
+ *
+ * The db-taking helpers leave the handle and any transaction to the caller.
+ * The hippoRoot-taking functions at the end open one of their own, for
+ * api.listDormant / restoreDormant / forgetDormant / isDormant.
+ */
+import { closeHippoDb, openHippoDb, withWriteScope, withWriteScopeOr } from '../db/index.js';
+import { RejectedValueError, rejectionDigest } from './rejection.js';
+import { escapeLike } from '../util/escape.js';
+import { warnDamagedColumn } from '../util/stored-json.js';
+import { DAY_MS } from '../util/time.js';
+import { appendAuditEvent } from './audit.js';
+import { audit, auditRejectionRefusal } from './audit-event.js';
+import { entryIdTakenAt } from './entry-reads.js';
+import { writeEntryDbOnly, writeEntryMirrors } from './entry-writes.js';
 const DEFAULT_LIST_LIMIT = 20;
 /**
  * Insert (or refresh) the dormant snapshot for `move.entry`. Does not touch
@@ -34,6 +60,7 @@ function parseSnapshot(row) {
     }
     catch {
         // A row that will not parse is out of shape, so it is not restorable.
+        warnDamagedColumn({ table: 'dormant_memories', id: row.id, column: 'entry_json' }, 'not valid JSON');
         return null;
     }
 }
@@ -53,7 +80,7 @@ function rowToDormantMemory(row) {
 const DORMANT_WITH_SCOPE = `(SELECT *, CASE WHEN json_valid(entry_json) THEN json_extract(entry_json, '$.scope') END AS scope FROM dormant_memories)`;
 const EVERY_SCOPE = { sql: '1', params: [] };
 /** A tenant's dormant memories whose scope `admit` passes, newest first, optionally filtered by search terms. */
-export function listDormantRows(db, tenantId, opts = {}, admit = EVERY_SCOPE) {
+function listDormantRows(db, tenantId, opts = {}, admit = EVERY_SCOPE) {
     const terms = (opts.query ?? '').trim().split(/\s+/).filter((t) => t.length > 0);
     const limit = opts.limit !== undefined && Number.isFinite(opts.limit) && opts.limit >= 1
         ? Math.floor(opts.limit)
@@ -103,7 +130,7 @@ export function replaceDormantEntry(db, tenantId, id, entry) {
         .run(entry.id, entry.content, JSON.stringify(entry), tenantId, id);
 }
 /** Whether a tenant has a dormant memory with this id whose scope `admit` passes (snapshot readable or not). */
-export function hasDormantRow(db, tenantId, id, admit = EVERY_SCOPE) {
+function hasDormantRow(db, tenantId, id, admit = EVERY_SCOPE) {
     return db.prepare(`SELECT 1 FROM ${DORMANT_WITH_SCOPE} WHERE tenant_id = ? AND id = ? AND ${admit.sql}`).get(tenantId, id, ...admit.params) !== undefined;
 }
 /** Delete a tenant's dormant memory. Returns false when there was none. */
@@ -125,13 +152,131 @@ export function purgeDormantByDigest(db, tenantId, digest, inReach) {
     }
     return removed;
 }
-export function expiredDormantKeys(db, cutoffIso) {
+function expiredDormantKeys(db, cutoffIso) {
     const sql = `SELECT tenant_id AS tenantId, id FROM dormant_memories WHERE dormant_at < ?`;
     // SAFETY: rows' shape matches the two columns named in the SELECT.
     return db.prepare(sql).all(cutoffIso);
 }
-export function deleteExpiredDormantRow(db, key, cutoffIso) {
+function deleteExpiredDormantRow(db, key, cutoffIso) {
     const sql = `DELETE FROM dormant_memories WHERE tenant_id = ? AND id = ? AND dormant_at < ?`;
     return Number(db.prepare(sql).run(key.tenantId, key.id, cutoffIso).changes ?? 0);
 }
+/** Deletes `keys` in transactions of about `budget.holdMs`, letting other writers in between; returns how many went. */
+async function expireInChunks(db, keys, cutoffIso, budget) {
+    let gone = 0;
+    let next = 0;
+    let committedAt = 0;
+    while (next < keys.length) {
+        if (next > 0)
+            await budget.pause(committedAt);
+        withWriteScope(db, 'expire_dormant_chunk', () => {
+            const begunAt = budget.clock();
+            do
+                gone += deleteExpiredDormantRow(db, keys[next++], cutoffIso);
+            while (next < keys.length && budget.clock() - begunAt < budget.holdMs);
+        });
+        committedAt = budget.clock();
+    }
+    return gone;
+}
+/** Deletes for good every memory that went dormant before `cutoffIso`, on one handle; returns how many went, or under `dryRun` how many would. */
+export async function expireDormantBefore(hippoRoot, cutoffIso, opts) {
+    const db = openHippoDb(hippoRoot, { busyWaitMs: opts.busyWaitMs });
+    try {
+        // The keys come from a read, so a run with nothing to expire never takes the write lock.
+        const keys = expiredDormantKeys(db, cutoffIso);
+        return opts.dryRun ? keys.length : await expireInChunks(db, keys, cutoffIso, opts.budget);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** A tenant's dormant memories whose scope `admit` passes, newest first, read on a handle of its own. */
+export function loadDormantMemories(hippoRoot, tenantId, opts = {}, admit = EVERY_SCOPE) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        return listDormantRows(db, tenantId, opts, admit);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Whether a tenant holds a dormant memory with this id whose scope `admit` passes, read on a handle of its own. */
+export function holdsDormantMemory(hippoRoot, tenantId, id, admit = EVERY_SCOPE) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        return hasDormantRow(db, tenantId, id, admit);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+function auditDormantRestore(db, restore, snapshot, now) {
+    appendAuditEvent(db, {
+        tenantId: restore.tenantId,
+        actor: restore.actor,
+        op: 'dormant_restore',
+        targetId: restore.id,
+        metadata: {
+            reason: snapshot.reason,
+            strengthAtDormancy: snapshot.strength,
+            dormantAt: snapshot.dormantAt,
+            daysDormant: Math.max(0, (now.getTime() - Date.parse(snapshot.dormantAt)) / DAY_MS),
+        },
+    });
+}
+function restoreInWriteScope(db, restore) {
+    return withWriteScopeOr(db, 'restore_dormant', (rollback) => {
+        const snapshot = readDormantSnapshot(db, restore.tenantId, restore.id);
+        if (!snapshot || !restore.inReach(snapshot.entry.scope ?? null))
+            return rollback({ status: 'missing' });
+        if (entryIdTakenAt(db, restore.id))
+            return rollback({ status: 'active' });
+        const now = new Date();
+        const entry = restore.revive(snapshot, now);
+        writeEntryDbOnly(db, entry, { actor: restore.actor });
+        deleteDormantRow(db, restore.tenantId, restore.id);
+        // A restore is a labelled "forgot it, then needed it" event, the signal a learned lifecycle trains on.
+        // Same write scope as the restore, so the label exists exactly when the restore does.
+        auditDormantRestore(db, restore, snapshot, now);
+        return { status: 'restored', entry };
+    });
+}
+/** Brings one dormant memory back on a single handle: the live row, the dormant delete and the audit row commit together, then its mirrors are written. */
+export function restoreDormantMemory(hippoRoot, restore) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        let outcome;
+        try {
+            outcome = restoreInWriteScope(db, restore);
+        }
+        catch (error) {
+            // Written after the rollback, so the refusal row outlives it.
+            if (error instanceof RejectedValueError)
+                auditRejectionRefusal(db, error, restore.actor);
+            throw error;
+        }
+        if (outcome.status === 'restored')
+            writeEntryMirrors(hippoRoot, outcome.entry);
+        return outcome;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Deletes a tenant's dormant memory for good and writes its `forget` audit row, on a single handle; false when it holds none `admit` passes. */
+export function forgetDormantMemory(hippoRoot, forget) {
+    const { tenantId, id, actor, admit } = forget;
+    const db = openHippoDb(hippoRoot);
+    try {
+        if (!hasDormantRow(db, tenantId, id, admit) || !deleteDormantRow(db, tenantId, id))
+            return false;
+        // Best-effort, like every other forget audit row: the delete stands.
+        audit(db, 'forget', { tenantId, actor, targetId: id, metadata: { dormant: true } });
+        return true;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 //# sourceMappingURL=dormant.js.map

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

@@ -3,11 +3,11 @@
  * Uses @huggingface/transformers (local, zero API keys, ~22MB model).
  * Falls back silently if the library is not installed.
  */
-import { MemoryEntry } from './memory.js';
-import { type DatabaseSyncLike } from './db.js';
-import { EMBEDDING_MODEL_META_KEY } from './vector-store.js';
-import { type EmbeddingProvider } from './embedding-provider.js';
-import type { HippoStore } from './store-port.js';
+import { MemoryEntry } from '../../core/memory.js';
+import { type DatabaseSyncLike } from '../../db/index.js';
+import { EMBEDDING_MODEL_META_KEY } from '../../db/vector-store.js';
+import { type EmbeddingProvider } from './provider.js';
+import type { HippoStore } from '../index.js';
 export { EMBEDDING_MODEL_META_KEY };
 /**
  * Bump whenever `embeddingInputText`'s composition changes in a way that
@@ -87,10 +87,14 @@ export declare function embeddingIndexStateOn(db: DatabaseSyncLike): EmbeddingIn
  * Returns 0 for empty or mismatched vectors.
  */
 export declare function cosineSimilarity(a: number[], b: number[]): number;
+/** `cosineSimilarity` over any indexable vectors; a Float32 view reads the same doubles as its number[] copy, so the score is the same. */
+export declare function cosineOf(a: ArrayLike<number>, b: ArrayLike<number>): number;
 /** Every stored vector keyed by memory id; `{}` when none. Search reads only the rows it ranks via `loadStoredVectors`. */
 export declare function loadEmbeddingIndex(hippoRoot: string): Record<string, number[]>;
 /** Stored vectors for `ids` only. */
 export declare function loadStoredVectors(hippoRoot: string, ids: readonly string[]): Map<string, number[]>;
+/** `loadStoredVectors` as Float32 views, for a caller that only scores them. */
+export declare function loadStoredVectorViews(hippoRoot: string, ids: readonly string[]): Map<string, Float32Array>;
 /** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
 export declare function saveEmbeddingIndex(hippoRoot: string, index: Record<string, number[]>, model?: string): void;
 /** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
@@ -98,4 +102,4 @@ export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model
 /** Embeds every entry with no cached vector, prunes vectors of deleted memories, and returns how many it embedded; `provider` defaults to the
  *  configured one. With `store`, every tenant's memories with no vector for the provider's model go through its `vectorWrites`, never hippo.db. */
 export declare function embedAll(hippoRoot: string, model?: string, provider?: EmbeddingProvider, store?: HippoStore): Promise<number>;
-//# sourceMappingURL=embeddings.d.ts.map
+//# sourceMappingURL=index.d.ts.map

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

@@ -3,20 +3,20 @@
  * Uses @huggingface/transformers (local, zero API keys, ~22MB model).
  * Falls back silently if the library is not installed.
  */
-import { envByName } from './env.js';
+import { envByName } from '../../util/env.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
-import { loadAllEntries } from './store/entry-reads.js';
-import { openHippoDb, closeHippoDb, getMeta, rethrowIfSqliteBlocked, setMeta } from './db.js';
-import { EMBEDDING_MODEL_META_KEY, deleteOrphanVectors, hasStoredVectors, loadVectors, replaceAllVectors, storedVectorIds, upsertVectors, } from './vector-store.js';
-import { initializeParticle, savePhysicsState, loadPhysicsState, resetAllPhysicsState } from './physics-state.js';
-import { loadConfig } from './config.js';
-import { resolveEmbeddingProvider } from './embedding-provider.js';
-import { DEFAULT_EMBEDDING_MODEL } from './local-embedding.js';
-import { redactSecretsStrict } from './secret-detect.js';
-import { log } from './log.js';
-import { StoreNotPortedError } from './db/sqlite-blocked.js';
+import { loadAllEntries } from '../entry-reads.js';
+import { openHippoDb, closeHippoDb, getMeta, rethrowIfSqliteBlocked, setMeta } from '../../db/index.js';
+import { EMBEDDING_MODEL_META_KEY, deleteOrphanVectors, hasStoredVectors, loadVectors, loadVectorViews, replaceAllVectors, storedVectorIds, upsertVectors, } from '../../db/vector-store.js';
+import { initializeParticle, savePhysicsState, loadPhysicsState, resetAllPhysicsState } from '../../db/physics-state.js';
+import { loadConfig } from '../../core/config.js';
+import { resolveEmbeddingProvider } from './provider.js';
+import { DEFAULT_EMBEDDING_MODEL } from './local.js';
+import { redactSecretsStrict } from '../../util/secret-detect.js';
+import { errorMessage, log } from '../../util/log.js';
+import { StoreNotPortedError } from '../../util/sqlite-blocked.js';
 export { EMBEDDING_MODEL_META_KEY };
 /**
  * Bump whenever `embeddingInputText`'s composition changes in a way that
@@ -83,7 +83,7 @@ function loadStoredEmbeddingModel(hippoRoot) {
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);
-        log.debug(`stored embedding model unreadable: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`stored embedding model unreadable: ${errorMessage(err)}`);
         return null;
     }
 }
@@ -166,7 +166,7 @@ function resetPhysicsFromIndex(hippoRoot, entries, index) {
     }
     catch (err) {
         // Best effort: retrieval still falls back without physics state.
-        log.warn(`physics reset after reindex failed: ${err instanceof Error ? err.message : String(err)}`);
+        log.warn(`physics reset after reindex failed: ${errorMessage(err)}`);
     }
 }
 /** A provider's `[]` row is a swallowed per-item failure; name the memory so the gap can be traced. */
@@ -178,6 +178,10 @@ function noteSkippedEmbedding(id) {
  * Returns 0 for empty or mismatched vectors.
  */
 export function cosineSimilarity(a, b) {
+    return cosineOf(a, b);
+}
+/** `cosineSimilarity` over any indexable vectors; a Float32 view reads the same doubles as its number[] copy, so the score is the same. */
+export function cosineOf(a, b) {
     if (a.length === 0 || b.length === 0 || a.length !== b.length)
         return 0;
     let dot = 0;
@@ -211,6 +215,10 @@ export function loadEmbeddingIndex(hippoRoot) {
 export function loadStoredVectors(hippoRoot, ids) {
     return ids.length === 0 ? new Map() : withVectorDb(hippoRoot, (db) => loadVectors(db, ids));
 }
+/** `loadStoredVectors` as Float32 views, for a caller that only scores them. */
+export function loadStoredVectorViews(hippoRoot, ids) {
+    return ids.length === 0 ? new Map() : withVectorDb(hippoRoot, (db) => loadVectorViews(db, ids));
+}
 /** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
 export function saveEmbeddingIndex(hippoRoot, index, model) {
     withVectorDb(hippoRoot, (db) => replaceAllVectors(db, index, model ?? getMeta(db, EMBEDDING_MODEL_META_KEY, '')));
@@ -381,10 +389,10 @@ function embedMemoryInStore(store, provider, entry) {
                 warnEmbedFailureOnce('index', OTHER_MODEL_INDEX);
         }
         catch (err) {
-            warnEmbedFailureOnce(provider.kind, err instanceof Error ? err.message : String(err));
+            warnEmbedFailureOnce(provider.kind, errorMessage(err));
         }
     }).catch((err) => {
-        log.warn(`skipped embedding ${entry.id} (${err instanceof Error ? err.message : String(err)})`);
+        log.warn(`skipped embedding ${entry.id} (${errorMessage(err)})`);
     });
 }
 /** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
@@ -395,7 +403,7 @@ export async function embedMemory(hippoRoot, entry, model, store) {
     }
     catch (err) {
         // Callers fire and forget, so this must resolve: a bad config warns once instead of rejecting.
-        warnEmbedFailureOnce('config', err instanceof Error ? err.message : String(err));
+        warnEmbedFailureOnce('config', errorMessage(err));
         return;
     }
     if (!provider.isAvailable())
@@ -410,15 +418,7 @@ export async function embedMemory(hippoRoot, entry, model, store) {
         try {
             const identity = provider.id;
             if (embeddingModelRequiresReindex(hippoRoot, identity)) {
-                // Host-wide rebuild. The embedding index is keyed by entry.id
-                // (which is tenant-scoped) but the index itself is one per hippoRoot.
-                // Cross-tenant content equivalence is visible at the vector level.
-                // Per-tenant indices would be a larger architecture change.
-                const entries = loadAllEntries(hippoRoot);
-                const rebuiltIndex = await rebuildEmbeddingIndex(entries, provider);
-                saveEmbeddingIndex(hippoRoot, rebuiltIndex, embeddingIndexIdentity(identity));
-                saveStoredEmbeddingModel(hippoRoot, identity);
-                resetPhysicsFromIndex(hippoRoot, entries, rebuiltIndex);
+                await rebuildIndexForProvider(hippoRoot, provider);
                 return;
             }
             const text = embeddingInputText(entry);
@@ -428,31 +428,47 @@ export async function embedMemory(hippoRoot, entry, model, store) {
             withVectorDb(hippoRoot, (db) => upsertVectors(db, [[entry.id, vector]], embeddingIndexIdentity(identity)));
             saveStoredEmbeddingModel(hippoRoot, identity);
             // Initialize physics state for this memory
-            try {
-                const db = openHippoDb(hippoRoot);
-                try {
-                    const existing = loadPhysicsState(db, [entry.id]);
-                    if (!existing.has(entry.id)) {
-                        const particle = initializeParticle(entry, vector);
-                        savePhysicsState(db, [particle]);
-                    }
-                }
-                finally {
-                    closeHippoDb(db);
-                }
-            }
-            catch {
-                // Physics init is best-effort — don't break embedding
-            }
+            initializePhysicsIfMissing(hippoRoot, entry, vector);
         }
         catch (err) {
             // Provider failure (API down / bad key). Best-effort: leave the index as-is, but say so once.
-            warnEmbedFailureOnce(provider.kind, err instanceof Error ? err.message : String(err));
+            warnEmbedFailureOnce(provider.kind, errorMessage(err));
         }
     }).catch((err) => {
-        log.warn(`skipped embedding ${entry.id} (${err instanceof Error ? err.message : String(err)}); run 'hippo embed' to backfill`);
+        log.warn(`skipped embedding ${entry.id} (${errorMessage(err)}); run 'hippo embed' to backfill`);
     });
 }
+async function rebuildIndexForProvider(hippoRoot, provider) {
+    const identity = provider.id;
+    // Host-wide rebuild. The embedding index is keyed by entry.id
+    // (which is tenant-scoped) but the index itself is one per hippoRoot.
+    // Cross-tenant content equivalence is visible at the vector level.
+    // Per-tenant indices would be a larger architecture change.
+    const entries = loadAllEntries(hippoRoot);
+    const rebuiltIndex = await rebuildEmbeddingIndex(entries, provider);
+    saveEmbeddingIndex(hippoRoot, rebuiltIndex, embeddingIndexIdentity(identity));
+    saveStoredEmbeddingModel(hippoRoot, identity);
+    resetPhysicsFromIndex(hippoRoot, entries, rebuiltIndex);
+}
+function initializePhysicsIfMissing(hippoRoot, entry, vector) {
+    try {
+        const db = openHippoDb(hippoRoot);
+        try {
+            const existing = loadPhysicsState(db, [entry.id]);
+            if (!existing.has(entry.id)) {
+                const particle = initializeParticle(entry, vector);
+                savePhysicsState(db, [particle]);
+            }
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    catch (err) {
+        // Physics init is best-effort and must not fail the embedding that just landed.
+        log.debug(`physics state not initialised for ${entry.id}: ${errorMessage(err)}`);
+    }
+}
 /** Throws when an unavailable provider is a misconfiguration rather than an intentional no-op. */
 function throwIfProviderKeyMissing(hippoRoot, provider) {
     // A configured (non-disabled) API provider with a missing key is a
@@ -541,4 +557,4 @@ export async function embedAll(hippoRoot, model, provider = resolveEmbeddingProv
         return count;
     });
 }
-//# sourceMappingURL=embeddings.js.map
+//# sourceMappingURL=index.js.map

package/dist/{local-embedding.d.ts → store/embeddings/local.d.ts}

@@ -12,4 +12,4 @@ export declare function requireLocalPipeline(model: string): Promise<void>;
 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[]>;
-//# sourceMappingURL=local-embedding.d.ts.map
+//# sourceMappingURL=local.d.ts.map