rohitg00/agentmemory · warning

[agentmemory] Persisted vector index has ${mismatches.length

Error message

[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.

What it means

At startup, main() loads the persisted vector index and compares each vector's dimension to the active embedding provider's declared dimension. When mismatches exist and AGENTMEMORY_DROP_STALE_INDEX=true is set, it warns loudly and discards the persisted vectors; the index is rebuilt from live observations over time. This prevents dimension-mismatched vectors from corrupting similarity search after an embedding model change.

Source

Thrown at src/index.ts:437

    // 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 = 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` +

View on GitHub (pinned to e04ba88819)

Solutions

1. No action needed if the drop is intended — the index rebuilds from live observations.
2. If you did NOT intend to change dimensions, restore the previous embedding provider config to keep existing vectors.
3. Back up ./data before switching embedding providers so you can roll back.
4. Re-embed historical observations if you need old data searchable under the new provider.

Example fix

// before: provider switched, data silently dropped
AGENTMEMORY_DROP_STALE_INDEX=true
// after: pin the provider matching the persisted vectors, or back up first
cp -r ./data ./data.bak  # then switch providers intentionally

// before switching providers, compare declared dimension to persisted index
const declaredDim = provider.dimensions;
if (persistedDim && persistedDim !== declaredDim) {
  console.warn(`dimension change ${persistedDim} -> ${declaredDim}; index will be dropped/rebuilt`);
}

When it happens

Trigger: main() startup: loaded.vector.size > 0 with mismatches.length > 0, isDropStaleIndexEnabled() true — i.e. the on-disk index was built with a different embedding dimension than the currently configured provider declares.

Common situations: Switching embedding providers/models (e.g. 1536-dim OpenAI to 768-dim local) without clearing data; restoring an old data directory; config change of AGENTMEMORY_EMBEDDING_* variables while stale index remains.

Related errors

• [agentmemory] Refusing to start: persisted vector index has
• ${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/290fc91a6672d5c6. Report an issue: GitHub.