Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(serve): keep startup alive on embedding mismatch

AkitaOnRails789970c71ee1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index aa0d3598..16b0888d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -71,6 +71,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Docker images now bundle both POSIX and PowerShell hook scripts.
### Fixed
+- `serve` now warns and starts when stored embedding rows were created with a
+ different `(provider, model, dim)` than the current config. Hybrid search
+ ignores stale rows until `ai-memory embed --force` or scheduled backfill
+ re-embeds them, avoiding the previous startup deadlock.
- Session capture now persists every documented agent kind (`cursor`,
`gemini-cli`, `claude-desktop`, `openclaw`, `omp` / `pi`) instead of
failing the `sessions.agent_kind` database CHECK for agents added after
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index 1020f08b..9235ceeb 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -428,8 +428,8 @@ async fn configure_embedder(
store: &Store,
wiki: Wiki,
) -> Result<(Wiki, Option<Arc<dyn Embedder>>)> {
- // M9 — pluggable embedder. Refuse to start if any stored
- // embeddings disagree with the configured (provider, model, dim).
+ // M9 — pluggable embedder. Stored rows carry provider/model/dim so
+ // query paths can ignore stale vectors after an embedding config change.
let Some(cfg) = config.embedder_config()? else {
info!("AI_MEMORY_EMBEDDING_PROVIDER unset; hybrid search disabled (FTS5-only)");
return Ok((wiki, None));
@@ -444,18 +444,18 @@ async fn configure_embedder(
)
.await?;
if !mismatch.is_empty() {
- // Refuse-on-mismatch applies to hybrid search (queries only load
+ // Mismatch handling applies to hybrid search (queries only load
// rows matching the configured triple), not to process liveness.
- // Blocking startup made `embed --reembed` impossible because the
+ // Blocking startup made `embed --force` impossible because the
// CLI is an HTTP client to this server.
tracing::warn!(
stored = ?mismatch,
- configured_provider = cfg.provider.name(),
- configured_model = %cfg.model,
- configured_dim = cfg.dim,
+ configured_provider = embedder.provider(),
+ configured_model = embedder.model(),
+ configured_dim = embedder.dim(),
"stored embeddings use a different (provider, model, dim) than configured; \
hybrid search ignores stale rows until pages are re-embedded — \
- run `ai-memory embed --reembed` (or wait for scheduled backfill)"
+ run `ai-memory embed --force` (or wait for scheduled backfill)"
);
}
info!(
@@ -606,6 +606,9 @@ fn host_without_port(host: &str) -> &str {
#[cfg(test)]
mod tests {
use super::*;
+ use ai_memory_core::{PagePath, Tier};
+ use ai_memory_llm::SyntheticEmbedder;
+ use ai_memory_wiki::WritePageRequest;
use axum::http::Request;
use tempfile::TempDir;
use tower::ServiceExt;
@@ -653,4 +656,50 @@ mod tests {
assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
}
+
+ #[tokio::test]
+ async fn embedder_mismatch_warns_but_keeps_server_startable() {
+ let tmp = TempDir::new().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let ws = store
+ .writer
+ .get_or_create_workspace("default")
+ .await
+ .unwrap();
+ let proj = store
+ .writer
+ .get_or_create_project(ws, "scratch", None)
+ .await
+ .unwrap();
+
+ let synthetic: Arc<dyn Embedder> = Arc::new(SyntheticEmbedder::new(64));
+ let wiki = Wiki::new(tmp.path(), store.writer.clone())
+ .unwrap()
+ .with_embedder(synthetic);
+ wiki.write_page(WritePageRequest {
+ workspace_id: ws,
+ project_id: proj,
+ path: PagePath::new("notes/old-embedding.md").unwrap(),
+ frontmatter: serde_json::json!({"title": "old embedding"}),
+ body: "existing vector row".into(),
+ tier: Tier::Semantic,
+ pinned: false,
+ title: None,
+ })
+ .await
+ .unwrap();
+
+ let cfg = Config {
+ data_dir: tmp.path().to_path_buf(),
+ embedding_provider: Some("openai".into()),
+ runtime_env: crate::config::RuntimeEnv::with_openai_api_key_for_tests("test-key"),
+ ..Config::default()
+ };
+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
+
+ let (_wiki, embedder) = configure_embedder(&cfg, &store, wiki).await.unwrap();
+
+ let embedder = embedder.expect("configured embedder should be enabled");
+ assert_eq!(embedder.provider(), "openai");
+ }
}
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index 668f6d27..bf15931c 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -147,6 +147,14 @@ impl RuntimeEnv {
..Self::default()
}
}
+
+ #[cfg(test)]
+ pub fn with_openai_api_key_for_tests(api_key: impl Into<String>) -> Self {
+ Self {
+ openai_api_key: Some(SecretString::from(api_key.into())),
+ ..Self::default()
+ }
+ }
}
/// Accept `Vec<String>` either as a real sequence (config.toml /
diff --git a/crates/ai-memory-consolidate/tests/embeddings.rs b/crates/ai-memory-consolidate/tests/embeddings.rs
index 0d7c2a92..c868f381 100644
--- a/crates/ai-memory-consolidate/tests/embeddings.rs
+++ b/crates/ai-memory-consolidate/tests/embeddings.rs
@@ -4,7 +4,7 @@
//! 1. Writing a page through `Wiki::write_page` with an embedder
//! attached actually persists an embedding row.
//! 2. The hybrid RRF path returns sensible results.
-//! 3. The refuse-on-mismatch check flags heterogeneous
+//! 3. The mismatch diagnostic query flags heterogeneous
//! `(provider, model, dim)` triples.
//!
//! The test uses [`SyntheticEmbedder`] — a deterministic bag-of-words
@@ -92,7 +92,7 @@ async fn m9_embeddings_roundtrip_via_synthetic() {
);
}
- // 2. Refuse-on-mismatch reports stale triples.
+ // 2. Mismatch diagnostics report stale triples.
let mismatch_with_wrong_dim = store
.reader
.embedding_meta_for_mismatch(
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index ffb9d79c..a4547ac9 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -162,7 +162,7 @@ backpressure, or single-writer SQLite actor.
| `observations_fts` | FTS5 virtual table over raw observation `(title, body)`, used only as bounded fallback. |
| `links` | Wikilink / markdown cross-references with `to_page_id` nullable for unresolved forward links. |
| `handoffs` | Typed cross-agent handoff records (open / accepted / expired). |
-| `page_embeddings` | Optional vector rows for latest pages, with `(provider, model, dim)` denormalised for refuse-on-mismatch checks and missing-embedding diagnostics. |
+| `page_embeddings` | Optional vector rows for latest pages, with `(provider, model, dim)` denormalised so hybrid search can ignore stale vectors after an embedding config change and report missing-embedding diagnostics. |
| `audit_log` | Every mutation, addressable by `at DESC`. |
**Memory tiers (M8 policy):**
diff --git a/docs/deploy.md b/docs/deploy.md
index 94578fc7..a3a4b290 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -219,7 +219,7 @@ ssh "$SERVER" "tail -100 $DEPLOY_DIR/data/logs/ai-memory.log.$(date +%F)"
- **Embedding mismatch after a model change**: startup logs a warning
when stored `(provider, model, dim)` triples differ from config.
Hybrid search ignores stale rows until they are re-embedded. Start
- the server normally, then run `ai-memory embed --reembed` (or rely
+ the server normally, then run `ai-memory embed --force` (or rely
on scheduled embedding backfill if enabled).
- **Container restart loop**: check
`docker logs ai-memory` - the `ai-memory starting` line at the top
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 4d77a42b..172171af 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -218,7 +218,7 @@ Top-line rules carved into the codebase:
4. Hooks fire-and-forget (agentmemory #221, #143).
5. No background-task index-after-return; either sync or `index_status: pending` (basic-memory #763).
6. 3-tuple identity from day one (basic-memory #783/#834).
-7. Vector index records `{provider, model, dim}`; refuse on mismatch (agentmemory #469).
+7. Vector index records `{provider, model, dim}`; ignore stale vectors and warn on mismatch (agentmemory #469).
8. Embedding cache path absolute, not `/tmp` (basic-memory #741).
9. Watcher heartbeat + reconciliation pass (basic-memory #580/#758/#798).
10. Live-process check before destructive ops (basic-memory #765).