hippo-memory 1.71.0 → 2.0.0

package/dist/doctor.js

@@ -3,17 +3,18 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { findHippoStoreDir } from './core/project-identity.js';
+import { findHippoStoreDir, isInitialized } from './core/project-identity.js';
 import { getGlobalRoot } from './sharing/global-store.js';
-import { isInitialized } from './store/open.js';
 import { readStoreHealth } from './store/diagnostics.js';
 import { loadConfig } from './core/config.js';
 import { openHippoDbReadOnly, closeHippoDb, getCurrentSchemaVersion, IncompatibleBinaryError } from './db/index.js';
-import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './capture/compaction-record.js';
+import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './core/compaction-timing.js';
 import { SPOOL_DIR, spoolCounts } from './capture/compaction-spool.js';
-import { isEmbeddingAvailable } from './store/embeddings/local.js';
-import { CODEX_TRUST_LINE, claudeConfigDir, codexHomeDir, isCodexPresent } from './hooks/shared.js';
+import { isEmbeddingAvailable } from './embeddings/local.js';
+import { CODEX_TRUST_LINE, isCodexPresent } from './hooks/shared.js';
+import { claudeConfigDir, codexHomeDir } from './util/agent-homes.js';
 import { planProjectRepair } from './sharing/project-merge.js';
+import { projectTagReads } from './store/project-tags.js';
 import { resolveTenantId } from './store/tenant.js';
 import { errorMessage, log } from './util/log.js';
 import { readJsonFile, isJsonObjectLiteral } from './util/json.js';
@@ -104,16 +105,16 @@ function sleepCheck(lastSleep, now) {
         : { 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) {
+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)' }
@@ -121,7 +122,7 @@ function compactionsCheck(compactions, store, now) {
     }
     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 === '')
@@ -132,7 +133,8 @@ function compactionsCheck(compactions, store, now) {
     ].filter((s) => s !== '');
     const unfinished = stuck === 0
         ? `${recorded} in the store`
-        : `${stuck} compaction${stuck === 1 ? '' : 's'} unfinished after 10 minutes (${summarised} with a summary whose memories are not saved yet, ${started} with no summary yet)`;
+        : `${stuck} compaction${stuck === 1 ? '' : 's'} unfinished after 10 minutes ` +
+            `(${summarised} with a summary whose memories are not saved yet, ${started} with no summary yet)`;
     const note = spooled ? `; spool: ${spool.waiting} waiting, ${spool.stale} left by a replay that stopped, ${spool.bad} .bad` : '';
     return { id: 'compactions', status: 'warn', detail: `${unfinished}${note}${unread}`, fix: fix.join('; ') };
 }
