Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(llm): preserve embedding factory compatibility (#300)
AkitaOnRails856bf782b9aa
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rsindex 33c3655a..2d66da78 100644--- a/crates/ai-memory-cli/src/config.rs+++ b/crates/ai-memory-cli/src/config.rs@@ -102,7 +102,8 @@ pub struct Config {/// `install-hooks --capture-assistant`. Set with/// `AI_MEMORY_CAPTURE_ASSISTANT=true`.pub capture_assistant: bool,- /// Optional embedding provider (`openai`, `voyage`, `google` / `gemini`).+ /// Optional embedding provider (`openai`, `voyage`, `google` / `gemini`,+ /// or `openai-compat`).pub embedding_provider: Option<String>,/// Optional embedding model override.pub embedding_model: Option<String>,@@ -806,31 +807,39 @@ impl Config {},};let dim = match self.embedding_dim {+ Some(0) => {+ return Err(LlmError::NotConfigured(+ "AI_MEMORY_EMBEDDING_DIM must be greater than zero".into(),+ ));+ }Some(d) => d,- None => ai_memory_llm::default_embedding_dim(provider, &model).ok_or_else(|| {- LlmError::NotConfigured(- "AI_MEMORY_EMBEDDING_DIM must be set explicitly for openai-compat \+ None => {+ ai_memory_llm::try_default_embedding_dim(provider, &model).ok_or_else(|| {+ LlmError::NotConfigured(+ "AI_MEMORY_EMBEDDING_DIM must be set explicitly for openai-compat \(self-hosted model dims vary)"- .into(),- )- })?,+ .into(),+ )+ })?+ }};let api_key = match provider {- EmbedderChoice::OpenAi => Some(self.openai_embedding_api_key()?),- EmbedderChoice::Voyage => Some(- self.runtime_env- .voyage_api_key- .clone()- .ok_or_else(|| LlmError::NotConfigured("VOYAGE_API_KEY".into()))?,- ),- EmbedderChoice::Google => {- Some(self.runtime_env.gemini_api_key.clone().ok_or_else(|| {- LlmError::NotConfigured("GEMINI_API_KEY or GOOGLE_API_KEY".into())- })?)- }+ EmbedderChoice::OpenAi => self.openai_embedding_api_key()?,+ EmbedderChoice::Voyage => self+ .runtime_env+ .voyage_api_key+ .clone()+ .ok_or_else(|| LlmError::NotConfigured("VOYAGE_API_KEY".into()))?,+ EmbedderChoice::Google => self.runtime_env.gemini_api_key.clone().ok_or_else(|| {+ LlmError::NotConfigured("GEMINI_API_KEY or GOOGLE_API_KEY".into())+ })?,// Keyless engines (Ollama, LM Studio) are the norm; a// gateway key rides on LLM_API_KEY when present.- EmbedderChoice::OpenAiCompat => self.runtime_env.llm_api_key.clone(),+ EmbedderChoice::OpenAiCompat => self+ .runtime_env+ .llm_api_key+ .clone()+ .unwrap_or_else(|| SecretString::from(String::new())),};let base_url = self.embedding_base_url.clone();if provider == EmbedderChoice::OpenAiCompat && non_empty(base_url.as_deref()).is_none() {@@ -1243,10 +1252,7 @@ mod tests {let embedder = cfg.embedder_config().unwrap().unwrap();assert_eq!(embedder.provider, EmbedderChoice::OpenAi);assert_eq!(embedder.model, "text-embedding-3-small");- assert_eq!(- embedder.api_key.as_ref().unwrap().expose_secret(),- "sk-or-test-key"- );+ assert_eq!(embedder.api_key.expose_secret(), "sk-or-test-key");assert_eq!(embedder.base_url.as_deref(),Some("https://openrouter.ai/api/v1")@@ -1267,7 +1273,7 @@ mod tests {assert_eq!(embedder.provider, EmbedderChoice::OpenAiCompat);assert_eq!(embedder.model, "nomic-embed-text");assert_eq!(embedder.dim, 768);- assert!(embedder.api_key.is_none());+ assert!(embedder.api_key.expose_secret().is_empty());assert_eq!(embedder.base_url.as_deref(),Some("http://localhost:11434/v1")@@ -1282,10 +1288,7 @@ mod tests {..cfg.clone()};let embedder = cfg_with_key.embedder_config().unwrap().unwrap();- assert_eq!(- embedder.api_key.as_ref().unwrap().expose_secret(),- "sk-or-key"- );+ assert_eq!(embedder.api_key.expose_secret(), "sk-or-key");// Missing model / dim / base URL each fail closed.let missing_model = Config {@@ -1304,6 +1307,14 @@ mod tests {missing_dim.embedder_config().unwrap_err(),LlmError::NotConfigured(msg) if msg.contains("AI_MEMORY_EMBEDDING_DIM")));+ let zero_dim = Config {+ embedding_dim: Some(0),+ ..cfg.clone()+ };+ assert!(matches!(+ zero_dim.embedder_config().unwrap_err(),+ LlmError::NotConfigured(msg) if msg.contains("greater than zero")+ ));let missing_base = Config {embedding_base_url: None,..cfgdiff --git a/crates/ai-memory-llm/src/factory.rs b/crates/ai-memory-llm/src/factory.rsindex 136f42c0..37ac2db3 100644--- a/crates/ai-memory-llm/src/factory.rs+++ b/crates/ai-memory-llm/src/factory.rs@@ -5,7 +5,7 @@use std::sync::Arc;-use secrecy::SecretString;+use secrecy::{ExposeSecret, SecretString};use crate::AnthropicProvider;use crate::CopilotProvider;@@ -139,50 +139,41 @@ pub struct EmbedderConfig {/// Vector dimensionality. Refused on mismatch with the stored/// pages' dim.pub dim: u32,- /// API key. Required for openai/voyage/google; optional for- /// openai-compat (local engines such as Ollama run keyless).- pub api_key: Option<SecretString>,+ /// API key. An empty value selects keyless `openai-compat`; hosted+ /// providers require a non-empty key from the CLI configuration boundary.+ pub api_key: SecretString,/// Optional base URL override. Required for openai-compat.pub base_url: Option<String>,}-impl EmbedderConfig {- fn require_api_key(&self) -> LlmResult<SecretString> {- self.api_key.clone().ok_or_else(|| {- LlmError::NotConfigured(format!(- "API key required for {} embeddings",- self.provider.name()- ))- })- }-}-/// Construct an `Arc<dyn Embedder>` from the config.////// # Errors-/// Returns [`LlmError::NotConfigured`] for a missing required API key-/// or base URL; propagates HTTP-client construction errors.+/// Returns [`LlmError::NotConfigured`] for a zero dimension or missing required+/// base URL; propagates HTTP-client construction errors.pub fn build_embedder(config: EmbedderConfig) -> LlmResult<Arc<dyn Embedder>> {+ if config.dim == 0 {+ return Err(LlmError::NotConfigured(+ "AI_MEMORY_EMBEDDING_DIM must be greater than zero".into(),+ ));+ }let arc: Arc<dyn Embedder> = match config.provider {EmbedderChoice::OpenAi => {- let key = config.require_api_key()?;- let mut e = OpenAiEmbedder::new(key, config.model, config.dim)?;+ let mut e = OpenAiEmbedder::new(config.api_key, config.model, config.dim)?;if let Some(url) = config.base_url {e = e.with_base_url(url);}Arc::new(e)}EmbedderChoice::Voyage => {- let key = config.require_api_key()?;- let mut e = VoyageEmbedder::new(key, config.model, config.dim)?;+ let mut e = VoyageEmbedder::new(config.api_key, config.model, config.dim)?;if let Some(url) = config.base_url {e = e.with_base_url(url);}Arc::new(e)}EmbedderChoice::Google => {- let key = config.require_api_key()?;- let mut e = GoogleEmbedder::new(key, config.model, config.dim)?;+ let mut e = GoogleEmbedder::new(config.api_key, config.model, config.dim)?;if let Some(url) = config.base_url {e = e.with_base_url(url);}@@ -192,9 +183,10 @@ pub fn build_embedder(config: EmbedderConfig) -> LlmResult<Arc<dyn Embedder>> {let base = config.base_url.ok_or_else(|| LlmError::NotConfigured("AI_MEMORY_EMBEDDING_BASE_URL".into()))?;+ let api_key = (!config.api_key.expose_secret().is_empty()).then_some(config.api_key);Arc::new(OpenAiCompatEmbedder::new(base,- config.api_key,+ api_key,config.model,config.dim,)?)@@ -203,12 +195,19 @@ pub fn build_embedder(config: EmbedderConfig) -> LlmResult<Arc<dyn Embedder>> {Ok(arc)}-/// Default dim for known embedding models. Used when the operator-/// omits `AI_MEMORY_EMBEDDING_DIM`. Falls back to a model-family-/// default; openai-compat (unknown self-hosted models) and unknown-/// models return `None` and require an explicit dim.+/// Default dim for known embedding models. Used when the operator omits+/// `AI_MEMORY_EMBEDDING_DIM`. `openai-compat` has no safe default and returns+/// zero; new callers should use [`try_default_embedding_dim`] when accepting+/// that provider.+#[must_use]+pub fn default_embedding_dim(provider: EmbedderChoice, model: &str) -> u32 {+ try_default_embedding_dim(provider, model).unwrap_or(0)+}++/// Return the model-family embedding dimension when ai-memory has a safe+/// default. Self-hosted OpenAI-compatible models require an explicit value.#[must_use]-pub fn default_embedding_dim(provider: EmbedderChoice, model: &str) -> Option<u32> {+pub fn try_default_embedding_dim(provider: EmbedderChoice, model: &str) -> Option<u32> {match (provider, model) {(EmbedderChoice::OpenAi, "text-embedding-3-small") => Some(1536),(EmbedderChoice::OpenAi, "text-embedding-3-large") => Some(3072),diff --git a/crates/ai-memory-llm/src/lib.rs b/crates/ai-memory-llm/src/lib.rsindex 27b5a94c..a01a541a 100644--- a/crates/ai-memory-llm/src/lib.rs+++ b/crates/ai-memory-llm/src/lib.rs@@ -61,7 +61,7 @@ pub use embedding::{pub use error::{LlmError, LlmResult};pub use factory::{EmbedderChoice, EmbedderConfig, ProviderChoice, ProviderConfig, build_embedder, build_provider,- default_embedding_dim,+ default_embedding_dim, try_default_embedding_dim,};pub use gemini::GeminiProvider;pub use google::{DEFAULT_MODEL as GOOGLE_DEFAULT_EMBED_MODEL, GoogleEmbedder};diff --git a/crates/ai-memory-llm/tests/openai_compat_embedder.rs b/crates/ai-memory-llm/tests/openai_compat_embedder.rsindex 2851fbb6..ac70b128 100644--- a/crates/ai-memory-llm/tests/openai_compat_embedder.rs+++ b/crates/ai-memory-llm/tests/openai_compat_embedder.rs@@ -12,6 +12,7 @@use ai_memory_llm::{Embedder, EmbedderChoice, EmbedderConfig, LlmError, OpenAiCompatEmbedder, build_embedder,+ default_embedding_dim, try_default_embedding_dim,};use secrecy::SecretString;use serde_json::json;@@ -81,7 +82,7 @@ async fn factory_builds_compat_embedder_and_requires_base_url() {provider: EmbedderChoice::OpenAiCompat,model: "nomic-embed-text".into(),dim: 768,- api_key: None,+ api_key: SecretString::from(String::new()),base_url: Some("http://localhost:11434/v1".into()),}).expect("factory builds compat embedder");@@ -92,7 +93,7 @@ async fn factory_builds_compat_embedder_and_requires_base_url() {provider: EmbedderChoice::OpenAiCompat,model: "nomic-embed-text".into(),dim: 768,- api_key: None,+ api_key: SecretString::from(String::new()),base_url: None,}) {Ok(_) => panic!("compat embedder must not build without a base URL"),@@ -102,4 +103,28 @@ async fn factory_builds_compat_embedder_and_requires_base_url() {matches!(err, LlmError::NotConfigured(ref msg) if msg.contains("AI_MEMORY_EMBEDDING_BASE_URL")),"expected NotConfigured for missing base URL, got {err:?}");++ let zero_dim = build_embedder(EmbedderConfig {+ provider: EmbedderChoice::OpenAiCompat,+ model: "nomic-embed-text".into(),+ dim: 0,+ api_key: SecretString::from(String::new()),+ base_url: Some("http://localhost:11434/v1".into()),+ });+ assert!(+ matches!(zero_dim, Err(LlmError::NotConfigured(ref msg)) if msg.contains("greater than zero")),+ "zero-dimensional vectors must fail at the factory boundary"+ );+}++#[test]+fn existing_default_dimension_api_remains_source_compatible() {+ assert_eq!(+ default_embedding_dim(EmbedderChoice::OpenAi, "text-embedding-3-small"),+ 1536+ );+ assert_eq!(+ try_default_embedding_dim(EmbedderChoice::OpenAiCompat, "nomic-embed-text"),+ None+ );}diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 7508718f..2414bf91 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -505,14 +505,21 @@ Copilot chat endpoint.**Embedder env** (opt-in):```-AI_MEMORY_EMBEDDING_PROVIDER openai | voyage | google | gemini+AI_MEMORY_EMBEDDING_PROVIDER openai | voyage | google | gemini | openai-compatAI_MEMORY_EMBEDDING_MODEL e.g. text-embedding-3-small, gemini-embedding-001-AI_MEMORY_EMBEDDING_BASE_URL optional OpenAI-compatible embeddings endpoint-AI_MEMORY_EMBEDDING_DIM 1536 (OpenAI), 1024 (Voyage), 768 (Google)+AI_MEMORY_EMBEDDING_BASE_URL optional override; required for openai-compat+AI_MEMORY_EMBEDDING_DIM 1536 (OpenAI), 1024 (Voyage), 768 (Google);+ required explicitly for openai-compatOPENAI_API_KEY / VOYAGE_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY-LLM_API_KEY accepted for openai embeddings only with a custom base URL+LLM_API_KEY accepted for openai with a custom base URL and as+ optional bearer auth for openai-compat```+`openai-compat` also requires an explicit model because self-hosted engines have+no safe shared model or dimensionality default. It sends no authorization header+when `LLM_API_KEY` is absent and stores vectors under the distinct+`provider="openai-compat"` identity.+## Future work* **M9.5 - local embeddings via `ort`.** Bundle `bge-small-en-v1.5`diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex d0002255..64c5eb3c 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -89,7 +89,7 @@ Why not LanceDB/Qdrant/Kuzu/CozoDB/SurrealDB?## 5. Embedding & LLM**Embeddings:**-- The original prototype proposed a default local `ort` / `fastembed-rs` model. The shipped v1 posture is instead **off by default**, with opt-in OpenAI, Voyage, or Google Gemini embeddings. Local ONNX embeddings remain future work; the current provider and model reference lives in [`ARCHITECTURE.md`](ARCHITECTURE.md).+- The original prototype proposed a default local `ort` / `fastembed-rs` model. The shipped v1 posture is instead **off by default**, with opt-in OpenAI, Voyage, Google Gemini, or keyless OpenAI-compatible embeddings. The compatible path requires an explicit base URL, model, and dimension because self-hosted engines have no safe common defaults, and it uses a distinct provider identity to prevent vector-family mixing. Local ONNX embeddings remain future work; the current provider and model reference lives in [`ARCHITECTURE.md`](ARCHITECTURE.md).- Persist `{provider, model, dim}` next to every vector. On mismatch, warn and ignore stale vectors until `ai-memory embed --force` or scheduled backfill re-embeds them (agentmemory #469 lesson, without blocking startup).- Any future local model cache belongs under `<data_dir>/models/`, never `/tmp` (basic-memory #741).- The shipped provider implementations share the `Embedder` trait and are selected through typed configuration.