Skip to content

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.rs
index 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,
..cfg
diff --git a/crates/ai-memory-llm/src/factory.rs b/crates/ai-memory-llm/src/factory.rs
index 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.rs
index 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.rs
index 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.md
index 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-compat
AI_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-compat
OPENAI_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.md
index 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.