hippo-memory 1.64.1 → 1.66.0

package/dist/predictions/planning-fallacy.d.ts

@@ -1,3 +1,6 @@
+import { type AppendAuditOpts } from '../audit.js';
+import { type ForwardClaimMatch } from '../forward-claim-detector.js';
+import { type PredictionBaserate } from './store.js';
 /**
  * Surface delivered on `RecallResult.planningFallacyHint` when an
  * agent's recall query carries a forward-prediction phrase AND the closest
@@ -66,6 +69,49 @@ export interface ComputePlanningFallacyHintOpts {
      *  carry the right attribution instead of the 'cli' default. */
     actor?: string;
 }
+export interface ClassResolution {
+    classTag: string | null;
+    /** True when ≥2 classes tied at the best overlap score AND best ≥ 1.
+     *  Caller emits `recall_autodebias_hint_tiebreak` audit and returns
+     *  null hint (silent — prevents the "show wrong class half the time"
+     *  failure mode the alphabetical-tiebreak alternative would create). */
+    tiebreak: boolean;
+}
+/** The prediction class a forward claim resolves to, and that class's closed-prediction stats when one resolved. */
+export interface PlanningFallacyEvidence extends ClassResolution {
+    readonly baserate: PredictionBaserate | null;
+}
+/** The output a claim earns from its evidence, and the audit row that records the decision when there is one. */
+export interface PlanningFallacyDecision {
+    output: PlanningFallacyOutput;
+    audit?: AppendAuditOpts;
+}
+/**
+ * Resolve a query-token set to a unique best-matching class_tag for the
+ * tenant. Scores by lower-cased token overlap; requires best score ≥ 1
+ * AND strictly greater than the 2nd-best score.
+ *
+ * Indexed via idx_predictions_tenant_class (db.ts:1015) → O(log n) seek
+ * plus a small DISTINCT scan over the per-tenant class-tag set.
+ *
+ * Scope behaviour (deliberate): class_tag selection is TENANT-GLOBAL,
+ * NOT scope-filtered against
+ * the recall's opts.scope. The class_tag is an aggregator label across
+ * historical predictions in the class, not a per-memory scope-bound
+ * property. A no-scope recall CAN surface a class_tag from a privately-
+ * scoped prediction's class in PlanningFallacyHint.classTag — by design,
+ * because base-rate reasoning needs the full historical sample.
+ * Implications:
+ *   - The hint payload itself carries no memory content (only the aggregate
+ *     summary string + numeric stats), so memory bodies do not leak.
+ *   - The class_tag NAME is the side-channel. If sensitive labels are a
+ *     concern, callers should either use opaque class names (e.g. hashes
+ *     or numeric tokens) or set HIPPO_AUTODEBIAS=off.
+ *   - tests/api-recall-autodebias.test.ts locks this with an explicit
+ *     test asserting that scope-set predictions surface via no-scope
+ *     recalls (so future "fix" attempts that scope-filter trip CI).
+ */
+export declare function resolveClassFromTokens(hippoRoot: string, tenantId: string, queryTokens: readonly string[]): ClassResolution;
 /**
  * Planning-fallacy orchestrator.
  *
@@ -92,4 +138,10 @@ export interface ComputePlanningFallacyHintOpts {
  * Latency budget: well under 50ms; a miss pays only the regex.
  */
 export declare function computePlanningFallacyOutput(hippoRoot: string, tenantId: string, queryText: string, opts?: ComputePlanningFallacyHintOpts): PlanningFallacyOutput;
+/** The forward claim in a recall query; null when HIPPO_AUTODEBIAS=off, the query is empty or no claim matches. */
+export declare function detectPlanningClaim(queryText: string, opts?: ComputePlanningFallacyHintOpts): ForwardClaimMatch | null;
+/** Resolves a claim's tokens to one class and reads its baserate, writing no audit row. */
+export declare function planningFallacyEvidenceAt(hippoRoot: string, tenantId: string, classQueryTokens: readonly string[]): PlanningFallacyEvidence;
+/** The hint, the watching variant or nothing for a claim and its class evidence; reads and writes nothing itself. */
+export declare function decidePlanningFallacy(match: ForwardClaimMatch, evidence: PlanningFallacyEvidence, tenantId: string, actor: string): PlanningFallacyDecision;
 //# sourceMappingURL=planning-fallacy.d.ts.map

