hippo-memory 1.60.0 → 1.61.0

package/dist/recall-pipeline.d.ts

@@ -2,7 +2,7 @@ import { type GoalRecallLogRow } from './goals.js';
 import { type MemoryEntry } from './memory.js';
 import type { PhysicsConfig } from './physics-config.js';
 import type { RerankerFn } from './rerankers/types.js';
-import { type ResultCost, type SearchResult } from './search.js';
+import type { ResultCost, SearchResult } from './search/types.js';
 /** Stores rankRecall reads and where it sends operator notes. */
 export interface RankRecallCtx {
     hippoRoot: string;
@@ -23,7 +23,7 @@ export interface RecallSearchOpts {
     mmrLambda: number;
     localBump: number;
     minResults?: number;
-    /** Score breakdowns for `hippo explain`; explain's physics call also leaves out the bi-temporal flags. */
+    /** Score breakdowns for `hippo explain`; explain's physics call also leaves out minResults and includeSuperseded. */
     explain: boolean;
 }
 /** `--graph-hops` and `--graph-seeds`. */

package/dist/recall-pipeline.js

@@ -4,17 +4,18 @@ import { evalNow } from './ablation.js';
 import { oneCopyPerMemory } from './api.js';
 import { compareEntryIdentity } from './compare.js';
 import { closeHippoDb, openHippoDb } from './db.js';
-import { isEmbeddingAvailable } from './embeddings.js';
+import { isEmbeddingAvailable } from './local-embedding.js';
 import { computeGoalStackBoost } from './goals.js';
 import { graphExpandRecall } from './graph-recall.js';
 import { DEFAULT_GRAPH_STREAM_WEIGHT } from './graph-stream.js';
 import { Layer } from './memory.js';
 import { multihopSearch } from './multihop.js';
 import { passesCliRecallScopeFilter } from './recall-scope.js';
-import { hybridSearch, physicsSearch, textOverlap } from './search.js';
+import { hybridSearch } from './search/hybrid.js';
+import { physicsSearch } from './search/physics-search.js';
 import { searchBothHybrid } from './shared.js';
-import { loadRecallSearchEntries } from './store.js';
-import { tokenize as tokenizeQuery } from './tokenize.js';
+import { loadRecallSearchEntries, recallScopeFilter } from './store/search-rows.js';
+import { textOverlap, tokenize as tokenizeQuery } from './tokenize.js';
 /** Ranks memories for a query as `hippo recall` does, through the `limit` slice. Reads stores, embeddings and
  *  physics state; writes nothing and prints nothing (notes go to `ctx.note`). The caller supplies the cost
  *  function and reranker in `opts`, and persists the returned goal-log rows. */
@@ -124,10 +125,17 @@ async function searchPool(ctx, opts, pool) {
         const allEntries = oneCopyPerMemory(pool.local, pool.global, evalNow()).flat();
         return multihopSearch(query, allEntries, { budget, cost, hippoRoot: ctx.hippoRoot, minResults, includeSuperseded, asOf });
     }
+    const requested = opts.explicitScope || undefined;
+    const vectorCandidates = {
+        tenantId: ctx.tenantId,
+        scope: recallScopeFilter(requested, 'additive'),
+        includeSuperseded: includeSuperseded || Boolean(asOf),
+        admit: (e) => passesCliRecallScopeFilter(e.scope ?? null, requested),
+    };
     if (search.usePhysics && !globalRoot) {
-        // Explain has never passed the bi-temporal flags to physics; keeping that holds its output steady.
-        const temporal = explain ? {} : { minResults, includeSuperseded, asOf };
-        return physicsSearch(query, pool.local, { budget, cost, hippoRoot: ctx.hippoRoot, physicsConfig: search.physicsConfig, scope, explain, ...temporal });
+        // Explain leaves minResults and includeSuperseded out to hold its output steady; asOf must reach physics or later rows leak.
+        const temporal = explain ? { asOf } : { minResults, includeSuperseded, asOf };
+        return physicsSearch(query, pool.local, { budget, cost, hippoRoot: ctx.hippoRoot, physicsConfig: search.physicsConfig, scope, explain, vectorCandidates, ...temporal });
     }
     if (globalRoot) {
         // searchBothHybrid reloads candidates itself, so the scope rule is passed in rather than inherited from the pool.
@@ -137,7 +145,7 @@ async function searchPool(ctx, opts, pool) {
             recallScope: opts.explicitScope ? { requested: opts.explicitScope, additive: true } : {},
         });
     }
-    return hybridSearch(query, pool.local, { budget, cost, hippoRoot: ctx.hippoRoot, explain, mmr, mmrLambda, minResults, scope, includeSuperseded, asOf });
+    return hybridSearch(query, pool.local, { budget, cost, hippoRoot: ctx.hippoRoot, explain, mmr, mmrLambda, minResults, scope, includeSuperseded, asOf, vectorCandidates });
 }
 /** Adds memories reached by walking the entity graph out from the lexical seeds. */
 function expandGraph(ctx, opts, graph, state) {

package/dist/recall-scope.js

@@ -124,7 +124,7 @@ export function isRestrictedScope(scope) {
         return false;
     // SAFETY: RECALL_DEFAULT_DENY_SCOPES is a readonly tuple of string
     // literals; widening the array (not the input) lets .includes() take any scope.
-    // `:private:` anywhere, any case, matches the store's SQL default-deny (store.ts:894) so JS never admits what SQL hides.
+    // `:private:` anywhere, any case, matches the store's SQL default-deny (store/search-rows.ts) so JS never admits what SQL hides.
     return isPrivateScope(scope) || /:private:/i.test(scope) || RECALL_DEFAULT_DENY_SCOPES.includes(scope);
 }
 /** True when `actor` may read `scope`: admin always; member needs an exact grant on a restricted scope. */

package/dist/recall-trace.d.ts

@@ -16,7 +16,7 @@
  * new debug env var).
  */
 import { type DatabaseSyncLike } from './db.js';
