Skip to content

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

Rust

feat(doctor): report a dead server, a full spool and skipped Codex hooks

AkitaOnRails980b3455da07
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5ec93910..ca02cdb1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- `ai-memory doctor` now reports three silent capture failures: an unreachable
+ server (reported instead of aborting the check), a hook spool that is full and
+ evicting undelivered events, and installed ai-memory Codex hooks that Codex
+ skips because they are untrusted or changed since they were trusted (asked
+ of Codex itself through `codex app-server`). `ai-memory status` no longer says
+ queued events will be delivered once the spool has started evicting them.
- Added two-way sync to the `ai-memory-wikisync` companion (#986, slice 3):
`sync` imports repository edits and new pages through the public
`memory_write_page` MCP tool and exports server edits, comparing each
diff --git a/crates/ai-memory-cli/src/commands/codex_hook_trust.rs b/crates/ai-memory-cli/src/commands/codex_hook_trust.rs
new file mode 100644
index 00000000..92741349
--- /dev/null
+++ b/crates/ai-memory-cli/src/commands/codex_hook_trust.rs
@@ -0,0 +1,202 @@
+//! Whether Codex will actually run ai-memory's hooks.
+//!
+//! Codex runs a non-managed hook only after the user trusts it, and records
+//! that trust against a hash of the hook's event, matcher and command. A hook
+//! that was never trusted, or whose command changed after it was (a new
+//! binary path, data dir or server URL), is skipped without any message, so
+//! every Codex session goes uncaptured while `doctor`'s coverage table only
+//! shows the symptom. Codex itself is the authority on the hash, so this asks
+//! it — `codex app-server`'s `hooks/list` — instead of re-deriving it.
+
+use std::path::Path;
+use std::process::Stdio;
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
+
+/// How long Codex gets to start and answer before the probe gives up.
+const PROBE_TIMEOUT: Duration = Duration::from_secs(15);
+
+/// The trust state of the ai-memory hooks in one Codex hooks file.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub(crate) struct CodexHookTrust {
+ /// Event names (`sessionStart`, ...) of ai-memory hooks Codex will run.
+ pub(crate) trusted: Vec<String>,
+ /// Event names of ai-memory hooks Codex skips, with the reason Codex gives
+ /// (`untrusted` or `modified`).
+ pub(crate) skipped: Vec<(String, String)>,
+}
+
+#[derive(Deserialize)]
+struct ListResponse {
+ data: Vec<ListEntry>,
+}
+
+#[derive(Deserialize)]
+struct ListEntry {
+ hooks: Vec<HookMetadata>,
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct HookMetadata {
+ event_name: String,
+ trust_status: String,
+ source_path: String,
+ #[serde(default)]
+ command: Option<String>,
+}
+
+/// Ask `codex` (the program at `program`) for the trust state of the
+/// ai-memory hooks in `hooks_file`. `None` when Codex is not installed, does
+/// not answer in time, speaks a protocol this does not understand, or lists
+/// no ai-memory hook in that file — the caller reports the state as unknown.
+pub(crate) async fn probe(program: &Path, hooks_file: &Path, cwd: &Path) -> Option<CodexHookTrust> {
+ let result = tokio::time::timeout(PROBE_TIMEOUT, list_hooks(program, cwd)).await;
+ let response = result.ok()??;
+ summarize(&response, hooks_file)
+}
+
+async fn list_hooks(program: &Path, cwd: &Path) -> Option<serde_json::Value> {
+ let mut child = tokio::process::Command::new(program)
+ .arg("app-server")
+ .current_dir(cwd)
+ .stdin(Stdio::piped())
+ .stdout(Stdio::piped())
+ .stderr(Stdio::null())
+ .kill_on_drop(true)
+ .spawn()
+ .ok()?;
+ let mut stdin = child.stdin.take()?;
+ let stdout = child.stdout.take()?;
+ let cwd = cwd.to_string_lossy();
+ let requests = [
+ serde_json::json!({"jsonrpc": "2.0", "id": 1, "method": "initialize",
+ "params": {"clientInfo": {"name": "ai-memory-doctor", "version": env!("CARGO_PKG_VERSION")}}}),
+ serde_json::json!({"jsonrpc": "2.0", "method": "initialized"}),
+ serde_json::json!({"jsonrpc": "2.0", "id": 2, "method": "hooks/list",
+ "params": {"cwds": [cwd]}}),
+ ];
+ for request in requests {
+ let mut line = request.to_string();
+ line.push('\n');
+ stdin.write_all(line.as_bytes()).await.ok()?;
+ }
+ stdin.flush().await.ok()?;
+ let mut lines = BufReader::new(stdout).lines();
+ while let Ok(Some(line)) = lines.next_line().await {
+ let Ok(message) = serde_json::from_str::<serde_json::Value>(&line) else {
+ continue;
+ };
+ if message.get("id") == Some(&serde_json::json!(2)) {
+ return message.get("result").cloned();
+ }
+ }
+ None
+}
+
+/// The trust state of the ai-memory hooks `hooks_file` declares, from a
+/// `hooks/list` result. A hook is ai-memory's when its command runs
+/// `ai-memory ... hook --event ...`, the form `install-hooks` writes.
+fn summarize(result: &serde_json::Value, hooks_file: &Path) -> Option<CodexHookTrust> {
+ let response = serde_json::from_value::<ListResponse>(result.clone()).ok()?;
+ let mut trust = CodexHookTrust {
+ trusted: Vec::new(),
+ skipped: Vec::new(),
+ };
+ for hook in response.data.into_iter().flat_map(|entry| entry.hooks) {
+ let ours = hook.command.as_deref().is_some_and(|command| {
+ command.contains("ai-memory") && command.contains(" hook --event ")
+ });
+ if !ours || Path::new(&hook.source_path) != hooks_file {
+ continue;
+ }
+ match hook.trust_status.as_str() {
+ "trusted" | "managed" => trust.trusted.push(hook.event_name),
+ other => trust.skipped.push((hook.event_name, other.to_owned())),
+ }
+ }
+ (!trust.trusted.is_empty() || !trust.skipped.is_empty()).then_some(trust)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn hook(event: &str, status: &str, source: &str, command: &str) -> serde_json::Value {
+ serde_json::json!({
+ "eventName": event, "trustStatus": status, "sourcePath": source,
+ "handlerType": "command", "command": command, "currentHash": "sha256:x",
+ })
+ }
+
+ #[test]
+ fn summarizes_only_ai_memory_hooks_from_the_installed_file() {
+ let file = "/home/me/.codex/hooks.json";
+ let ours = "/home/me/.local/share/ai-memory/native-runner/ai-memory --data-dir /d hook --event session-start --agent codex";
+ let result = serde_json::json!({"data": [{"cwd": "/repo", "warnings": [], "errors": [], "hooks": [
+ hook("sessionStart", "trusted", file, ours),
+ hook("stop", "modified", file, ours),
+ hook("preToolUse", "untrusted", file, ours),
+ hook("postToolUse", "untrusted", file, "/usr/bin/other-tool --check"),
+ hook("userPromptSubmit", "untrusted", "/repo/.codex/hooks.json", ours),
+ ]}]});
+ let trust = summarize(&result, Path::new(file)).unwrap();
+ assert_eq!(trust.trusted, vec!["sessionStart"]);
+ assert_eq!(
+ trust.skipped,
+ vec![
+ ("stop".to_owned(), "modified".to_owned()),
+ ("preToolUse".to_owned(), "untrusted".to_owned()),
+ ]
+ );
+ }
+
+ #[test]
+ fn no_ai_memory_hook_or_an_unknown_shape_is_unknown() {
+ let file = Path::new("/home/me/.codex/hooks.json");
+ let other = serde_json::json!({"data": [{"hooks": [
+ hook("stop", "untrusted", "/home/me/.codex/hooks.json", "/usr/bin/other-tool"),
+ ]}]});
+ assert_eq!(summarize(&other, file), None);
+ assert_eq!(
+ summarize(&serde_json::json!({"unexpected": true}), file),
+ None
+ );
+ }
+
+ /// The probe drives a real process over stdio: a stand-in `codex` that
+ /// answers `hooks/list` proves the request sequence and the reply parse.
+ #[cfg(unix)]
+ #[tokio::test]
+ async fn probe_reads_hooks_list_from_the_app_server() {
+ use std::os::unix::fs::PermissionsExt;
+ let temp = tempfile::tempdir().unwrap();
+ let hooks_file = temp.path().join("hooks.json");
+ let reply = serde_json::json!({"jsonrpc": "2.0", "id": 2, "result": {"data": [{"hooks": [
+ hook("sessionStart", "modified", &hooks_file.to_string_lossy(),
+ "ai-memory hook --event session-start --agent codex"),
+ ]}]}});
+ let fake = temp.path().join("codex");
+ std::fs::write(
+ &fake,
+ format!(
+ "#!/bin/sh\n[ \"$1\" = app-server ] || exit 2\nread -r _init\nread -r _ready\nread -r list\ncase \"$list\" in *hooks/list*) ;; *) exit 3 ;; esac\necho '{{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{{}}}}'\necho '{reply}'\n"
+ ),
+ )
+ .unwrap();
+ std::fs::set_permissions(&fake, std::fs::Permissions::from_mode(0o755)).unwrap();
+
+ let trust = probe(&fake, &hooks_file, temp.path()).await.unwrap();
+ assert!(trust.trusted.is_empty());
+ assert_eq!(
+ trust.skipped,
+ vec![("sessionStart".to_owned(), "modified".to_owned())]
+ );
+ assert_eq!(
+ probe(&temp.path().join("missing"), &hooks_file, temp.path()).await,
+ None
+ );
+ }
+}
diff --git a/crates/ai-memory-cli/src/commands/doctor.rs b/crates/ai-memory-cli/src/commands/doctor.rs
index 40d099f4..e4b9fac4 100644
--- a/crates/ai-memory-cli/src/commands/doctor.rs
+++ b/crates/ai-memory-cli/src/commands/doctor.rs
@@ -169,6 +169,16 @@ struct DoctorReport {
/// #1003). Only Claude Code's location is known today; harnesses with no
/// established convention are simply absent from this list.
native_memory: Vec<NativeMemoryReport>,
+ /// The local hook spool: events waiting for the server, and whether it is
+ /// full and evicting undelivered ones.
+ spool: super::hook_spool::SpoolHealth,
+ /// Nothing answered at the server URL; capture counts are unavailable and
+ /// hook events are being spooled.
+ server_unreachable: bool,
+ /// Whether Codex will run the installed ai-memory hooks, from Codex
+ /// itself. `None` when no ai-memory Codex hook is installed or Codex could
+ /// not be asked.
+ codex_hooks: Option<super::codex_hook_trust::CodexHookTrust>,
}
#[derive(Debug, Clone, Serialize)]
@@ -497,6 +507,8 @@ pub async fn run(config: &Config, args: crate::cli::DoctorArgs) -> Result<()> {
)
.await,
);
+ let spool = super::hook_spool::spool_health(&super::hook_spool::spool_dir(&config.data_dir));
+ let mut server_unreachable = false;
let mut capture_coverage_problem = None;
let captured = match get_json::<ByAgentResponse>(
&ep,
@@ -510,6 +522,13 @@ pub async fn run(config: &Config, args: crate::cli::DoctorArgs) -> Result<()> {
{
Ok(response) => response.by_agent,
Err(error) if super::is_scope_not_found(&error) => Vec::new(),
+ Err(error) if crate::http_client::server_unreachable(&error) => {
+ server_unreachable = true;
+ capture_coverage_problem = Some(CaptureCoverageProblem {
+ reason: "the server did not answer; captured counts are unavailable".to_owned(),
+ });
+ Vec::new()
+ }
Err(error) if super::is_scope_ambiguous(&error) => {
capture_coverage_problem = Some(CaptureCoverageProblem {
reason: "server scope is ambiguous; captured counts are unavailable".to_owned(),
@@ -554,6 +573,7 @@ pub async fn run(config: &Config, args: crate::cli::DoctorArgs) -> Result<()> {
});
let native_memory = native_memory_reports(&home, &cwd);
+ let codex_hooks = codex_hook_trust(&cwd).await;
let report = DoctorReport {
workspace,
@@ -568,6 +588,9 @@ pub async fn run(config: &Config, args: crate::cli::DoctorArgs) -> Result<()> {
identity,
project_coordinate,
native_memory,
+ spool,
+ server_unreachable,
+ codex_hooks,
};
if args.json {
@@ -578,6 +601,75 @@ pub async fn run(config: &Config, args: crate::cli::DoctorArgs) -> Result<()> {
Ok(())
}
+/// The trust state of the installed ai-memory Codex hooks, when there are
+/// any: asking Codex starts it, so a machine without ai-memory's Codex hooks
+/// is left alone.
+async fn codex_hook_trust(cwd: &Path) -> Option<super::codex_hook_trust::CodexHookTrust> {
+ let hooks_file = super::install_hooks::codex_hooks_path().ok()?;
+ let installed = std::fs::read_to_string(&hooks_file).ok()?;
+ if !installed.contains("ai-memory") {
+ return None;
+ }
+ super::codex_hook_trust::probe(Path::new("codex"), &hooks_file, cwd).await
+}
+
+/// Human lines for the spool, the server and the Codex hook trust; empty
+/// when there is nothing to warn about.
+fn render_capture_health(report: &DoctorReport) -> String {
+ let mut out = String::new();
+ if report.server_unreachable {
+ out.push_str(&format!(
+ "⚠ The server at {} did not answer. Hook events are being spooled locally.\n",
+ report.server
+ ));
+ }
+ let spool = &report.spool;
+ if spool.evicting() {
+ out.push_str(&format!(
+ "⚠ The hook spool is full ({} events, oldest {}): each new event evicts the \
+ oldest undelivered one, which is lost until the server is back.\n",
+ spool.pending,
+ spool_age(spool.oldest_age_ms),
+ ));
+ } else if spool.pending > 0 {
+ out.push_str(&format!(
+ " hook spool: {} event(s) waiting for the server (oldest {}).\n",
+ spool.pending,
+ spool_age(spool.oldest_age_ms),
+ ));
+ }
+ if let Some(trust) = &report.codex_hooks
+ && !trust.skipped.is_empty()
+ {
+ let skipped: Vec<String> = trust
+ .skipped
+ .iter()
+ .map(|(event, status)| format!("{event} ({status})"))
+ .collect();
+ out.push_str(&format!(
+ "⚠ Codex skips {} ai-memory hook(s): {}. Codex runs a hook only after you \
+ trust it, and again after its command changes. Open Codex, run /hooks, and \
+ trust them; until then Codex sessions are not captured.\n",
+ trust.skipped.len(),
+ skipped.join(", "),
+ ));
+ }
+ out
+}
+
+fn spool_age(age_ms: Option<u64>) -> String {
+ let Some(ms) = age_ms else {
+ return "n/a".to_owned();
+ };
+ let secs = ms / 1000;
+ match secs {
+ 0..60 => format!("{secs}s"),
+ 60..3600 => format!("{}m", secs / 60),
+ 3600..86_400 => format!("{}h", secs / 3600),
+ _ => format!("{}d", secs / 86_400),
+ }
+}
+
fn render_project_coordinate(coordinate: &ProjectCoordinateReport) -> String {
use std::fmt::Write as _;
let mut output = String::new();
@@ -662,6 +754,7 @@ fn render_human(report: &DoctorReport) {
if let Some(problem) = &report.capture_coverage_problem {
println!(" capture coverage: unavailable ({})", problem.reason);
}
+ print!("{}", render_capture_health(report));
if report.since_days == 0 {
println!(" recent window: all on-disk sessions\n");
} else {
@@ -765,6 +858,78 @@ fn render_human(report: &DoctorReport) {
mod tests {
use super::*;
+ fn health_report(
+ spool: super::super::hook_spool::SpoolHealth,
+ server_unreachable: bool,
+ codex_hooks: Option<super::super::codex_hook_trust::CodexHookTrust>,
+ ) -> DoctorReport {
+ DoctorReport {
+ workspace: "ws".into(),
+ project: "proj".into(),
+ server: "http://192.0.2.1:49374".into(),
+ since_days: 7,
+ rows: Vec::new(),
+ capture_coverage_problem: None,
+ uncaptured: Vec::new(),
+ marker_capture_problem: None,
+ capture_owner_active: false,
+ identity: None,
+ project_coordinate: None,
+ native_memory: Vec::new(),
+ spool,
+ server_unreachable,
+ codex_hooks,
+ }
+ }
+
+ /// A dead server, a full spool and Codex hooks Codex skips are each silent
+ /// today; doctor names every one, and stays quiet when all is well.
+ #[test]
+ fn capture_health_names_silent_failures() {
+ use super::super::codex_hook_trust::CodexHookTrust;
+ use super::super::hook_spool::SpoolHealth;
+ let full = SpoolHealth {
+ pending: 10_000,
+ oldest_age_ms: Some(30 * 3600 * 1000),
+ retries_total: 0,
+ capacity: 10_000,
+ };
+ let skipped = CodexHookTrust {
+ trusted: vec!["sessionStart".into()],
+ skipped: vec![("stop".into(), "modified".into())],
+ };
+ let out = render_capture_health(&health_report(full, true, Some(skipped)));
+ assert!(out.contains("did not answer"), "{out}");
+ assert!(
+ out.contains("spool is full (10000 events, oldest 1d)"),
+ "{out}"
+ );
+ assert!(
+ out.contains("Codex skips 1 ai-memory hook(s): stop (modified)"),
+ "{out}"
+ );
+
+ let waiting = SpoolHealth {
+ pending: 4,
+ oldest_age_ms: Some(90_000),
+ retries_total: 1,
+ capacity: 10_000,
+ };
+ let out = render_capture_health(&health_report(waiting, false, None));
+ assert_eq!(
+ out,
+ " hook spool: 4 event(s) waiting for the server (oldest 1m).\n"
+ );
+
+ let trusted = CodexHookTrust {
+ trusted: vec!["sessionStart".into()],
+ skipped: Vec::new(),
+ };
+ let quiet =
+ render_capture_health(&health_report(SpoolHealth::default(), false, Some(trusted)));
+ assert_eq!(quiet, "");
+ }
+
fn server_coordinate(
status: ai_memory_store::ProjectCoordinateStatus,
collision_reason: Option<ai_memory_store::ProjectCoordinateCollisionReason>,
diff --git a/crates/ai-memory-cli/src/commands/hook_spool.rs b/crates/ai-memory-cli/src/commands/hook_spool.rs
index 73816322..200cf7cb 100644
--- a/crates/ai-memory-cli/src/commands/hook_spool.rs
+++ b/crates/ai-memory-cli/src/commands/hook_spool.rs
@@ -149,7 +149,7 @@ pub fn spool_len(spool: &Path) -> usize {
/// Deliberately content-free: counts, ages, and attempt sums only — never
/// payload excerpts, URLs, or token material (the spool holds private capture
/// until it drains).
-#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct SpoolHealth {
/// Events queued locally awaiting delivery.
pub pending: usize,
@@ -157,6 +157,28 @@ pub struct SpoolHealth {
pub oldest_age_ms: Option<u64>,
/// Sum of failed-delivery attempts across all queued events.
pub retries_total: u64,
+ /// Most events the spool holds; past it the oldest undelivered ones are
+ /// evicted to make room.
+ pub capacity: usize,
+}
+
+impl Default for SpoolHealth {
+ fn default() -> Self {
+ Self {
+ pending: 0,
+ oldest_age_ms: None,
+ retries_total: 0,
+ capacity: MAX_SPOOL_FILES,
+ }
+ }
+}
+
+impl SpoolHealth {
+ /// The spool is full, so each new event evicts the oldest undelivered one.
+ #[must_use]
+ pub fn evicting(&self) -> bool {
+ self.pending >= self.capacity
+ }
}
/// Snapshot local spool health: queued count and oldest-event age from the
@@ -200,7 +222,7 @@ pub fn spool_health(spool: &Path) -> SpoolHealth {
let mut health = SpoolHealth {
pending: files.len(),
oldest_age_ms: Some(now.saturating_sub(oldest_created)),
- retries_total: 0,
+ ..SpoolHealth::default()
};
for (_, path) in &files {
if let Ok(bytes) = read_spool_entry_bytes(path)
diff --git a/crates/ai-memory-cli/src/commands/mod.rs b/crates/ai-memory-cli/src/commands/mod.rs
index 6f07049c..7e1e95b0 100644
--- a/crates/ai-memory-cli/src/commands/mod.rs
+++ b/crates/ai-memory-cli/src/commands/mod.rs
@@ -37,6 +37,7 @@ pub mod backup;
pub mod backup_agents;
pub mod bootstrap;
pub mod checkpoints;
+pub mod codex_hook_trust;
pub mod commit;
pub mod compact;
pub mod completions;
diff --git a/crates/ai-memory-cli/src/commands/run.rs b/crates/ai-memory-cli/src/commands/run.rs
index ed69d58e..2b52255e 100644
--- a/crates/ai-memory-cli/src/commands/run.rs
+++ b/crates/ai-memory-cli/src/commands/run.rs
@@ -6951,12 +6951,14 @@ mod tests {
pending: 3,
oldest_age_ms: Some(45_000),
retries_total: 1,
+ ..SpoolHealth::default()
});
assert_eq!(note, "3 hook events remain spooled locally (oldest 45s)");
let one = spooled_events_note(&SpoolHealth {
pending: 1,
oldest_age_ms: Some(0),
retries_total: 0,
+ ..SpoolHealth::default()
});
assert_eq!(one, "1 hook event remains spooled locally (oldest 0s)");
}
diff --git a/crates/ai-memory-cli/src/commands/status.rs b/crates/ai-memory-cli/src/commands/status.rs
index c435d9c5..4f7a0d49 100644
--- a/crates/ai-memory-cli/src/commands/status.rs
+++ b/crates/ai-memory-cli/src/commands/status.rs
@@ -179,7 +179,13 @@ fn report_offline_spool(spool: &SpoolHealth, json: bool) {
eprintln!(" pending: {}", spool.pending);
eprintln!(" oldest: {}", spool_age_line(spool.oldest_age_ms));
eprintln!(" retries: {}", spool.retries_total);
- if spool.pending > 0 {
+ if spool.evicting() {
+ eprintln!(
+ " The spool is full ({} events): each new event evicts the oldest \
+ undelivered one, which is lost. Bring the server back to stop the loss.",
+ spool.capacity
+ );
+ } else if spool.pending > 0 {
eprintln!(
" {} event(s) are queued locally and will be delivered once the \
server is reachable again.",
@@ -690,17 +696,21 @@ mod tests {
pending: 2,
oldest_age_ms: Some(900_000),
retries_total: 4,
+ ..SpoolHealth::default()
};
let rendered = serde_json::to_string(&spool).expect("SpoolHealth serialises");
assert_eq!(
rendered,
- r#"{"pending":2,"oldest_age_ms":900000,"retries_total":4}"#
+ r#"{"pending":2,"oldest_age_ms":900000,"retries_total":4,"capacity":3}"#
);
// The shape is the contract: counts and ages only. If a field
// carrying captured text is ever added, this fails loudly.
let value: serde_json::Value = serde_json::from_str(&rendered).unwrap();
let keys: Vec<_> = value.as_object().unwrap().keys().cloned().collect();
- assert_eq!(keys, vec!["pending", "oldest_age_ms", "retries_total"]);
+ assert_eq!(
+ keys,
+ vec!["pending", "oldest_age_ms", "retries_total", "capacity"]
+ );
// Both render paths must tolerate an empty spool.
report_offline_spool(&SpoolHealth::default(), false);
diff --git a/crates/ai-memory-cli/src/http_client.rs b/crates/ai-memory-cli/src/http_client.rs
index 78c15992..44bdf9f3 100644
--- a/crates/ai-memory-cli/src/http_client.rs
+++ b/crates/ai-memory-cli/src/http_client.rs
@@ -432,6 +432,15 @@ pub(crate) fn augment_connect_error(
}
}
+/// Whether a request failed because nothing answered — a refused connection
+/// or a timeout — rather than because the server answered with an error.
+pub(crate) fn server_unreachable(err: &anyhow::Error) -> bool {
+ let answered = err
+ .chain()
+ .any(|cause| cause.downcast_ref::<ServerResponseError>().is_some());
+ !answered && err.chain().any(error_chain_indicates_no_answer)
+}
+
/// Whether an error chain means "nothing answered at the transport
/// layer": reqwest classified it as a connect-phase or timeout failure,
/// or a `ConnectionRefused`/`TimedOut` io::Error — or its platform
@@ -559,6 +568,24 @@ mod tests {
use super::*;
+ #[test]
+ fn only_an_unanswered_request_is_unreachable() {
+ let refused =
+ anyhow::Error::new(std::io::Error::from(std::io::ErrorKind::ConnectionRefused))
+ .context("HTTP request to http://127.0.0.1:1/admin/status failed");
+ assert!(server_unreachable(&refused));
+ let answered = server_response_error_for_test(
+ reqwest::Method::GET,
+ "/admin/status",
+ reqwest::StatusCode::SERVICE_UNAVAILABLE,
+ "down for maintenance".to_owned(),
+ );
+ assert!(!server_unreachable(&answered));
+ assert!(!server_unreachable(&anyhow::anyhow!(
+ "malformed response body"
+ )));
+ }
+
#[cfg(unix)]
#[test]
fn downloaded_backup_output_is_private_when_created() {
diff --git a/docs/cookbook.md b/docs/cookbook.md
index d5c0551c..56b8ea7e 100644
--- a/docs/cookbook.md
+++ b/docs/cookbook.md
@@ -458,6 +458,13 @@ ai-memory serve # run the server
and is not reported. An `excluded` verdict applies only to native/generated
hooks; shell and PowerShell compatibility hooks do not enforce capture-policy
exclusions.
+- **Nothing new is being remembered at all**: run `ai-memory doctor`. It works
+ with the server down and says so; it reports the local hook spool (events
+ waiting for the server, and a warning once it is full and each new event
+ evicts the oldest undelivered one); and when ai-memory's Codex hooks are
+ installed, it asks Codex whether it will run them. Codex skips a hook you
+ have not trusted, and skips it again after its command changes, without
+ telling you: open Codex, run `/hooks`, and trust them.
- **I just installed hooks in a project I've worked in for a while**: the first
time you open the project after installing, ai-memory imports your existing
local session history once (bounded, sanitized on the server, only into an