Skip to content

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.md
index 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 and
Qwen3-Embedding instead need a task-instruction string on the query side
only (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.rs
index 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(),
)
.await
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index 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 cold
diff --git a/crates/ai-memory-consolidate/src/embed.rs b/crates/ai-memory-consolidate/src/embed.rs
index 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.rs
index 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.rs
index 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 the
diff --git a/crates/ai-memory-llm/src/health.rs b/crates/ai-memory-llm/src/health.rs
index 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.rs
index 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 state
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index 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.rs
index 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.md
index 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}`, leave
exact string for the other — the trailing-space difference is
publisher-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 as
the `copilot` LLM provider (`ai-memory auth login copilot` or