#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix(embedding): guard provider responses against dimension mismatches (#248)
Ammar Salehab4a16664ea8
diff --git a/src/index.ts b/src/index.tsindex 6385a96c..418847b7 100644--- a/src/index.ts+++ b/src/index.ts@@ -336,10 +336,58 @@ async function main() {);}if (loaded?.vector && vectorIndex && loaded.vector.size > 0) {- vectorIndex.restoreFrom(loaded.vector);- console.log(- `[agentmemory] Loaded persisted vector index (${vectorIndex.size} vectors)`,- );+ // Persisted vectors carry whatever dimension the provider had when+ // they were written. If the active provider declares a different+ // dimension — or if the on-disk index contains a mix of dimensions+ // (legacy indexes written before the live-API guard in this PR) —+ // restoring would silently corrupt search: cosineSimilarity returns+ // 0 on cross-dim pairs, so affected observations stop matching+ // anything and recall degrades without an error. Walk every stored+ // vector instead of trusting the first; refuse to load if anything+ // is off.+ const activeDim = embeddingProvider?.dimensions ?? 0;+ const { mismatches, seenDimensions } =+ activeDim > 0+ ? loaded.vector.validateDimensions(activeDim)+ : { mismatches: [], seenDimensions: new Set<number>() };++ if (mismatches.length > 0) {+ const sample = mismatches+ .slice(0, 5)+ .map((m) => `${m.obsId} (dim=${m.dim})`)+ .join(", ");+ const distinct = Array.from(seenDimensions).sort((a, b) => a - b).join(", ");+ const dropStale =+ process.env["AGENTMEMORY_DROP_STALE_INDEX"] === "true";+ if (dropStale) {+ console.warn(+ `[agentmemory] Persisted vector index has ${mismatches.length} of ` ++ `${loaded.vector.size} vectors with the wrong dimension. Active ` ++ `provider (${embeddingProvider?.name}) declares ${activeDim}; ` ++ `dimensions seen on disk: ${distinct}. ` ++ `AGENTMEMORY_DROP_STALE_INDEX=true is set — discarding the persisted ` ++ `vectors. Live observations will rebuild the index over time.`,+ );+ } else {+ throw new Error(+ `[agentmemory] Refusing to start: persisted vector index has ` ++ `${mismatches.length} of ${loaded.vector.size} vectors with the ` ++ `wrong dimension. Active provider (${embeddingProvider?.name}) ` ++ `declares ${activeDim}; dimensions seen on disk: ${distinct}. ` ++ `First mismatched obsIds: ${sample}. Loading would silently corrupt ` ++ `search (cross-dimension cosine returns 0). Choose one:\n` ++ ` - Re-embed the existing index against the new provider, then start.\n` ++ ` - Set AGENTMEMORY_DROP_STALE_INDEX=true to discard the persisted ` ++ `vectors and rebuild from live observations.\n` ++ ` - Switch the embedding provider back to the one that wrote the index.`,+ );+ }+ } else {+ vectorIndex.restoreFrom(loaded.vector);+ console.log(+ `[agentmemory] Loaded persisted vector index (${vectorIndex.size} vectors)`,+ );+ }}const needsRebuild = bm25Index.size === 0;diff --git a/src/providers/embedding/index.ts b/src/providers/embedding/index.tsindex 4580232c..d18de232 100644--- a/src/providers/embedding/index.ts+++ b/src/providers/embedding/index.ts@@ -23,7 +23,7 @@ let imageEmbeddingProvider: EmbeddingProvider | null = null;export function createImageEmbeddingProvider(): EmbeddingProvider | null {if (process.env["AGENTMEMORY_IMAGE_EMBEDDINGS"] !== "true") return null;if (imageEmbeddingProvider) return imageEmbeddingProvider;- imageEmbeddingProvider = new ClipEmbeddingProvider();+ imageEmbeddingProvider = withDimensionGuard(new ClipEmbeddingProvider());return imageEmbeddingProvider;}@@ -33,18 +33,48 @@ export function createEmbeddingProvider(): EmbeddingProvider | null {switch (detected) {case "gemini":- return new GeminiEmbeddingProvider(getEnvVar("GEMINI_API_KEY")!);+ return withDimensionGuard(new GeminiEmbeddingProvider(getEnvVar("GEMINI_API_KEY")!));case "openai":- return new OpenAIEmbeddingProvider(getEnvVar("OPENAI_API_KEY")!);+ return withDimensionGuard(new OpenAIEmbeddingProvider(getEnvVar("OPENAI_API_KEY")!));case "voyage":- return new VoyageEmbeddingProvider(getEnvVar("VOYAGE_API_KEY")!);+ return withDimensionGuard(new VoyageEmbeddingProvider(getEnvVar("VOYAGE_API_KEY")!));case "cohere":- return new CohereEmbeddingProvider(getEnvVar("COHERE_API_KEY")!);+ return withDimensionGuard(new CohereEmbeddingProvider(getEnvVar("COHERE_API_KEY")!));case "openrouter":- return new OpenRouterEmbeddingProvider(getEnvVar("OPENROUTER_API_KEY")!);+ return withDimensionGuard(new OpenRouterEmbeddingProvider(getEnvVar("OPENROUTER_API_KEY")!));case "local":- return new LocalEmbeddingProvider();+ return withDimensionGuard(new LocalEmbeddingProvider());default:return null;}}++// Wrong-dimension vectors corrupt the index silently: vector-index.ts+// returns 0 from cosineSimilarity on length mismatch instead of throwing,+// so a bad vector is stored, never matches anything, and the memory+// becomes invisible without an error. Catch it at the boundary.+export function withDimensionGuard(provider: EmbeddingProvider): EmbeddingProvider {+ const expected = provider.dimensions;+ const check = (v: Float32Array, where: string): Float32Array => {+ if (v.length !== expected) {+ throw new Error(+ `Embedding dimension mismatch in ${provider.name}.${where}: expected ${expected}, got ${v.length}`,+ );+ }+ return v;+ };+ // Preserve the provider's prototype chain so `instanceof` checks+ // against concrete classes (e.g. GeminiEmbeddingProvider) keep working.+ const wrapped = Object.create(provider) as EmbeddingProvider;+ wrapped.embed = async (t) => check(await provider.embed(t), "embed");+ wrapped.embedBatch = async (ts) => {+ const out = await provider.embedBatch(ts);+ out.forEach((v, i) => check(v, `embedBatch[${i}]`));+ return out;+ };+ if (provider.embedImage) {+ wrapped.embedImage = async (s: string) =>+ check(await provider.embedImage!(s), "embedImage");+ }+ return wrapped;+}diff --git a/src/state/vector-index.ts b/src/state/vector-index.tsindex 63033d94..03c8248e 100644--- a/src/state/vector-index.ts+++ b/src/state/vector-index.ts@@ -66,6 +66,29 @@ export class VectorIndex {return this.vectors.size;}+ // Walks every stored vector and returns the obsIds whose dimension+ // doesn't match `expected`, plus the set of distinct dimensions seen.+ // Used by the persistence-restore guard in src/index.ts to refuse+ // loading any index containing wrong-dimension vectors — including+ // legacy on-disk indexes written before the live-API dimension guard+ // existed (where a mid-session provider swap could mix dimensions+ // inside a single index). Empty `mismatches` plus a single-entry+ // `seenDimensions` matching `expected` is the only clean state.+ validateDimensions(+ expected: number,+ ): { mismatches: Array<{ obsId: string; dim: number }>; seenDimensions: Set<number> } {+ const mismatches: Array<{ obsId: string; dim: number }> = [];+ const seenDimensions = new Set<number>();+ for (const [obsId, entry] of this.vectors) {+ const dim = entry.embedding.length;+ seenDimensions.add(dim);+ if (dim !== expected) {+ mismatches.push({ obsId, dim });+ }+ }+ return { mismatches, seenDimensions };+ }+clear(): void {this.vectors.clear();}diff --git a/test/embedding-provider.test.ts b/test/embedding-provider.test.tsindex 48092eb4..e6442ae4 100644--- a/test/embedding-provider.test.ts+++ b/test/embedding-provider.test.ts@@ -1,7 +1,11 @@import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";-import { createEmbeddingProvider } from "../src/providers/embedding/index.js";+import {+ createEmbeddingProvider,+ withDimensionGuard,+} from "../src/providers/embedding/index.js";import { GeminiEmbeddingProvider } from "../src/providers/embedding/gemini.js";import { OpenAIEmbeddingProvider } from "../src/providers/embedding/openai.js";+import type { EmbeddingProvider } from "../src/types.js";describe("createEmbeddingProvider", () => {const originalEnv = { ...process.env };@@ -149,3 +153,97 @@ describe("OpenAIEmbeddingProvider", () => {);});});++describe("withDimensionGuard", () => {+ function fakeProvider(opts: {+ dimensions: number;+ embed: () => Float32Array;+ batch?: () => Float32Array[];+ image?: () => Float32Array;+ }): EmbeddingProvider {+ const provider: EmbeddingProvider = {+ name: "fake",+ dimensions: opts.dimensions,+ embed: async () => opts.embed(),+ embedBatch: async () => opts.batch?.() ?? [opts.embed()],+ };+ if (opts.image) provider.embedImage = async () => opts.image!();+ return provider;+ }++ it("preserves the wrapped provider's prototype so instanceof keeps working", async () => {+ class FakeProvider implements EmbeddingProvider {+ readonly name = "fake-class";+ readonly dimensions = 4;+ async embed(): Promise<Float32Array> {+ return new Float32Array([1, 2, 3, 4]);+ }+ async embedBatch(): Promise<Float32Array[]> {+ return [new Float32Array([1, 2, 3, 4])];+ }+ }+ const guarded = withDimensionGuard(new FakeProvider());+ expect(guarded).toBeInstanceOf(FakeProvider);+ expect(guarded.name).toBe("fake-class");+ expect(guarded.dimensions).toBe(4);+ });++ it("passes through vectors that match the declared dimensions", async () => {+ const guarded = withDimensionGuard(+ fakeProvider({+ dimensions: 4,+ embed: () => new Float32Array([1, 2, 3, 4]),+ batch: () => [new Float32Array([1, 2, 3, 4]), new Float32Array([5, 6, 7, 8])],+ }),+ );+ await expect(guarded.embed("x")).resolves.toEqual(new Float32Array([1, 2, 3, 4]));+ await expect(guarded.embedBatch(["a", "b"])).resolves.toHaveLength(2);+ });++ it("throws when embed() returns the wrong dimension", async () => {+ const guarded = withDimensionGuard(+ fakeProvider({+ dimensions: 4,+ embed: () => new Float32Array([1, 2, 3]),+ }),+ );+ await expect(guarded.embed("x")).rejects.toThrow(+ /dimension mismatch in fake\.embed: expected 4, got 3/,+ );+ });++ it("throws when any vector in embedBatch() returns the wrong dimension", async () => {+ const guarded = withDimensionGuard(+ fakeProvider({+ dimensions: 4,+ embed: () => new Float32Array([1, 2, 3, 4]),+ batch: () => [new Float32Array([1, 2, 3, 4]), new Float32Array([1, 2])],+ }),+ );+ await expect(guarded.embedBatch(["a", "b"])).rejects.toThrow(+ /dimension mismatch in fake\.embedBatch\[1\]: expected 4, got 2/,+ );+ });++ it("guards embedImage when present and omits it when absent", async () => {+ const withImage = withDimensionGuard(+ fakeProvider({+ dimensions: 4,+ embed: () => new Float32Array([1, 2, 3, 4]),+ image: () => new Float32Array([1, 2]),+ }),+ );+ expect(withImage.embedImage).toBeDefined();+ await expect(withImage.embedImage!("/tmp/x")).rejects.toThrow(+ /dimension mismatch in fake\.embedImage: expected 4, got 2/,+ );++ const withoutImage = withDimensionGuard(+ fakeProvider({+ dimensions: 4,+ embed: () => new Float32Array([1, 2, 3, 4]),+ }),+ );+ expect(withoutImage.embedImage).toBeUndefined();+ });+});diff --git a/test/vector-index-dimensions.test.ts b/test/vector-index-dimensions.test.tsnew file mode 100644index 00000000..380ef3f7--- /dev/null+++ b/test/vector-index-dimensions.test.ts@@ -0,0 +1,42 @@+import { describe, it, expect } from "vitest";+import { VectorIndex } from "../src/state/vector-index.js";++describe("VectorIndex.validateDimensions", () => {+ it("reports no mismatches and an empty dim set on an empty index", () => {+ const result = new VectorIndex().validateDimensions(384);+ expect(result.mismatches).toEqual([]);+ expect(Array.from(result.seenDimensions)).toEqual([]);+ });++ it("reports no mismatches when every vector matches the expected dimension", () => {+ const idx = new VectorIndex();+ idx.add("o1", "s1", new Float32Array(384));+ idx.add("o2", "s1", new Float32Array(384));+ const result = idx.validateDimensions(384);+ expect(result.mismatches).toEqual([]);+ expect(Array.from(result.seenDimensions)).toEqual([384]);+ });++ it("reports every wrong-dimension vector, not just the first", () => {+ const idx = new VectorIndex();+ idx.add("good1", "s1", new Float32Array(384));+ idx.add("bad1", "s1", new Float32Array(1536));+ idx.add("good2", "s1", new Float32Array(384));+ idx.add("bad2", "s1", new Float32Array(768));+ const result = idx.validateDimensions(384);+ expect(result.mismatches).toHaveLength(2);+ expect(result.mismatches.map((m) => m.obsId).sort()).toEqual(["bad1", "bad2"]);+ expect(Array.from(result.seenDimensions).sort((a, b) => a - b)).toEqual([+ 384, 768, 1536,+ ]);+ });++ it("flags every entry when the entire index has the wrong dimension", () => {+ const idx = new VectorIndex();+ idx.add("o1", "s1", new Float32Array(384));+ idx.add("o2", "s1", new Float32Array(384));+ const result = idx.validateDimensions(1536);+ expect(result.mismatches).toHaveLength(2);+ expect(Array.from(result.seenDimensions)).toEqual([384]);+ });+});