Skip to content

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

Rust

fix(hook): reliably drain macOS native backlogs

AkitaOnRails7393f2e802c6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dd6e0f13..9883b1c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,13 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
+### Fixed
+
+- Fixed native hook backlogs repeatedly missing their 250 ms mid-session
+ delivery window on loaded macOS hosts. Threshold catch-up now launches the
+ long-budget detached drainer, and POSIX fallback hooks use macOS's real
+ Application Support data directory for spool and auth state (#1744).
+
## [3.2.6] - 2026-10-26
### Fixed
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index 88e3508d..fd289909 100644
--- a/crates/ai-memory-cli/src/commands/hook.rs
+++ b/crates/ai-memory-cli/src/commands/hook.rs
@@ -64,10 +64,6 @@ const CAPTURE_OWNER_ENV: &str = "AI_MEMORY_CAPTURE_OWNER";
/// light session pays only a `read_dir`. Override via the env var above.
const DEFAULT_INCREMENTAL_THRESHOLD: usize = 32;
const MAX_BRIEFED_MARKERS: usize = 512;
-/// Total budget AND per-event timeout for the mid-session catch-up drain — kept
-/// well under a second so a `post-tool-use` hook never stalls a tool call (one
-/// in-flight POST against a slow server is bounded by this too).
-const INCREMENTAL_DRAIN_BUDGET: Duration = Duration::from_millis(250);
/// Total budget, lock wait included, for a `session-end` drained in-process
/// ([`session_end_drains_in_process`]). Fixed rather than env-overridable:
/// together with [`IN_PROCESS_SESSION_END_DEADLINE`] it has to stay inside
@@ -123,8 +119,12 @@ fn background_drain_budget_from(lookup: impl FnMut(&str) -> Option<String>) -> D
/// Backlog size at which `post-tool-use` triggers a mid-session catch-up drain.
/// Env: `AI_MEMORY_HOOK_INCREMENTAL_THRESHOLD` (positive integer).
-fn incremental_drain_threshold() -> usize {
- incremental_drain_threshold_from(env_lookup)
+fn incremental_drain_threshold(runtime_env: &RuntimeEnv) -> usize {
+ incremental_drain_threshold_from(|name| {
+ runtime_env
+ .var_os(name)
+ .map(|value| value.to_string_lossy().into_owned())
+ })
}
fn incremental_drain_threshold_from(mut lookup: impl FnMut(&str) -> Option<String>) -> usize {
@@ -1465,6 +1465,7 @@ where
// resolved directory the handoff stays open for `memory_handoff_accept`.
let handoff_scoped = policy_cwd.is_some();
let spool = hook_spool::spool_dir(&dd);
+ let mut incremental_background_drain = false;
let session_qs = session_id_query_suffix(&dd, &args.agent, &args.event, &json);
let managed_qs = managed_run_query_suffix();
let hook_qs = format!("{qs}{session_qs}{managed_qs}");
@@ -1572,24 +1573,31 @@ where
}
// Mid-session catch-up: per-event hooks only enqueue, so a heavy session
- // outpaces the boundary-only drain and the spool grows until the next
- // boundary. On `post-tool-use`, once the backlog crosses the threshold, do a
- // tightly time-boxed drain (budget == per-event timeout, sub-second) so the
- // spool stays flat without ever stalling a tool call.
+ // can outpace the boundary-only drain. Once a `post-tool-use` backlog
+ // crosses the threshold, hand it to the same long-budget detached
+ // drainer used at boundaries. A 250 ms inline attempt proved too short
+ // on loaded macOS hosts and could leave every later threshold attempt
+ // timing out too (#1744). Zero kills detached children, so it retains a
+ // tightly bounded in-process pass.
if should_incremental_drain(
&args.event,
hook_spool::spool_len(&spool),
- incremental_drain_threshold(),
+ incremental_drain_threshold(&runtime_env),
) {
- let _ = hook_spool::drain_exclusive(
- &spool,
- &dd,
- INCREMENTAL_DRAIN_BUDGET,
- INCREMENTAL_DRAIN_BUDGET,
- hook_spool::DrainLockWait::NoWait,
- max_attempts,
- )
- .await;
+ if agent_kind == AgentKind::Zero {
+ let budget = Duration::from_millis(250);
+ let _ = hook_spool::drain_exclusive(
+ &spool,
+ &dd,
+ budget,
+ budget,
+ hook_spool::DrainLockWait::NoWait,
+ max_attempts,
+ )
+ .await;
+ } else {
+ incremental_background_drain = true;
+ }
}
// session-start: if this checkout has never had the one-time boot backfill
@@ -1928,7 +1936,7 @@ where
if !external_capture && session_end_drains_in_process(agent_kind, &args.event) {
drain_session_end_in_process(&spool, &dd, max_attempts).await;
} else if !external_capture
- && should_spawn_background_drainer(&args.event)
+ && (incremental_background_drain || should_spawn_background_drainer(&args.event))
&& let Err(err) = after_background_drain_event_enqueue(
&dd,
// The install's own token, resolved the same way an install-default
@@ -3829,6 +3837,57 @@ mod tests {
}
}
+ #[tokio::test]
+ async fn post_tool_threshold_spawns_long_budget_background_drainer() {
+ let tmp = tempfile::tempdir().unwrap();
+ let data_dir = tmp.path().to_path_buf();
+ let spool = hook_spool::spool_dir(&data_dir);
+ for index in 0..2 {
+ hook_spool::enqueue(
+ &spool,
+ &hook_spool::entry_for(
+ format!("http://127.0.0.1:1/hook?queued={index}"),
+ "{}".into(),
+ None,
+ false,
+ ),
+ )
+ .unwrap();
+ }
+ let called = std::cell::Cell::new(0);
+ let mut stdout = Vec::new();
+ let args = HookArgs {
+ event: "post-tool-use".into(),
+ agent: "claude-code".into(),
+ server_url: dead_server_url(),
+ auth_token: None,
+ project_strategy: None,
+ check_capture: false,
+ capture_assistant: false,
+ capture_mode: None,
+ };
+
+ run_with_payload_in_home(
+ Some(data_dir.clone()),
+ args,
+ r#"{"session_id":"s","cwd":"/tmp","tool_name":"Read","tool_input":{"file_path":"/tmp/example"}}"#.into(),
+ &mut stdout,
+ |path, _token| {
+ assert_eq!(path, data_dir.as_path());
+ assert_eq!(hook_spool::spool_len(&spool), 3);
+ called.set(called.get() + 1);
+ Ok(())
+ },
+ None,
+ RuntimeEnv::with_process_env_for_tests(&[(INCREMENTAL_THRESHOLD_ENV, "3")]),
+ )
+ .await
+ .unwrap();
+
+ assert_eq!(stdout, b"{}\n");
+ assert_eq!(called.get(), 1);
+ }
+
fn zero_hook_args(event: &str, server_url: &str) -> HookArgs {
HookArgs {
event: event.into(),
diff --git a/hooks/_lib.sh b/hooks/_lib.sh
index 7fb409e4..0d5ba896 100644
--- a/hooks/_lib.sh
+++ b/hooks/_lib.sh
@@ -871,7 +871,10 @@ ai_memory_state_dir() {
elif [ -n "${XDG_DATA_HOME:-}" ]; then
printf '%s/ai-memory' "$XDG_DATA_HOME"
elif [ -n "${HOME:-}" ]; then
- printf '%s/.local/share/ai-memory' "$HOME"
+ case "$(uname -s 2>/dev/null || printf '')" in
+ Darwin) printf '%s/Library/Application Support/ai-memory' "$HOME" ;;
+ *) printf '%s/.local/share/ai-memory' "$HOME" ;;
+ esac
else
printf '.ai-memory'
fi
@@ -925,7 +928,7 @@ ai_memory_clear_session_id() {
# Path of the `Authorization:` header file `install-hooks --apply` writes
# (0600, inside the 0700 data dir). Printed only when readable.
ai_memory_auth_header_file() {
- _amhf="${AI_MEMORY_DATA_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/ai-memory}/auth-header"
+ _amhf="$(ai_memory_state_dir)/auth-header"
[ -r "$_amhf" ] && printf '%s' "$_amhf"
}
diff --git a/tests/hooks/test_lib.sh b/tests/hooks/test_lib.sh
index 611037c5..5987d6bc 100755
--- a/tests/hooks/test_lib.sh
+++ b/tests/hooks/test_lib.sh
@@ -655,6 +655,29 @@ assert_eq "url_encode encodes an accented macOS path" \
"$(ai_memory_url_encode '/Users/me/Área de Trabalho')"
# --- offline spool ----------------------------------------------------
+# Without an explicit data-dir, the script fallback must agree with the
+# native client's platform default. In particular, macOS setup stores state
+# under Application Support rather than a shadow ~/.local/share tree.
+MAC_HOME="$TMP/mac-home"
+mkdir -p "$MAC_HOME/Library/Application Support/ai-memory"
+: > "$MAC_HOME/Library/Application Support/ai-memory/auth-header"
+MAC_STATE=$(
+ HOME="$MAC_HOME"; export HOME
+ unset AI_MEMORY_DATA_DIR XDG_DATA_HOME
+ uname() { printf 'Darwin\n'; }
+ ai_memory_state_dir
+)
+assert_eq "state_dir uses the macOS data directory" \
+ "$MAC_HOME/Library/Application Support/ai-memory" "$MAC_STATE"
+MAC_AUTH=$(
+ HOME="$MAC_HOME"; export HOME
+ unset AI_MEMORY_DATA_DIR XDG_DATA_HOME
+ uname() { printf 'Darwin\n'; }
+ ai_memory_auth_header_file
+)
+assert_eq "auth header follows the macOS state directory" \
+ "$MAC_HOME/Library/Application Support/ai-memory/auth-header" "$MAC_AUTH"
+
# The spool dir follows the data dir, which the harness pins inside $TMP.
AI_MEMORY_DATA_DIR="$TMP/spool-data"
export AI_MEMORY_DATA_DIR