fix(search): invalidate the embedding cache when the model changes

The vector cache keys entries by text hash alone and validated only that the
dimension count was unchanged. That was sufficient while the model was fixed,
but selecting a model makes it reachable: `bge-large-en-v1.5` and `bge-m3` are
both 1024d, so switching between them kept every cached vector and served one
model's embeddings for the other's queries.

The result is not a crash but silently wrong ranking — documents embedded in
one space, queries in another. Observed on a 43-document corpus where the
correct answer dropped out of the top 3 entirely.

Record the embedder identity alongside dimensions and clear the cache when it
changes. Identity is `<model>@<device>`, since the same model on a different
backend can differ numerically. A cache with no stored model predates this key
and has unknown provenance, so it is also cleared.

Author: mrrobertkent

src/retriv/embedding-cache.ts

@@ -50,7 +50,16 @@ function createSqliteStorage(db: DatabaseSync) {
   }
 }
 
-export async function cachedEmbeddings(config: EmbeddingConfig): Promise<EmbeddingConfig> {
+/**
+ * Wrap an embedding provider with the on-disk vector cache.
+ *
+ * `model` identifies which embedder produced the cached vectors. Entries are
+ * keyed by text hash alone, so vectors from a different model would be served
+ * for the same text — two models of equal width (bge-large and
+ * qwen3-embedding:0.6b are both 1024d) would silently mix embedding spaces and
+ * destroy ranking. Dimensions alone cannot catch that; the model id can.
+ */
+export async function cachedEmbeddings(config: EmbeddingConfig, model?: string): Promise<EmbeddingConfig> {
   const { cachedEmbeddings: retrivCached } = await import('retriv/embeddings/cached')
   const db = await openDb()
   const storage = createSqliteStorage(db)
@@ -63,10 +72,18 @@ export async function cachedEmbeddings(config: EmbeddingConfig): Promise<Embeddi
       const setMetaStmt = db.prepare('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)')
 
       const storedDims = getMetaStmt.get('dimensions') as { value: string } | undefined
-      if (storedDims && Number(storedDims.value) !== resolved.dimensions) {
+      const storedModel = getMetaStmt.get('model') as { value: string } | undefined
+      const dimsChanged = storedDims && Number(storedDims.value) !== resolved.dimensions
+      // A cache written before this key existed has unknown provenance, so
+      // treat a missing stored model as a mismatch once a model is supplied.
+      const modelChanged = model !== undefined && storedModel?.value !== model
+
+      if (dimsChanged || modelChanged)
         db.exec('DELETE FROM embeddings')
-      }
+
       setMetaStmt.run('dimensions', String(resolved.dimensions))
+      if (model !== undefined)
+        setMetaStmt.run('model', model)
 
       return resolved
     },

src/retriv/index.ts

@@ -73,12 +73,18 @@ export async function getDb(config: Pick<IndexConfig, 'dbPath'>) {
     throw err
   }
   const userConfig = readConfig()
+  const embedModel = resolveEmbedModel(userConfig.embedModel)
   const device = resolveEmbedDevice(userConfig.embedDevice)
-  const embeddings = await cachedEmbeddings(transformersJs({
-    model: resolveEmbedModel(userConfig.embedModel),
-    // Omitted when `auto` so transformers.js keeps its own device resolution.
-    ...(device ? { device } : {}),
-  }))
+  // Cache identity pairs model with device: cached vectors are only valid for
+  // the embedder that produced them, and backends can differ numerically.
+  const embeddings = await cachedEmbeddings(
+    transformersJs({
+      model: embedModel,
+      // Omitted when `auto` so transformers.js keeps its own device resolution.
+      ...(device ? { device } : {}),
+    }),
+    `${embedModel}@${device ?? 'auto'}`,
+  )
   return createRetriv({
     driver: sqliteMod.default({
       path: config.dbPath,

test/unit/embedding-cache-identity.test.ts

@@ -0,0 +1,103 @@
+import { DatabaseSync } from 'node:sqlite'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Guards the cache-invalidation rule in `src/retriv/embedding-cache.ts`.
+ *
+ * Vectors are keyed by text hash alone, so the only thing preventing one
+ * model's vectors being served to another is the stored identity. Dimensions
+ * are not enough: `Xenova/bge-large-en-v1.5` and `ollama:qwen3-embedding:0.6b`
+ * are both 1024d, so switching between them would silently mix embedding
+ * spaces and wreck ranking.
+ *
+ * This reimplements the decision against an in-memory database so the rule is
+ * pinned without touching the user's real cache.
+ */
+function applyIdentity(db: DatabaseSync, dimensions: number, model?: string): void {
+  const get = db.prepare('SELECT value FROM meta WHERE key = ?')
+  const set = db.prepare('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)')
+
+  const storedDims = get.get('dimensions') as { value: string } | undefined
+  const storedModel = get.get('model') as { value: string } | undefined
+  const dimsChanged = storedDims && Number(storedDims.value) !== dimensions
+  const modelChanged = model !== undefined && storedModel?.value !== model
+
+  if (dimsChanged || modelChanged)
+    db.exec('DELETE FROM embeddings')
+
+  set.run('dimensions', String(dimensions))
+  if (model !== undefined)
+    set.run('model', model)
+}
+
+function makeDb(): DatabaseSync {
+  const db = new DatabaseSync(':memory:')
+  db.exec('CREATE TABLE embeddings (text_hash TEXT PRIMARY KEY, embedding BLOB NOT NULL)')
+  db.exec('CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)')
+  return db
+}
+
+function seed(db: DatabaseSync, n = 3): void {
+  const stmt = db.prepare('INSERT OR IGNORE INTO embeddings (text_hash, embedding) VALUES (?, ?)')
+  for (let i = 0; i < n; i++)
+    stmt.run(`hash-${i}`, Buffer.from(new Float32Array([i, i, i]).buffer))
+}
+
+function count(db: DatabaseSync): number {
+  return (db.prepare('SELECT COUNT(*) c FROM embeddings').get() as { c: number }).c
+}
+
+describe('embedding cache identity', () => {
+  it('keeps cached vectors when model and dimensions are unchanged', () => {
+    const db = makeDb()
+    applyIdentity(db, 1024, 'model-a')
+    seed(db)
+    applyIdentity(db, 1024, 'model-a')
+    expect(count(db)).toBe(3)
+    db.close()
+  })
+
+  // The regression: equal width, different model.
+  it('clears cached vectors when the model changes at identical dimensions', () => {
+    const db = makeDb()
+    applyIdentity(db, 1024, 'Xenova/bge-large-en-v1.5@webgpu')
+    seed(db)
+    expect(count(db)).toBe(3)
+
+    applyIdentity(db, 1024, 'ollama:qwen3-embedding:0.6b')
+    expect(count(db)).toBe(0)
+    db.close()
+  })
+
+  it('clears cached vectors when dimensions change', () => {
+    const db = makeDb()
+    applyIdentity(db, 384, 'model-a')
+    seed(db)
+    applyIdentity(db, 1024, 'model-a')
+    expect(count(db)).toBe(0)
+    db.close()
+  })
+
+  // Same model on a different backend: numeric output can differ, so vectors
+  // are only interchangeable within a device.
+  it('clears cached vectors when only the device changes', () => {
+    const db = makeDb()
+    applyIdentity(db, 1024, 'Xenova/bge-large-en-v1.5@cpu')
+    seed(db)
+    applyIdentity(db, 1024, 'Xenova/bge-large-en-v1.5@webgpu')
+    expect(count(db)).toBe(0)
+    db.close()
+  })
+
+  // A cache written before the model key existed has unknown provenance.
+  it('clears a legacy cache that has no stored model', () => {
+    const db = makeDb()
+    applyIdentity(db, 1024)
+    seed(db)
+    expect(count(db)).toBe(3)
+
+    applyIdentity(db, 1024, 'model-a')
+    expect(count(db)).toBe(0)
+    db.close()
+  })
+})