Skip to content

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

Rust

feat(status): report passive provider health

AkitaOnRails4cdfcd7de9f9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0d8b1a32..baec99b6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
+### Added
+- `ai-memory status` / `status --json` now includes passive process-scoped LLM
+ and embedding provider health based on the last real provider call, without
+ active probing or token spend ([#46]).
+
### Fixed
- Claude Code hook installs on native Windows now render Git Bash-compatible
`bash -c` commands that keep the POSIX `.sh` hook scripts and convert
diff --git a/Cargo.lock b/Cargo.lock
index 24873d8b..8fabb82c 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -152,6 +152,7 @@ dependencies = [
"anyhow",
"async-trait",
"base64",
+ "jiff",
"regex",
"reqwest",
"schemars",
diff --git a/README.md b/README.md
index 3af2f73c..d8c4d10e 100644
--- a/README.md
+++ b/README.md
@@ -78,10 +78,12 @@ priors are at the [bottom](#influences-and-prior-art).
(`pi` / `omp` aliases).
Server runs local (loopback) OR on a homelab box (LAN/VPN/cloud)
with bearer-token auth.
-- **Thin-client CLI.** `ai-memory bootstrap`, `purge-project`,
+- **Thin-client CLI.** `ai-memory status`, `bootstrap`, `purge-project`,
`rename-project`, `lint`, `embed`, `forget-sweep`, `backup` are
all HTTP clients of the running server - never touch SQLite or
- wiki files directly. Server is the single source of truth.
+ wiki files directly. `status` also reports passive LLM/embedding
+ provider health from the last real provider call. Server is the
+ single source of truth.
- **LLM is opt-in.** Zero-LLM mode still gives you FTS5 search +
rule-based summarisation. Add a provider when you want consolidated
pages and lint contradictions.
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index 610e3f43..bbe77d2f 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -5,7 +5,7 @@ use std::sync::Arc;
use ai_memory_consolidate::{Consolidator, run_lint, run_sweep};
use ai_memory_core::{ActiveProject, ProjectId, Sanitizer, WorkspaceId};
use ai_memory_hooks::{DEFAULT_HOOK_INGEST_MAX_IN_FLIGHT, HookState, hook_router};
-use ai_memory_llm::{Embedder, LlmProvider, build_embedder, build_provider};
+use ai_memory_llm::{Embedder, LlmProvider, ProviderHealth, build_embedder, build_provider};
use ai_memory_mcp::{AdminState, AiMemoryServer, admin_router};
use ai_memory_store::{EmbeddingWrite, ReaderPool, Store, WriterHandle, f32_vec_to_bytes};
use ai_memory_web;
@@ -82,7 +82,8 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
let sanitizer = Sanitizer::new(&config.sanitize)
.context("compiling sanitizer.extra_patterns from config")?;
let wiki = Wiki::new(&config.data_dir, store.writer.clone())?.with_sanitizer(sanitizer.clone());
- let (wiki, embedder) = configure_embedder(config, &store, wiki).await?;
+ let provider_health = ProviderHealth::default();
+ let (wiki, embedder) = configure_embedder(config, &store, wiki, &provider_health).await?;
// Keep the guard alive for the lifetime of `serve`.
let _watcher = start_watcher(&args, &wiki)?;
@@ -102,7 +103,8 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
if let Some(e) = embedder.clone() {
server = server.with_embedder(e);
}
- let consolidator_setup = configure_consolidator(config, server, &store, &wiki, ws, proj)?;
+ let consolidator_setup =
+ configure_consolidator(config, server, &store, &wiki, ws, proj, &provider_health)?;
let server = consolidator_setup.server;
let consolidator = consolidator_setup.consolidator;
let admin_llm = consolidator_setup.admin_llm;
@@ -183,6 +185,7 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
wiki: wiki.clone(),
llm: admin_llm,
embedder: embedder.clone(),
+ provider_health: provider_health.clone(),
decay_params: config.decay,
data_dir: config.data_dir.clone(),
db_path: store.db_path().to_path_buf(),
@@ -428,6 +431,7 @@ async fn configure_embedder(
config: &Config,
store: &Store,
wiki: Wiki,
+ provider_health: &ProviderHealth,
) -> Result<(Wiki, Option<Arc<dyn Embedder>>)> {
// M9 — pluggable embedder. Stored rows carry provider/model/dim so
// query paths can ignore stale vectors after an embedding config change.
@@ -435,6 +439,9 @@ async fn configure_embedder(
info!("AI_MEMORY_EMBEDDING_PROVIDER unset; hybrid search disabled (FTS5-only)");
return Ok((wiki, None));
};
+ let provider_name = cfg.provider.name().to_string();
+ let model = cfg.model.clone();
+ let dim = cfg.dim;
let embedder = build_embedder(cfg).context("building embedder from config")?;
let mismatch = store
.reader
@@ -465,6 +472,7 @@ async fn configure_embedder(
dim = embedder.dim(),
"embedder enabled"
);
+ let embedder = provider_health.wrap_embedder(embedder, provider_name, model, dim);
Ok((wiki.with_embedder(embedder.clone()), Some(embedder)))
}
@@ -489,6 +497,7 @@ fn configure_consolidator(
wiki: &Wiki,
workspace_id: WorkspaceId,
project_id: ProjectId,
+ provider_health: &ProviderHealth,
) -> Result<ConsolidatorSetup> {
// Build the consolidator (if LLM configured) once, then share the
// Arc between the MCP server (for `memory_consolidate` + lint),
@@ -505,7 +514,11 @@ fn configure_consolidator(
admin_llm: None,
});
};
+ let provider_name = cfg.provider.name().to_string();
+ let model = cfg.model.clone();
+ let retry_hint = llm_retry_hint(&provider_name, &model, cfg.base_url.as_deref());
let llm = build_provider(cfg).context("building LLM provider from config")?;
+ let llm = provider_health.wrap_llm_provider(llm, provider_name, model, Some(retry_hint));
info!(
provider = llm.name(),
model = llm.model(),
@@ -527,6 +540,15 @@ fn configure_consolidator(
})
}
+fn llm_retry_hint(provider: &str, model: &str, base_url: Option<&str>) -> String {
+ let mut command = format!("ai-memory llm-test --provider {provider} --model {model}");
+ if let Some(base_url) = base_url {
+ command.push_str(&format!(" --base-url {base_url}"));
+ }
+ command.push_str(" --prompt ping");
+ command
+}
+
fn mount_web_router(
router: axum::Router,
enable_web: bool,
@@ -698,9 +720,16 @@ mod tests {
};
let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
- let (_wiki, embedder) = configure_embedder(&cfg, &store, wiki).await.unwrap();
+ let provider_health = ProviderHealth::default();
+ let (_wiki, embedder) = configure_embedder(&cfg, &store, wiki, &provider_health)
+ .await
+ .unwrap();
let embedder = embedder.expect("configured embedder should be enabled");
assert_eq!(embedder.provider(), "openai");
+ assert_eq!(
+ provider_health.snapshot().embedding.status,
+ ai_memory_llm::ProviderHealthStatus::Unknown
+ );
}
}
diff --git a/crates/ai-memory-cli/src/commands/status.rs b/crates/ai-memory-cli/src/commands/status.rs
index 7a49eec2..6e00b69e 100644
--- a/crates/ai-memory-cli/src/commands/status.rs
+++ b/crates/ai-memory-cli/src/commands/status.rs
@@ -4,6 +4,7 @@
//! server; renders the response as human text or JSON. Never opens
//! the store directly — the server is the source of truth.
+use ai_memory_llm::{ProviderHealthSnapshot, ProviderHealthStatus, ProviderRoleHealthSnapshot};
use anyhow::Result;
use serde::{Deserialize, Serialize};
@@ -27,6 +28,9 @@ struct Report {
/// Derived-index diagnostics.
#[serde(default)]
derived: Derived,
+ /// Passive process-scoped provider health.
+ #[serde(default)]
+ providers: ProviderHealthSnapshot,
}
#[derive(Debug, Deserialize, Serialize)]
@@ -83,6 +87,7 @@ pub async fn run(config: &Config, args: StatusArgs) -> Result<()> {
"observations": report.counts.observations,
},
"derived": report.derived,
+ "providers": report.providers,
"client": { "server_url": ep.url, "auth": ep.auth_token.is_some() },
}))?
);
@@ -115,6 +120,113 @@ pub async fn run(config: &Config, args: StatusArgs) -> Result<()> {
report.derived.unresolved_links_from_latest_pages,
report.derived.stale_links_from_latest_pages
);
+ println!(" providers:");
+ println!(
+ " llm: {}",
+ provider_health_line(&report.providers.llm)
+ );
+ println!(
+ " embedding: {}",
+ provider_health_line(&report.providers.embedding)
+ );
+ if report.providers.llm.status == ProviderHealthStatus::Error
+ && let Some(hint) = &report.providers.llm.retry_hint
+ {
+ println!(" retry: {hint}");
+ }
}
Ok(())
}
+
+fn provider_health_line(role: &ProviderRoleHealthSnapshot) -> String {
+ match role.status {
+ ProviderHealthStatus::Disabled => "disabled".to_string(),
+ ProviderHealthStatus::Unknown => {
+ format!("{} unknown (no calls yet)", provider_label(role))
+ }
+ ProviderHealthStatus::Ok => {
+ let when = role
+ .last_call_at
+ .as_ref()
+ .map(ToString::to_string)
+ .unwrap_or_else(|| "unknown time".to_string());
+ format!("{} ok (last call: {when})", provider_label(role))
+ }
+ ProviderHealthStatus::Error => {
+ let detail = error_detail(role);
+ format!("{} error ({detail})", provider_label(role))
+ }
+ }
+}
+
+fn provider_label(role: &ProviderRoleHealthSnapshot) -> String {
+ match (&role.provider, &role.model, role.dim) {
+ (Some(provider), Some(model), Some(dim)) => format!("{provider}/{model} ({dim}d)"),
+ (Some(provider), Some(model), None) => format!("{provider}/{model}"),
+ (Some(provider), None, _) => provider.clone(),
+ _ => "provider".to_string(),
+ }
+}
+
+fn error_detail(role: &ProviderRoleHealthSnapshot) -> String {
+ let mut parts = Vec::new();
+ if let Some(status) = role.last_error_status {
+ parts.push(format!("status {status}"));
+ }
+ if let Some(message) = &role.last_error_message
+ && !message.is_empty()
+ {
+ parts.push(message.clone());
+ }
+ if let Some(when) = &role.last_error_at {
+ parts.push(format!("last error: {when}"));
+ }
+ if parts.is_empty() {
+ "last call failed".to_string()
+ } else {
+ parts.join("; ")
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use jiff::Timestamp;
+
+ #[test]
+ fn provider_health_line_renders_unknown_and_disabled() {
+ assert_eq!(
+ provider_health_line(&ProviderRoleHealthSnapshot::default()),
+ "disabled"
+ );
+
+ let role = ProviderRoleHealthSnapshot {
+ status: ProviderHealthStatus::Unknown,
+ provider: Some("openai".to_string()),
+ model: Some("gpt-5.5".to_string()),
+ ..ProviderRoleHealthSnapshot::default()
+ };
+ assert_eq!(
+ provider_health_line(&role),
+ "openai/gpt-5.5 unknown (no calls yet)"
+ );
+ }
+
+ #[test]
+ fn provider_health_line_renders_error_details() {
+ let when = "2026-05-28T12:00:00Z".parse::<Timestamp>().unwrap();
+ let role = ProviderRoleHealthSnapshot {
+ status: ProviderHealthStatus::Error,
+ provider: Some("anthropic-oauth".to_string()),
+ model: Some("claude-sonnet-4-6".to_string()),
+ last_error_at: Some(when),
+ last_error_status: Some(401),
+ last_error_message: Some("bad token".to_string()),
+ ..ProviderRoleHealthSnapshot::default()
+ };
+
+ assert!(provider_health_line(&role).contains("anthropic-oauth/claude-sonnet-4-6 error"));
+ assert!(provider_health_line(&role).contains("status 401"));
+ assert!(provider_health_line(&role).contains("bad token"));
+ }
+}
diff --git a/crates/ai-memory-llm/Cargo.toml b/crates/ai-memory-llm/Cargo.toml
index a7960e33..942a79a6 100644
--- a/crates/ai-memory-llm/Cargo.toml
+++ b/crates/ai-memory-llm/Cargo.toml
@@ -23,6 +23,7 @@ async-trait.workspace = true
regex.workspace = true
base64.workspace = true
uuid.workspace = true
+jiff.workspace = true
[dev-dependencies]
tokio = { workspace = true }
diff --git a/crates/ai-memory-llm/src/factory.rs b/crates/ai-memory-llm/src/factory.rs
index ca0c7c07..cb716270 100644
--- a/crates/ai-memory-llm/src/factory.rs
+++ b/crates/ai-memory-llm/src/factory.rs
@@ -39,6 +39,20 @@ pub enum ProviderChoice {
}
impl ProviderChoice {
+ /// Wire-format provider name.
+ #[must_use]
+ pub const fn name(self) -> &'static str {
+ match self {
+ Self::Anthropic => "anthropic",
+ Self::OpenAi => "openai",
+ Self::Gemini => "gemini",
+ Self::OpenAiCompat => "openai-compat",
+ Self::OpenAiOAuth => "openai-oauth",
+ Self::Copilot => "copilot",
+ Self::AnthropicOAuth => "anthropic-oauth",
+ }
+ }
+
/// Auth requirement for this provider.
#[must_use]
pub const fn auth_requirement(self) -> AuthRequirement {
diff --git a/crates/ai-memory-llm/src/health.rs b/crates/ai-memory-llm/src/health.rs
new file mode 100644
index 00000000..30659d19
--- /dev/null
+++ b/crates/ai-memory-llm/src/health.rs
@@ -0,0 +1,493 @@
+//! Passive provider-health recording wrappers.
+//!
+//! These wrappers never probe providers on their own. They only record
+//! the result of calls the server was already going to make.
+
+use std::sync::{Arc, Mutex};
+
+use async_trait::async_trait;
+use jiff::Timestamp;
+use serde::{Deserialize, Serialize};
+
+use crate::embedding::Embedder;
+use crate::error::{LlmError, LlmResult};
+use crate::provider::LlmProvider;
+use crate::types::{ChatRequest, ChatResponse};
+
+const MAX_ERROR_MESSAGE_CHARS: usize = 1024;
+
+/// Process-scoped health recorder for the configured provider roles.
+#[derive(Clone, Default)]
+pub struct ProviderHealth {
+ llm: ProviderRoleHealth,
+ embedding: ProviderRoleHealth,
+}
+
+impl ProviderHealth {
+ /// Return a serializable snapshot of the latest recorded state.
+ #[must_use]
+ pub fn snapshot(&self) -> ProviderHealthSnapshot {
+ ProviderHealthSnapshot {
+ llm: self.llm.snapshot(),
+ embedding: self.embedding.snapshot(),
+ }
+ }
+
+ /// Mark the LLM role as configured and wrap it with passive recording.
+ #[must_use]
+ pub fn wrap_llm_provider(
+ &self,
+ inner: Arc<dyn LlmProvider>,
+ provider: impl Into<String>,
+ model: impl Into<String>,
+ retry_hint: Option<String>,
+ ) -> Arc<dyn LlmProvider> {
+ let health = self.llm.clone();
+ health.configure(provider.into(), model.into(), None, retry_hint);
+ Arc::new(HealthRecordingLlmProvider { inner, health })
+ }
+
+ /// Mark the embedding role as configured and wrap it with passive recording.
+ #[must_use]
+ pub fn wrap_embedder(
+ &self,
+ inner: Arc<dyn Embedder>,
+ provider: impl Into<String>,
+ model: impl Into<String>,
+ dim: u32,
+ ) -> Arc<dyn Embedder> {
+ let health = self.embedding.clone();
+ health.configure(provider.into(), model.into(), Some(dim), None);
+ Arc::new(HealthRecordingEmbedder { inner, health })
+ }
+}
+
+/// Wire-format provider-health status.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum ProviderHealthStatus {
+ /// The role has no provider configured.
+ #[default]
+ Disabled,
+ /// The role is configured, but no provider call has happened in this process.
+ Unknown,
+ /// The last provider call succeeded.
+ Ok,
+ /// The last provider call failed.
+ Error,
+}
+
+/// Wire-format health snapshot for all provider roles.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct ProviderHealthSnapshot {
+ /// LLM provider role.
+ pub llm: ProviderRoleHealthSnapshot,
+ /// Embedding provider role.
+ pub embedding: ProviderRoleHealthSnapshot,
+}
+
+/// Wire-format health snapshot for one provider role.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ProviderRoleHealthSnapshot {
+ /// Current role status.
+ pub status: ProviderHealthStatus,
+ /// Configured provider label, when the role is enabled.
+ pub provider: Option<String>,
+ /// Configured model, when the role is enabled.
+ pub model: Option<String>,
+ /// Configured embedding dimensionality. Only set for the embedding role.
+ pub dim: Option<u32>,
+ /// Timestamp of the last provider call, successful or failed.
+ pub last_call_at: Option<Timestamp>,
+ /// Timestamp of the last successful provider call.
+ pub last_success_at: Option<Timestamp>,
+ /// Timestamp of the last failed provider call.
+ pub last_error_at: Option<Timestamp>,
+ /// HTTP status captured from the last error, when available.
+ pub last_error_status: Option<u16>,
+ /// Truncated message captured from the last error, when available.
+ pub last_error_message: Option<String>,
+ /// Manual retry command hint. Set only for LLM provider errors.
+ pub retry_hint: Option<String>,
+}
+
+impl Default for ProviderRoleHealthSnapshot {
+ fn default() -> Self {
+ Self {
+ status: ProviderHealthStatus::Disabled,
+ provider: None,
+ model: None,
+ dim: None,
+ last_call_at: None,
+ last_success_at: None,
+ last_error_at: None,
+ last_error_status: None,
+ last_error_message: None,
+ retry_hint: None,
+ }
+ }
+}
+
+#[derive(Clone)]
+struct ProviderRoleHealth {
+ state: Arc<Mutex<ProviderRoleState>>,
+}
+
+impl Default for ProviderRoleHealth {
+ fn default() -> Self {
+ Self {
+ state: Arc::new(Mutex::new(ProviderRoleState::disabled())),
+ }
+ }
+}
+
+impl ProviderRoleHealth {
+ fn configure(
+ &self,
+ provider: String,
+ model: String,
+ dim: Option<u32>,
+ retry_hint: Option<String>,
+ ) {
+ *self.state.lock().unwrap_or_else(|e| e.into_inner()) =
+ ProviderRoleState::configured(provider, model, dim, retry_hint);
+ }
+
+ fn snapshot(&self) -> ProviderRoleHealthSnapshot {
+ self.state
+ .lock()
+ .unwrap_or_else(|e| e.into_inner())
+ .snapshot()
+ }
+
+ fn record_result<T>(&self, result: &LlmResult<T>) {
+ match result {
+ Ok(_) => self.record_success(),
+ Err(err) => self.record_error(err),
+ }
+ }
+
+ fn record_success(&self) {
+ let now = Timestamp::now();
+ let mut state = self.state.lock().unwrap_or_else(|e| e.into_inner());
+ state.status = ProviderHealthStatus::Ok;
+ state.last_call_at = Some(now);
+ state.last_success_at = Some(now);
+ state.last_error_at = None;
+ state.last_error_status = None;
+ state.last_error_message = None;
+ }
+
+ fn record_error(&self, err: &LlmError) {
+ let now = Timestamp::now();
+ let (status, message) = error_status_and_message(err);
+ let mut state = self.state.lock().unwrap_or_else(|e| e.into_inner());
+ state.status = ProviderHealthStatus::Error;
+ state.last_call_at = Some(now);
+ state.last_error_at = Some(now);
+ state.last_error_status = status;
+ state.last_error_message = Some(message);
+ }
+}
+
+#[derive(Clone)]
+struct ProviderRoleState {
+ status: ProviderHealthStatus,
+ provider: Option<String>,
+ model: Option<String>,
+ dim: Option<u32>,
+ last_call_at: Option<Timestamp>,
+ last_success_at: Option<Timestamp>,
+ last_error_at: Option<Timestamp>,
+ last_error_status: Option<u16>,
+ last_error_message: Option<String>,
+ retry_hint: Option<String>,
+}
+
+impl ProviderRoleState {
+ fn disabled() -> Self {
+ Self {
+ status: ProviderHealthStatus::Disabled,
+ provider: None,
+ model: None,
+ dim: None,
+ last_call_at: None,
+ last_success_at: None,
+ last_error_at: None,
+ last_error_status: None,
+ last_error_message: None,
+ retry_hint: None,
+ }
+ }
+
+ fn configured(
+ provider: String,
+ model: String,
+ dim: Option<u32>,
+ retry_hint: Option<String>,
+ ) -> Self {
+ Self {
+ status: ProviderHealthStatus::Unknown,
+ provider: Some(provider),
+ model: Some(model),
+ dim,
+ last_call_at: None,
+ last_success_at: None,
+ last_error_at: None,
+ last_error_status: None,
+ last_error_message: None,
+ retry_hint,
+ }
+ }
+
+ fn snapshot(&self) -> ProviderRoleHealthSnapshot {
+ ProviderRoleHealthSnapshot {
+ status: self.status,
+ provider: self.provider.clone(),
+ model: self.model.clone(),
+ dim: self.dim,
+ last_call_at: self.last_call_at,
+ last_success_at: self.last_success_at,
+ last_error_at: self.last_error_at,
+ last_error_status: self.last_error_status,
+ last_error_message: self.last_error_message.clone(),
+ retry_hint: if self.status == ProviderHealthStatus::Error {
+ self.retry_hint.clone()
+ } else {
+ None
+ },
+ }
+ }
+}
+
+struct HealthRecordingLlmProvider {
+ inner: Arc<dyn LlmProvider>,
+ health: ProviderRoleHealth,
+}
+
+#[async_trait]
+impl LlmProvider for HealthRecordingLlmProvider {
+ fn name(&self) -> &'static str {
+ self.inner.name()
+ }
+
+ fn model(&self) -> &str {
+ self.inner.model()
+ }
+
+ async fn complete(&self, request: ChatRequest) -> LlmResult<ChatResponse> {
+ let result = self.inner.complete(request).await;
+ self.health.record_result(&result);
+ result
+ }
+
+ async fn complete_structured_raw(
+ &self,
+ request: ChatRequest,
+ schema: serde_json::Value,
+ ) -> LlmResult<serde_json::Value> {
+ let result = self.inner.complete_structured_raw(request, schema).await;
+ self.health.record_result(&result);
+ result
+ }
+}
+
+struct HealthRecordingEmbedder {
+ inner: Arc<dyn Embedder>,
+ health: ProviderRoleHealth,
+}
+
+#[async_trait]
+impl Embedder for HealthRecordingEmbedder {
+ fn provider(&self) -> &'static str {
+ self.inner.provider()
+ }
+
+ fn model(&self) -> &str {
+ self.inner.model()
+ }
+
+ fn dim(&self) -> u32 {
+ self.inner.dim()
+ }
+
+ async fn embed(&self, text: &str) -> LlmResult<Vec<f32>> {
+ let result = self.inner.embed(text).await;
+ self.health.record_result(&result);
+ result
+ }
+
+ async fn embed_document(&self, text: &str) -> LlmResult<Vec<f32>> {
+ let result = self.inner.embed_document(text).await;
+ self.health.record_result(&result);
+ result
+ }
+
+ async fn embed_query(&self, text: &str) -> LlmResult<Vec<f32>> {
+ let result = self.inner.embed_query(text).await;
+ self.health.record_result(&result);
+ result
+ }
+}
+
+fn error_status_and_message(err: &LlmError) -> (Option<u16>, String) {
+ match err {
+ LlmError::Http(e) => (
+ e.status().map(|status| status.as_u16()),
+ truncate_error_message(&e.to_string()),
+ ),
+ LlmError::Provider { status, body } => (Some(*status), truncate_error_message(body)),
+ _ => (None, truncate_error_message(&err.to_string())),
+ }
+}
+
+fn truncate_error_message(message: &str) -> String {
+ let mut chars = message.chars();
+ let truncated: String = chars.by_ref().take(MAX_ERROR_MESSAGE_CHARS).collect();
+ if chars.next().is_some() {
+ format!("{truncated}...")
+ } else {
+ truncated
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ struct FakeLlm {
+ fail: bool,
+ }
+
+ #[async_trait]
+ impl LlmProvider for FakeLlm {
+ fn name(&self) -> &'static str {
+ "fake"
+ }
+
+ fn model(&self) -> &str {
+ "fake-model"
+ }
+
+ async fn complete(&self, _request: ChatRequest) -> LlmResult<ChatResponse> {
+ if self.fail {
+ return Err(LlmError::Provider {
+ status: 401,
+ body: "bad token".to_string(),
+ });
+ }
+ Ok(ChatResponse {
+ text: "pong".to_string(),
+ usage: None,
+ model: "fake-model".to_string(),
+ })
+ }
+
+ async fn complete_structured_raw(
+ &self,
+ _request: ChatRequest,
+ _schema: serde_json::Value,
+ ) -> LlmResult<serde_json::Value> {
+ self.complete(ChatRequest::user_prompt("ping"))
+ .await
+ .map(|_| serde_json::json!({ "ok": true }))
+ }
+ }
+
+ struct TaskAwareEmbedder;
+
+ #[async_trait]
+ impl Embedder for TaskAwareEmbedder {
+ fn provider(&self) -> &'static str {
+ "google"
+ }
+
+ fn model(&self) -> &str {
+ "gemini-embedding-001"
+ }
+
+ fn dim(&self) -> u32 {
+ 2
+ }
+
+ async fn embed(&self, _text: &str) -> LlmResult<Vec<f32>> {
+ Ok(vec![0.0, 0.0])
+ }
+
+ async fn embed_document(&self, _text: &str) -> LlmResult<Vec<f32>> {
+ Ok(vec![1.0, 0.0])
+ }
+
+ async fn embed_query(&self, _text: &str) -> LlmResult<Vec<f32>> {
+ Ok(vec![0.0, 1.0])
+ }
+ }
+
+ #[tokio::test]
+ async fn llm_wrapper_records_unknown_success_and_error() {
+ let health = ProviderHealth::default();
+ let retry_hint =
+ "ai-memory llm-test --provider anthropic-oauth --model claude-sonnet-4-6 --prompt ping"
+ .to_string();
+ let llm = health.wrap_llm_provider(
+ Arc::new(FakeLlm { fail: false }),
+ "anthropic-oauth",
+ "claude-sonnet-4-6",
+ Some(retry_hint.clone()),
+ );
+
+ let before = health.snapshot().llm;
+ assert_eq!(before.status, ProviderHealthStatus::Unknown);
+ assert_eq!(before.provider.as_deref(), Some("anthropic-oauth"));
+ assert_eq!(before.model.as_deref(), Some("claude-sonnet-4-6"));
+ assert!(before.retry_hint.is_none());
+
+ llm.complete(ChatRequest::user_prompt("ping"))
+ .await
+ .unwrap();
+ let after_success = health.snapshot().llm;
+ assert_eq!(after_success.status, ProviderHealthStatus::Ok);
+ assert!(after_success.last_call_at.is_some());
+ assert!(after_success.last_success_at.is_some());
+ assert!(after_success.last_error_message.is_none());
+
+ let llm = health.wrap_llm_provider(
+ Arc::new(FakeLlm { fail: true }),
+ "anthropic-oauth",
+ "claude-sonnet-4-6",
+ Some(retry_hint.clone()),
+ );
+ let err = llm.complete(ChatRequest::user_prompt("ping")).await;
+ assert!(err.is_err());
+ let after_error = health.snapshot().llm;
+ assert_eq!(after_error.status, ProviderHealthStatus::Error);
+ assert_eq!(after_error.last_error_status, Some(401));
+ assert_eq!(after_error.last_error_message.as_deref(), Some("bad token"));
+ assert_eq!(after_error.retry_hint.as_deref(), Some(retry_hint.as_str()));
+ }
+
+ #[tokio::test]
+ async fn embedder_wrapper_records_and_preserves_task_specific_methods() {
+ let health = ProviderHealth::default();
+ let embedder = health.wrap_embedder(
+ Arc::new(TaskAwareEmbedder),
+ "google",
+ "gemini-embedding-001",
+ 2,
+ );
+
+ let before = health.snapshot().embedding;
+ assert_eq!(before.status, ProviderHealthStatus::Unknown);
+ assert_eq!(before.dim, Some(2));
+
+ assert_eq!(
+ embedder.embed_document("doc").await.unwrap(),
+ vec![1.0, 0.0]
+ );
+ assert_eq!(embedder.embed_query("query").await.unwrap(), vec![0.0, 1.0]);
+
+ let after = health.snapshot().embedding;
+ assert_eq!(after.status, ProviderHealthStatus::Ok);
+ assert!(after.last_call_at.is_some());
+ }
+}
diff --git a/crates/ai-memory-llm/src/lib.rs b/crates/ai-memory-llm/src/lib.rs
index 077f4156..1d730f9b 100644
--- a/crates/ai-memory-llm/src/lib.rs
+++ b/crates/ai-memory-llm/src/lib.rs
@@ -34,6 +34,7 @@ pub mod error;
pub mod factory;
pub mod gemini;
pub mod google;
+pub mod health;
pub mod openai;
pub mod openai_compat;
pub mod openai_oauth;
@@ -58,6 +59,9 @@ pub use factory::{
};
pub use gemini::GeminiProvider;
pub use google::{DEFAULT_MODEL as GOOGLE_DEFAULT_EMBED_MODEL, GoogleEmbedder};
+pub use health::{
+ ProviderHealth, ProviderHealthSnapshot, ProviderHealthStatus, ProviderRoleHealthSnapshot,
+};
pub use openai::OpenAiProvider;
pub use openai_compat::OpenAiCompatProvider;
pub use openai_oauth::{
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rs
index 863b5858..f6c1edc0 100644
--- a/crates/ai-memory-mcp/src/admin.rs
+++ b/crates/ai-memory-mcp/src/admin.rs
@@ -31,7 +31,7 @@ use ai_memory_consolidate::{
use ai_memory_core::{
DEFAULT_PROJECT_NAME, DEFAULT_WORKSPACE_NAME, PagePath, ProjectId, SessionId, Tier, WorkspaceId,
};
-use ai_memory_llm::{Embedder, LlmProvider};
+use ai_memory_llm::{Embedder, LlmProvider, ProviderHealth, ProviderHealthSnapshot};
use ai_memory_store::{
DecayParams, EmbeddingWrite, ReaderPool, StoreError, WriterHandle, f32_vec_to_bytes,
};
@@ -64,6 +64,8 @@ pub struct AdminState {
pub llm: Option<Arc<dyn LlmProvider>>,
/// Optional embedder. When `None`, `/admin/embed` returns 503.
pub embedder: Option<Arc<dyn Embedder>>,
+ /// Passive process-scoped health recorder for configured providers.
+ pub provider_health: ProviderHealth,
/// Retention-decay parameters forwarded from server config.
pub decay_params: DecayParams,
/// Server's resolved data directory (e.g. `/data` in the docker
@@ -251,6 +253,8 @@ pub struct StatusReport {
pub counts: ai_memory_store::StatusCounts,
/// Derived-index and retrieval-readiness diagnostics.
pub derived: ai_memory_store::DerivedIndexStatus,
+ /// Passive process-scoped provider health.
+ pub providers: ProviderHealthSnapshot,
}
async fn handle_status(State(state): State<Arc<AdminState>>) -> impl IntoResponse {
@@ -264,6 +268,7 @@ async fn handle_status(State(state): State<Arc<AdminState>>) -> impl IntoRespons
db_path: state.db_path.display().to_string(),
counts,
derived,
+ providers: state.provider_health.snapshot(),
};
(
StatusCode::OK,
@@ -1502,3 +1507,49 @@ async fn handle_write_page(
),
))
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use ai_memory_store::Store;
+ use axum::body::to_bytes;
+ use axum::http::Request;
+ use tempfile::TempDir;
+ use tower::ServiceExt;
+
+ #[tokio::test]
+ async fn status_reports_provider_health_block() {
+ let tmp = TempDir::new().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
+ let router = admin_router(AdminState {
+ writer: store.writer.clone(),
+ reader: store.reader.clone(),
+ wiki,
+ llm: None,
+ embedder: None,
+ provider_health: ProviderHealth::default(),
+ decay_params: DecayParams::default(),
+ data_dir: tmp.path().to_path_buf(),
+ db_path: store.db_path().to_path_buf(),
+ bind: "127.0.0.1:49374".to_string(),
+ bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
+ });
+
+ let resp = router
+ .oneshot(
+ Request::builder()
+ .uri("/admin/status")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+
+ assert_eq!(resp.status(), StatusCode::OK);
+ let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
+ let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
+ assert_eq!(json["providers"]["llm"]["status"], "disabled");
+ assert_eq!(json["providers"]["embedding"]["status"], "disabled");
+ }
+}
diff --git a/crates/ai-memory-mcp/tests/admin_backup.rs b/crates/ai-memory-mcp/tests/admin_backup.rs
index 39a4d35f..787ac431 100644
--- a/crates/ai-memory-mcp/tests/admin_backup.rs
+++ b/crates/ai-memory-mcp/tests/admin_backup.rs
@@ -29,6 +29,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
wiki,
llm: None,
embedder: None,
+ provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
data_dir: tmp.path().to_path_buf(),
db_path,
diff --git a/crates/ai-memory-mcp/tests/admin_bootstrap.rs b/crates/ai-memory-mcp/tests/admin_bootstrap.rs
index 6802224e..64894964 100644
--- a/crates/ai-memory-mcp/tests/admin_bootstrap.rs
+++ b/crates/ai-memory-mcp/tests/admin_bootstrap.rs
@@ -26,6 +26,7 @@ async fn make_admin_state(tmp: &TempDir) -> AdminState {
wiki,
llm: None, // no LLM — dry-run path only
embedder: None,
+ provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
data_dir: tmp.path().to_path_buf(),
db_path,
diff --git a/crates/ai-memory-mcp/tests/admin_phase3.rs b/crates/ai-memory-mcp/tests/admin_phase3.rs
index 0553c68c..0cf1a250 100644
--- a/crates/ai-memory-mcp/tests/admin_phase3.rs
+++ b/crates/ai-memory-mcp/tests/admin_phase3.rs
@@ -37,6 +37,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
wiki,
llm: None,
embedder: None,
+ provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
data_dir: tmp.path().to_path_buf(),
db_path,
diff --git a/crates/ai-memory-mcp/tests/admin_purge.rs b/crates/ai-memory-mcp/tests/admin_purge.rs
index 2db54f8d..c84f7e38 100644
--- a/crates/ai-memory-mcp/tests/admin_purge.rs
+++ b/crates/ai-memory-mcp/tests/admin_purge.rs
@@ -31,6 +31,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
wiki,
llm: None,
embedder: None,
+ provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
data_dir: tmp.path().to_path_buf(),
bind: "127.0.0.1:0".to_string(),
@@ -341,6 +342,7 @@ async fn purge_project_idempotent_second_call_is_404() {
wiki: state_a.wiki.clone(),
llm: None,
embedder: None,
+ provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
diff --git a/crates/ai-memory-mcp/tests/admin_rename.rs b/crates/ai-memory-mcp/tests/admin_rename.rs
index 809cf334..6d5d01fb 100644
--- a/crates/ai-memory-mcp/tests/admin_rename.rs
+++ b/crates/ai-memory-mcp/tests/admin_rename.rs
@@ -28,6 +28,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
wiki,
llm: None,
embedder: None,
+ provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
data_dir: tmp.path().to_path_buf(),
db_path,
@@ -306,6 +307,7 @@ async fn rename_project_pages_still_searchable() {
wiki: state.wiki.clone(),
llm: None,
embedder: None,
+ provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
diff --git a/crates/ai-memory-mcp/tests/admin_status_search.rs b/crates/ai-memory-mcp/tests/admin_status_search.rs
index 758cbaa6..e809f4ae 100644
--- a/crates/ai-memory-mcp/tests/admin_status_search.rs
+++ b/crates/ai-memory-mcp/tests/admin_status_search.rs
@@ -23,6 +23,7 @@ async fn make_admin_state(tmp: &TempDir) -> (AdminState, Store) {
wiki,
llm: None,
embedder: None,
+ provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
data_dir: tmp.path().to_path_buf(),
db_path,
diff --git a/crates/ai-memory-mcp/tests/admin_write_page.rs b/crates/ai-memory-mcp/tests/admin_write_page.rs
index 027a7be8..6f75541c 100644
--- a/crates/ai-memory-mcp/tests/admin_write_page.rs
+++ b/crates/ai-memory-mcp/tests/admin_write_page.rs
@@ -23,6 +23,7 @@ async fn make_state(tmp: &TempDir) -> AdminState {
wiki,
llm: None,
embedder: None,
+ provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
data_dir: tmp.path().to_path_buf(),
db_path,
diff --git a/docs/deploy.md b/docs/deploy.md
index 5832763b..1e978239 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -237,6 +237,10 @@ ssh "$SERVER" "tail -100 $DEPLOY_DIR/data/logs/ai-memory.log.$(date +%F)"
every project in the workspace, or add `--project <name>` to scope
the rebuild. Scheduled embedding backfill can also fill missing
rows when enabled.
+- **Provider failures**: `ai-memory status` reports passive LLM and
+ embedding health from the last real provider call. A fresh process
+ reports `unknown` until the server actually uses that role; it does
+ not probe providers or spend tokens for health reporting.
- **Container restart loop**: check
`docker logs ai-memory` - the `ai-memory starting` line at the top
reports the resolved config; a missing required env var (e.g.
diff --git a/docs/install.md b/docs/install.md
index 42b151ec..2e1da430 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -831,7 +831,7 @@ docker run --rm akitaonrails/ai-memory:latest --help # full subcommand tree
| Subcommand | Pattern | What it does |
|---|---|---|
| `serve` | `docker compose up -d` (already done) | Run the HTTP MCP server |
-| `status` | `docker exec` | Counts, paths, and derived-index diagnostics |
+| `status` | `docker exec` | Counts, paths, derived-index diagnostics, and passive LLM/embedding provider health |
| `search "<query>"` | `docker exec` | Wiki search with FTS5 + graph/vector RRF |
| `write-page` | `docker exec` | Manual page write (atomic + indexed) |
| `backup --to` / `restore --from` | `docker exec` | Snapshot or restore the data dir |