@@ -141,7 +143,7 @@ function projectsCheck(globalRoot) {
     let db = null;
     try {
         db = openHippoDbReadOnly(globalRoot);
-        const r = planProjectRepair(db, globalRoot, resolveTenantId({}));
+        const r = planProjectRepair(projectTagReads(db, resolveTenantId({})), globalRoot);
         const found = [
             r.copies.length > 0 ? `${r.copies.length} imported notes copied under the wrong project` : '',
             r.folds.length > 0 ? `old project names that now resolve to another project: ${r.folds.map((f) => `${f.from} -> ${f.into}`).join(', ')}` : '',
@@ -253,11 +255,12 @@ 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. */
-function databaseChecks(store, now) {
+function databaseChecks(store, now, spoolFs) {
     let health;
     try {
         health = readStoreHealth(store, {
@@ -281,7 +284,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.
@@ -331,7 +334,7 @@ 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({

package/dist/embeddings/local.d.ts

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

package/dist/embeddings/local.js

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

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

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

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

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

package/dist/embeddings/transformers.d.ts

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

package/dist/embeddings/transformers.js

@@ -0,0 +1,89 @@
+// The optional Transformers.js package, and a bounded load of a model from it, shared by the local embedder and the cross-encoder.
+import { MINUTE_MS } from '../util/time.js';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { errorCode, errorMessage } from '../util/log.js';
+const _require = createRequire(import.meta.url);
+// Importing both loads two onnxruntime-node builds whose finalizers can double-free on exit, so one is picked:
+// the maintained package hippo ships, with Xenova only as a fallback a user installed.
+const TRANSFORMERS_PACKAGES = ['@huggingface/transformers', '@xenova/transformers'];
+/** The installed package to import, or null when neither is installed. */
+export function resolveTransformersPackage() {
+    for (const name of TRANSFORMERS_PACKAGES) {
+        const url = entryUrl(name);
+        if (url)
+            return { name, url };
+    }
+    return null;
+}
+function entryUrl(name) {
+    try {
+        return import.meta.resolve(name);
+    }
+    catch {
+        // import.meta.resolve is missing under some module runners (vitest's included), so the require-based resolve stands in there.
+        try {
+            return pathToFileURL(_require.resolve(name)).href;
+        }
+        catch {
+            return null; // not installed; the caller tries the next package
+        }
+    }
+}
+/** The package's module namespace, typed by the parts the caller reads; null when neither package is installed. */
+export async function importTransformers() {
+    const pkg = resolveTransformersPackage();
+    if (!pkg)
+        return null;
+    try {
+        return { name: pkg.name, mod: await import(/* @vite-ignore */ pkg.url) };
+    }
+    catch (err) {
+        // A Node error's code (ERR_MODULE_NOT_FOUND and the like) says more than its message alone.
+        const code = errorCode(err);
+        throw new Error(`transformers import failed (${pkg.name}): ${code ? `${code} ` : ''}${errorMessage(err)}`, { cause: err });
+    }
+}
+// A quantized MiniLM is about 23 MB, so two minutes is a 1.5 Mbit/s link; a load from disk takes about a second.
+// The backoff matches the reranker outage warning's repeat window, so each window has one attempt and one warning.
+export const MODEL_LOAD_POLICY = { timeoutMs: 2 * MINUTE_MS, backoffMs: 5 * MINUTE_MS };
+/** One load per key at a time, bounded by the policy's timeout; `onFailure` hears each failed attempt, so once per backoff window. */
+export function createModelLoads(policy, onFailure) {
+    const loaded = new Map();
+    const inFlight = new Map();
+    const failed = new Map();
+    const attempt = (key, start) => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${key} did not load within ${policy.timeoutMs / 1000} s`)), policy.timeoutMs);
+        timer.unref();
+        Promise.resolve().then(start).then((model) => {
+            clearTimeout(timer);
+            loaded.set(key, model);
+            failed.delete(key);
+            resolve(model);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err instanceof Error ? err : new Error(errorMessage(err)));
+        });
+    });
+    return {
+        load(key, start) {
+            const model = loaded.get(key);
+            if (model !== undefined)
+                return Promise.resolve(model);
+            const pending = inFlight.get(key);
+            if (pending)
+                return pending;
+            const failure = failed.get(key);
+            if (failure && Date.now() < failure.until)
+                return Promise.reject(failure.error);
+            const next = attempt(key, start).catch((err) => {
+                failed.set(key, { error: err, until: Date.now() + policy.backoffMs });
+                onFailure?.(key, err);
+                throw err;
+            }).finally(() => inFlight.delete(key));
+            inFlight.set(key, next);
+            return next;
+        },
+    };
+}
+//# sourceMappingURL=transformers.js.map

package/dist/entry/session-text.d.ts

@@ -3,5 +3,5 @@ export { scrubForSharing } from '../capture/share-scrub.js';
 export { transcriptWorkingState, WORKING_STATE_CAPS } from '../capture/working-state.js';
 export { lessonFromFailure, failureReport, type FailureReport } from '../capture/failure-reading.js';
 export { collectHandoffEvidence } from '../capture/handoff-evidence.js';
-export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../capture/compaction-items.js';
+export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../util/compaction-items.js';
 //# sourceMappingURL=session-text.d.ts.map

package/dist/entry/session-text.js

@@ -5,5 +5,5 @@ export { scrubForSharing } from '../capture/share-scrub.js';
 export { transcriptWorkingState, WORKING_STATE_CAPS } from '../capture/working-state.js';
 export { lessonFromFailure, failureReport } from '../capture/failure-reading.js';
 export { collectHandoffEvidence } from '../capture/handoff-evidence.js';
-export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../capture/compaction-items.js';
+export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../util/compaction-items.js';
 //# sourceMappingURL=session-text.js.map

package/dist/entry/store-kit.d.ts

@@ -0,0 +1,37 @@
+export { hasGroup, sqliteStore, type AmbientCandidateRequest, type ContextReads, type EntryRemoval, type EntryTarget, type EntryWrite, type EntryWrites, type HippoStore, type KeyAudit, type KeyListQuery, type KeyMint, type KeyRevoke, type KeyWrites, type LastRecall, type LastRecallWrites, type OutcomeWrite, type RawArchive, type RecallSearchArgs, type RecallWrites, type SelfKeyMint, type StoreGroup, type StoreGroups, type SupersedeWrite, type VectorReads, type VectorBackfillQuery, type VectorRowWrite, type VectorWrite, type VectorWriteResult, type VectorWrites, } from '../store/index.js';
+export { entryAfterOutcome } from '../core/memory.js';
+export { rejectionDigest } from '../store/rejection.js';
+export { RejectedValueError } from '../core/api-errors.js';
+export { ownScopeTouches } from '../core/recall-scope.js';
+export type { HippoDbContext } from '../api/types.js';
+export type { ApiKeyListItem, ApiKeyListRow, ApiKeyRecord, ListApiKeysOpts, NewApiKey } from '../store/auth.js';
+export type { KeysetPosition } from '../util/keyset.js';
+export type { AppendAuditOpts, AuditEvent, ListAuditAfterOpts } from '../store/audit.js';
+export type { ContinuityBlock } from '../api/recall-types.js';
+export type { ActiveGoals, GetActiveGoalsOpts, Goal, GoalRecallLogRow, RetrievalPolicy } from '../store/goals.js';
+export type { MemoryEntry } from '../core/memory.js';
+export type { ClassResolution, PlanningFallacyEvidence } from '../store/planning-fallacy-evidence.js';
+export type { PredictionBaserate } from '../store/predictions.js';
+export type { RecallTraceInput } from '../store/recall-trace.js';
+export type { StrengthenOptions } from '../store/entry-writes.js';
+export type { OriginFilter, RecallScopeFilter, VectorCandidateSpec } from '../store/search-rows.js';
+export type { ContinuityKey } from '../store/sessions.js';
+export type { SessionEvent, TaskSnapshot } from '../store/rows.js';
+export type { SessionHandoff } from '../core/handoff.js';
+export type { AmbientLoadResult, AmbientRecallRequest, ContextCandidateFilter, RecentOrigins } from '../store/candidates.js';
+export type { AmbientStoreFilter } from '../store/ambient.js';
+export type { AmbientTallies } from '../core/ambient.js';
+export type { TokenUse } from '../store/token-ledger.js';
+export type { EmbeddingIndexState } from '../store/vector-index.js';
+export type { PhysicsParticle } from '../core/physics.js';
+export { StoreBusyError } from '../store/port.js';
+export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows, type VectorMatch, type VectorRow } from '../db/vector-store.js';
+export { bufferToFloat32, float32ToBuffer } from '../util/vector-codec.js';
+export { replacesIndex } from '../store/vector-index.js';
+export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from '../core/recall-scope.js';
+export { SECRET_TAGS } from '../util/secret-detect.js';
+export { tallyAmbientEntries } from '../core/ambient.js';
+export { ftsTermParts, rarestFtsQuery } from '../core/prompt-recall.js';
+export { OTHER_STORE_MARKER } from '../db/index.js';
+export { isSharedStore } from '../core/config.js';
+//# sourceMappingURL=store-kit.d.ts.map

package/dist/entry/store-kit.js

@@ -0,0 +1,25 @@
+// The hippo-memory/store-kit subpath: the contract for a second HippoStore (port types, row types, hippo.db's rule helpers),
+// so a store built on it applies hippo.db's rules with the same code.
+// An add-on serves from another database by passing serve() its own HippoStore.
+export { hasGroup, sqliteStore, } from '../store/index.js';
+// An add-on store's entry writes apply an outcome, guard tombstones and check reach exactly as hippo.db does.
+export { entryAfterOutcome } from '../core/memory.js';
+export { rejectionDigest } from '../store/rejection.js';
+export { RejectedValueError } from '../core/api-errors.js';
+export { ownScopeTouches } from '../core/recall-scope.js';
+export { StoreBusyError } from '../store/port.js';
+// An add-on store encodes, decodes and ranks vectors and particles with hippo.db's own code, and drops the index by its rule,
+// so both stores keep the same bytes and return the same ids in the same order.
+export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows } from '../db/vector-store.js';
+export { bufferToFloat32, float32ToBuffer } from '../util/vector-codec.js';
+export { replacesIndex } from '../store/vector-index.js';
+// An add-on's ContextReads applies hippo.db's scope, secret, tally and rarest-term rules with the same code.
+export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from '../core/recall-scope.js';
+export { SECRET_TAGS } from '../util/secret-detect.js';
+export { tallyAmbientEntries } from '../core/ambient.js';
+export { ftsTermParts, rarestFtsQuery } from '../core/prompt-recall.js';
+// store copy --db writes the marker into the other store's folder.
+export { OTHER_STORE_MARKER } from '../db/index.js';
+// An add-on that serves a team store checks the flag before it starts.
+export { isSharedStore } from '../core/config.js';
+//# sourceMappingURL=store-kit.js.map

package/dist/entry/testing.d.ts

@@ -0,0 +1,6 @@
+export { _resetAblationCacheForTests } from '../core/ablation.js';
+export { _resetSharedStoreCacheForTests } from '../core/config.js';
+export { _resetLossAversionRatioCacheForTests } from '../core/memory.js';
+export { _resetSessionRecallHistoryMcpForTests } from '../mcp/session-state.js';
+export { __resetSessionRecallHistoryHttp } from '../server/routes/recall.js';
+//# sourceMappingURL=testing.d.ts.map