rohitg00/agentmemory · critical · Error

[agentmemory] Refusing to start: persisted vector index has

Error message

[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:
  - Re-embed the existing index against the new provider, then start.
  - Set AGENTMEMORY_DROP_STALE_INDEX=true to discard the persisted vectors and start fresh.

What it means

At startup, agentmemory loads the persisted vector index and verifies each stored vector's dimension against the active embedding provider. If mismatches exist and AGENTMEMORY_DROP_STALE_INDEX is not set, main() throws to prevent cross-dimension cosine comparisons that would silently corrupt search results. The error names the offending observation ids and offers re-embedding or dropping the index.

Source

Thrown at src/index.ts:446

    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 = isDropStaleIndexEnabled();
      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);
      bootLog(
        `Loaded persisted vector index (${vectorIndex.size} vectors)`,
      );
    }

View on GitHub (pinned to e04ba88819)

Solutions

1. Re-embed the persisted index against the new provider, then restart.
2. Set AGENTMEMORY_DROP_STALE_INDEX=true to discard stale vectors and start fresh (observations text is kept; the index rebuilds over time).
3. Revert the embedding provider/model config to the one that produced the persisted vectors.

Example fix

// before
EMBEDDING_PROVIDER=openai  # switched model, old 384-dim vectors on disk
// after
# either re-embed, or explicitly accept data loss:
AGENTMEMORY_DROP_STALE_INDEX=true EMBEDDING_PROVIDER=openai npm start

// before starting, check the persisted index against the provider
const providerDim = embeddingProvider.dimensions;
const onDisk = loadPersistedDims(); // from data/state_store.db
const stale = onDisk.filter((d) => d !== providerDim);
if (stale.length > 0 && process.env.AGENTMEMORY_DROP_STALE_INDEX !== "true") {
  process.env.AGENTMEMORY_DROP_STALE_INDEX = "true"; // or run re-embed job first
}

try {
  await startAgentMemory();
} catch (e) {
  if (String(e.message).includes("wrong dimension")) {
    // do NOT auto-drop in prod; alert and require a re-embed or explicit opt-in
    process.env.AGENTMEMORY_DROP_STALE_INDEX = "true";
    return startAgentMemory();
  }
  throw e;
}

When it happens

Trigger: Switching embedding providers/models (e.g. from a 384-dim model to a 1536-dim one) and restarting agentmemory against the existing ./data/state_store.db vector index, without AGENTMEMORY_DROP_STALE_INDEX=true.

Common situations: Upgrading agentmemory or changing EMBEDDING_PROVIDER/EMBEDDING_MODEL config on a deployment with existing observations; moving a data directory from one project config to another.

Related errors

• [agentmemory] Persisted vector index has ${mismatches.length
• ${envName} must be a positive integer, got: ${override}
• Install @huggingface/transformers for CLIP embeddings: npm i
• COHERE_API_KEY is required
• Cohere embedding failed (${response.status}): ${err}

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/98e58572c5a673a8. Report an issue: GitHub.