-import type { RerankStep } from './search.js';
+import type { RerankStep } from './search/types.js';
 import { type DeliveryEventInput } from './delivery-recorder.js';
 /** One ranked result to persist alongside its trace row. */
 export interface RecallTraceResultInput {

package/dist/refine-llm.js

@@ -13,7 +13,8 @@
  * - On failure (API error, bad response), the original memory is untouched.
  */
 import { Layer } from './memory.js';
-import { loadAllEntries, readEntry, writeEntry } from './store.js';
+import { writeEntry } from './store/entry-writes.js';
+import { loadAllEntries, readEntry } from './store/entry-reads.js';
 import { redactSecretsStrict } from './secret-detect.js';
 import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
 import { log } from './log.js';

package/dist/reject-flow.js

@@ -15,7 +15,12 @@ import { closeHippoDb } from './db.js';
 import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { deleteDormantRow, listDormantSnapshots, purgeDormantByDigest, replaceDormantEntry } from './dormant.js';
-import { openStore, deleteEntryCore, purgeMirrorBestEffort, selectAllEntries, stampOriginProject, writeEntryDbOnly, writeEntryMirrors, } from './store.js';
+import { stampOriginProject } from './store/entry-row.js';
+import { purgeMirrorBestEffort } from './store/mirrors.js';
+import { openStore } from './store/open.js';
+import { writeEntryDbOnly, writeEntryMirrors } from './store/entry-writes.js';
+import { selectAllEntries } from './store/entry-reads.js';
+import { deleteEntryCore } from './store/delete-and-batch.js';
 import { heldTexts } from './same-text.js';
 import { mergedSuccessor } from './merged-row.js';
 import { rejectionDigest, normalizeValueForRejection, insertRejectedValue, deleteRejectedValue, listRejectedValues, } from './rejection.js';

package/dist/rerankers/clef.js

@@ -1,3 +1,4 @@
+import { envClefEndpoint, envClefEndpointToken, envClefTimeoutMs, envCloudflareAccountId, envCloudflareApiToken } from '../env.js';
 import { buildRelevanceRequest, JEV_DEFAULT_TOP_K, rankByScores } from './jev.js';
 import { isJsonObjectRecord } from '../http-util.js';
 import { log } from '../log.js';
@@ -33,7 +34,7 @@ function checkHeaderSafe(name, token) {
 }
 /** Transport from trusted local env, never call arguments: HIPPO_CLEF_ENDPOINT wins over hosted Workers AI. */
 export function resolveClefRoute(model) {
-    const endpoint = process.env.HIPPO_CLEF_ENDPOINT?.trim();
+    const endpoint = envClefEndpoint();
     if (endpoint) {
         let parsed;
         try {
@@ -52,13 +53,13 @@ export function resolveClefRoute(model) {
         if (parsed.protocol === 'http:' && !isLoopback(parsed.hostname)) {
             throw new Error('HIPPO_CLEF_ENDPOINT must use https unless it is on this machine');
         }
-        const endpointToken = process.env.HIPPO_CLEF_ENDPOINT_TOKEN?.trim() || undefined;
+        const endpointToken = envClefEndpointToken();
         if (endpointToken)
             checkHeaderSafe('HIPPO_CLEF_ENDPOINT_TOKEN', endpointToken);
         return { url: parsed.href, token: endpointToken, backend: 'private-endpoint' };
     }
-    const account = process.env.CLOUDFLARE_ACCOUNT_ID?.trim() ?? '';
-    const token = process.env.CLOUDFLARE_API_TOKEN?.trim() ?? '';
+    const account = envCloudflareAccountId();
+    const token = envCloudflareApiToken();
     if (!account || !token)
         throw new Error('CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN not set');
     if (!ACCOUNT_ID.test(account))
@@ -137,7 +138,7 @@ async function readCappedJson(resp) {
 async function requestScores(model, query, head, route) {
     const { state, questions } = buildRelevanceRequest(query, head);
     // Strict parse: parseInt would read "15s" as 15 ms, and Node clamps a delay past 2^31-1 to 1 ms.
-    const requested = Number(process.env.HIPPO_CLEF_TIMEOUT_MS);
+    const requested = Number(envClefTimeoutMs());
     const timeoutMs = Number.isInteger(requested) && requested > 0 && requested <= MAX_TIMEOUT_MS ? requested : DEFAULT_TIMEOUT_MS;
     const headers = new Headers({ 'content-type': 'application/json' });
     if (route.token)

package/dist/rerankers/jev.d.ts

@@ -1,5 +1,5 @@
 import type { RerankerFn, RerankResult } from './types.js';
-import type { SearchResult } from '../search.js';
+import type { SearchResult } from '../search/types.js';
 export declare const JEV_DEFAULT_TOP_K = 40;
 /** The System One `state` and one `noul` question per candidate (`c1`..`cN`). */
 export interface RelevanceRequest {

package/dist/rerankers/jev.js

@@ -1,3 +1,4 @@
+import { envJevModel, envJevTimeoutMs, envTypesafeApiKey } from '../env.js';
 import { crossEncoderReranker } from './cross-encoder.js';
 import { redactSecretsStrict } from '../secret-detect.js';
 import { log } from '../log.js';
@@ -45,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 {
@@ -59,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,

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 { 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: ${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/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,13 +47,25 @@ export function loadWorkspaceRegistry(globalRoot) {
             workspaces,
         };
     }
-    catch {
-        // A missing or corrupt registry starts empty; the next registration rewrites it.
+    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