package/dist/predictions/planning-fallacy.js

@@ -28,7 +28,7 @@ import { computePredictionBaserate } from './store.js';
  *     test asserting that scope-set predictions surface via no-scope
  *     recalls (so future "fix" attempts that scope-filter trip CI).
  */
-function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
+export function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
     if (queryTokens.length === 0)
         return { classTag: null, tiebreak: false };
     const db = openHippoDb(hippoRoot);
@@ -100,56 +100,69 @@ function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
  * Latency budget: well under 50ms; a miss pays only the regex.
  */
 export function computePlanningFallacyOutput(hippoRoot, tenantId, queryText, opts = {}) {
-    // Env read FIRST so AUTODEBIAS=off pays zero regex cost. Per-call read
-    // (rather than module-load cache) is deliberate: tests env-toggle this
-    // via process.env mutation without module reload.
-    const mode = opts.mode ?? (envAutodebiasOff() ? 'off' : 'regex');
-    if (mode === 'off')
-        return {};
-    if (!queryText)
-        return {};
-    const match = detectForwardClaim(queryText);
+    const match = detectPlanningClaim(queryText, opts);
     if (!match)
         return {};
     const actor = opts.actor ?? 'recall';
-    const resolution = resolveClassFromTokens(hippoRoot, tenantId, match.classQueryTokens);
-    if (resolution.tiebreak) {
+    const { output, audit } = decidePlanningFallacy(match, planningFallacyEvidenceAt(hippoRoot, tenantId, match.classQueryTokens), tenantId, actor);
+    if (audit)
+        appendAuditEventOnce(hippoRoot, audit);
+    return output;
+}
+/** The forward claim in a recall query; null when HIPPO_AUTODEBIAS=off, the query is empty or no claim matches. */
+export function detectPlanningClaim(queryText, opts = {}) {
+    // Env read FIRST so AUTODEBIAS=off pays zero regex cost; read per call so tests can toggle it without a module reload.
+    const mode = opts.mode ?? (envAutodebiasOff() ? 'off' : 'regex');
+    if (mode === 'off')
+        return null;
+    if (!queryText)
+        return null;
+    return detectForwardClaim(queryText);
+}
+/** Resolves a claim's tokens to one class and reads its baserate, writing no audit row. */
+export function planningFallacyEvidenceAt(hippoRoot, tenantId, classQueryTokens) {
+    const resolution = resolveClassFromTokens(hippoRoot, tenantId, classQueryTokens);
+    // emitAudit=false: the recall_autodebias_hint row carries n_closed and mean_ratio, so predict_baserate stays off.
+    const baserate = resolution.classTag ? computePredictionBaserate(hippoRoot, tenantId, resolution.classTag, 'recall', false) : null;
+    return { ...resolution, baserate };
+}
+/** The hint, the watching variant or nothing for a claim and its class evidence; reads and writes nothing itself. */
+export function decidePlanningFallacy(match, evidence, tenantId, actor) {
+    if (evidence.tiebreak) {
         // Telemetry: forward-claim detected, ≥2 classes tied at best overlap. The watching variant lets the
         // caller render "watching but no baserate (tiebreak)"; the audit channel stays the source of truth.
-        return watchingWithAudit(hippoRoot, tenantId, actor, match, 'tiebreak', TIEBREAK_SUGGESTION);
+        return watchingWithAudit(tenantId, actor, match, 'tiebreak', TIEBREAK_SUGGESTION);
     }
-    if (!resolution.classTag) {
-        // Telemetry: forward-claim detected, no class scored ≥ 1. High volume here means regex+token-overlap
-        // misses real forward-claims with no class signal, the case for an embedding fallback.
-        // The watching variant lets the caller render "watching but no baserate (no class match)".
-        return watchingWithAudit(hippoRoot, tenantId, actor, match, 'no_class_match', NO_CLASS_MATCH_SUGGESTION);
+    if (!evidence.classTag) {
+        // Telemetry: no class scored ≥ 1. High volume here means regex+token-overlap misses real forward-claims
+        // with no class signal, the case for an embedding fallback.
+        return watchingWithAudit(tenantId, actor, match, 'no_class_match', NO_CLASS_MATCH_SUGGESTION);
     }
-    // emitAudit=false: avoid double-write to predict_baserate channel.
-    // The recall_autodebias_hint audit below carries n_closed + mean_ratio.
-    const baserate = computePredictionBaserate(hippoRoot, tenantId, resolution.classTag, actor, 
-    /*emitAudit=*/ false);
-    if (baserate.nClosed === 0)
-        return {}; // Silent — wait for closed data.
-    appendAuditEventOnce(hippoRoot, {
-        tenantId,
-        actor,
-        op: 'recall_autodebias_hint',
-        targetId: resolution.classTag,
-        metadata: {
-            class_tag: resolution.classTag,
-            detected_phrase: match.phrase,
-            n_closed: baserate.nClosed,
-            mean_ratio: baserate.meanRatio,
-        },
-    });
+    const baserate = evidence.baserate;
+    if (!baserate || baserate.nClosed === 0)
+        return { output: {} }; // Silent — wait for closed data.
     return {
-        hint: {
-            classTag: resolution.classTag,
-            baserateSummary: baserate.summary,
-            source: 'j3.2-auto',
-            detectedPhrase: match.phrase,
-            nClosed: baserate.nClosed,
-            meanRatio: baserate.meanRatio,
+        output: {
+            hint: {
+                classTag: evidence.classTag,
+                baserateSummary: baserate.summary,
+                source: 'j3.2-auto',
+                detectedPhrase: match.phrase,
+                nClosed: baserate.nClosed,
+                meanRatio: baserate.meanRatio,
+            },
+        },
+        audit: {
+            tenantId,
+            actor,
+            op: 'recall_autodebias_hint',
+            targetId: evidence.classTag,
+            metadata: {
+                class_tag: evidence.classTag,
+                detected_phrase: match.phrase,
+                n_closed: baserate.nClosed,
+                mean_ratio: baserate.meanRatio,
+            },
         },
     };
 }
@@ -165,19 +178,21 @@ function appendAuditEventOnce(hippoRoot, event) {
         closeHippoDb(db);
     }
 }
-function watchingWithAudit(hippoRoot, tenantId, actor, match, reason, suggestion) {
-    appendAuditEventOnce(hippoRoot, {
-        tenantId,
-        actor,
-        op: reason === 'tiebreak' ? 'recall_autodebias_hint_tiebreak' : 'recall_autodebias_hint_no_class_match',
-        targetId: match.phrase.slice(0, 100),
-        metadata: { detected_phrase: match.phrase, token_count: match.classQueryTokens.length },
-    });
+function watchingWithAudit(tenantId, actor, match, reason, suggestion) {
     return {
-        watching: {
-            detectedPhrase: match.phrase,
-            reason,
-            suggestion,
+        output: {
+            watching: {
+                detectedPhrase: match.phrase,
+                reason,
+                suggestion,
+            },
+        },
+        audit: {
+            tenantId,
+            actor,
+            op: reason === 'tiebreak' ? 'recall_autodebias_hint_tiebreak' : 'recall_autodebias_hint_no_class_match',
+            targetId: match.phrase.slice(0, 100),
+            metadata: { detected_phrase: match.phrase, token_count: match.classQueryTokens.length },
         },
     };
 }

package/dist/quality-repair.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { appendAuditEvent } from './audit.js';
 import { withBackup } from './db/backup.js';
+import { assertSqliteAllowed } from './db/open.js';
 import { DatabaseSync } from './db/sqlite.js';
 import { getMeta, setMeta } from './db/meta.js';
 import { tableColumns } from './db/tables.js';
@@ -187,6 +188,8 @@ function repairOn(db, root, opts) {
     return { ...result, warnings };
 }
 function openForRepair(root, readOnly, fn) {
+    // Opens without openHippoDb to skip migrations, so it takes the same refusal itself.
+    assertSqliteAllowed(root);
     const file = path.join(root, 'hippo.db');
     if (!fs.existsSync(file))
         throw new Error(`No existing Hippo database at ${file}`);

package/dist/recall-trace.d.ts

@@ -173,7 +173,7 @@ export interface DeliveryEventRow {
 }
 /** One event plus its candidates in one write transaction, then prune; fail-soft. The caller must not hold a transaction on `db`. */
 export declare function writeDeliveryEvent(db: DatabaseSyncLike, input: DeliveryEventInput): number | null;
-/** Write on a short-lived connection that waits at most {@link DELIVERY_LEDGER_WAIT_MS} for the lock. Fail-soft. */
+/** Write on the request's handle, or a short-lived one, waiting at most {@link DELIVERY_LEDGER_WAIT_MS} for the lock. Fail-soft. */
 export declare function writeDeliveryEventAtRoot(root: string, input: DeliveryEventInput): number | null;
 /** On a caller's open handle, which saves a second open and close per turn; the handle's own lock wait comes back after. */
 export declare function writeDeliveryEventOnHandle(db: DatabaseSyncLike, input: DeliveryEventInput): number | null;

package/dist/recall-trace.js

@@ -15,7 +15,7 @@
  * new debug env var).
  */
 import { createHash } from 'node:crypto';
-import { openHippoDb, closeHippoDb } from './db.js';
+import { openHippoDb, closeHippoDb, rethrowIfSqliteBlocked } from './db.js';
 import { DELIVERY_LEDGER_VERSION } from './delivery-recorder.js';
 import { log } from './log.js';
 /**
@@ -109,6 +109,7 @@ export function writeRecallTraceAtRoot(root, input) {
         db = openHippoDb(root);
     }
     catch (error) {
+        rethrowIfSqliteBlocked(error);
         log.error(`recall trace connection failed: ${error instanceof Error ? error.message : String(error)}`);
         return null;
     }
@@ -267,11 +268,11 @@ export function writeDeliveryEvent(db, input) {
         return null;
     }
 }
-/** Write on a short-lived connection that waits at most {@link DELIVERY_LEDGER_WAIT_MS} for the lock. Fail-soft. */
+/** Write on the request's handle, or a short-lived one, waiting at most {@link DELIVERY_LEDGER_WAIT_MS} for the lock. Fail-soft. */
 export function writeDeliveryEventAtRoot(root, input) {
     let db;
     try {
-        db = openHippoDb(root, { busyWaitMs: DELIVERY_LEDGER_WAIT_MS });
+        db = openHippoDb(root);
     }
     catch (error) {
         // Same hook stderr line as writeDeliveryEvent above.
@@ -279,7 +280,7 @@ export function writeDeliveryEventAtRoot(root, input) {
         return null;
     }
     try {
-        return writeDeliveryEvent(db, input);
+        return writeDeliveryEventOnHandle(db, input);
     }
     finally {
         closeHippoDb(db);

package/dist/search/hybrid.d.ts

@@ -4,6 +4,7 @@ import { type BM25Corpus } from './bm25.js';
 import { type HybridVectorCandidates } from './vector.js';
 import { type GraphStreamOptions } from './fusion.js';
 import { type ResultCost, type SearchResult } from './types.js';
+import type { HippoStore } from '../store-port.js';
 export interface HybridSearchOptions {
     budget?: number;
     now?: Date;
@@ -40,6 +41,8 @@ export interface HybridSearchOptions {
     graphStream?: GraphStreamOptions;
     /** Add the rows nearest the query vector, not only rescore `entries`; without it a row no query word matches cannot surface. */
     vectorCandidates?: HybridVectorCandidates;
+    /** Where vectors are read; hippo.db under `hippoRoot` when unset. */
+    store?: HippoStore;
 }
 /** BM25 blended with cosine similarity when stored vectors and a provider are available, BM25 * strength * recency otherwise. */
 export declare function hybridSearch(query: string, entries: MemoryEntry[], options?: HybridSearchOptions): Promise<SearchResult[]>;

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

@@ -1,5 +1,6 @@
 import { type MemoryEntry } from '../memory.js';
 import { type PhysicsConfig } from '../physics-config.js';
+import { type HippoStore } from '../store-port.js';
 import { type HybridVectorCandidates } from './vector.js';
 import { type ResultCost, type SearchResult } from './types.js';
 export interface PhysicsSearchOptions {
@@ -23,6 +24,8 @@ export interface PhysicsSearchOptions {
     summaryFreshness?: boolean;
     /** Same as hybridSearch's: rows nearest the query join the pool before physics scoring. */
     vectorCandidates?: HybridVectorCandidates;
+    /** Where vectors and particles are read; hippo.db under `hippoRoot` when unset. */
+    store?: HippoStore;
 }
 /** Scores memories by gravity, momentum and cluster amplification; rows without physics state rank through hybridSearch. */
 export declare function physicsSearch(query: string, entries: MemoryEntry[], options?: PhysicsSearchOptions): Promise<SearchResult[]>;

package/dist/search/physics-search.js

@@ -1,20 +1,20 @@
 import { calculateStrength } from '../memory.js';
 import { estimateTokens } from '../token-ledger.js';
 import { evalNow, isRecallBoostAblated } from '../ablation.js';
-import { embeddingModelRequiresReindex } from '../embeddings.js';
+import { indexedModel, indexNeedsRebuild } from '../embeddings.js';
 import { resolveEmbeddingProvider } from '../embedding-provider.js';
 import { physicsScore as computePhysicsScores, computeMass } from '../physics.js';
 import { DEFAULT_PHYSICS_CONFIG } from '../physics-config.js';
-import { loadPhysicsState } from '../physics-state.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
+import { rethrowIfSqliteBlocked } from '../db.js';
 import { compareScoredResults } from '../compare.js';
 import { log } from '../log.js';
+import { sqliteStore } from '../store-port.js';
 import { churnStaleFactor, summaryMultipliers, summaryScoring } from './boosts.js';
 import { addDagFields, ageInDays } from './breakdown.js';
 import { fitBudget } from './finalize.js';
 import { hybridSearch } from './hybrid.js';
 import { currentEntries } from './as-of.js';
-import { vectorCandidatesOutside } from './vector.js';
+import { requireVectorReads, vectorCandidatesOutside } from './vector.js';
 import { DEFAULT_RECALL_BUDGET } from './types.js';
 /** Scores memories by gravity, momentum and cluster amplification; rows without physics state rank through hybridSearch. */
 export async function physicsSearch(query, entries, options = {}) {
@@ -27,11 +27,14 @@ export async function physicsSearch(query, entries, options = {}) {
     if (options.asOf)
         return hybridSearch(query, entries, options);
     const root = options.hippoRoot;
-    const queryVector = await physicsQueryVector(query, root, options.queryEmbedding);
+    const store = options.store ?? sqliteStore(root);
+    const queryVector = await physicsQueryVector(query, root, store, options.queryEmbedding);
     if (!queryVector)
         return hybridSearch(query, entries, options);
-    const pool = currentEntries(withVectorCandidates(root, entries, queryVector, options.vectorCandidates), options);
-    const physicsMap = loadCandidateParticles(root, pool);
+    // Checked here too, since a caller's own query vector skips the check inside physicsQueryVector.
+    const reads = requireVectorReads(store);
+    const pool = currentEntries(await withVectorCandidates(reads, entries, queryVector, options.vectorCandidates), options);
+    const physicsMap = await loadCandidateParticles(reads, pool);
     if (!physicsMap)
         return hybridSearch(query, pool, options);
     const pools = splitByParticle(pool, physicsMap, queryVector, now);
@@ -45,45 +48,44 @@ export async function physicsSearch(query, entries, options = {}) {
     return fitBudget(merged, options.budget ?? DEFAULT_RECALL_BUDGET, options.minResults ?? 1, options.cost);
 }
 /** The caller's vector, else the provider's; null sends the caller to hybridSearch. */
-async function physicsQueryVector(query, root, given) {
+async function physicsQueryVector(query, root, store, given) {
     if (given && given.length > 0)
         return given;
     // Physics scores against particle positions, not the stored vector index, so a pruned index must not block it.
     try {
         const provider = resolveEmbeddingProvider(root);
-        if (!provider.isAvailable() || embeddingModelRequiresReindex(root, provider.id))
+        if (!provider.isAvailable())
+            return null;
+        if (indexNeedsRebuild(indexedModel(await requireVectorReads(store).embeddingIndexState()), provider.id))
             return null;
         const [vec] = await provider.embed([query], 'query');
         return vec && vec.length > 0 ? vec : null;
     }
     catch (err) {
+        rethrowIfSqliteBlocked(err);
         log.debug(`physics search: query embed failed, using hybrid: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
 }
-function withVectorCandidates(root, entries, queryVector, spec) {
+async function withVectorCandidates(reads, entries, queryVector, spec) {
     if (!spec)
         return entries;
     try {
-        return [...entries, ...vectorCandidatesOutside(root, entries, queryVector, spec)];
+        return [...entries, ...await vectorCandidatesOutside(reads, entries, queryVector, spec)];
     }
     catch (err) {
+        rethrowIfSqliteBlocked(err);
         log.warn(`physics search ranked the lexical pool only; the vector lookup failed: ${err instanceof Error ? err.message : String(err)}`);
         return entries;
     }
 }
 /** Particles for the candidate rows only, so one tenant's search never reads every tenant's physics state. */
-function loadCandidateParticles(root, pool) {
+async function loadCandidateParticles(reads, pool) {
     try {
-        const db = openHippoDb(root);
-        try {
-            return loadPhysicsState(db, pool.map((e) => e.id));
-        }
-        finally {
-            closeHippoDb(db);
-        }
+        return await reads.physicsParticles(pool.map((e) => e.id));
     }
     catch (err) {
+        rethrowIfSqliteBlocked(err);
         log.debug(`physics search: state load failed, using hybrid: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }

package/dist/search/vector.d.ts

@@ -1,5 +1,6 @@
 import type { MemoryEntry } from '../memory.js';
-import { type VectorCandidateSpec } from '../store/search-rows.js';
+import type { VectorCandidateSpec } from '../store/search-rows.js';
+import { type HippoStore, type VectorReads } from '../store-port.js';
 import { type CurrentnessOptions } from './as-of.js';
 /** hybridSearch's vector arm: which rows it may add, plus the caller's JS admission rules (exact private regex, entry filters). */
 export type HybridVectorCandidates = VectorCandidateSpec & {
@@ -16,9 +17,13 @@ export interface VectorArm {
 export interface VectorArmOptions extends CurrentnessOptions {
     hippoRoot?: string;
     vectorCandidates?: HybridVectorCandidates;
+    /** Where vectors are read; hippo.db under `hippoRoot` when unset. */
+    store?: HippoStore;
 }
+/** The store's vector reads; a store without them answers 501, as any unported path does. */
+export declare function requireVectorReads(store: HippoStore): VectorReads;
 /** The nearest admitted rows not already in `entries`. */
-export declare function vectorCandidatesOutside(hippoRoot: string, entries: readonly MemoryEntry[], queryVector: readonly number[], spec: HybridVectorCandidates): MemoryEntry[];
+export declare function vectorCandidatesOutside(reads: VectorReads, entries: readonly MemoryEntry[], queryVector: readonly number[], spec: HybridVectorCandidates): Promise<MemoryEntry[]>;
 /** Embeds the query and loads stored vectors; any failure leaves BM25 to rank alone. */
 export declare function resolveVectorArm(query: string, entries: MemoryEntry[], options: VectorArmOptions): Promise<VectorArm>;
 export interface DenseScores {

package/dist/search/vector.js

@@ -1,17 +1,32 @@
-import { cosineSimilarity, embeddingModelRequiresReindex, hasEmbeddings, loadStoredVectors } from '../embeddings.js';
-import { loadVectorCandidateEntries } from '../store/search-rows.js';
+import { cosineSimilarity, indexedModel, indexNeedsRebuild } from '../embeddings.js';
 import { resolveEmbeddingProvider } from '../embedding-provider.js';
+import { rethrowIfSqliteBlocked } from '../db.js';
+import { StoreNotPortedError } from '../db/sqlite-blocked.js';
 import { log } from '../log.js';
+import { sqliteStore } from '../store-port.js';
 import { redactSecretsStrict } from '../secret-detect.js';
 import { currentEntries } from './as-of.js';
 // Search runs on every hook prompt, so one line per reason per process says why vectors went unused without flooding stderr.
 function warnBm25Fallback(reason, detail) {
     log.once(`search.bm25-fallback.${reason}`, 'warn', `hybrid search fell back to BM25 only: ${redactSecretsStrict(detail)}`);
 }
+function reindexHint(storeKind) {
+    const why = 'the embedding index was built by another model or is being rebuilt';
+    // `hippo embed` writes only hippo.db, so another store gets its vectors by a rebuild from it.
+    return storeKind === 'sqlite'
+        ? `${why}; run 'hippo embed'`
+        : `${why}; run 'hippo embed' on the SQLite store, then rebuild the '${storeKind}' database from it`;
+}
+/** The store's vector reads; a store without them answers 501, as any unported path does. */
+export function requireVectorReads(store) {
+    if (!store.vectors)
+        throw new StoreNotPortedError(store.kind, 'vectors');
+    return store.vectors;
+}
 /** The nearest admitted rows not already in `entries`. */
-export function vectorCandidatesOutside(hippoRoot, entries, queryVector, spec) {
+export async function vectorCandidatesOutside(reads, entries, queryVector, spec) {
     const inPool = new Set(entries.map((e) => e.id));
-    return loadVectorCandidateEntries(hippoRoot, queryVector, spec).filter((e) => !inPool.has(e.id) && (spec.admit?.(e) ?? true));
+    return (await reads.nearestEntries(queryVector, spec)).filter((e) => !inPool.has(e.id) && (spec.admit?.(e) ?? true));
 }
 /** Embeds the query and loads stored vectors; any failure leaves BM25 to rank alone. */
 export async function resolveVectorArm(query, entries, options) {
@@ -22,6 +37,7 @@ export async function resolveVectorArm(query, entries, options) {
         await fillVectorArm(arm, query, options.hippoRoot, options);
     }
     catch (err) {
+        rethrowIfSqliteBlocked(err);
         warnBm25Fallback('error', err instanceof Error ? err.message : String(err));
     }
     return arm;
@@ -30,14 +46,17 @@ async function fillVectorArm(arm, query, root, options) {
     const provider = resolveEmbeddingProvider(root);
     if (!provider.isAvailable())
         return;
-    if (embeddingModelRequiresReindex(root, provider.id)) {
-        warnBm25Fallback('reindex', "the embedding index was built by another model or is being rebuilt; run 'hippo embed'");
+    const store = options.store ?? sqliteStore(root);
+    const reads = requireVectorReads(store);
+    const index = await reads.embeddingIndexState();
+    if (indexNeedsRebuild(indexedModel(index), provider.id)) {
+        warnBm25Fallback('reindex', reindexHint(store.kind));
         return;
     }
     const spec = options.vectorCandidates;
-    const vectors = loadStoredVectors(root, arm.entries.map((e) => e.id));
+    const vectors = await reads.storedVectors(arm.entries.map((e) => e.id));
     // Only spend a (possibly paid, off-box) query embedding when there is a stored vector this search can use.
-    if (vectors.size === 0 && !(spec !== undefined && hasEmbeddings(root)))
+    if (vectors.size === 0 && !(spec !== undefined && index.hasVectors))
         return;
     const [vec] = await provider.embed([query], 'query');
     arm.queryVector = vec ?? [];
@@ -45,11 +64,11 @@ async function fillVectorArm(arm, query, root, options) {
         warnBm25Fallback('empty-query-vector', 'the embedding provider returned no vector for the query');
         return;
     }
-    const added = spec ? vectorCandidatesOutside(root, arm.entries, arm.queryVector, spec) : [];
+    const added = spec ? await vectorCandidatesOutside(reads, arm.entries, arm.queryVector, spec) : [];
     if (added.length > 0) {
         arm.addedRows = true;
         arm.entries = currentEntries([...arm.entries, ...added], options);
-        for (const [id, v] of loadStoredVectors(root, added.map((e) => e.id)))
+        for (const [id, v] of await reads.storedVectors(added.map((e) => e.id)))
             vectors.set(id, v);
     }
     arm.embeddingIndex = Object.fromEntries(vectors);

package/dist/server/routes/recall.d.ts

@@ -1,5 +1,5 @@
 import type { RouteRequest } from '../types.js';
-/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
+/** Test-only: reset the HTTP recall rings. Call from beforeEach. */
 export declare function __resetSessionRecallHistoryHttp(): void;
 export declare function handleRecallMemories({ req, res, opts, query }: RouteRequest): Promise<void>;
 export declare function handleAssembleSession({ req, res, opts, query }: RouteRequest, assembleMatch: Record<string, string>): Promise<void>;