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.mdindex 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 eachdiff --git a/crates/ai-memory-cli/src/commands/codex_hook_trust.rs b/crates/ai-memory-cli/src/commands/codex_hook_trust.rsnew file mode 100644index 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.mdindex d5c0551c..56b8ea7e 100644--- a/docs/cookbook.md+++ b/docs/cookbook.md@@ -458,6 +458,13 @@ ai-memory serve # run the serverand is not reported. An `excluded` verdict applies only to native/generatedhooks; shell and PowerShell compatibility hooks do not enforce capture-policyexclusions.+- **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 firsttime you open the project after installing, ai-memory imports your existinglocal session history once (bounded, sanitized on the server, only into an