Worker refuses to start after embedding provider change: stale index dimension mismatch (2048D vs 384D) #455

Problem

After switching embedding providers (or after an agentmemory upgrade that changed the default local model), the worker refuses to start with a fatal error:

[agentmemory] Fatal: Error: [agentmemory] Refusing to start: persisted vector index has 19 of 19 vectors with the wrong dimension. Active provider (local) declares 384; dimensions seen on disk: 2048. First mismatched obsIds: mem_mp8ctmgi_37deb553385b (dim=2048), ...

The worker process exits immediately, leaving the REST API (:3111) unreachable. The dashboard (:3113) stays in "CONNECTING..." state with all counters at 0.

Root Cause

The local embedding provider switched from a 2048D model to all-MiniLM-L6-v2 (384D). The persisted vector index on disk still contains vectors from the old provider. The worker detects this mismatch and refuses to start to prevent silent search corruption.

Workaround

Add to ~/.agentmemory/.env:

AGENTMEMORY_DROP_STALE_INDEX=true

Then restart the worker. All existing memories are lost — the index is purged and rebuilt from scratch.

Expected Behavior

1. Graceful degradation: The worker should start even with a stale index, falling back to BM25-only search until re-embedding completes
2. Auto-migration: Detect dimension mismatch and offer to re-embed existing vectors against the new provider (with a progress indicator)
3. Clear CLI guidance: The error message mentions 3 options but requires manual .env editing. A CLI flag like agentmemory start --drop-stale-index or agentmemory reset-index would be more discoverable
4. Dashboard visibility: The dashboard should show a warning banner when the index is stale, rather than silently showing "0 sessions" with "CONNECTING..."

Environment

• agentmemory: v0.9.17
• iii-engine: v0.11.6
• Host: OpenCode Desktop 1.15.3
• OS: macOS 15.4 (arm64)
• Embedding provider: local (all-MiniLM-L6-v2, 384D)
• Previous provider: unknown (2048D vectors on disk)

Reproduction Steps

1. Run agentmemory with an embedding provider that produces 2048D vectors
2. Create some sessions/memories
3. Switch to local provider (384D) or upgrade agentmemory to a version with a different default model
4. Restart agentmemory → worker crashes with dimension mismatch error
5. REST API unreachable, dashboard shows "CONNECTING..."

Suggested Fix

• Add a --reset-index or --migrate-index CLI flag
• Implement background re-embedding of stale vectors when provider changes
• Show index health status in the dashboard
• Provide a non-destructive fallback mode (BM25-only) when vector index is incompatible