hippo-memory 1.59.0 → 1.61.0

package/dist/rerankers/jev.js

@@ -1,5 +1,7 @@
+import { envJevModel, envJevTimeoutMs, envTypesafeApiKey } from '../env.js';
 import { crossEncoderReranker } from './cross-encoder.js';
-import { redactSecrets } from '../secret-detect.js';
+import { redactSecretsStrict } from '../secret-detect.js';
+import { log } from '../log.js';
 const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
 const DEFAULT_TIMEOUT_MS = 5_000;
 const TRUNCATE_CHARS = 1200;
@@ -30,8 +32,9 @@ function parseScores(answers, n) {
 }
 /** Redacted query plus numbered, redacted, truncated candidates. Shared with CLEF so both arms see matched input. */
 export function buildRelevanceRequest(query, head) {
-    const lines = head.map((r, i) => `[${i + 1}] ${truncate(redactSecrets(r.entry.content), TRUNCATE_CHARS)}`);
-    const state = `Query: ${redactSecrets(query)}\n\nNumbered candidate memories from an AI coding agent's project store:\n\n${lines.join('\n\n')}`;
+    // 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 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++) {
         questions[`c${i}`] = {
@@ -43,12 +46,11 @@ export function buildRelevanceRequest(query, head) {
 }
 /** One batched request for the whole candidate list. Rejects with the reason when there are no usable scores. */
 async function requestScores(query, head) {
-    const key = process.env.TYPESAFE_API_KEY;
+    const key = envTypesafeApiKey();
     if (!key)
         throw new Error('TYPESAFE_API_KEY not set');
     const { state, questions } = buildRelevanceRequest(query, head);
-    const parsed = Number.parseInt(process.env.HIPPO_JEV_TIMEOUT_MS ?? '', 10);
-    const timeoutMs = parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS;
+    const timeoutMs = envJevTimeoutMs() ?? DEFAULT_TIMEOUT_MS;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -57,7 +59,7 @@ async function requestScores(query, head) {
             headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
             body: JSON.stringify({
                 state,
-                model: process.env.HIPPO_JEV_MODEL ?? DEFAULT_MODEL,
+                model: envJevModel() ?? DEFAULT_MODEL,
                 questions,
             }),
             signal: controller.signal,
@@ -101,23 +103,26 @@ export function createJevReranker(localFallback) {
             if (!warned) {
                 warned = true;
                 const reason = err instanceof Error ? err.message : 'unknown error';
-                // eslint-disable-next-line no-console
-                console.warn(`[hippo] jev reranker unavailable (${reason}); falling back to the local cross-encoder. Subsequent calls will not repeat this warning.`);
+                log.warn(`jev reranker unavailable (${reason}); falling back to the local cross-encoder. Subsequent calls will not repeat this warning.`);
             }
             return localFallback(query, head, options);
         }
-        const scored = head.map((r, i) => ({
-            ...r,
-            rerankScore: scores[i],
-            preRerankRank: r.preRerankRank ?? i + 1,
-            postRerankRank: 0,
-        }));
-        // Stable sort: ties fall back to the prior relevance order.
-        scored.sort((a, b) => b.rerankScore - a.rerankScore);
-        scored.forEach((r, i) => (r.postRerankRank = i + 1));
-        return scored;
+        return rankByScores(head, scores);
     };
 }
+/** Orders `head` by `scores[i]`, keeping any upstream pre-rerank rank. Shared with CLEF. */
+export function rankByScores(head, scores) {
+    const scored = head.map((r, i) => ({
+        ...r,
+        rerankScore: scores[i],
+        preRerankRank: r.preRerankRank ?? i + 1,
+        postRerankRank: 0,
+    }));
+    // Stable sort: ties fall back to the prior relevance order.
+    scored.sort((a, b) => b.rerankScore - a.rerankScore);
+    scored.forEach((r, i) => (r.postRerankRank = i + 1));
+    return scored;
+}
 /** Track 4 reranker: hosted TypeSafe Jev, opt-in and paid (TYPESAFE_API_KEY), one batched call per recall.
  *  Any failure warns once and delegates to the local cross-encoder. Scores are not bit-stable run to run.
  *  Cost, env vars, evidence and limits: docs/evals/2026-09-19-jev-reranker.md. */

package/dist/rerankers/llm.d.ts

@@ -8,8 +8,10 @@ import type { RerankerFn } from './types.js';
  * Full characterisation deferred to a follow-on plan.
  *
  * Timeout: defaults to 30s; overridable via HIPPO_LLM_RERANKER_TIMEOUT_MS.
- * On timeout or any fetch failure, the reranker silently falls back to
- * identity ordering — recall must not hang on a wedged endpoint.
+ * On timeout or any fetch failure, the reranker warns once per process and
+ * falls back to identity ordering; recall must not hang on a wedged endpoint.
  */
+export declare function createLlmReranker(): RerankerFn;
+/** The instance the reranker registry serves; its warn-once flag lasts the process. */
 export declare const llmReranker: RerankerFn;
 //# sourceMappingURL=llm.d.ts.map

package/dist/rerankers/llm.js

@@ -1,4 +1,6 @@
-import { redactSecrets } from '../secret-detect.js';
+import { envLlmRerankerKey, envLlmRerankerModel, envLlmRerankerTimeoutMs, envLlmRerankerUrl } from '../env.js';
+import { redactSecretsStrict } from '../secret-detect.js';
+import { log } from '../log.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 /**
  * Track 3 reranker: listwise LLM rerank. Uses a customer-supplied
@@ -9,24 +11,50 @@ const DEFAULT_TIMEOUT_MS = 30_000;
  * Full characterisation deferred to a follow-on plan.
  *
  * Timeout: defaults to 30s; overridable via HIPPO_LLM_RERANKER_TIMEOUT_MS.
- * On timeout or any fetch failure, the reranker silently falls back to
- * identity ordering — recall must not hang on a wedged endpoint.
+ * On timeout or any fetch failure, the reranker warns once per process and
+ * falls back to identity ordering; recall must not hang on a wedged endpoint.
  */
-export const llmReranker = async (query, results, options) => {
-    const url = process.env.HIPPO_LLM_RERANKER_URL;
-    const key = process.env.HIPPO_LLM_RERANKER_KEY;
-    if (!url) {
-        throw new Error('HIPPO_LLM_RERANKER_URL not set; refusing to run LLM reranker.');
-    }
-    const topK = options?.topK ?? 20;
-    const head = results.slice(0, topK);
+export function createLlmReranker() {
+    let warned = false;
+    return async (query, results, options) => {
+        const url = envLlmRerankerUrl();
+        if (!url) {
+            throw new Error('HIPPO_LLM_RERANKER_URL not set; refusing to run LLM reranker.');
+        }
+        const head = results.slice(0, options?.topK ?? 20);
+        let permutation = null;
+        try {
+            permutation = await requestPermutation(url, query, head);
+        }
+        catch (err) {
+            // A read path never throws, and never hands back the unranked order without saying so.
+            if (!warned) {
+                warned = true;
+                const reason = err instanceof Error ? err.message : 'unknown error';
+                log.warn(`llm reranker unavailable (${reason}); keeping the input order. Subsequent calls will not repeat this warning.`);
+            }
+        }
+        const ordered = permutation ? permutation.map((idx) => head[idx]) : head;
+        return ordered.map((r, i) => ({
+            ...r,
+            rerankScore: ordered.length - i,
+            preRerankRank: r.preRerankRank ?? i + 1,
+            postRerankRank: i + 1,
+        }));
+    };
+}
+/** The instance the reranker registry serves; its warn-once flag lasts the process. */
+export const llmReranker = createLlmReranker();
+/** One chat-completions call; rejects with the reason when the reply holds no usable permutation. */
+async function requestPermutation(url, query, head) {
+    const key = envLlmRerankerKey();
     const prompt = [
         `Rerank the candidates below by relevance to the query. Output a JSON array of indices (zero-indexed) in best-first order.`,
-        `Query: ${redactSecrets(query)}`,
-        ...head.map((r, i) => `[${i}] ${redactSecrets(r.entry.content)}`),
+        `Query: ${redactSecretsStrict(query)}`,
+        ...head.map((r, i) => `[${i}] ${redactSecretsStrict(r.entry.content)}`),
         `Output format: [<int>, <int>, ...] with all ${head.length} indices.`,
     ].join('\n');
-    const timeoutMs = Number.parseInt(process.env.HIPPO_LLM_RERANKER_TIMEOUT_MS ?? '', 10) || DEFAULT_TIMEOUT_MS;
+    const timeoutMs = envLlmRerankerTimeoutMs() ?? DEFAULT_TIMEOUT_MS;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     const headers = {
@@ -35,47 +63,39 @@ export const llmReranker = async (query, results, options) => {
     if (key) {
         headers.authorization = `Bearer ${key}`;
     }
-    let permutation = null;
     try {
         const resp = await fetch(`${url.replace(/\/$/, '')}/chat/completions`, {
             method: 'POST',
             headers: { ...headers },
             body: JSON.stringify({
-                model: process.env.HIPPO_LLM_RERANKER_MODEL ?? 'gpt-4o-mini',
+                model: envLlmRerankerModel() ?? 'gpt-4o-mini',
                 messages: [{ role: 'user', content: prompt }],
                 temperature: 0,
             }),
             signal: controller.signal,
         });
-        if (resp.ok) {
-            const j = await resp.json();
-            const txt = j.choices?.[0]?.message?.content ?? '';
-            const m = txt.match(/\[\s*(\d+(?:\s*,\s*\d+)*)\s*\]/);
-            if (m) {
-                const parsed = m[1].split(',').map((s) => parseInt(s.trim(), 10));
-                if (parsed.length === head.length &&
-                    parsed.every((n) => Number.isInteger(n) && n >= 0 && n < head.length) &&
-                    new Set(parsed).size === head.length) {
-                    permutation = parsed;
-                }
-            }
+        if (!resp.ok) {
+            await resp.body?.cancel();
+            throw new Error(`HTTP ${resp.status}`);
         }
+        const j = await resp.json();
+        const txt = j.choices?.[0]?.message?.content ?? '';
+        const m = txt.match(/\[\s*(\d+(?:\s*,\s*\d+)*)\s*\]/);
+        const parsed = m ? m[1].split(',').map((s) => parseInt(s.trim(), 10)) : [];
+        const isPermutation = parsed.length === head.length &&
+            parsed.every((n) => Number.isInteger(n) && n >= 0 && n < head.length) &&
+            new Set(parsed).size === head.length;
+        if (!isPermutation)
+            throw new Error('reply is not a permutation of the candidates');
+        return parsed;
     }
-    catch {
-        // Fall through to identity. Includes AbortError on timeout — see
-        // DEFAULT_TIMEOUT_MS / HIPPO_LLM_RERANKER_TIMEOUT_MS above.
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError')
+            throw new Error(`no answer within ${timeoutMs} ms`);
+        throw err;
     }
     finally {
         clearTimeout(timer);
     }
-    const ordered = permutation
-        ? permutation.map((idx) => head[idx])
-        : head;
-    return ordered.map((r, i) => ({
-        ...r,
-        rerankScore: ordered.length - i,
-        preRerankRank: r.preRerankRank ?? i + 1,
-        postRerankRank: i + 1,
-    }));
-};
+}
 //# sourceMappingURL=llm.js.map

package/dist/rerankers/types.d.ts

@@ -1,4 +1,4 @@
-import type { SearchResult } from '../search.js';
+import type { SearchResult } from '../search/types.js';
 /**
  * A reranker reorders (and optionally rescales) the candidate set produced
  * by hybridSearch's BM25 + cosine + MMR pipeline. Rerankers run AFTER MMR

package/dist/salience.js

@@ -5,7 +5,7 @@
  * Inspired by the biological salience network (anterior insula + dACC):
  * not everything that enters working memory deserves long-term storage.
  */
-import { textOverlap } from './search.js';
+import { textOverlap } from './tokenize.js';
 import { duplicateKey, heldTextKeys } from './same-text.js';
 const DEFAULTS = {
     recentWindow: 20,

package/dist/same-text.d.ts

@@ -10,6 +10,8 @@ export declare function mergedText(header: string, texts: readonly string[]): st
 export declare function heldTexts(entry: Text): string[];
 /** Keys of every text a row holds word for word: its own, plus each source text inside a sleep-merged row. */
 export declare function heldTextKeys(entry: Text): string[];
+/** The longest word of a text: every row holding the text word for word contains it, so a store lookup can filter on it. */
+export declare function longestWord(text: string): string;
 export declare function storedTextKeys(entries: readonly Text[]): Set<string>;
 /** A final result list without copies: drops each unpinned row a sleep-merged row in the list holds word for word, and each later unpinned copy of a text. */
 export declare function dropHeldCopies<T>(rows: readonly T[], textOf: (row: T) => Text): T[];

package/dist/same-text.js

@@ -19,6 +19,10 @@ export function heldTexts(entry) {
 export function heldTextKeys(entry) {
     return [duplicateKey(entry.content), ...heldTexts(entry).map(duplicateKey)];
 }
+/** The longest word of a text: every row holding the text word for word contains it, so a store lookup can filter on it. */
+export function longestWord(text) {
+    return duplicateKey(text).split(' ').reduce((best, w) => (w.length > best.length ? w : best), '');
+}
 export function storedTextKeys(entries) {
     return new Set(entries.flatMap(heldTextKeys));
 }

package/dist/scheduler.d.ts

@@ -16,6 +16,7 @@ export interface SchedulerFsDeps {
     readFileSync: typeof fs.readFileSync;
     mkdirSync: typeof fs.mkdirSync;
     writeFileSync: typeof fs.writeFileSync;
+    renameSync: typeof fs.renameSync;
 }
 /** Test-only override. Not part of this module's public API surface. */
 export declare function __setSchedulerFsDeps(overrides: Partial<SchedulerFsDeps>): void;

package/dist/scheduler.js

@@ -1,11 +1,13 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import { log } from './log.js';
 export const DAILY_TASK_NAME = 'hippo-daily-runner';
 let fsDeps = {
     existsSync: fs.existsSync,
     readFileSync: fs.readFileSync,
     mkdirSync: fs.mkdirSync,
     writeFileSync: fs.writeFileSync,
+    renameSync: fs.renameSync,
 };
 /** Test-only override. Not part of this module's public API surface. */
 export function __setSchedulerFsDeps(overrides) {
@@ -27,8 +29,16 @@ export function loadWorkspaceRegistry(globalRoot) {
     const registryPath = workspaceRegistryPath(globalRoot);
     if (!fsDeps.existsSync(registryPath))
         return defaultRegistry();
+    let text;
     try {
-        const parsed = JSON.parse(fsDeps.readFileSync(registryPath, 'utf8'));
+        text = fsDeps.readFileSync(registryPath, 'utf8');
+    }
+    catch (err) {
+        log.warn(`workspace registry ${registryPath} could not be read (${err instanceof Error ? err.message : String(err)}); starting with no workspaces`);
+        return defaultRegistry();
+    }
+    try {
+        const parsed = JSON.parse(text);
         const workspaces = Array.isArray(parsed.workspaces)
             ? [...new Set(parsed.workspaces.map((entry) => normalizeWorkspace(String(entry))).filter(Boolean))].sort()
             : [];
@@ -37,12 +47,25 @@ export function loadWorkspaceRegistry(globalRoot) {
             workspaces,
         };
     }
-    catch {
+    catch (err) {
+        // The next registration rewrites the file, so keep the bad copy for the user to recover entries from.
+        setAsideCorruptRegistry(registryPath, err);
         return defaultRegistry();
     }
 }
+function setAsideCorruptRegistry(registryPath, err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    const aside = `${registryPath}.corrupt-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+    try {
+        fsDeps.renameSync(registryPath, aside);
+        log.warn(`workspace registry ${registryPath} is corrupt (${reason}); moved it to ${aside} and starting with no workspaces`);
+    }
+    catch (renameErr) {
+        log.warn(`workspace registry ${registryPath} is corrupt (${reason}) and could not be moved aside (${renameErr instanceof Error ? renameErr.message : String(renameErr)}); starting with no workspaces`);
+    }
+}
 export function saveWorkspaceRegistry(globalRoot, registry) {
-    fsDeps.mkdirSync(globalRoot, { recursive: true });
+    fsDeps.mkdirSync(globalRoot, { recursive: true, mode: 0o700 });
     fsDeps.writeFileSync(workspaceRegistryPath(globalRoot), JSON.stringify({
         version: 1,
         workspaces: [...new Set(registry.workspaces.map(normalizeWorkspace))].sort(),

package/dist/scope.js

@@ -1,3 +1,4 @@
+import { envGstackSkill, envOpenclawSkill, envScope } from './env.js';
 /**
  * Detect the current operational scope from environment signals.
  * Returns a scope name string (no prefix), or null if no scope detected.
@@ -6,13 +7,13 @@
  * Pure env var reads: no I/O, safe to call from hot paths (e.g. UserPromptSubmit hook).
  */
 export function detectScope() {
-    const explicit = process.env['HIPPO_SCOPE'];
+    const explicit = envScope();
     if (explicit && explicit.trim())
         return explicit.trim();
-    const gstackSkill = process.env['GSTACK_SKILL'];
+    const gstackSkill = envGstackSkill();
     if (gstackSkill && gstackSkill.trim())
         return gstackSkill.trim();
-    const openclawSkill = process.env['OPENCLAW_SKILL'];
+    const openclawSkill = envOpenclawSkill();
     if (openclawSkill && openclawSkill.trim())
         return openclawSkill.trim();
     return null;

package/dist/search/as-of.d.ts

@@ -0,0 +1,10 @@
+import type { MemoryEntry } from '../memory.js';
+export interface CurrentnessOptions {
+    /** Keep only rows current at this ISO date string. */
+    asOf?: string;
+    /** Keep superseded rows when no `asOf` is given. */
+    includeSuperseded?: boolean;
+}
+/** Rows current at `asOf`, or rows not superseded unless `includeSuperseded`. */
+export declare function currentEntries(entries: MemoryEntry[], options: CurrentnessOptions): MemoryEntry[];
+//# sourceMappingURL=as-of.d.ts.map

package/dist/search/as-of.js

@@ -0,0 +1,22 @@
+/** Rows current at `asOf`, or rows not superseded unless `includeSuperseded`. */
+export function currentEntries(entries, options) {
+    if (options.asOf)
+        return entriesAsOf(entries, new Date(options.asOf));
+    return options.includeSuperseded ? entries : entries.filter((e) => !e.superseded_by);
+}
+function entriesAsOf(entries, asOfDate) {
+    // A merged pool can repeat an id; the first row wins, as a scan from the front would pick.
+    const byId = new Map();
+    for (const e of entries)
+        if (!byId.has(e.id))
+            byId.set(e.id, e);
+    return entries.filter((e) => {
+        if (new Date(e.valid_from) > asOfDate)
+            return false;
+        if (!e.superseded_by)
+            return true;
+        const successor = byId.get(e.superseded_by);
+        return successor?.valid_from ? new Date(successor.valid_from) > asOfDate : true;
+    });
+}
+//# sourceMappingURL=as-of.js.map

package/dist/search/bm25-search.d.ts

@@ -0,0 +1,14 @@
+import type { MemoryEntry } from '../memory.js';
+import type { ResultCost, SearchResult } from './types.js';
+export interface SearchOptions {
+    budget?: number;
+    now?: Date;
+    hippoRoot?: string;
+    minResults?: number;
+    cost?: ResultCost;
+    includeSuperseded?: boolean;
+    asOf?: string;
+}
+/** Synchronous BM25 search: relevance * strength * recency and the rank boosts, without embeddings or the outcome nudge. */
+export declare function search(query: string, entries: MemoryEntry[], options?: SearchOptions): SearchResult[];
+//# sourceMappingURL=bm25-search.d.ts.map

package/dist/search/bm25-search.js

@@ -0,0 +1,43 @@
+import { estimateTokens } from '../token-ledger.js';
+import { tokenize } from '../tokenize.js';
+import { evalNow } from '../ablation.js';
+import { extractPathTags } from '../path-context.js';
+import { detectScope } from '../scope.js';
+import { compareScoredResults } from '../compare.js';
+import { bm25Score, buildCorpus, entryText } from './bm25.js';
+import { currentEntries } from './as-of.js';
+import { applyRankBoosts, strengthRecencyMultipliers, NO_SUMMARY_SCORING } from './boosts.js';
+import { temporalContext } from './temporal.js';
+import { dedupeExtracted, fitBudget, withDagChildren } from './finalize.js';
+/** Synchronous BM25 search: relevance * strength * recency and the rank boosts, without embeddings or the outcome nudge. */
+export function search(query, entries, options = {}) {
+    const now = options.now ?? evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
+    const pool = currentEntries(entries, options);
+    if (pool.length === 0)
+        return [];
+    const queryTerms = tokenize(query);
+    if (queryTerms.length === 0)
+        return [];
+    const corpus = buildCorpus(pool.map(entryText));
+    const ctx = {
+        now,
+        pathTags: extractPathTags(process.cwd()),
+        scope: detectScope(),
+        temporal: temporalContext(query, pool),
+        outcome: false,
+        summary: NO_SUMMARY_SCORING,
+    };
+    const scored = [];
+    for (let i = 0; i < pool.length; i++) {
+        const bm25 = bm25Score(corpus, i, queryTerms);
+        if (bm25 <= 0)
+            continue;
+        const { strength, recency } = strengthRecencyMultipliers(pool[i], now);
+        const normBm25 = bm25 / queryTerms.length;
+        const score = applyRankBoosts(normBm25 * strength * recency, pool[i], ctx).score;
+        scored.push({ entry: pool[i], score, bm25, cosine: 0, tokens: estimateTokens(pool[i].content) });
+    }
+    scored.sort(compareScoredResults);
+    return fitBudget(withDagChildren(dedupeExtracted(scored), pool), options.budget ?? 4000, options.minResults ?? 1, options.cost);
+}
+//# sourceMappingURL=bm25-search.js.map

package/dist/search/bm25.d.ts

@@ -0,0 +1,15 @@
+import type { MemoryEntry } from '../memory.js';
+/** Tokenized BM25 corpus; build it once with `buildCorpus` and reuse it across queries on the same entry set. */
+export interface BM25Corpus {
+    docs: string[][];
+    avgLen: number;
+    df: Map<string, number>;
+    N: number;
+}
+/** The text BM25 indexes for an entry: its content followed by its tags. */
+export declare function entryText(entry: MemoryEntry): string;
+export declare function buildCorpus(texts: string[]): BM25Corpus;
+export declare function bm25Score(corpus: BM25Corpus, docIdx: number, queryTerms: string[]): number;
+/** Query terms that appear in the entry's indexed text, in query order. */
+export declare function matchedQueryTerms(queryTerms: Iterable<string>, entry: MemoryEntry): string[];
+//# sourceMappingURL=bm25.d.ts.map

package/dist/search/bm25.js

@@ -0,0 +1,54 @@
+import { tokenize } from '../tokenize.js';
+const BM25_K1 = 1.5;
+const BM25_B = 0.75;
+/** The text BM25 indexes for an entry: its content followed by its tags. */
+export function entryText(entry) {
+    return `${entry.content} ${entry.tags.join(' ')}`;
+}
+export function buildCorpus(texts) {
+    const docs = texts.map(tokenize);
+    const N = docs.length;
+    const df = new Map();
+    let totalLen = 0;
+    for (const doc of docs) {
+        totalLen += doc.length;
+        const seen = new Set();
+        for (const term of doc) {
+            if (!seen.has(term)) {
+                df.set(term, (df.get(term) ?? 0) + 1);
+                seen.add(term);
+            }
+        }
+    }
+    const avgLen = N > 0 ? totalLen / N : 1;
+    return { docs, avgLen, df, N };
+}
+export function bm25Score(corpus, docIdx, queryTerms) {
+    const doc = corpus.docs[docIdx];
+    const docLen = doc.length;
+    let score = 0;
+    const tf = new Map();
+    for (const t of doc)
+        tf.set(t, (tf.get(t) ?? 0) + 1);
+    for (const term of queryTerms) {
+        const f = tf.get(term) ?? 0;
+        if (f === 0)
+            continue;
+        const df = corpus.df.get(term) ?? 0;
+        const idf = Math.log((corpus.N - df + 0.5) / (df + 0.5) + 1);
+        const numerator = f * (BM25_K1 + 1);
+        const denominator = f + BM25_K1 * (1 - BM25_B + BM25_B * (docLen / corpus.avgLen));
+        score += idf * (numerator / denominator);
+    }
+    return score;
+}
+/** Query terms that appear in the entry's indexed text, in query order. */
+export function matchedQueryTerms(queryTerms, entry) {
+    const docTerms = new Set(tokenize(entryText(entry)));
+    const matched = [];
+    for (const t of queryTerms)
+        if (docTerms.has(t))
+            matched.push(t);
+    return matched;
+}
+//# sourceMappingURL=bm25.js.map

package/dist/search/boosts.d.ts

@@ -0,0 +1,54 @@
+import { type MemoryEntry } from '../memory.js';
+import { type TemporalDirection, type TemporalRange } from './temporal.js';
+export declare const CHURN_STALE_RANK_MULTIPLIER = 0.5;
+export declare function churnStaleFactor(entry: MemoryEntry): number;
+export declare function recencyBoost(entry: MemoryEntry, now: Date): number;
+/** Retrieval-time outcome nudge in [0.85, 1.15]; the bm25-outcome eval baseline ranks with it too. */
+export declare function outcomeMultiplier(entry: MemoryEntry): number;
+/** A DAG summary is a topic summary (level 2) or an entity profile (level 3); both take the same deboost. */
+export declare function isDagSummary(entry: MemoryEntry): boolean;
+/** Summary deboost: per-call, then HIPPO_SUMMARY_DEBOOST, then 0.85; values outside (0, 1] fall through. */
+export declare function resolveSummaryDeboost(perCall?: number): number;
+export interface SummaryScoring {
+    deboost: number;
+    freshness: boolean;
+}
+/** The sync BM25 path applies no summary scoring; multiplying by exactly 1 keeps its scores bit-identical. */
+export declare const NO_SUMMARY_SCORING: SummaryScoring;
+export declare function summaryScoring(options: {
+    summaryDeboost?: number;
+    summaryFreshness?: boolean;
+}): SummaryScoring;
+export declare function summaryMultipliers(entry: MemoryEntry, now: Date, s: SummaryScoring): {
+    deboost: number;
+    freshness: number;
+};
+export declare function strengthRecencyMultipliers(entry: MemoryEntry, now: Date): {
+    strength: number;
+    recency: number;
+};
+export interface BoostContext {
+    now: Date;
+    pathTags: string[];
+    scope: string | null;
+    temporal: {
+        direction: TemporalDirection;
+        range: TemporalRange;
+    };
+    /** The sync BM25 path never applied the outcome nudge. */
+    outcome: boolean;
+    summary: SummaryScoring;
+}
+export interface AppliedBoosts {
+    score: number;
+    decisionBoost: number;
+    churnStaleMultiplier: number;
+    pathBoost: number;
+    outcomeBoost: number;
+    scopeBoost: number;
+    summaryDeboost: number;
+    summaryFreshnessBoost: number;
+}
+/** Applies every rank multiplier one at a time, in a fixed order, so float rounding matches across paths. */
+export declare function applyRankBoosts(score: number, entry: MemoryEntry, ctx: BoostContext): AppliedBoosts;
+//# sourceMappingURL=boosts.d.ts.map