hippo-memory 1.65.0 → 1.66.0

package/dist/api/recall-types.d.ts

@@ -152,6 +152,7 @@ export interface RecallOpts {
     /** Set only by the MCP recall tool, which ranks with its own scorer and drops copies from its own final list: this call
      *  then keeps a memory that a merged row in the same result holds word for word. Other callers leave it unset. */
     keepHeldCopies?: boolean;
+    leadingAudit?: readonly AppendAuditOpts[];
     /** MCP recall only: `retrieve` ranks the whole scoped store and strengthens and traces (pipeline 'mcp') just the ids this returns; `results` stays the window band. */
     showRanked?: (ranking: StoreRanking, result: RecallResult) => ShownRanking;
 }

package/dist/api/recall.js

@@ -62,7 +62,7 @@ export function recall(ctx, opts) {
     const all = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false, recallOrigin(opts), own);
     const plan = planRecall(ctx, opts, all, own);
     const { result, writes } = composeRecall(ctx, opts, windowSize, all, plan, readRecallSync(ctx, opts, plan));
-    finishRecallAt(ctx.hippoRoot, writes);
+    finishRecallAt(ctx.hippoRoot, { ...writes, audit: [...(opts.leadingAudit ?? []), ...writes.audit] });
     return result;
 }
 function recallOrigin(opts) {
@@ -82,7 +82,7 @@ export async function retrieve(ctx, opts) {
     const store = storeFor(ctx);
     let candidates = await store.searchRecallEntries(opts.query, recallSearchArgs(ctx, opts, windowSize, own));
     if (opts.mode === 'hybrid' || opts.mode === 'physics') {
-        const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, scope: opts.scope ?? null, vectorCandidates: recallVectorSpec(ctx, opts, own) };
+        const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, scope: opts.scope ?? null, vectorCandidates: recallVectorSpec(ctx, opts, own), store };
         const ranked = opts.mode === 'physics'
             ? await physicsSearch(opts.query, candidates, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
             : await hybridSearch(opts.query, candidates, searchOpts);
@@ -91,7 +91,7 @@ export async function retrieve(ctx, opts) {
     }
     const plan = planRecall(ctx, opts, candidates, own);
     const { result, writes } = composeRecall(ctx, opts, windowSize, candidates, plan, await readRecall(store, ctx, opts, plan));
-    await store.finishRecall({ ...writes, strengthen: strengthenOf(ctx, result.results.map((r) => r.id)) });
+    await store.finishRecall({ ...writes, audit: [...(opts.leadingAudit ?? []), ...writes.audit], strengthen: strengthenOf(ctx, result.results.map((r) => r.id)) });
     return result;
 }
 /** The recall load's arguments: exact scope, current rows only, the caller's project and personal scope. */
@@ -127,7 +127,7 @@ async function retrieveFromStore(ctx, opts, windowSize, show, own) {
     const loaded = await store.searchRecallEntries(opts.query, recallSearchArgs(ctx, opts, Math.max(windowSize, SHOW_RANKED_LEXICAL_WINDOW), own));
     const pool = loaded.filter((e) => passesScopeFilterForRecall(e.scope ?? null, opts.scope, own));
     // No scope option: the scope boost follows HIPPO_SCOPE and the skill env, as MCP recall always ranked.
-    const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, vectorCandidates: recallVectorSpec(ctx, opts, own) };
+    const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, vectorCandidates: recallVectorSpec(ctx, opts, own), store };
     let ranked = opts.mode === 'physics'
         ? await physicsSearch(opts.query, pool, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
         : await hybridSearch(opts.query, pool, searchOpts);
@@ -151,7 +151,7 @@ async function retrieveFromStore(ctx, opts, windowSize, show, own) {
     const shownRow = recallAuditRow(callerOf(ctx), 'recall', undefined, recallAuditMetadata(opts.query, shown.ids.length));
     await store.finishRecall({
         goalLog: [...rankedLog, ...writes.goalLog],
-        audit: [...writes.audit, shownRow, ...shown.audit],
+        audit: [...(opts.leadingAudit ?? []), ...writes.audit, shownRow, ...shown.audit],
         trace: opts.suppressRecallTrace ? undefined : {
             tenantId: ctx.tenantId,
             sessionId: opts.sessionId ?? null,

package/dist/db/open.d.ts

@@ -18,10 +18,14 @@ export declare const SLEEP_DB_WAIT_MS = 5000;
 export declare function scopedBusyWait(): number | undefined;
 /** Runs `fn` so that every hippo.db open inside it, across awaits, throws; otherwise a missed port would create and write a hippo.db nobody reads. */
 export declare function withSqliteBlocked<T>(storeKind: string, fn: () => T): T;
-/** Runs `fn` with hippo.db opens allowed again, for a store whose own methods are backed by hippo.db. */
+/** Runs `fn` with hippo.db opens allowed again, for a store whose own methods are backed by hippo.db, or a copy that reads the old hippo.db. */
 export declare function withSqliteAllowed<T>(fn: () => T): T;
 /** First line of a best-effort catch around a hippo.db open: an unported path must fail closed, not fall back silently. */
 export declare function rethrowIfSqliteBlocked<E>(err: E): void;
+/** store init --db, store copy --db and serve --db write this file in the hippo root; its text is the store kind. */
+export declare const OTHER_STORE_MARKER = "other-store";
+/** Throws where hippo.db must not open; checked on every open, not cached, since the marker can appear while a process runs. */
+export declare function assertSqliteAllowed(hippoRoot: string): void;
 /** `busyWaitMs` shortens every lock wait of this open, for a hook that must finish inside its own timeout. */
 export declare function openHippoDb(hippoRoot: string, opts?: {
     busyWaitMs?: number;

package/dist/db/open.js

@@ -1,11 +1,13 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { log } from '../log.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { errorMessage, log } from '../log.js';
 import { DatabaseSync } from './sqlite.js';
 import { tableExists } from './tables.js';
 import { assertBinaryCompatible } from './migrate.js';
 import { connectHippoDb, getHippoDbPath } from './connect.js';
 import { currentRequestStores, isScopedHandle, runWithRequestStores } from './request-stores.js';
-import { SqliteBlockedError } from './sqlite-blocked.js';
+import { OtherStoreFolderError, SqliteBlockedError } from './sqlite-blocked.js';
 export { getHippoDbPath };
 /** Lock wait for hook commands: under the 5 s prompt-hook budget even after a few skipped writes, and far above a normal write's hold. */
 export const HOOK_DB_WAIT_MS = 1000;
@@ -32,29 +34,48 @@ const sqliteBlockedBy = new AsyncLocalStorage();
 export function withSqliteBlocked(storeKind, fn) {
     return sqliteBlockedBy.run(storeKind, fn);
 }
-/** Runs `fn` with hippo.db opens allowed again, for a store whose own methods are backed by hippo.db. */
+/** Runs `fn` with hippo.db opens allowed again, for a store whose own methods are backed by hippo.db, or a copy that reads the old hippo.db. */
 export function withSqliteAllowed(fn) {
-    return sqliteBlockedBy.exit(fn);
+    return sqliteBlockedBy.exit(() => markerWaived.run(true, fn));
 }
 /** First line of a best-effort catch around a hippo.db open: an unported path must fail closed, not fall back silently. */
 export function rethrowIfSqliteBlocked(err) {
     if (err instanceof SqliteBlockedError)
         throw err;
 }
-function assertSqliteAllowed() {
+/** store init --db, store copy --db and serve --db write this file in the hippo root; its text is the store kind. */
+export const OTHER_STORE_MARKER = 'other-store';
+const markerWaived = new AsyncLocalStorage();
+// An empty or unreadable marker still refuses: falling through would write the hippo.db the marker forbids.
+function markerKind(marker) {
+    try {
+        return readFileSync(marker, 'utf8').trim() || 'unknown';
+    }
+    catch (err) {
+        log.debug(`${marker} is unreadable, so its store kind reads as unknown: ${errorMessage(err)}`);
+        return 'unknown';
+    }
+}
+/** Throws where hippo.db must not open; checked on every open, not cached, since the marker can appear while a process runs. */
+export function assertSqliteAllowed(hippoRoot) {
     const storeKind = sqliteBlockedBy.getStore();
     if (storeKind !== undefined)
         throw new SqliteBlockedError(storeKind);
+    if (markerWaived.getStore())
+        return;
+    const marker = join(hippoRoot, OTHER_STORE_MARKER);
+    if (existsSync(marker))
+        throw new OtherStoreFolderError(markerKind(marker), marker);
 }
 /** `busyWaitMs` shortens every lock wait of this open, for a hook that must finish inside its own timeout. */
 export function openHippoDb(hippoRoot, opts) {
-    assertSqliteAllowed();
+    assertSqliteAllowed(hippoRoot);
     const stores = currentRequestStores();
     return stores ? stores.get(hippoRoot, opts) : connectHippoDb(hippoRoot, opts?.busyWaitMs);
 }
 /** Open an existing store without changing it: no mkdir, WAL switch, migration or mirror cleanup. Throws when hippo.db is missing. */
 export function openHippoDbReadOnly(hippoRoot) {
-    assertSqliteAllowed();
+    assertSqliteAllowed(hippoRoot);
     const db = new DatabaseSync(getHippoDbPath(hippoRoot), { readOnly: true });
     try {
         db.exec('PRAGMA busy_timeout = 5000');

package/dist/db/sqlite-blocked.d.ts

@@ -1,6 +1,16 @@
 /** Thrown by a hippo.db open inside a request served from another store: the code path is not ported to the store port yet. */
 export declare class SqliteBlockedError extends Error {
     readonly storeKind: string;
-    constructor(storeKind: string);
+    constructor(storeKind: string, message?: string);
+}
+/** A store that lacks a whole group of port methods; it maps to the same 501, and the log names the group instead of hippo.db. */
+export declare class StoreNotPortedError extends SqliteBlockedError {
+    readonly group: string;
+    constructor(storeKind: string, group: string);
+}
+/** Thrown by a hippo.db open in a folder whose marker file names the store that holds its memories, from the CLI as from a request. */
+export declare class OtherStoreFolderError extends SqliteBlockedError {
+    readonly markerPath: string;
+    constructor(storeKind: string, markerPath: string);
 }
 //# sourceMappingURL=sqlite-blocked.d.ts.map

package/dist/db/sqlite-blocked.js

@@ -2,10 +2,28 @@
 /** Thrown by a hippo.db open inside a request served from another store: the code path is not ported to the store port yet. */
 export class SqliteBlockedError extends Error {
     storeKind;
-    constructor(storeKind) {
-        super(`hippo.db is not opened while the '${storeKind}' store serves this request; this code path is not ported to the store yet`);
+    constructor(storeKind, message = `hippo.db is not opened while the '${storeKind}' store serves this request; this code path is not ported to the store yet`) {
+        super(message);
         this.storeKind = storeKind;
         this.name = 'SqliteBlockedError';
     }
 }
+/** A store that lacks a whole group of port methods; it maps to the same 501, and the log names the group instead of hippo.db. */
+export class StoreNotPortedError extends SqliteBlockedError {
+    group;
+    constructor(storeKind, group) {
+        super(storeKind, `the '${storeKind}' store has no '${group}' reads; this code path is not ported to the store yet`);
+        this.group = group;
+        this.name = 'StoreNotPortedError';
+    }
+}
+/** Thrown by a hippo.db open in a folder whose marker file names the store that holds its memories, from the CLI as from a request. */
+export class OtherStoreFolderError extends SqliteBlockedError {
+    markerPath;
+    constructor(storeKind, markerPath) {
+        super(storeKind, `This folder's memories live in the '${storeKind}' store, so hippo.db is not used here (marker: ${markerPath})`);
+        this.markerPath = markerPath;
+        this.name = 'OtherStoreFolderError';
+    }
+}
 //# sourceMappingURL=sqlite-blocked.js.map

package/dist/db.d.ts

@@ -3,7 +3,7 @@ export { isSqliteBusy, isStoreBusy, StoreBusyError, STORE_BUSY_MESSAGE, execWith
 export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './db/meta.js';
 export { countTableRows, pruneConsolidationRuns } from './db/tables.js';
 export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './db/migrate.js';
-export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, rethrowIfSqliteBlocked, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, rethrowIfSqliteBlocked, OTHER_STORE_MARKER, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
 export { RequestStores, runWithRequestStores, currentRequestStores, outsideRequestStores } from './db/request-stores.js';
-export { SqliteBlockedError } from './db/sqlite-blocked.js';
+export { OtherStoreFolderError, SqliteBlockedError } from './db/sqlite-blocked.js';
 //# sourceMappingURL=db.d.ts.map

package/dist/db.js

@@ -2,7 +2,7 @@ export { isSqliteBusy, isStoreBusy, StoreBusyError, STORE_BUSY_MESSAGE, execWith
 export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './db/meta.js';
 export { countTableRows, pruneConsolidationRuns } from './db/tables.js';
 export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './db/migrate.js';
-export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, rethrowIfSqliteBlocked, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, rethrowIfSqliteBlocked, OTHER_STORE_MARKER, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
 export { RequestStores, runWithRequestStores, currentRequestStores, outsideRequestStores } from './db/request-stores.js';
-export { SqliteBlockedError } from './db/sqlite-blocked.js';
+export { OtherStoreFolderError, SqliteBlockedError } from './db/sqlite-blocked.js';
 //# sourceMappingURL=db.js.map

package/dist/embeddings.d.ts

@@ -64,8 +64,19 @@ export declare function embeddingInputText(entry: {
  * consistent with the compare side in `embeddingModelRequiresReindex`.
  */
 export declare function saveStoredEmbeddingModel(hippoRoot: string, model: string): void;
+/** What a store's vector index was built by: the stored identity, and whether any vector exists. */
+export interface EmbeddingIndexState {
+    readonly storedModel: string | null;
+    readonly hasVectors: boolean;
+}
+/** The model the index was built by: the stored identity, else the default model when vectors exist. */
+export declare function indexedModel(state: EmbeddingIndexState): string | null;
+/** The one rebuild rule every store applies to its indexed model. */
+export declare function indexNeedsRebuild(indexed: string | null, providerId: string): boolean;
 export declare function resolveIndexedEmbeddingModel(hippoRoot: string, index?: Record<string, number[]>): string | null;
 export declare function embeddingModelRequiresReindex(hippoRoot: string, model: string, index?: Record<string, number[]>): boolean;
+/** hippo.db's index state, the meta row and the EXISTS on one handle. */
+export declare function embeddingIndexStateAt(hippoRoot: string): EmbeddingIndexState;
 /**
  * Cosine similarity between two vectors. Handles unnormalized vectors.
  * Returns 0 for empty or mismatched vectors.
@@ -75,8 +86,6 @@ export declare function cosineSimilarity(a: number[], b: number[]): number;
 export declare function loadEmbeddingIndex(hippoRoot: string): Record<string, number[]>;
 /** Stored vectors for `ids` only. */
 export declare function loadStoredVectors(hippoRoot: string, ids: readonly string[]): Map<string, number[]>;
-/** Whether the store holds any vector at all. */
-export declare function hasEmbeddings(hippoRoot: string): boolean;
 /** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
 export declare function saveEmbeddingIndex(hippoRoot: string, index: Record<string, number[]>, model?: string): void;
 /**

package/dist/embeddings.js

@@ -101,16 +101,29 @@ export function saveStoredEmbeddingModel(hippoRoot, model) {
         closeHippoDb(db);
     }
 }
+/** The model the index was built by: the stored identity, else the default model when vectors exist. */
+export function indexedModel(state) {
+    return state.storedModel ?? (state.hasVectors ? DEFAULT_EMBEDDING_MODEL : null);
+}
+/** The one rebuild rule every store applies to its indexed model. */
+export function indexNeedsRebuild(indexed, providerId) {
+    return indexed !== null && indexed !== embeddingIndexIdentity(providerId);
+}
 export function resolveIndexedEmbeddingModel(hippoRoot, index) {
-    const stored = loadStoredEmbeddingModel(hippoRoot);
-    if (stored)
-        return stored;
-    const hasVectors = index ? Object.keys(index).length > 0 : withVectorDb(hippoRoot, hasStoredVectors);
-    return hasVectors ? DEFAULT_EMBEDDING_MODEL : null;
+    const storedModel = loadStoredEmbeddingModel(hippoRoot);
+    if (storedModel)
+        return storedModel;
+    return indexedModel({ storedModel, hasVectors: index ? Object.keys(index).length > 0 : withVectorDb(hippoRoot, hasStoredVectors) });
 }
 export function embeddingModelRequiresReindex(hippoRoot, model, index) {
-    const stored = resolveIndexedEmbeddingModel(hippoRoot, index);
-    return stored !== null && stored !== embeddingIndexIdentity(model);
+    return indexNeedsRebuild(resolveIndexedEmbeddingModel(hippoRoot, index), model);
+}
+/** hippo.db's index state, the meta row and the EXISTS on one handle. */
+export function embeddingIndexStateAt(hippoRoot) {
+    return withVectorDb(hippoRoot, (db) => ({
+        storedModel: getMeta(db, EMBEDDING_MODEL_META_KEY, '').trim() || null,
+        hasVectors: hasStoredVectors(db),
+    }));
 }
 async function rebuildEmbeddingIndex(entries, provider) {
     const rebuilt = {};
@@ -189,10 +202,6 @@ export function loadEmbeddingIndex(hippoRoot) {
 export function loadStoredVectors(hippoRoot, ids) {
     return ids.length === 0 ? new Map() : withVectorDb(hippoRoot, (db) => loadVectors(db, ids));
 }
-/** Whether the store holds any vector at all. */
-export function hasEmbeddings(hippoRoot) {
-    return withVectorDb(hippoRoot, hasStoredVectors);
-}
 /** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
 export function saveEmbeddingIndex(hippoRoot, index, model) {
     withVectorDb(hippoRoot, (db) => replaceAllVectors(db, index, model ?? getMeta(db, EMBEDDING_MODEL_META_KEY, '')));

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/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, rethrowIfSqliteBlocked } 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,13 +48,15 @@ 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;
@@ -62,11 +67,11 @@ async function physicsQueryVector(query, root, given) {
         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);
@@ -75,15 +80,9 @@ function withVectorCandidates(root, entries, queryVector, spec) {
     }
 }
 /** 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);

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,18 +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) {
@@ -32,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 ?? [];
@@ -47,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.js

@@ -16,21 +16,18 @@ export function __resetSessionRecallHistoryHttp() {
     resetSessionRings('http');
 }
 // HTTP threads the ring through opts.recallHistory, so the hint retrieve() returns is the one the caller sees.
-async function recallHistoryFor(ctx, q, sessionId) {
-    if (!biasHintEnabled('anchoring'))
-        return undefined;
-    if (sessionId)
-        return peekSessionRing('http', ctx.tenantId, sessionId);
-    await storeFor(ctx).appendAuditEvents(anchorSkippedRows({ tenantId: ctx.tenantId, actor: ctx.actor.subject }, q));
-    return undefined;
+function recallHistoryFor(ctx, sessionId) {
+    return sessionId && biasHintEnabled('anchoring') ? peekSessionRing('http', ctx.tenantId, sessionId) : undefined;
 }
 // GET /v1/memories?q=...&limit=...&mode=...&scope=...&include_continuity=1
 export async function handleRecallMemories({ req, res, opts, query }) {
     const { opts: recallOpts, limit, mode, explain } = parseRecallRequest(httpParams(query));
     const { query: q, includeContinuity, sessionId } = recallOpts;
     const ctx = await buildContextWithAuth(req, opts);
-    const recallHistory = await recallHistoryFor(ctx, q, sessionId);
-    const result = await retrieve(ctx, { ...recallOpts, limit, mode, explain, recallHistory });
+    const recallHistory = recallHistoryFor(ctx, sessionId);
+    // Written first in the recall's own write, so a recall that fails leaves no row.
+    const leadingAudit = sessionId ? [] : anchorSkippedRows({ tenantId: ctx.tenantId, actor: ctx.actor.subject }, q);
+    const result = await retrieve(ctx, { ...recallOpts, limit, mode, explain, recallHistory, leadingAudit });
     // The ring is created only after recall succeeds, so a 400 cannot LRU-evict a live session.
     const ring = sessionRing('http', ctx.tenantId, sessionId);
     if (ring)

package/dist/server.d.ts

@@ -11,7 +11,7 @@ export { HttpError } from './http-util.js';
 export { promptHookContext, type CallerProject } from './prompt-hook.js';
 export type { JsonValue } from './json.js';
 export { captureSessionTexts, type SessionCaptureRequest, type SessionCaptureResult } from './capture/session-texts.js';
-export { sqliteStore, type HippoStore, type RecallSearchArgs, type RecallWrites } from './store-port.js';
+export { sqliteStore, type HippoStore, type RecallSearchArgs, type RecallWrites, type VectorReads } from './store-port.js';
 export type { ApiKeyRecord } from './auth.js';
 export type { AppendAuditOpts } from './audit.js';
 export type { ContinuityBlock } from './api/recall-types.js';
@@ -21,10 +21,15 @@ export type { ClassResolution, PlanningFallacyEvidence } from './predictions/pla
 export type { PredictionBaserate } from './predictions/store.js';
 export type { RecallTraceInput } from './recall-trace.js';
 export type { StrengthenOptions } from './store/entry-writes.js';
-export type { OriginFilter } from './store/search-rows.js';
+export type { OriginFilter, RecallScopeFilter, VectorCandidateSpec } from './store/search-rows.js';
 export type { ContinuityKey } from './store/sessions.js';
 export type { TokenUse } from './token-ledger.js';
+export type { EmbeddingIndexState } from './embeddings.js';
+export type { PhysicsParticle } from './physics.js';
 export { StoreBusyError } from './db.js';
+export { decodeVector, EMBEDDING_MODEL_META_KEY, rankVectorRows, type VectorMatch, type VectorRow } from './vector-store.js';
+export { bufferToFloat32 } from './physics-state.js';
+export { OTHER_STORE_MARKER, OtherStoreFolderError, withSqliteAllowed } from './db.js';
 export { authCreate, type AuthCreateOpts, type AuthCreateResult } from './api.js';
 export { isSharedStore } from './config.js';
 export { ownerOrSubject } from './api.js';

package/dist/server.js

@@ -48,6 +48,11 @@ export { captureSessionTexts } from './capture/session-texts.js';
 // An add-on serves from another database by passing serve() its own HippoStore.
 export { sqliteStore } from './store-port.js';
 export { StoreBusyError } from './db.js';
+// An add-on store decodes and ranks with hippo.db's own code, so both return the same ids in the same order.
+export { decodeVector, EMBEDDING_MODEL_META_KEY, rankVectorRows } from './vector-store.js';
+export { bufferToFloat32 } from './physics-state.js';
+// store copy --db writes the marker and reads the old hippo.db under the waiver.
+export { OTHER_STORE_MARKER, OtherStoreFolderError, withSqliteAllowed } from './db.js';
 // An add-on's install step mints the first admin key into a store folder it names, which `hippo auth create` cannot reach.
 export { authCreate } from './api.js';
 // An add-on that serves a team store checks the flag before it starts.

package/dist/store/open.js

@@ -25,9 +25,10 @@ export function initStore(hippoRoot) {
 }
 /** One open connection with init done on it, for callers who used to pay for `initStore` + a second `openHippoDb`. */
 export function openStore(hippoRoot, opts) {
-    ensureMirrorDirectories(hippoRoot);
+    // Open first: a folder marked for another store must refuse before any mirror folder appears.
     const db = openHippoDb(hippoRoot, opts);
     try {
+        ensureMirrorDirectories(hippoRoot);
         const bootstrapped = bootstrapLegacyStore(db, hippoRoot);
         if (bootstrapped) {
             syncMirrorFiles(hippoRoot, db);

package/dist/store-port.d.ts

@@ -1,12 +1,14 @@
 import { type ApiKeyRecord } from './auth.js';
 import { type AppendAuditOpts } from './audit.js';
 import type { ContinuityBlock } from './api/recall-types.js';
+import { type EmbeddingIndexState } from './embeddings.js';
 import { type ActiveGoals, type GetActiveGoalsOpts, type GoalRecallLogRow } from './goals.js';
 import type { MemoryEntry } from './memory.js';
+import type { PhysicsParticle } from './physics.js';
 import { type PlanningFallacyEvidence } from './predictions/planning-fallacy.js';
 import { type RecallTraceInput } from './recall-trace.js';
 import { type StrengthenOptions } from './store/entry-writes.js';
-import { type OriginFilter } from './store/search-rows.js';
+import { type OriginFilter, type VectorCandidateSpec } from './store/search-rows.js';
 import { type ContinuityKey } from './store/sessions.js';
 import { type TokenUse } from './token-ledger.js';
 /** The arguments of `loadRecallSearchEntries` after the query, by name. */
@@ -35,6 +37,17 @@ export interface RecallWrites {
         readonly opts: StrengthenOptions;
     };
 }
+/** The reads behind recall's vector arm, one group a store sets in full as `HippoStore.vectors` or leaves unset. */
+export interface VectorReads {
+    /** The stored model and whether any vector exists, in one snapshot. */
+    embeddingIndexState(): Promise<EmbeddingIndexState>;
+    storedVectors(ids: readonly string[]): Promise<Map<string, number[]>>;
+    /** The `spec.limit ?? 50` rows nearest `queryVector` by `rankVectorRows` among those where the tenant matches (when set), kind is not 'archived', a superseded row
+     *  shows only with `includeSuperseded`, scope follows `RecallScopeFilter`, and origin is '' or listed (when `spec.origin` is set). */
+    nearestEntries(queryVector: readonly number[], spec: VectorCandidateSpec): Promise<MemoryEntry[]>;
+    /** The particles of `ids` only; an empty list reads nothing. */
+    physicsParticles(ids: readonly string[]): Promise<Map<string, PhysicsParticle>>;
+}
 /** What `serve()` reads and writes through. Each method is atomic and no transaction spans an await, since SQLite's lock wait blocks the event loop; a lock timeout throws `StoreBusyError`. */
 export interface HippoStore {
     /** 'sqlite' is hippo.db under the served root. Under any other kind, an unported route answers 501 and a hippo.db open inside a request throws. */
@@ -65,6 +78,8 @@ export interface HippoStore {
     bumpRecallStats(recalled: number): Promise<void>;
     /** One token-ledger row. Throws, so the caller decides whether a ledger failure matters. */
     recordTokens(use: TokenUse): Promise<void>;
+    /** Unset on a store built before them, where hybrid and physics recall under an embedding provider answer 501. */
+    readonly vectors?: VectorReads;
     /** Releases the store's connections; `serve()` closes only a store it made itself. */
     close(): Promise<void>;
 }
@@ -74,7 +89,9 @@ export declare function storeFor(ctx: {
     readonly store?: HippoStore;
 }): HippoStore;
 /** The built-in store: today's synchronous hippo.db functions behind the port, each call on its own short-lived handles, so close has nothing to release. */
-export declare function sqliteStore(hippoRoot: string): HippoStore;
+export declare function sqliteStore(hippoRoot: string): HippoStore & {
+    readonly vectors: VectorReads;
+};
 /** sqliteStore's continuity read, for the synchronous recall that cannot await the port. */
 export declare function continuityAt(hippoRoot: string, tenantId: string, eventLimit: number, key: ContinuityKey | null): ContinuityBlock;
 /** sqliteStore's finishRecall, for the synchronous recall that cannot await the port. */

package/dist/store-port.js

@@ -2,14 +2,16 @@
 import { readApiKeyRecord } from './auth.js';
 import { appendAuditEvent } from './audit.js';
 import { closeHippoDb, openHippoDb, withWriteScope } from './db.js';
+import { embeddingIndexStateAt, loadStoredVectors } from './embeddings.js';
 import { activeGoalsWithPolicies, localGoalRecallRows, writeGoalRecallLog, } from './goals.js';
+import { loadPhysicsState } from './physics-state.js';
 import { planningFallacyEvidenceAt } from './predictions/planning-fallacy.js';
 import { writeRecallTrace } from './recall-trace.js';
 import { loadEntriesByIds, loadFreshRawMemories } from './store/entry-reads.js';
 import { strengthenRetrievedInOwnTx } from './store/entry-writes.js';
 import { loadLatestHandoff } from './store/handoffs.js';
 import { updateStats } from './store/index-and-stats.js';
-import { loadRecallSearchEntries } from './store/search-rows.js';
+import { loadRecallSearchEntries, loadVectorCandidateEntries } from './store/search-rows.js';
 import { listSessionEvents, loadActiveTaskSnapshot } from './store/sessions.js';
 import { recordTokenUse } from './token-ledger.js';
 function onHandle(hippoRoot, fn) {
@@ -67,6 +69,21 @@ export function sqliteStore(hippoRoot) {
         async recordTokens(use) {
             onHandle(hippoRoot, (db) => recordTokenUse(db, use));
         },
+        vectors: {
+            async embeddingIndexState() {
+                return embeddingIndexStateAt(hippoRoot);
+            },
+            async storedVectors(ids) {
+                return loadStoredVectors(hippoRoot, ids);
+            },
+            async nearestEntries(queryVector, spec) {
+                return loadVectorCandidateEntries(hippoRoot, queryVector, spec);
+            },
+            async physicsParticles(ids) {
+                // loadPhysicsState reads every row for an empty list.
+                return ids.length === 0 ? new Map() : onHandle(hippoRoot, (db) => loadPhysicsState(db, [...ids]));
+            },
+        },
         async close() { },
     };
 }

package/dist/vector-store.d.ts

@@ -18,6 +18,14 @@ export interface VectorMatch {
     id: string;
     score: number;
 }
+/** A stored vector, decoded. */
+export interface VectorRow {
+    readonly id: string;
+    readonly vector: Float32Array;
+}
+/** The `k` rows closest to `query` by cosine, best first; ties go to the smaller id, so row order never changes the top k.
+ *  The query rounds to Float32 as stored vectors are, and scores add up in float64, so every store that feeds it the same bytes ranks alike. */
+export declare function rankVectorRows(query: readonly number[], rows: Iterable<VectorRow>, k: number): VectorMatch[];
 /** The `k` stored vectors closest to `query` among `memories m` rows passing `where` (SQL starting with ` AND`).
  *  Filters run before the cut, so rows a caller may not see can never push admitted rows out of the top k. */
 export declare function topVectorMatches(db: DatabaseSyncLike, query: readonly number[], k: number, where: string, params: readonly (string | number)[]): VectorMatch[];

package/dist/vector-store.js

@@ -24,8 +24,8 @@ export function encodeVector(vector) {
     return new Uint8Array(Float32Array.from(vector).buffer);
 }
 export function decodeVector(blob) {
-    // A view needs 4-byte alignment; copy when SQLite hands back an unaligned slice.
-    const bytes = blob.byteOffset % 4 === 0 ? blob : blob.slice();
+    // A view needs 4-byte alignment; Buffer#slice is a view too, so copy with the constructor.
+    const bytes = blob.byteOffset % 4 === 0 ? blob : new Uint8Array(blob);
     return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / 4);
 }
 /** Insert or replace vectors, skipping empty or non-finite ones; the caller owns any surrounding transaction. */
@@ -92,28 +92,22 @@ export function storedVectorIds(db) {
 export function hasStoredVectors(db) {
     return db.prepare('SELECT 1 FROM memory_vectors LIMIT 1').get() !== undefined;
 }
-/** The `k` stored vectors closest to `query` among `memories m` rows passing `where` (SQL starting with ` AND`).
- *  Filters run before the cut, so rows a caller may not see can never push admitted rows out of the top k. */
-export function topVectorMatches(db, query, k, where, params) {
+/** The `k` rows closest to `query` by cosine, best first; ties go to the smaller id, so row order never changes the top k.
+ *  The query rounds to Float32 as stored vectors are, and scores add up in float64, so every store that feeds it the same bytes ranks alike. */
+export function rankVectorRows(query, rows, k) {
+    const top = [];
     if (k <= 0 || query.length === 0)
-        return [];
+        return top;
     const q = Float32Array.from(query);
     let qNorm = 0;
     for (let i = 0; i < q.length; i++)
         qNorm += q[i] * q[i];
     qNorm = Math.sqrt(qNorm);
     if (qNorm < 1e-10)
-        return [];
-    // SHORTCUT: brute-force cosine over every vector of matching dim, fine to ~100k rows; an ANN index (sqlite-vec, HNSW) is the upgrade.
-    const rows = db.prepare(`
-    SELECT v.memory_id AS id, v.vector AS vector
-    FROM memory_vectors v JOIN memories m ON m.id = v.memory_id
-    WHERE v.dim = ?${where}
-  `).iterate(q.length, ...params);
-    const top = [];
-    // SAFETY: the SELECT above names exactly these two columns; node:sqlite returns BLOBs as Uint8Array.
-    for (const row of rows) {
-        const v = decodeVector(row.vector);
+        return top;
+    for (const { id, vector: v } of rows) {
+        if (v.length !== q.length)
+            continue;
         let dot = 0;
         let norm = 0;
         for (let i = 0; i < v.length; i++) {
@@ -123,12 +117,30 @@ export function topVectorMatches(db, query, k, where, params) {
         if (norm < 1e-20)
             continue;
         const score = dot / (qNorm * Math.sqrt(norm));
-        if (top.length === k && !beats(score, row.id, top[k - 1]))
+        if (top.length === k && !beats(score, id, top[k - 1]))
             continue;
-        insertSorted(top, { id: row.id, score }, k);
+        insertSorted(top, { id, score }, k);
     }
     return top;
 }
+function* decodedRows(rows) {
+    for (const row of rows)
+        yield { id: row.id, vector: decodeVector(row.vector) };
+}
+/** The `k` stored vectors closest to `query` among `memories m` rows passing `where` (SQL starting with ` AND`).
+ *  Filters run before the cut, so rows a caller may not see can never push admitted rows out of the top k. */
+export function topVectorMatches(db, query, k, where, params) {
+    if (k <= 0 || query.length === 0)
+        return [];
+    // SHORTCUT: brute-force cosine over every vector of matching dim, fine to ~100k rows; an ANN index (sqlite-vec, HNSW) is the upgrade.
+    const rows = db.prepare(`
+    SELECT v.memory_id AS id, v.vector AS vector
+    FROM memory_vectors v JOIN memories m ON m.id = v.memory_id
+    WHERE v.dim = ?${where}
+  `).iterate(query.length, ...params);
+    // SAFETY: the SELECT above names exactly these two columns; node:sqlite returns BLOBs as Uint8Array.
+    return rankVectorRows(query, decodedRows(rows), k);
+}
 // Ties break on id so the cut is the same on every run.
 function beats(score, id, other) {
     return score > other.score || (score === other.score && id < other.id);

package/dist/version.d.ts

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export declare const PACKAGE_VERSION = "1.65.0";
+export declare const PACKAGE_VERSION = "1.66.0";
 /** The floor a store takes on its first expiring key: the first release with schema v53, set by hand in that release; scripts/check-expiring-keys-floor.mjs gates it. */
 export declare const EXPIRING_KEYS_MIN_BINARY = "1.64.0";
 /** The floor a store takes on its first session bind or owner snapshot: first release with v54; set by hand in that release. */

package/dist/version.js

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export const PACKAGE_VERSION = '1.65.0';
+export const PACKAGE_VERSION = '1.66.0';
 /** The floor a store takes on its first expiring key: the first release with schema v53, set by hand in that release; scripts/check-expiring-keys-floor.mjs gates it. */
 export const EXPIRING_KEYS_MIN_BINARY = '1.64.0';
 /** The floor a store takes on its first session bind or owner snapshot: first release with v54; set by hand in that release. */

package/extensions/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
-  "version": "1.65.0",
+  "version": "1.66.0",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.65.0",
+  "version": "1.66.0",
   "type": "module",
   "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
   "main": "index.ts",

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
-  "version": "1.65.0",
+  "version": "1.66.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.65.0",
+  "version": "1.66.0",
   "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
   "mcpName": "io.github.kitfunso/hippo-memory",
   "type": "module",