hippo-memory 1.69.0 → 1.71.0

package/dist/store/rule-sql.js

@@ -0,0 +1,37 @@
+// The SQL twins of the model's strength and keep rules (src/core/memory.ts); keep in step with calculateStrength and canAutoDelete.
+import { DAY_MS } from '../util/time.js';
+import { isDecayAblated, isOutcomeSlowAblated, isRecallBoostAblated } from '../core/ablation.js';
+import { DECAY_BASE, EMOTIONAL_MULTIPLIERS, FALLBACK_HALF_LIFE_DAYS, KEEP_PAIRS, MAX_WRONG_HALVINGS, RETRIEVAL_BOOST_SLOPE, REWARD_SLOPE, applyLossAversionRatio, } from '../core/memory.js';
+const UNIX_EPOCH_JULIAN_DAY = 2440587.5;
+/** calculateStrength's clock-basis formula as SQL over `memories` columns, flags and multipliers baked in; keep in step.
+ *  An unparseable date scores NULL here and 0 in JS, so sums agree. */
+export function strengthSql(now) {
+    const num = (n) => (Number.isInteger(n) ? n.toFixed(1) : String(n));
+    const pos = 'COALESCE(outcome_positive, 0)';
+    const neg = 'COALESCE(outcome_negative, 0)';
+    const wrong = isOutcomeSlowAblated() || isDecayAblated() ? '0' : `MAX(0, ${neg} - ${pos})`;
+    const reward = isOutcomeSlowAblated()
+        ? '1.0'
+        : `(CASE WHEN ${pos} = 0 AND ${neg} = 0 THEN 1.0 ELSE 1.0 + ${REWARD_SLOPE} * (${pos} - ${neg}) / (${pos} + ${neg} + 1.0) END)`;
+    const halfLife = `(COALESCE(half_life_days, ${FALLBACK_HALF_LIFE_DAYS}) * ${reward})`;
+    const anchor = isRecallBoostAblated() ? 'created' : 'last_retrieved';
+    const nowJulian = num(now.getTime() / DAY_MS + UNIX_EPOCH_JULIAN_DAY);
+    const decay = isDecayAblated() ? '1.0' : `pow(${DECAY_BASE}, (${nowJulian} - julianday(${anchor})) / ${halfLife})`;
+    const boost = isRecallBoostAblated()
+        ? '1.0'
+        : `(CASE WHEN ${wrong} > 0 THEN 1.0 ELSE 1.0 + ${RETRIEVAL_BOOST_SLOPE} * log2(COALESCE(retrieval_count, 0) + 1) END)`;
+    const valences = /* SAFETY: a Record keyed by EmotionalValence */ Object.keys(EMOTIONAL_MULTIPLIERS);
+    const emotion = `(CASE COALESCE(emotional_valence, 'neutral') ${valences
+        .map((v) => `WHEN '${v}' THEN ${num(applyLossAversionRatio(v, EMOTIONAL_MULTIPLIERS[v]))}`)
+        .join(' ')} ELSE 1.0 END)`;
+    const penalty = `pow(${DECAY_BASE}, MIN(${wrong}, ${MAX_WRONG_HALVINGS}))`;
+    return `(CASE WHEN pinned THEN ${penalty} WHEN ${halfLife} <= 0 THEN 0.0
+    ELSE MIN(1.0, MAX(0.0, ${decay} * ${boost} * ${emotion})) * ${penalty} END)`;
+}
+const sqlText = (s) => `'${s.replace(/'/g, "''")}'`;
+// json_each matches the tag as a whole element; substr, not LIKE, keeps the prefix case-sensitive like startsWith.
+const keepPairSql = (p) => `(COALESCE(superseded_by, '') = '' AND EXISTS (SELECT 1 FROM json_each(CASE WHEN json_valid(tags_json) THEN tags_json ELSE '[]' END) WHERE value = ${sqlText(p.tag)}) AND substr(source, 1, ${p.sourcePrefix.length}) = ${sqlText(p.sourcePrefix)})`;
+// Pinned and kept rows stay (a superseded row is not kept: its successor carries the tag and
+// source); raw rows leave only through archiveRawMemory. The SQL twin guards the DELETE itself.
+export const AUTO_DELETABLE_SQL = `pinned = 0 AND kind != 'raw'${KEEP_PAIRS.map((p) => ` AND NOT ${keepPairSql(p)}`).join('')}`;
+//# sourceMappingURL=rule-sql.js.map

