feat(ai-core): semantic recall adapter for AgentMemoryPort (E10)

[rickylabs]

AgentMemoryPort.recall is a declared optional seam with no shipped implementation (packages/ai/src/ports/memory.ts, E10). eis-chat proves the pattern app-side: cosine recall over embedded memories injected per turn (packages/channel/mod.ts:422-528, routes/api/chat.ts:464-488).

Ship a reference adapter composing EmbeddingProviderPort + a pluggable vector-store seam (KV-backed starter), keeping stores app-owned per the persistence law.

Acceptance criteria

• recall returns scored RecallResults; the loop falls back to load when recall is absent (existing behavior, regression-tested).

Found by the beta.5 eis-chat validation gate (charter Step 3). Refs #219.

[rickylabs]

Moved to Backlog / Triage by the beta-8 orchestrator (4d300496): wave:defer maps to Backlog per the taxonomy law. The port seam work stays in beta.8 via #269; this reference adapter follows once #269 lands and is scoped.

[rickylabs]

eis-chat production finding: embedding-space changes can crash semantic recall

A provider/model switch in eis-chat exposed a concrete failure mode for this adapter's contract.

Incident

After changing the embedding provider/model for an existing corpus, Turso recall failed with:

step failed: Conversion error: Vectors must have the same dimensions

The failure occurred inside vector_distance_cos(stored_embedding, query_embedding) and surfaced as a 500 from memory recall. The OCR provider was not the source: Tesseract produced text locally, then the configured embedding provider vectorized that text. Existing rows and new rows belonged to different embedding spaces.

This sharpens the earlier “one model per corpus” warning in #245 and the model-scoped query-cache note in #270 with a production reproduction.

Root causes found

1. Stored vectors had no enforced embedding-space identity, so recall evaluated every non-null vector.
2. The query embedding cache was intended to be model-scoped, but its key used the startup default model instead of the effective per-request model. A runtime model switch could therefore reuse a stale vector.
3. Dimension equality alone is insufficient as a durable identity: two models can emit vectors of the same length while representing incompatible semantic spaces.
4. With nullable vectors, Turso may still evaluate vector_extract(NULL) when the guard and extraction are combined in one boolean expression. Nullable title vectors needed a nested CASE guard.

Consumer mitigation validated in eis-chat

The local fix now:

• filters memory, knowledge-chunk, title, and skill candidates by the query vector's actual dimension before calling vector_distance_cos;
• guards nullable title vectors with a nested CASE;
• keys query embeddings by provider + endpoint + effective model + query;
• preserves incompatible historical rows and falls back to keyword/no-recall behavior instead of throwing;
• requires re-embedding to restore semantic recall for rows from an old embedding space.

The Turso candidate guard is equivalent to:

WHERE embedding IS NOT NULL
  AND json_array_length(vector_extract(embedding)) = ?

The fix is covered by mixed-dimension regression tests across knowledge retrieval, memory recall, and skill matching, plus a cache-isolation test for runtime model switches. The focused suite passes 26 tests and the full repository type check passes.

Recommendation for this adapter

Please make embedding-space compatibility explicit in the reference adapter rather than leaving it as an implicit store invariant:

• Persist an embeddingSpaceId (or provider/model/revision fingerprint) and dimensions alongside each vector.
• Scope query caches by the same embedding-space identity.
• Filter candidates by space identity before distance evaluation; dimension filtering should remain a defensive last gate.
• On mismatch, return the documented fail-soft result/fallback or an explicit “reindex required” diagnostic, never a backend vector-conversion error.
• Provide a reindex/migration hook for provider or model changes.
• Add an acceptance test that seeds model-A vectors, queries with model B, and verifies deterministic degradation without an exception.

This applies directly to AgentMemoryPort.recall here and to RetrieverPort adapters from #270.