Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

fix(embedding): guard provider responses against dimension mismatches (#248)

Ammar Salehab4a16664ea8
diff --git a/src/index.ts b/src/index.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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]);
+ });
+});