package/dist/store/search-rows.d.ts

@@ -1,18 +1,7 @@
-import type { MemoryEntry } from '../memory.js';
-import { type DatabaseSyncLike } from '../db.js';
-/**
- * Recall-mode scope filter shape, exported so callers and tests can name it. Three modes:
- *   - 'default-deny': exclude scopes in `RECALL_DEFAULT_DENY_SCOPES`.
- *   - 'exact': exact match on `m.scope = value` (api.recall's explicit-scope request semantics).
- *   - 'default-deny-or-exact': the default-admitted set PLUS rows whose scope equals `value` (CLI `--scope`).
- *     The flag began as a tag-boost hint, so narrowing would return zero rows for tag-scoped workflows.
- *
- * Background pipelines (`consolidate`, `embeddings`, `refine-llm`, ...) call
- * `loadSearchEntries` (no scopeFilter arg) and see all rows including
- * quarantine.
- */
-/** @internal Internal SQL-builder shape; not on the public API
- *  surface (not re-exported from `src/index.ts`). Subject to change. */
+import type { MemoryEntry } from '../core/memory.js';
+import { type DatabaseSyncLike } from '../db/index.js';
+/** Recall scope filter: 'default-deny' (exclude RECALL_DEFAULT_DENY_SCOPES), 'exact' (m.scope = value), 'default-deny-or-exact' (both; CLI `--scope`).
+ * @internal Internal SQL-builder shape; not re-exported from `src/index.ts`. Subject to change. */
 export type RecallScopeFilter = {
     mode: 'default-deny';
     ownScope?: string;
@@ -26,35 +15,26 @@ export type RecallScopeFilter = {
 };
 /** One project name, or every name a project's rows carry. */
 export type OriginFilter = string | readonly string[];
-/** Scope rule for recall: none requested is default-deny; 'exact' narrows to the request; 'additive' adds it to the default set, unless it is personal, which only `ownScope` opens. */
+/** Scope rule for recall: none requested is default-deny; 'exact' narrows to the request; 'additive' adds it to the default set, unless it is personal,
+ * which only `ownScope` opens. */
 export declare function recallScopeFilter(requestedScope: string | undefined, mode: 'exact' | 'additive', ownScope?: string): RecallScopeFilter;
-/**
- * Load likely search candidates directly from SQLite.
- * Uses FTS5 when available, falls back to LIKE matching, then full-store fallback.
- *
- * When `tenantId` is provided, every SELECT (FTS join, LIKE, fallback) filters
- * by tenant_id. Cross-tenant memories never surface. Omitted = no filter.
- */
+/** Sends term queries down the LIKE path on a build that has FTS. Only tests call it. */
+export declare function _forceLikePathForTests(on: boolean): void;
+/** Load likely search candidates: FTS5 when available, else LIKE, then full-store fallback. With `tenantId` every SELECT filters by it; omitted = no filter. */
 export declare function loadSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string): MemoryEntry[];
