hippo-memory 1.71.0 → 1.72.0

package/dist/rerankers/cross-encoder.js

@@ -1,108 +1,53 @@
-import { createRequire } from 'node:module';
-import { pathToFileURL } from 'node:url';
 import { createOutageWarning } from './outage-warning.js';
 import { compareScoresDesc } from '../core/compare.js';
-import { errorMessage, log } from '../util/log.js';
+import { createModelLoads, importTransformers, MODEL_LOAD_POLICY } from '../embeddings/transformers.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 const DEFAULT_CROSS_ENCODER_TOP_K = 50;
 const MODEL_NAME = 'Xenova/ms-marco-MiniLM-L-6-v2';
-const _require = createRequire(import.meta.url);
-const TRANSFORMERS_PACKAGES = ['@huggingface/transformers', '@xenova/transformers'];
-// Returns the ESM entry URL, the same build src/store/embeddings/index.ts imports; a require-style resolve picks the CommonJS build and
-// puts a second copy of the library, with its own ONNX sessions, in the process.
-function resolveTransformersPackage() {
-    for (const name of TRANSFORMERS_PACKAGES) {
-        try {
-            return import.meta.resolve(name);
-        }
-        catch {
-            // import.meta.resolve is missing under some module runners (vitest's
-            // included); fall through to the require-based resolve there.
-            try {
-                return pathToFileURL(_require.resolve(name)).href;
-            }
-            catch {
-                // Try the legacy fallback only when the preferred package is not installed.
-            }
-        }
-    }
-    return null;
-}
-async function loadTransformersModule() {
-    // Import one backend only. Loading both native ONNX runtimes in one process
-    // can abort during finalization; Hugging Face is the maintained default.
-    const url = resolveTransformersPackage();
-    if (!url)
-        return null;
-    try {
-        const mod = await import(/* @vite-ignore */ url);
-        const tok = mod.AutoTokenizer ?? mod.default?.AutoTokenizer;
-        const seq = mod.AutoModelForSequenceClassification ?? mod.default?.AutoModelForSequenceClassification;
-        return tok && seq ? { AutoTokenizer: tok, AutoModelForSequenceClassification: seq } : null;
-    }
-    catch (err) {
-        log.debug(`cross-encoder: transformers import failed: ${errorMessage(err)}`);
-        return null;
-    }
+async function importModelClasses(importModule) {
+    const imported = await importModule();
+    if (!imported)
+        throw new Error('no Transformers.js package is installed');
+    const { name, mod } = imported;
+    const tok = mod.AutoTokenizer ?? mod.default?.AutoTokenizer;
+    const seq = mod.AutoModelForSequenceClassification ?? mod.default?.AutoModelForSequenceClassification;
+    if (!tok || !seq)
+        throw new Error(`${name} exports no AutoTokenizer or AutoModelForSequenceClassification`);
+    return { AutoTokenizer: tok, AutoModelForSequenceClassification: seq };
 }
-let pipelineLoading = null;
-const outage = createOutageWarning('cross-encoder', 'falling back to identity ordering');
 // NOT the text-classification pipeline: this is a num_labels=1 regression head and that pipeline softmaxes a length-1 logit vector (always 1.0).
 // Read the logit, then squash it.
-async function buildPipeline() {
-    try {
-        const mod = await loadTransformersModule();
-        if (!mod)
-            return null;
-        const [tokenizer, model] = await Promise.all([
-            mod.AutoTokenizer.from_pretrained(MODEL_NAME),
-            mod.AutoModelForSequenceClassification.from_pretrained(MODEL_NAME),
-        ]);
-        return async (query, candidate) => {
-            const inputs = await tokenizer(query, {
-                text_pair: candidate,
-                padding: true,
-                truncation: true,
-            });
-            const { logits } = await model(inputs);
-            const score = 1 / (1 + Math.exp(-Number(logits.data[0])));
-            // NaN would make the sort comparator a no-op; throwing hands this
-            // candidate to the per-candidate fallback instead.
-            if (!Number.isFinite(score))
-                throw new Error('cross-encoder returned a non-finite score');
-            return score;
-        };
-    }
-    catch (err) {
-        log.debug(`cross-encoder: model load failed: ${errorMessage(err)}`);
-        return null;
-    }
+async function buildPipeline(importModule) {
+    const mod = await importModelClasses(importModule);
+    const [tokenizer, model] = await Promise.all([
+        mod.AutoTokenizer.from_pretrained(MODEL_NAME),
+        mod.AutoModelForSequenceClassification.from_pretrained(MODEL_NAME),
+    ]);
+    return async (query, candidate) => {
+        const inputs = await tokenizer(query, {
+            text_pair: candidate,
+            padding: true,
+            truncation: true,
+        });
+        const { logits } = await model(inputs);
+        const score = 1 / (1 + Math.exp(-Number(logits.data[0])));
+        // NaN would make the sort comparator a no-op; throwing hands this
+        // candidate to the per-candidate fallback instead.
+        if (!Number.isFinite(score))
+            throw new Error('cross-encoder returned a non-finite score');
+        return score;
+    };
 }
-// One shared in-flight load: two first calls must not fetch the model twice.
-// A failed load clears the slot so a later call can try again.
-function loadPipeline() {
-    pipelineLoading ??= buildPipeline().then((pipe) => {
-        if (!pipe)
-            pipelineLoading = null;
-        return pipe;
-    });
-    return pipelineLoading;
+/** The head in its input order, scored as it came. */
+function identityOrder(head) {
+    return head.map((r, i) => ({
+        ...r,
+        rerankScore: r.score,
+        preRerankRank: r.preRerankRank ?? i + 1,
+        postRerankRank: i + 1,
+    }));
 }
-/** Track 2 reranker: MS-MARCO MiniLM cross-encoder, identity fallback if the model will not load. */
-export const crossEncoderReranker = async (query, results, options) => {
-    const topK = options?.topK ?? DEFAULT_CROSS_ENCODER_TOP_K;
-    const head = results.slice(0, topK);
-    const pipe = await loadPipeline();
-    if (!pipe) {
-        // A silent identity fallback otherwise reads as a working reranker.
-        outage.failed('no Transformers.js backend, or model fetch blocked');
-        return head.map((r, i) => ({
-            ...r,
-            rerankScore: r.score,
-            preRerankRank: r.preRerankRank ?? i + 1,
-            postRerankRank: i + 1,
-        }));
-    }
-    outage.answered();
+async function scoreHead(pipe, query, head) {
     const scored = await Promise.all(head.map(async (r, i) => {
         let ceScore;
         try {
@@ -125,5 +70,26 @@ export const crossEncoderReranker = async (query, results, options) => {
     scored.sort((a, b) => compareScoresDesc(a.rerankScore, b.rerankScore));
     scored.forEach((r, i) => (r.postRerankRank = i + 1));
     return scored;
-};
+}
+/** Track 2 reranker: MS-MARCO MiniLM cross-encoder, identity fallback if the model will not load. Each instance owns its model and outage warning. */
+export function createCrossEncoderReranker(importModule = importTransformers) {
+    const outage = createOutageWarning('cross-encoder', 'falling back to identity ordering');
+    // The outage warning already says each failure, at most once per window, so the loads report nothing themselves.
+    const pipelines = createModelLoads(MODEL_LOAD_POLICY);
+    return async (query, results, options) => {
+        const head = results.slice(0, options?.topK ?? DEFAULT_CROSS_ENCODER_TOP_K);
+        let pipe;
+        try {
+            // One shared load per backoff window: two first calls fetch the model once, and a failure is not fetched again on every recall.
+            pipe = await pipelines.load(MODEL_NAME, () => buildPipeline(importModule));
+        }
+        catch (err) {
+            // A silent identity fallback otherwise reads as a working reranker.
+            outage.failed(errorMessage(err), errorFields(err));
+            return identityOrder(head);
+        }
+        outage.answered();
+        return scoreHead(pipe, query, head);
+    };
+}
 //# sourceMappingURL=cross-encoder.js.map

package/dist/rerankers/index.js

@@ -1,13 +1,14 @@
 import { createClefReranker } from './clef.js';
-import { crossEncoderReranker } from './cross-encoder.js';
+import { createCrossEncoderReranker } from './cross-encoder.js';
 import { createJevReranker } from './jev.js';
 import { createLlmReranker } from './llm.js';
-// Each hosted reranker is built once here, so its outage warning lasts the process.
+// Each reranker is built once here, so its outage warning lasts the process; jev falls back to the same cross-encoder, so one model loads.
+const crossEncoder = createCrossEncoderReranker();
 const REGISTRY = {
     clef: createClefReranker('clef'),
     'clef-flash': createClefReranker('clef-flash'),
-    'cross-encoder': crossEncoderReranker,
-    jev: createJevReranker(crossEncoderReranker),
+    'cross-encoder': crossEncoder,
+    jev: createJevReranker(crossEncoder),
     llm: createLlmReranker(),
 };
 function isRegisteredRerankerName(name) {

package/dist/rerankers/jev.js

@@ -1,3 +1,4 @@
+import { truncateWithEllipsis } from '../util/ellipsize.js';
 import { envJevModel, envJevTimeoutMs, envTypesafeApiKey } from '../util/env.js';
 import { redactSecretsStrict } from '../util/secret-detect.js';
 import { createOutageWarning } from './outage-warning.js';
@@ -15,9 +16,6 @@ const TRUNCATE_CHARS = 1200;
 const DEFAULT_MODEL = 'jev-1.13.0';
 // The pool size the eval numbers were measured at.
 export const JEV_DEFAULT_TOP_K = 40;
-function truncate(s, n) {
-    return s.length <= n ? s : `${s.slice(0, n)}...`;
-}
 // Number.isFinite rejects a string or null without coercing it, which the
 // declared type cannot promise about a third-party payload.
 function isProbability(v) {
@@ -40,7 +38,7 @@ function parseScores(body, n) {
 /** Redacted query plus numbered, redacted, truncated candidates. Shared with CLEF so both arms see matched input. */
 export function buildRelevanceRequest(query, head) {
     // Strict: this text leaves the machine, so Bearer, Basic-auth and JWT shapes go too.
-    const lines = head.map((r, i) => `[${i + 1}] ${truncate(redactSecretsStrict(r.entry.content), TRUNCATE_CHARS)}`);
+    const lines = head.map((r, i) => `[${i + 1}] ${truncateWithEllipsis(redactSecretsStrict(r.entry.content), TRUNCATE_CHARS)}`);
     const state = `Query: ${redactSecretsStrict(query)}\n\nNumbered candidate memories from an AI coding agent's project store:\n\n${lines.join('\n\n')}`;
     const questions = {};
     for (let i = 1; i <= head.length; i++) {

package/dist/rerankers/outage-warning.d.ts

@@ -1,5 +1,7 @@
+import { type LogFields } from '../util/log.js';
 export interface OutageWarning {
-    failed(reason: string): void;
+    /** `fields` carries the error's class and stack onto the warning line. */
+    failed(reason: string, fields?: LogFields): void;
     answered(): void;
 }
 /** Warns when `name` starts failing, at most every five minutes while it keeps failing,

package/dist/rerankers/outage-warning.js

@@ -1,6 +1,7 @@
 // One way for a reranker to report that it stopped working, without a line per recall.
+import { MINUTE_MS } from '../util/time.js';
 import { log } from '../util/log.js';
-const REPEAT_MS = 5 * 60_000;
+const REPEAT_MS = 5 * MINUTE_MS;
 /** Warns when `name` starts failing, at most every five minutes while it keeps failing,
  * and once when it answers again. `fallback` says what recall does meanwhile. */
 export function createOutageWarning(name, fallback) {
@@ -8,14 +9,15 @@ export function createOutageWarning(name, fallback) {
     let unreported = 0;
     let warnedAt = 0;
     return {
-        failed(reason) {
+        failed(reason, fields) {
             failures++;
             if (failures > 1 && Date.now() - warnedAt < REPEAT_MS) {
                 unreported++;
                 return;
             }
             const skipped = unreported > 0 ? ` ${unreported} more calls failed since the last warning.` : '';
-            log.warn(`${name} reranker unavailable (${reason}); ${fallback}.${skipped} While it fails this repeats at most every ${REPEAT_MS / 60_000} minutes.`);
+            const repeat = `While it fails this repeats at most every ${REPEAT_MS / MINUTE_MS} minutes.`;
+            log.warn(`${name} reranker unavailable (${reason}); ${fallback}.${skipped} ${repeat}`, fields);
             warnedAt = Date.now();
             unreported = 0;
         },

package/dist/search/bm25-search.js

@@ -2,7 +2,7 @@ import { estimateTokens } from '../util/token-text.js';
 import { tokenize } from '../util/tokenize.js';
 import { evalNow } from '../core/ablation.js';
 import { extractPathTags } from './path-context.js';
-import { detectScope } from '../sharing/scope.js';
+import { detectScope } from '../core/active-scope.js';
 import { compareScoredResults } from '../core/compare.js';
 import { bm25Score, buildCorpus, entryText } from './bm25.js';
 import { currentEntries } from './as-of.js';

package/dist/search/boosts.js

@@ -2,7 +2,7 @@ import { envSummaryDeboost } from '../util/env.js';
 import { calculateStrength, CHURN_STALE_TAG } from '../core/memory.js';
 import { isOutcomeFastAblated, isRecencyAblated, evalRecencyScaleDays } from '../core/ablation.js';
 import { pathBoostMultiplier } from './path-context.js';
-import { scopeMatch } from '../sharing/scope.js';
+import { scopeMatch } from '../core/active-scope.js';
 import { temporalBoost } from './temporal.js';
 import { DAY_MS } from '../util/time.js';
 const CHURN_STALE_RANK_MULTIPLIER = 0.5; // SHORTCUT: untuned; measure on real recall before any default.

package/dist/search/embed-memories.d.ts

@@ -0,0 +1,9 @@
+import type { MemoryEntry } from '../core/memory.js';
+import { type EmbeddingProvider } from '../embeddings/provider.js';
+import { type HippoStore } from '../store/port.js';
+/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
+export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model?: string, store?: HippoStore): Promise<void>;
+/** 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=embed-memories.d.ts.map