Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(embedding): fold document prefix into the stored embedding identity
seathatflowsinourveins4ebc7f5d0cde
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex cfffc68b..e212099c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -19,11 +19,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0`"query: "` / `"passage: "` pair; instruction-tuned E5 variants andQwen3-Embedding instead need a task-instruction string on the query sideonly (documents stay plain). Empty by default — no behaviour change when- unset, and not trimmed (nor is a present-but-empty env-var override,- which now clears a `config.toml` value), so a publisher's trailing space- is preserved. Changing a prefix does not change the stored- `{provider, model, dim}` triple pages are keyed by; run `ai-memory embed- --force` to re-embed after changing one. See `docs/llm-providers.md`.+ unset, and not trimmed (nor is a present-but-empty env-var override, which+ now clears a `config.toml` value), so a publisher's trailing space is+ preserved. A non-empty `embedding_document_prefix` is folded into the+ stored embedding identity (`Embedder::model_identity`), so a document+ prefix change makes retrieval, backfill, and cleanup treat existing pages+ as stale and re-embed them automatically — an empty prefix keeps the+ pre-existing identity, so upgrading installs need no migration, and a+ query-only prefix change never needs a rebuild. See+ `docs/llm-providers.md`.### Fixed- `memory_query`'s vector stream called the generic `Embedder::embed`diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex d2c1811b..21448f1f 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -1633,7 +1633,7 @@ async fn start_maintenance_scheduler(.as_ref().map(|e| ai_memory_consolidate::EmbeddingCoord {provider: e.provider().to_string(),- model: e.model().to_string(),+ model: e.model_identity(),dim: e.dim(),});@@ -2367,11 +2367,15 @@ async fn configure_embedder(}Err(e) => return Err(e).context("building embedder from config"),};+ // Not `.model()`: the running triple must match what pages are+ // actually stored under, which a configured document prefix changes.+ // See `Embedder::model_identity`.+ let configured_model_identity = embedder.model_identity();let mismatch = store.reader.embedding_meta_for_mismatch(embedder.provider().into(),- embedder.model().into(),+ configured_model_identity.clone(),embedder.dim(),).await?;@@ -2383,7 +2387,7 @@ async fn configure_embedder(tracing::warn!(stored = ?mismatch,configured_provider = embedder.provider(),- configured_model = embedder.model(),+ configured_model = %configured_model_identity,configured_dim = embedder.dim(),"stored embeddings use a different (provider, model, dim) than configured; \hybrid search ignores stale rows until pages are re-embedded — \@@ -3999,7 +4003,7 @@ mod tests {ws,project,embedder.provider().to_string(),- embedder.model().to_string(),+ embedder.model_identity(),embedder.dim(),).awaitdiff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rsindex fcf37f20..b544ecf9 100644--- a/crates/ai-memory-cli/src/config.rs+++ b/crates/ai-memory-cli/src/config.rs@@ -471,11 +471,17 @@ pub struct Config {pub embedding_query_prefix: Option<String>,/// Document-side counterpart of `embedding_query_prefix` (e.g./// `"passage: "` for Nemotron-3-Embed / base E5; see that field's doc- /// comment for which models this applies to). Changing this does not- /// change the stored `{provider, model, dim}` triple pages are keyed- /// by — run `ai-memory embed --force` to re-embed after changing it.- /// Settable via `AI_MEMORY_EMBEDDING_DOCUMENT_PREFIX` (same raw-env- /// overlay as `embedding_query_prefix`).+ /// comment for which models this applies to). Unlike the query prefix,+ /// this one IS folded into the stored embedding identity+ /// (`Embedder::model_identity`): a non-empty value makes newly+ /// embedded pages distinguishable from ones embedded before the+ /// change (or under a different prefix), so `memory_query` and+ /// `ai-memory embed`'s stale-row detection both treat a document-prefix+ /// change like a model change — no manual `--force` needed, and an+ /// empty value keeps the pre-existing (legacy) identity so upgrading+ /// installs need no migration. Settable via+ /// `AI_MEMORY_EMBEDDING_DOCUMENT_PREFIX` (same raw-env overlay as+ /// `embedding_query_prefix`).pub embedding_document_prefix: Option<String>,/// M8 retention-sweep parameters. The defaults give an ~80-day/// "survival floor" for unused episodic content (above the colddiff --git a/crates/ai-memory-consolidate/src/embed.rs b/crates/ai-memory-consolidate/src/embed.rsindex 57299d2c..0302fac6 100644--- a/crates/ai-memory-consolidate/src/embed.rs+++ b/crates/ai-memory-consolidate/src/embed.rs@@ -91,7 +91,10 @@ pub async fn run_embedding_backfill(options: EmbedBackfillOptions,) -> Result<EmbedBackfillCounts, EmbedBackfillError> {let provider = embedder.provider().to_string();- let model = embedder.model().to_string();+ // Not `.model()`: this identity drives both stale-row detection below+ // (a document-prefix change must look "stale" like a model change+ // would) and every write this pass makes. See `Embedder::model_identity`.+ let model = embedder.model_identity();let dim = embedder.dim();let candidates = reader.decay_candidates(workspace_id, project_id).await?;diff --git a/crates/ai-memory-consolidate/tests/suite/embed_backfill.rs b/crates/ai-memory-consolidate/tests/suite/embed_backfill.rsindex e8e13cf8..3864e4d8 100644--- a/crates/ai-memory-consolidate/tests/suite/embed_backfill.rs+++ b/crates/ai-memory-consolidate/tests/suite/embed_backfill.rs@@ -156,3 +156,272 @@ async fn backfill_reembed_regenerates_existing_rows() {assert_eq!(counts.skipped, 0);assert_eq!(f.embedded_count().await, 1);}++/// A fake embedder standing in for `OpenAiEmbedder`/`OpenAiCompatEmbedder`+/// with a configurable document prefix: `identity_suffix` plays the role a+/// non-empty `document_prefix` plays there (`Embedder::model_identity`+/// diverges from `Embedder::model` when set), and `fail_on_substring` lets+/// one test drive a genuine per-page provider failure without a real+/// network call.+struct ConfigurableEmbedder {+ dim: u32,+ identity_suffix: String,+ fail_on_substring: Option<&'static str>,+}++#[async_trait::async_trait]+impl Embedder for ConfigurableEmbedder {+ fn provider(&self) -> &'static str {+ "synthetic"+ }++ fn model(&self) -> &str {+ "bag-of-words-v1"+ }++ fn model_identity(&self) -> String {+ if self.identity_suffix.is_empty() {+ self.model().to_string()+ } else {+ format!("{}+{}", self.model(), self.identity_suffix)+ }+ }++ fn dim(&self) -> u32 {+ self.dim+ }++ async fn embed(&self, text: &str) -> ai_memory_llm::LlmResult<Vec<f32>> {+ if let Some(marker) = self.fail_on_substring+ && text.contains(marker)+ {+ return Err(ai_memory_llm::LlmError::Provider {+ status: 500,+ body: "synthetic configured failure".into(),+ });+ }+ Ok(vec![0.5_f32; self.dim as usize])+ }+}++/// A document-prefix change (a new `identity_suffix` here) must make a+/// **normal** (non-force) backfill pass treat every page as needing a+/// fresh embedding, exactly like a model change would — this is what+/// keeps `memory_query`'s retrieval eligibility filter (keyed on the+/// currently configured embedder's `model_identity`) from ever mixing+/// vectors embedded under different prefixes. The old row is left in+/// place (nothing here deletes it — deletion is a separate, explicit step+/// mirroring `POST /admin/embed`'s `reembed` purge, covered by the next+/// test), but it is no longer reachable under the newly configured+/// identity.+#[tokio::test]+async fn document_prefix_change_makes_backfill_treat_pages_as_stale_and_reembeds_them() {+ let f = fixture().await;+ f.write_page("notes/a.md", "alpha content").await;++ let legacy: Arc<dyn Embedder> = Arc::new(ConfigurableEmbedder {+ dim: 8,+ identity_suffix: String::new(),+ fail_on_substring: None,+ });+ let first = run_embedding_backfill(+ &f.store.reader,+ &f.store.writer,+ &f.wiki,+ &legacy,+ f.ws,+ f.proj,+ EmbedBackfillOptions::default(),+ )+ .await+ .expect("first backfill");+ assert_eq!(first.embedded, 1);++ // Simulates reconfiguring `embedding_document_prefix`: same provider,+ // same wire model, same dim — only the document-side identity differs.+ let prefixed: Arc<dyn Embedder> = Arc::new(ConfigurableEmbedder {+ dim: 8,+ identity_suffix: "dp-test".into(),+ fail_on_substring: None,+ });+ assert_ne!(legacy.model_identity(), prefixed.model_identity());++ // Between the config change and the next backfill pass, the stored+ // row is still under the OLD identity — this is the property the fix+ // protects: a query using the NOW-configured embedder's identity (what+ // `memory_query`'s retrieval eligibility filter does) does not match+ // it, so the page is excluded from vector search rather than silently+ // matched with content embedded under the old prefix.+ let prefixed_ids_before = f+ .store+ .reader+ .embedded_page_ids(+ f.ws,+ f.proj,+ prefixed.provider().to_string(),+ prefixed.model_identity(),+ prefixed.dim(),+ )+ .await+ .expect("prefixed embedded_page_ids before backfill");+ assert_eq!(+ prefixed_ids_before.len(),+ 0,+ "the pre-change row must not be matched under the new identity"+ );++ let second = run_embedding_backfill(+ &f.store.reader,+ &f.store.writer,+ &f.wiki,+ &prefixed,+ f.ws,+ f.proj,+ EmbedBackfillOptions::default(), // reembed: false — a NORMAL pass+ )+ .await+ .expect("backfill after a document-prefix change");+ assert_eq!(+ second.embedded, 1,+ "a document-prefix change must be treated as stale and re-embedded, \+ not silently skipped as \"already embedded\""+ );+ assert_eq!(second.skipped, 0);++ // `page_embeddings` is one row per page (replace-on-write), so the+ // fresh write replaces the pre-change row rather than accumulating+ // alongside it: the old identity now matches nothing …+ let legacy_ids_after = f+ .store+ .reader+ .embedded_page_ids(+ f.ws,+ f.proj,+ legacy.provider().to_string(),+ legacy.model_identity(),+ legacy.dim(),+ )+ .await+ .expect("legacy embedded_page_ids after backfill");+ assert_eq!(+ legacy_ids_after.len(),+ 0,+ "the pre-change row was replaced, not left behind, by the re-embed"+ );+ // … and the new identity now does.+ let prefixed_ids_after = f+ .store+ .reader+ .embedded_page_ids(+ f.ws,+ f.proj,+ prefixed.provider().to_string(),+ prefixed.model_identity(),+ prefixed.dim(),+ )+ .await+ .expect("prefixed embedded_page_ids after backfill");+ assert_eq!(prefixed_ids_after.len(), 1);+}++/// Mirrors `POST /admin/embed`'s `reembed: true` sequence exactly+/// (`ai-memory-mcp/src/admin.rs::handle_embed`): purge stale rows for the+/// configured triple, then run a forced backfill. One of two pages fails+/// mid-run; the purge must still have applied to both, the surviving page+/// must still get a fresh row, and the failed page must be left with NO+/// row (not a stale one and not a half-written one) rather than silently+/// keeping a purged-then-never-replaced gap invisible to the operator —+/// `counts.failed` is what surfaces it.+#[tokio::test]+async fn force_rebuild_purges_first_and_counts_a_partial_failure_correctly() {+ let f = fixture().await;+ f.write_page("notes/ok.md", "alpha content").await;+ f.write_page("notes/bad.md", "FAIL_MARKER content").await;++ // Seed both pages under a stand-in "old" identity, matching a real+ // force-rebuild's starting point: pages already have rows, possibly+ // under a different identity than the one about to be forced.+ let legacy: Arc<dyn Embedder> = Arc::new(ConfigurableEmbedder {+ dim: 8,+ identity_suffix: "old".into(),+ fail_on_substring: None,+ });+ let seeded = run_embedding_backfill(+ &f.store.reader,+ &f.store.writer,+ &f.wiki,+ &legacy,+ f.ws,+ f.proj,+ EmbedBackfillOptions::default(),+ )+ .await+ .expect("seed backfill");+ assert_eq!(seeded.embedded, 2);++ let flaky: Arc<dyn Embedder> = Arc::new(ConfigurableEmbedder {+ dim: 8,+ identity_suffix: String::new(), // the configured (new) identity+ fail_on_substring: Some("FAIL_MARKER"),+ });++ // Step 1 (admin.rs's purge-before-reembed): delete every row in scope+ // that does not match the target triple — here that is BOTH seeded+ // rows, since they are under `legacy`'s identity.+ let purged = f+ .store+ .writer+ .delete_stale_page_embeddings(+ f.ws,+ Some(f.proj),+ flaky.provider().to_string(),+ flaky.model_identity(),+ flaky.dim(),+ )+ .await+ .expect("purge");+ assert_eq!(+ purged, 2,+ "purge removes every row under a non-matching identity"+ );++ // Step 2: forced backfill with the embedder that fails on notes/bad.md.+ let counts = run_embedding_backfill(+ &f.store.reader,+ &f.store.writer,+ &f.wiki,+ &flaky,+ f.ws,+ f.proj,+ EmbedBackfillOptions {+ reembed: true,+ dry_run: false,+ },+ )+ .await+ .expect("forced backfill with a partial failure");+ assert_eq!(counts.embedded, 1, "notes/ok.md succeeds");+ assert_eq!(counts.failed, 1, "notes/bad.md's provider call fails");++ let current_ids = f+ .store+ .reader+ .embedded_page_ids(+ f.ws,+ f.proj,+ flaky.provider().to_string(),+ flaky.model_identity(),+ flaky.dim(),+ )+ .await+ .expect("embedded_page_ids after the forced rebuild");+ assert_eq!(+ current_ids.len(),+ 1,+ "exactly the succeeding page has a row under the new identity; \+ the failed page is left with none — purged, not silently kept \+ stale, and not half-written — so it surfaces as `failed` for the \+ operator to retry rather than looking either fully migrated or \+ still on the old prefix"+ );+}diff --git a/crates/ai-memory-llm/src/embedding.rs b/crates/ai-memory-llm/src/embedding.rsindex 18580c41..52cf2a21 100644--- a/crates/ai-memory-llm/src/embedding.rs+++ b/crates/ai-memory-llm/src/embedding.rs@@ -18,6 +18,7 @@ use std::time::Duration;use async_trait::async_trait;use secrecy::{ExposeSecret, SecretString};use serde::{Deserialize, Serialize};+use sha2::{Digest, Sha256};use tracing::debug;use crate::error::{LlmError, LlmResult};@@ -39,9 +40,35 @@ pub trait Embedder: Send + Sync {/// Short identifier (e.g. `openai`, `voyage`, `synthetic`).fn provider(&self) -> &'static str;- /// Model identifier (e.g. `text-embedding-3-small`).+ /// Model identifier (e.g. `text-embedding-3-small`). The exact string+ /// sent on the wire — never suffixed or altered. See+ /// [`Self::model_identity`] for the value that should be stored+ /// alongside a vector or used to select eligible stored vectors.fn model(&self) -> &str;+ /// The `model` component of the stored/matched `(provider, model, dim)`+ /// identity for a **document** embedding — distinct from [`Self::model`]+ /// (the wire model name) whenever the effective document-side input+ /// text is not what the model id alone implies. Defaults to+ /// `self.model().to_string()`: providers with no such distinction (every+ /// provider except the two below) are unaffected.+ ///+ /// `OpenAiEmbedder`/`OpenAiCompatEmbedder` override this to fold in a+ /// fingerprint of their configured `document_prefix` when it is+ /// non-empty, so a page embedded under one document prefix is never+ /// silently matched against, or mixed with, vectors embedded under a+ /// different (or no) prefix — the same `(provider, model, dim)`+ /// refuse-on-mismatch and stale-row machinery that already protects+ /// against a plain model swap now also protects against a document+ /// prefix change. An empty prefix reproduces `self.model()` exactly+ /// (the pre-existing identity), so upgrading installs with no prefix+ /// configured need no migration. The **query** prefix never affects+ /// this: only the text actually embedded and stored needs a distinct+ /// identity, and a query is never stored.+ fn model_identity(&self) -> String {+ self.model().to_string()+ }+/// Vector dimensionality.fn dim(&self) -> u32;@@ -280,6 +307,10 @@ impl Embedder for OpenAiEmbedder {&self.model}+ fn model_identity(&self) -> String {+ document_prefix_identity(&self.model, &self.document_prefix)+ }+fn dim(&self) -> u32 {self.dim}@@ -411,6 +442,10 @@ impl Embedder for OpenAiCompatEmbedder {&self.model}+ fn model_identity(&self) -> String {+ document_prefix_identity(&self.model, &self.document_prefix)+ }+fn dim(&self) -> u32 {self.dim}@@ -622,6 +657,35 @@ pub(crate) fn prepend_prefix<'a>(prefix: &str, text: &'a str) -> std::borrow::Co}}+/// The `model` component of the stored embedding identity for a document+/// embedder configured with `document_prefix`. An empty prefix returns+/// `model` unchanged — the pre-existing identity, so an install with no+/// document prefix configured needs no migration. A non-empty prefix+/// appends a versioned SHA-256 fingerprint of the prefix bytes: `+dp1-`+/// followed by the first 16 hex characters (64 bits) of+/// `SHA-256(document_prefix)`. Not the raw prefix text itself, which+/// could be long, contain characters awkward in a stored column, or leak+/// an operator's exact instruction string into logs/admin output more+/// than necessary — and not a 32-bit hash (an earlier revision used+/// `fnv1a` truncated to 32 bits, which a search for a same-length ASCII+/// collision found in minutes: `"Document category 5hvhw0: "` and+/// `"Document category 1i4yh8i: "` both fingerprinted to `5c7f37a2`,+/// which would have silently mixed two different prefixes' vectors under+/// one identity — see `document_prefix_identity_does_not_collide_on_the_known_fnv32_pair`+/// below). SHA-256 truncated to 64 bits keeps the collision probability+/// negligible for the small number of prefixes one deployment actually+/// configures over time, without needing the full 256-bit digest in a+/// column meant to stay human-scannable. The `dp1` version tag lets a+/// future change to this scheme be distinguished from today's rather than+/// risking a silent collision with an old identity under a new one.+pub(crate) fn document_prefix_identity(model: &str, document_prefix: &str) -> String {+ if document_prefix.is_empty() {+ return model.to_string();+ }+ let digest = format!("{:x}", Sha256::digest(document_prefix.as_bytes()));+ format!("{model}+dp1-{}", &digest[..16])+}+/// Unit-normalise so dot-product equals cosine similarity.pub(crate) fn normalise(mut v: Vec<f32>) -> Vec<f32> {let norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();@@ -653,6 +717,109 @@ pub fn cosine(a: &[f32], b: &[f32]) -> f32 {mod tests {use super::*;+ #[test]+ fn document_prefix_identity_is_unchanged_when_the_prefix_is_empty() {+ // The legacy-identity guarantee: an install with no document+ // prefix configured must key its vectors exactly as before this+ // feature, so it needs no migration.+ assert_eq!(+ document_prefix_identity("nomic-embed-text", ""),+ "nomic-embed-text"+ );+ }++ #[test]+ fn document_prefix_identity_changes_deterministically_with_the_prefix() {+ let base = document_prefix_identity("nomic-embed-text", "passage: ");+ assert_ne!(+ base, "nomic-embed-text",+ "a set prefix must not reuse the legacy identity"+ );+ assert!(base.starts_with("nomic-embed-text+dp1-"));+ // Deterministic: the same (model, prefix) always produces the same+ // identity, so pages embedded in different requests still land+ // under one queryable identity.+ assert_eq!(+ base,+ document_prefix_identity("nomic-embed-text", "passage: ")+ );+ }++ #[test]+ fn document_prefix_identity_distinguishes_different_prefixes() {+ // Two distinct document prefixes on the same model must not+ // collide — otherwise a prefix *change* would look like no change+ // at all to the refuse-on-mismatch / stale-row machinery.+ let a = document_prefix_identity("nomic-embed-text", "passage: ");+ let b = document_prefix_identity("nomic-embed-text", "document: ");+ assert_ne!(a, b);+ }++ /// Regression test for a real collision found in an earlier revision+ /// of `document_prefix_identity`, which truncated `fnv1a` to 32 bits:+ /// `"Document category 5hvhw0: "` and `"Document category 1i4yh8i: "`+ /// both fingerprinted to `5c7f37a2` (verified independently in+ /// Python), which would have silently mixed the two prefixes' vectors+ /// under one stored identity. The SHA-256-based fingerprint here does+ /// not collide on this pair (also independently verified: their first+ /// 16 hex characters are `b32006f5a41f3d24` and `513594f86d5883fd`).+ #[test]+ fn document_prefix_identity_does_not_collide_on_the_known_fnv32_pair() {+ let a = document_prefix_identity("nomic-embed-text", "Document category 5hvhw0: ");+ let b = document_prefix_identity("nomic-embed-text", "Document category 1i4yh8i: ");+ assert_ne!(+ a, b,+ "these two prefixes collided under the old 32-bit fnv1a fingerprint; \+ the new SHA-256-based one must not repeat that collision"+ );+ }++ #[test]+ fn model_identity_defaults_to_model_for_providers_without_prefixes() {+ // Providers that never got the document-prefix override (google,+ // voyage, local, copilot, synthetic) must see byte-identical+ // behaviour: `model_identity` defaults to `model().to_string()`.+ let e = SyntheticEmbedder::new(8);+ assert_eq!(e.model_identity(), e.model());+ }++ #[test]+ fn openai_compat_embedder_model_identity_reflects_the_document_prefix() {+ let unset = OpenAiCompatEmbedder::new("http://localhost:9/v1", None, "nomic-embed-text", 8)+ .expect("embedder builds");+ assert_eq!(unset.model_identity(), "nomic-embed-text");++ let with_prefix =+ OpenAiCompatEmbedder::new("http://localhost:9/v1", None, "nomic-embed-text", 8)+ .expect("embedder builds")+ .with_prefixes("query: ", "passage: ");+ assert_ne!(with_prefix.model_identity(), "nomic-embed-text");+ assert_eq!(+ with_prefix.model_identity(),+ document_prefix_identity("nomic-embed-text", "passage: ")+ );+ // The query prefix must NOT affect the stored identity — only+ // documents are stored; a query is never persisted.+ let query_only =+ OpenAiCompatEmbedder::new("http://localhost:9/v1", None, "nomic-embed-text", 8)+ .expect("embedder builds")+ .with_prefixes("query: ", "");+ assert_eq!(query_only.model_identity(), "nomic-embed-text");+ }++ #[test]+ fn openai_embedder_model_identity_reflects_the_document_prefix() {+ let unset =+ OpenAiEmbedder::new(SecretString::from("k"), "text-embedding-3-small", 1536).unwrap();+ assert_eq!(unset.model_identity(), "text-embedding-3-small");++ let with_prefix =+ OpenAiEmbedder::new(SecretString::from("k"), "text-embedding-3-small", 1536)+ .unwrap()+ .with_prefixes("query: ", "passage: ");+ assert_ne!(with_prefix.model_identity(), "text-embedding-3-small");+ }+/// Transport-level proof that `OpenAiEmbedder` (not just/// `OpenAiCompatEmbedder`, covered in/// `tests/suite/openai_compat_embedder.rs`) actually sends thediff --git a/crates/ai-memory-llm/src/health.rs b/crates/ai-memory-llm/src/health.rsindex 6fd7ceb3..ceb53040 100644--- a/crates/ai-memory-llm/src/health.rs+++ b/crates/ai-memory-llm/src/health.rs@@ -375,6 +375,17 @@ impl Embedder for HealthRecordingEmbedder {self.inner.model()}+ fn model_identity(&self) -> String {+ // Not the default (`self.model().to_string()`): every configured+ // embedder is wrapped in this type before being handed to the rest+ // of the server (`serve.rs`'s `wrap_embedder`), so without this+ // override every caller of `model_identity` — the refuse-on-mismatch+ // check, backfill, retrieval, cleanup — would silently see the+ // wire model name instead of the inner embedder's actual document-+ // prefix-aware identity.+ self.inner.model_identity()+ }+fn dim(&self) -> u32 {self.inner.dim()}@@ -559,6 +570,35 @@ mod tests {assert!(after.last_call_at.is_some());}+ /// Every configured embedder is wrapped in `HealthRecordingEmbedder`+ /// before reaching the rest of the server (`serve.rs`'s+ /// `wrap_embedder`), so a caller of `model_identity` — the+ /// refuse-on-mismatch check, backfill, retrieval, cleanup — only ever+ /// sees the wrapper, never the inner embedder directly. Without the+ /// wrapper's own `model_identity` override, the default trait impl+ /// (`self.model().to_string()`) would silently discard a document+ /// prefix's identity fingerprint. `TaskAwareEmbedder` doesn't+ /// distinguish this (it never overrides `model_identity` either, so a+ /// missing wrapper override would coincidentally still pass against+ /// it); a real `OpenAiCompatEmbedder` with a document prefix set does.+ #[test]+ fn embedder_wrapper_forwards_the_inner_model_identity_override() {+ let inner =+ crate::OpenAiCompatEmbedder::new("http://localhost:9/v1", None, "nomic-embed-text", 8)+ .expect("embedder builds")+ .with_prefixes("query: ", "passage: ");+ let inner_identity = inner.model_identity();+ assert_ne!(+ inner_identity,+ inner.model(),+ "the fixture must actually have a distinct identity, or this test proves nothing"+ );++ let health = ProviderHealth::default();+ let wrapped = health.wrap_embedder(Arc::new(inner), "openai-compat", "nomic-embed-text", 8);+ assert_eq!(wrapped.model_identity(), inner_identity);+ }+#[test]fn provider_health_status_wire_labels() {for (status, label) in [diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex fa00baa1..636a63be 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -3449,7 +3449,7 @@ async fn handle_lint(.as_ref().map(|e| ai_memory_consolidate::EmbeddingCoord {provider: e.provider().to_string(),- model: e.model().to_string(),+ model: e.model_identity(),dim: e.dim(),}),},@@ -3599,7 +3599,10 @@ async fn handle_embed(};let provider = embedder.provider().to_string();- let model = embedder.model().to_string();+ // Not `.model()`: the purge below must match the identity rows were+ // actually stored under (a document-prefix change), not the wire+ // model name. See `Embedder::model_identity`.+ let model = embedder.model_identity();let dim = embedder.dim();let mut totals = EmbedBackfillCounts::default();@@ -6231,9 +6234,12 @@ async fn copy_purge_merge(let mut src_embeddings: std::collections::HashMap<String, Vec<u8>> =std::collections::HashMap::new();let embed_meta: Option<(String, String, u32)> = if let Some(embedder) = &state.embedder {+ // Not `.model()`: only vectors stored under the current document+ // identity are "current-model" for the carry-over below to load.+ // See `Embedder::model_identity`.let (provider, model, dim) = (embedder.provider().to_string(),- embedder.model().to_string(),+ embedder.model_identity(),embedder.dim(),);match statediff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex ba2cab16..0f9f7bc8 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -1995,7 +1995,11 @@ impl AiMemoryServer {// eligible; with no query vector the vector stream never runs,// so the empty triple is inert rather than a fake identity.let (provider, model, dim) = match (&self.embedder, options.query_vec) {- (Some(e), Some(_)) => (e.provider().to_string(), e.model().to_string(), e.dim()),+ // Not `.model()`: eligible stored vectors are keyed by the+ // DOCUMENT identity they were embedded under, which a+ // configured document prefix folds in. See+ // `Embedder::model_identity`.+ (Some(e), Some(_)) => (e.provider().to_string(), e.model_identity(), e.dim()),_ => (String::new(), String::new(), 0),};let fused: Vec<(PageHit, Option<ai_memory_store::SearchExplain>)> = if options.explain {@@ -3084,7 +3088,7 @@ impl AiMemoryServer {.as_ref().map(|e| ai_memory_consolidate::EmbeddingCoord {provider: e.provider().to_string(),- model: e.model().to_string(),+ model: e.model_identity(),dim: e.dim(),}),},diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex 4dac00be..8c486a03 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -2216,7 +2216,12 @@ impl Wiki {page_id,bytes,embedder.provider().to_string(),- embedder.model().to_string(),+ // Not `.model()`: a configured document prefix+ // must land under a distinct stored identity so+ // a prefix change is never silently mixed with+ // vectors embedded under a different (or no)+ // prefix. See `Embedder::model_identity`.+ embedder.model_identity(),embedder.dim(),).await?;@@ -2250,7 +2255,8 @@ impl Wiki {page_id,vector_bytes: f32_vec_to_bytes(&vec),provider: embedder.provider().to_string(),- model: embedder.model().to_string(),+ // See the body-embedding write above.+ model: embedder.model_identity(),dim: embedder.dim(),}]).await?;diff --git a/docs/llm-providers.md b/docs/llm-providers.mdindex 4134c947..2642018e 100644--- a/docs/llm-providers.md+++ b/docs/llm-providers.md@@ -252,10 +252,16 @@ Fill in your own task description for `{task description}`, leaveexact string for the other — the trailing-space difference ispublisher-specified, not a typo.-Changing either prefix does not change the stored-`{provider, model, dim}` triple pages are keyed by, so existing vectors keep-matching on the mismatch check but were embedded under the old (or no)-prefix; run `ai-memory embed --force` to re-embed after changing one.+Changing `embedding_query_prefix` alone never requires re-embedding: only+`embedding_document_prefix` is folded into the stored embedding identity+(a non-empty value changes what `ai-memory` treats as the current+`{provider, model, dim}` triple for that page's vectors), so a document+prefix change makes `memory_query` stop matching the old vectors and the+next `ai-memory embed` (scheduled or manual) pass re-embed them+automatically — no `--force` needed. `--force` remains useful to+re-embed everything immediately rather than waiting for scheduled+backfill, or to force a re-embed for a reason the triple alone doesn't+capture (e.g. touching up the vLLM server's tokenizer or quantization).`AI_MEMORY_EMBEDDING_PROVIDER=copilot` reuses the same Copilot OAuth login asthe `copilot` LLM provider (`ai-memory auth login copilot` or