-/**
- * Recall-mode loader. Pushes the recall-side scope predicate into SQL so
- * `unknown:legacy` cannot leak via any consumer that hasn't remembered to re-filter.
- *
- * - `requestedScope` undefined / '': default-deny on `unknown:legacy`, admitting `ownScope`, the caller's personal scope.
- * - `requestedScope` non-empty string: exact match on `m.scope = requestedScope`.
- *
- * Private scopes: SQL applies a conservative `NOT LIKE '%:private:%'` before the LIMIT window so private
- * rows cannot starve admitted ones; `passesScopeFilterForRecall` stays the exact JS post-filter.
- *
- * Consumers: `api.recall`, `cmdRecall`/`cmdExplain` direct CLI paths
- * and `searchBothHybrid` recall mode. Background pipelines
- * (`consolidate`, `embeddings`, `refine-llm`, ...) keep using
- * `loadSearchEntries` so they can see quarantined rows when needed.
- *
- * `tenantId` is optional because searchBothHybrid's is; undefined means no tenant filter.
- */
+/** Recall-mode loader: scope predicate in SQL so `unknown:legacy` cannot leak. Empty `requestedScope` default-denies (admits `ownScope`); else exact match.
+ * SQL `NOT LIKE '%:private:%'` runs before the LIMIT so private rows cannot starve admitted ones; `passesScopeFilterForRecall` is the exact post-filter. */
 export declare function loadRecallSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean, originProjects?: OriginFilter, ownScope?: string): MemoryEntry[];
