mongodb-memory-mcp: Skill for Claude Code

Migrating the embedding model or provider

Changing the embedding model invalidates every vector in the corpus. Done in the wrong order it strands the knowledge base — search returns nothing, and the reason is invisible. Done in this order it is a background backfill during which search keeps working.

---

Why nothing gets orphaned

Every chunk records who embedded it, as flat, indexed, filterable fields:

embeddingProvider   'voyage'
embeddingModel      'voyage-context-3'
embeddingDimensions 1024
embeddedAt          <Date>

Plus a matching stamp on the parent document (document.embedding) for the management views. Two of those fields — embeddingModel and embeddingDimensions — are declared filter paths in src/db/index-definitions/chunks.vector.json, and that is what the whole migration story rests on:

• Search is always constrained to the configured model. buildVectorFilter() in src/services/knowledge-service.ts unconditionally adds embeddingModel == config.embedding.model and embeddingDimensions == config.embedding.dimensions to every $vectorSearch. buildTextFilter() pins the model too (embeddingDimensions is not in chunks.text.json, which is fine — the vector leg pins both, and two configs sharing a model name but differing in width is pathological). So a half-migrated corpus returns fewer results, never a ranking that silently mixes two incompatible vector spaces. That failure mode — confidently wrong answers — is far worse than temporarily thin recall.
• The backfill knows exactly what is left. "Stale" is embeddingModel != target OR embeddingDimensions != target, served by the chunks_embeddingModel_dimensions index.
• storeContent notices too. An unchanged content hash whose chunks were embedded by a different model is re-ingested rather than skipped (event ingest.repair), so ordinary traffic helps the migration along.

---

Before you start

Answer these:

1. Does the vector width change? voyage-context-3 → voyage-3.5 at the same 1024 dims is the easy case. Any change to EMBEDDING_DIMENSIONS means the vector index must be dropped and recreated (see step 3) and there is an unavoidable window where the old vectors are unmatchable.
2. Is the new model contextual? CONTEXTUAL_MODELS in src/config/env.ts drives config.embedding.contextual. Moving from contextual to non-contextual is legal — the provider interface is the same either way — but retrieval characteristics change, so re-check quality by hand, not just by test.
3. Does the width the model supports match? The env schema rejects an EMBEDDING_DIMENSIONS the model does not offer (2048 | 1024 | 512 | 256 for the known Voyage Matryoshka models). Add the model to KNOWN_MODEL_DIMENSIONS if it is new.
4. How big is the corpus? GET /api/embedding-coverage (bearer token required) gives chunk and document counts per model. Multiply by your provider's rate limit to get a realistic wall-clock estimate before you start.