-export declare function loadRecallSearchEntriesFromDb(db: DatabaseSyncLike, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean, originProjects?: OriginFilter, ownScope?: string): MemoryEntry[];
+export interface RecallSearchEntriesOptions {
+    readonly limit?: number;
+    readonly tenantId?: string;
+    readonly requestedScope?: string;
+    readonly explicitScopeMode?: 'exact' | 'additive';
+    readonly includeSuperseded?: boolean;
+    readonly originProjects?: OriginFilter;
+    readonly ownScope?: string;
+}
+export declare function loadRecallSearchEntriesFromDb(db: DatabaseSyncLike, query: string, options?: RecallSearchEntriesOptions): MemoryEntry[];
 /** Which rows the vector arm of hybrid search may add: the same tenant, scope and superseded rules as the lexical load. */
 export interface VectorCandidateSpec {
     tenantId?: string;
@@ -65,7 +45,7 @@ export interface VectorCandidateSpec {
     origin?: OriginFilter;
 }
 /** The rows nearest `queryVector` that pass `spec`, nearest first. */
-export declare function loadVectorCandidateEntries(hippoRoot: string, queryVector: readonly number[], spec: VectorCandidateSpec): MemoryEntry[];
+export declare function loadVectorCandidateEntries(hippoRoot: string, queryVector: readonly number[], spec: VectorCandidateSpec): Promise<MemoryEntry[]>;
 /** Rarest-K prompt terms for this connection's FTS index, as a space-joined query string.
  *  Without FTS, returns the first 32 terms, as before rarest-term selection. */
 export declare function pickRarestFtsQuery(db: DatabaseSyncLike, terms: readonly string[], maxTerms?: number): string;

package/dist/store/search-rows.js

@@ -1,14 +1,13 @@
-import { envForceLikePath } from '../env.js';
-import { isFtsAvailable, closeHippoDb } from '../db.js';
-import { tokenize } from '../tokenize.js';
-import { isPersonalScope, scopeAdmitSql } from '../recall-scope.js';
-import { ftsTermParts, RAREST_TERM_COUNT, rarestFtsQuery } from '../prompt-recall.js';
-import { log } from '../log.js';
-import { originInSql } from '../project-identity.js';
-import { topVectorMatches } from '../vector-store.js';
+import { isFtsAvailable, closeHippoDb } from '../db/index.js';
+import { tokenize } from '../util/tokenize.js';
+import { isPersonalScope, scopeAdmitSql } from './recall-scope.js';
+import { ftsTermParts, RAREST_TERM_COUNT, rarestFtsQuery } from '../core/prompt-recall.js';
+import { errorMessage, log } from '../util/log.js';
+import { originInSql } from '../core/project-identity.js';
+import { topVectorMatches } from '../db/vector-store.js';
 import { MEMORY_SELECT_COLUMNS, MEMORY_SEARCH_COLUMNS, DEFAULT_SEARCH_CANDIDATE_LIMIT, rowToEntry, } from './rows.js';
-import { openStore } from './open.js';
-import { escapeLike } from '../escape.js';
+import { onHandle, openStore } from './open.js';
+import { escapeLike } from '../util/escape.js';
 /** The recall scope rule for a table column prefix (`m.` or none); `passesScopeFilterForRecall` in recall-scope.ts is its JS twin. */
 function recallScopeClause(col, scopeFilter) {
     if (scopeFilter === undefined)
@@ -29,23 +28,28 @@ function withProject(scope, col, origin) {
     const originProjects = [origin].flat();
     return { sql: `${scope.sql} AND (${col}origin_project = '' OR ${originInSql(originProjects, `${col}origin_project`)})`, params: [...scope.params, ...originProjects] };
 }
-/** Scope rule for recall: none requested is default-deny; 'exact' narrows to the request; 'additive' adds it to the default set, unless it is personal, which only `ownScope` opens. */
+/** Scope rule for recall: none requested is default-deny; 'exact' narrows to the request; 'additive' adds it to the default set, unless it is personal,
+ * which only `ownScope` opens. */
 export function recallScopeFilter(requestedScope, mode, ownScope) {
     if (!requestedScope || (mode === 'additive' && isPersonalScope(requestedScope)))
         return { mode: 'default-deny', ownScope };
     return mode === 'additive' ? { mode: 'default-deny-or-exact', value: requestedScope, ownScope } : { mode: 'exact', value: requestedScope };
 }
 const FTS_QUERY_SYNTAX_RE = /fts5: syntax error|unterminated string/i;
-function loadSearchRows(db, query, limit, tenantId, scopeFilter, includeSuperseded = true, originProjects) {
+let forceLikePath = false;
+/** Sends term queries down the LIKE path on a build that has FTS. Only tests call it. */
+export function _forceLikePathForTests(on) {
+    forceLikePath = on;
+}
+function loadSearchRows(db, query, limit, tenantId, options = {}) {
+    const { scopeFilter, includeSuperseded = true, originProjects } = options;
     const p = searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjects);
     const terms = Array.from(new Set(tokenize(query)));
     if (terms.length === 0) {
         // LIMIT here too, so every candidate path honours the caller's cap.
         return selectAllCandidates(db, p, limit);
     }
-    // `HIPPO_FORCE_LIKE_PATH=1` forces the LIKE path for tests; gated at this read site so
-    // writes keep using `isFtsAvailable` and never silently skip FTS index sync.
-    const forceLikePath = envForceLikePath();
+    // The test switch is read here, not in `isFtsAvailable`, so writes never skip FTS index sync.
     if (!forceLikePath && isFtsAvailable(db)) {
         const rows = selectFtsCandidates(db, terms, p, limit);
         if (rows.length > 0)
@@ -59,21 +63,14 @@ function loadSearchRows(db, query, limit, tenantId, scopeFilter, includeSupersed
     return selectAllCandidates(db, p, limit);
 }
 function searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjects) {
-    // tenantId undefined = no tenant filter (legacy callers / cross-deployment
-    // helpers). tenantId set = strict tenant isolation, leveraging the composite
-    // idx_memories_tenant_created (leading column tenant_id, O(log n) lookup).
+    // tenantId undefined = no tenant filter (legacy callers / cross-deployment helpers); set = strict isolation via the composite idx_memories_tenant_created.
     const tenantPredicate = tenantId !== undefined ? ` AND m.tenant_id = ?` : '';
-    const tenantPredicateNoAlias = tenantId !== undefined ? ` AND tenant_id = ?` : '';
     const tenantOnlyPredicate = tenantId !== undefined ? ` WHERE tenant_id = ?` : '';
     const tenantParams = tenantId !== undefined ? [tenantId] : [];
     // Defensive: kind='archived' is a transient sentinel inside archiveRawMemory's SAVEPOINT, so this only
     // guards against a dropped SAVEPOINT, a persisted 'archived' state, or direct-SQL writes.
     const archivedClauseAlias = ` AND m.kind != 'archived'`;
-    const archivedClauseNoAlias = ` AND kind != 'archived'`;
-    // For the "tenant-only" path: if no tenant set, tenantOnlyPredicate is '',
-    // so prepend WHERE; if tenant set, append AND. handled in each call site
-    // by always joining `tenantOnlyPredicate + archivedClauseTenantOnly` where
-    // the latter switches between " AND" and " WHERE" based on caller context.
+    // Tenant-only path: with no tenant `tenantOnlyPredicate` is '', so the archived clause switches between ' AND' and ' WHERE' by caller context.
     const archivedClauseTenantOnly = tenantId !== undefined ? ` AND kind != 'archived'` : ` WHERE kind != 'archived'`;
     const aliasScope = withProject(recallScopeClause('m.', scopeFilter), 'm.', originProjects);
     const plainScope = withProject(recallScopeClause('', scopeFilter), '', originProjects);
@@ -81,8 +78,8 @@ function searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjec
     const currentAlias = includeSuperseded ? '' : ' AND m.superseded_by IS NULL';
     const currentNoAlias = includeSuperseded ? '' : ' AND superseded_by IS NULL';
     return {
-        tenantPredicate, tenantPredicateNoAlias, tenantOnlyPredicate, tenantParams,
-        archivedClauseAlias, archivedClauseNoAlias, archivedClauseTenantOnly,
+        tenantPredicate, tenantOnlyPredicate, tenantParams,
+        archivedClauseAlias, archivedClauseTenantOnly,
         aliasScope, plainScope, scopeParams, currentAlias, currentNoAlias,
     };
 }
@@ -97,11 +94,8 @@ function selectAllCandidates(db, p, limit) {
 function selectFtsCandidates(db, terms, p, limit) {
     try {
         const ftsQuery = terms.map((t) => `"${t.replace(/"/g, '""')}"`).join(' OR ');
-        // memories_fts virtual table has no tenant_id column; filter via the
-        // joined memories row (cheap with idx_memories_tenant_created leading
-        // on tenant_id).
-        // SAFETY: MEMORY_SEARCH_COLUMNS aliases every column to the same name
-        // MEMORY_SELECT_COLUMNS uses (plus bm25_score), matching MemoryRow.
+        // memories_fts has no tenant_id column; filter via the joined memories row (cheap with idx_memories_tenant_created).
+        // SAFETY: MEMORY_SEARCH_COLUMNS aliases every column like MEMORY_SELECT_COLUMNS (plus bm25_score), matching MemoryRow.
         return db.prepare(`
         SELECT ${MEMORY_SEARCH_COLUMNS}
         FROM memories m
@@ -113,84 +107,67 @@ function selectFtsCandidates(db, terms, p, limit) {
     }
     catch (err) {
         // A query FTS5 cannot parse is expected input; anything else means the index itself is broken.
-        const message = err instanceof Error ? err.message : String(err);
+        const message = errorMessage(err);
         if (!FTS_QUERY_SYNTAX_RE.test(message))
             log.once('fts-match-fallback', 'warn', `FTS search failed, using the slower LIKE match: ${message}`);
         return [];
     }
 }
+/** Newest admitted rows the substring match tests, so a query matching nothing costs the same in a store of any size. */
+const LIKE_WINDOW_ROWS = 2000;
+/** Substring matches in content or tags among the newest admitted rows: the lexical path without FTS5, and the catch for a part-word that FTS5 tokens miss. */
 function selectLikeCandidates(db, terms, p, limit) {
     const where = terms.map(() => `(LOWER(content) LIKE ? ESCAPE '\\' OR LOWER(tags_json) LIKE ? ESCAPE '\\')`).join(' OR ');
     const params = terms.flatMap((term) => {
         const like = `%${escapeLike(term)}%`;
         return [like, like];
     });
-    // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
-    // MemoryRow's field set.
+    // idx_memories_tenant_created serves a tenant's newest rows; with no tenant only the table's own order needs no sort.
+    const newestFirst = p.tenantParams.length > 0 ? 'created DESC' : 'rowid DESC';
+    // SHORTCUT: no index serves a substring, so a match older than the window is missed; an FTS5 trigram index is the upgrade.
+    // SAFETY: the outer query selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
     return db.prepare(`
     SELECT ${MEMORY_SELECT_COLUMNS}
-    FROM memories
-    WHERE (${where})${p.tenantPredicateNoAlias}${p.archivedClauseNoAlias}${p.plainScope.sql}${p.currentNoAlias}
+    FROM (
+      SELECT ${MEMORY_SELECT_COLUMNS}, updated_at
+      FROM memories${p.tenantOnlyPredicate}${p.archivedClauseTenantOnly}${p.plainScope.sql}${p.currentNoAlias}
+      ORDER BY ${newestFirst}
+      LIMIT ?
+    )
+    WHERE (${where})
     ORDER BY updated_at DESC, created DESC, content ASC, id ASC
     LIMIT ?
-  `).all(...params, ...p.tenantParams, ...p.scopeParams, limit);
+  `).all(...p.tenantParams, ...p.scopeParams, Math.max(limit, LIKE_WINDOW_ROWS), ...params, limit);
 }
-/**
- * Load likely search candidates directly from SQLite.
- * Uses FTS5 when available, falls back to LIKE matching, then full-store fallback.
- *
- * When `tenantId` is provided, every SELECT (FTS join, LIKE, fallback) filters
- * by tenant_id. Cross-tenant memories never surface. Omitted = no filter.
- */
+/** Load likely search candidates: FTS5 when available, else LIKE, then full-store fallback. With `tenantId` every SELECT filters by it; omitted = no filter. */
 export function loadSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return loadSearchRows(db, query, limit, tenantId).map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Recall-mode loader. Pushes the recall-side scope predicate into SQL so
- * `unknown:legacy` cannot leak via any consumer that hasn't remembered to re-filter.
- *
- * - `requestedScope` undefined / '': default-deny on `unknown:legacy`, admitting `ownScope`, the caller's personal scope.
- * - `requestedScope` non-empty string: exact match on `m.scope = requestedScope`.
- *
- * Private scopes: SQL applies a conservative `NOT LIKE '%:private:%'` before the LIMIT window so private
- * rows cannot starve admitted ones; `passesScopeFilterForRecall` stays the exact JS post-filter.
- *
- * Consumers: `api.recall`, `cmdRecall`/`cmdExplain` direct CLI paths
- * and `searchBothHybrid` recall mode. Background pipelines
- * (`consolidate`, `embeddings`, `refine-llm`, ...) keep using
- * `loadSearchEntries` so they can see quarantined rows when needed.
- *
- * `tenantId` is optional because searchBothHybrid's is; undefined means no tenant filter.
- */
+/** Recall-mode loader: scope predicate in SQL so `unknown:legacy` cannot leak. Empty `requestedScope` default-denies (admits `ownScope`); else exact match.
+ * SQL `NOT LIKE '%:private:%'` runs before the LIMIT so private rows cannot starve admitted ones; `passesScopeFilterForRecall` is the exact post-filter. */
 export function loadRecallSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true, originProjects, ownScope) {
-    const db = openStore(hippoRoot);
-    try {
-        return loadRecallSearchEntriesFromDb(db, query, limit, tenantId, requestedScope, explicitScopeMode, includeSuperseded, originProjects, ownScope);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    return onHandle(hippoRoot, (db) => {
+        return loadRecallSearchEntriesFromDb(db, query, { limit, tenantId, requestedScope, explicitScopeMode, includeSuperseded, originProjects, ownScope });
+    }, openStore);
 }
 // Split out so callers with an already-open db (the prompt-recall path) skip
 // the initStore+open/close cycle per store per call.
-export function loadRecallSearchEntriesFromDb(db, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true, originProjects, ownScope) {
-    return loadSearchRows(db, query, limit, tenantId, recallScopeFilter(requestedScope, explicitScopeMode, ownScope), includeSuperseded, originProjects).map(rowToEntry);
+export function loadRecallSearchEntriesFromDb(db, query, options = {}) {
+    const { limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true, originProjects, ownScope } = options;
+    const scopeFilter = recallScopeFilter(requestedScope, explicitScopeMode, ownScope);
+    return loadSearchRows(db, query, limit, tenantId, { scopeFilter, includeSuperseded, originProjects }).map(rowToEntry);
 }
 /** The rows nearest `queryVector` that pass `spec`, nearest first. */
-export function loadVectorCandidateEntries(hippoRoot, queryVector, spec) {
+export async function loadVectorCandidateEntries(hippoRoot, queryVector, spec) {
     const scope = withProject(recallScopeClause('m.', spec.scope), 'm.', spec.origin);
     const tenant = spec.tenantId !== undefined ? ' AND m.tenant_id = ?' : '';
     const current = spec.includeSuperseded ? '' : ' AND m.superseded_by IS NULL';
     const params = [...(spec.tenantId !== undefined ? [spec.tenantId] : []), ...scope.params];
     const db = openStore(hippoRoot);
     try {
-        const matches = topVectorMatches(db, queryVector, spec.limit ?? 50, `${tenant} AND m.kind != 'archived'${scope.sql}${current}`, params);
+        const matches = await topVectorMatches(db, queryVector, spec.limit ?? 50, `${tenant} AND m.kind != 'archived'${scope.sql}${current}`, params);
         if (matches.length === 0)
             return [];
         // SAFETY: the SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.

package/dist/store/sessions.d.ts

@@ -1,3 +1,4 @@
+import type { JsonObject } from './working-memory.js';
 import { type TaskSnapshot, type SessionEvent } from './rows.js';
 /** A shared-store caller's task state bucket: its owner and every name its project's rows carry. */
 export interface ContinuityKey {
@@ -26,36 +27,11 @@ type SnapshotInput = {
 };
 export declare function saveActiveTaskSnapshot(hippoRoot: string, tenantId: string, snapshot: SnapshotInput, key?: ContinuityKey): TaskSnapshot;
 export declare function loadActiveTaskSnapshot(hippoRoot: string, tenantId: string, key?: ContinuityKey): TaskSnapshot | null;
-/**
- * Default freshness bound for AMBIENT active-task-snapshot reads: 72h, chosen over 48h so
- * a Friday-evening orphan still offers continuity on Monday morning.
- * Exported so callers can override via `loadFreshActiveTaskSnapshot`'s
- * `opts.maxAgeMs`; deliberately no env knob (Simplicity First).
- */
+/** Default freshness bound for AMBIENT active-task-snapshot reads: 72h rather than 48h so a Friday-evening orphan still offers continuity on Monday;
+ * override via `loadFreshActiveTaskSnapshot`'s `opts.maxAgeMs`; deliberately no env knob. */
 export declare const SNAPSHOT_AMBIENT_MAX_AGE_MS: number;
-/**
- * Bounded read for AMBIENT active-task-snapshot surfaces (UserPromptSubmit
- * hook context, MCP recall block), so snapshots expire. A
- * snapshot written by `hippo pre-compact` has no death path tied to the
- * session that owns it, so an orphaned row would otherwise inject into
- * every prompt of every later session forever. Wraps `loadActiveTaskSnapshot`
- * (unchanged, still the source of truth for explicit continuity surfaces),
- * then applies, in order:
- *
- * 1. Owner match — ONLY when both `opts.sessionId` and the snapshot's
- *    `session_id` are non-null, non-empty strings and strictly equal
- *    (`===`). Owner reads are unbounded: the session that owns the snapshot
- *    can always see its own working state, regardless of age.
- * 2. Age check — everything else, including absent-vs-absent ids. A
- *    null/undefined/empty id on EITHER side never counts as an owner match;
- *    it falls through here instead. (`runPreCompact` can legitimately save a
- *    snapshot with `session_id = null`; a null-equals-null "match" would
- *    reopen indefinite ambient injection for exactly those rows.) Returns
- *    the snapshot only when `age(updated_at) <= maxAgeMs` (default
- *    `SNAPSHOT_AMBIENT_MAX_AGE_MS`); otherwise null.
- *
- * No SQL change — age derives from the existing `updated_at` column.
- */
+/** Bounded read for AMBIENT snapshot surfaces so orphaned snapshots expire. The owner (both session ids non-empty and `===`) always sees its own state;
+ * all others, null ids included (null === null is no match), get it only if age(updated_at) <= maxAgeMs (default `SNAPSHOT_AMBIENT_MAX_AGE_MS`), else null. */
 export declare function loadFreshActiveTaskSnapshot(hippoRoot: string, tenantId: string, opts?: {
     maxAgeMs?: number;
     sessionId?: string | null;
@@ -66,41 +42,39 @@ export declare function freshActiveSnapshot(snapshot: TaskSnapshot | null, opts?
     sessionId?: string | null;
 }): TaskSnapshot | null;
 export declare function clearActiveTaskSnapshot(hippoRoot: string, tenantId: string, clearedStatus?: string): boolean;
-/**
- * Close the `active` task snapshot(s) owned by `sessionId`, for the
- * session-end death path.
- * Only one `active` row exists per tenant (per owner and project when keyed) in practice (supersession happens
- * at save), but the WHERE clause scopes on `session_id` too — not just
- * `status='active' AND tenant_id=?` — so an ending session can never close a
- * different, newer session's active snapshot. Returns the number of rows
- * closed (0 when no active row is owned by `sessionId`).
- */
+/** Close the `active` task snapshot(s) owned by `sessionId` at session end; the WHERE scopes on `session_id` too so an ending session can never close a
+ * newer session's snapshot. Returns the number of rows closed. */
 export declare function closeTaskSnapshotsForSession(hippoRoot: string, tenantId: string, sessionId: string, status?: string, key?: ContinuityKey): number;
-export declare function appendSessionEvent(hippoRoot: string, tenantId: string, event: {
+interface SessionEventInput {
     session_id: string;
     event_type: string;
     content: string;
     task?: string | null;
     source?: string;
     scope?: string | null;
-    metadata?: Record<string, unknown>;
-}): SessionEvent;
+    metadata?: JsonObject;
+}
+export declare function appendSessionEvent(hippoRoot: string, tenantId: string, event: SessionEventInput): SessionEvent;
 export declare function listSessionEvents(hippoRoot: string, tenantId: string, options?: {
     session_id?: string;
     task?: string;
     limit?: number;
 }): SessionEvent[];
-/**
- * Return session_ids with a `session_complete` event newer than `sinceMs`.
- * Used by the sleep auto-promotion pass to bound scanning to a fixed window.
- */
+/** Session_ids with a `session_complete` event newer than `sinceMs`; bounds the sleep auto-promotion scan to a fixed window. */
 export declare function findPromotableSessions(hippoRoot: string, tenantId: string, sinceMs: number): Array<{
     session_id: string;
 }>;
-/**
- * Idempotency guard — true if a trace-layer memory with this source_session_id
- * already exists.
- */
+/** Idempotency guard: true if a trace-layer memory with this source_session_id already exists. */
 export declare function traceExistsForSession(hippoRoot: string, tenantId: string, session_id: string): boolean;
+/** One caller's claim on a session id. */
+export interface SessionOwnerBinding {
+    readonly tenantId: string;
+    readonly sessionId: string;
+    readonly owner: string;
+    /** Bindings older than this are pruned in the write that adds a new one. */
+    readonly retentionMs: number;
+}
+/** The owner stored for the session id, binding `binding.owner` first when none is stored. */
+export declare function sessionOwnerOrBind(hippoRoot: string, binding: SessionOwnerBinding): string | null;
 export {};
 //# sourceMappingURL=sessions.d.ts.map