Skip to content

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

Rust

fix(hooks): document and bound timing overrides

AkitaOnRails6a3a2f5bf07a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fc40186b..4173859a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,14 @@ 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
+- Native hook drain and handoff timings can now be raised with
+ `AI_MEMORY_HOOK_DRAIN_TIMEOUT_MINUTES`,
+ `AI_MEMORY_HOOK_HANDOFF_TIMEOUT_MINUTES`,
+ `AI_MEMORY_HOOK_START_BUDGET_MINUTES`, and
+ `AI_MEMORY_HOOK_END_BUDGET_MINUTES` for high-latency or large-backlog
+ instances. Defaults preserve the existing short hook behavior; invalid,
+ zero, or overly large values fall back or clamp safely.
## [0.16.0] - 2026-06-11
### Added
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index 8b722915..3e82a12e 100644
--- a/crates/ai-memory-cli/src/commands/hook.rs
+++ b/crates/ai-memory-cli/src/commands/hook.rs
@@ -21,51 +21,82 @@ use crate::cli::HookArgs;
use super::hook_capture::{build_client, extract_cwd, get_handoff, marker_query_suffix};
use super::hook_spool;
-// All drain/handoff timings default to the values below and can be overridden
-// (in milliseconds) by the matching env var, for very high-latency or
-// large-backlog instances. Two kinds: per-request timeouts cap each individual
-// POST / handoff GET; session-boundary budgets cap how long a boundary spends
-// draining (so a boundary never hangs unbounded).
-const DEFAULT_DRAIN_TIMEOUT_MS: u64 = 3000;
-const DEFAULT_HANDOFF_TIMEOUT_MS: u64 = 3000;
-const DEFAULT_START_BUDGET_MS: u64 = 3000;
-const DEFAULT_END_BUDGET_MS: u64 = 10000;
-
-/// Per-event POST timeout during a drain. Env: `AI_MEMORY_HOOK_DRAIN_TIMEOUT_MS`.
+// All drain/handoff timings default to the current short values and can be
+// overridden by whole-minute env vars for very high-latency or large-backlog
+// instances. Two kinds: per-request timeouts cap each individual POST / handoff
+// GET; session-boundary budgets cap how long a boundary spends draining (so a
+// boundary never hangs unbounded).
+const DEFAULT_DRAIN_TIMEOUT: Duration = Duration::from_secs(3);
+const DEFAULT_HANDOFF_TIMEOUT: Duration = Duration::from_secs(3);
+const DEFAULT_START_BUDGET: Duration = Duration::from_secs(3);
+const DEFAULT_END_BUDGET: Duration = Duration::from_secs(10);
+const MAX_OVERRIDE_MINUTES: u64 = 60;
+
+const DRAIN_TIMEOUT_ENV: &str = "AI_MEMORY_HOOK_DRAIN_TIMEOUT_MINUTES";
+const HANDOFF_TIMEOUT_ENV: &str = "AI_MEMORY_HOOK_HANDOFF_TIMEOUT_MINUTES";
+const START_BUDGET_ENV: &str = "AI_MEMORY_HOOK_START_BUDGET_MINUTES";
+const END_BUDGET_ENV: &str = "AI_MEMORY_HOOK_END_BUDGET_MINUTES";
+
+/// Per-event POST timeout during a drain. Env: `AI_MEMORY_HOOK_DRAIN_TIMEOUT_MINUTES`.
fn drain_event_timeout() -> Duration {
- env_ms("AI_MEMORY_HOOK_DRAIN_TIMEOUT_MS", DEFAULT_DRAIN_TIMEOUT_MS)
+ drain_event_timeout_from(env_lookup)
}
-/// Synchronous handoff GET timeout. Env: `AI_MEMORY_HOOK_HANDOFF_TIMEOUT_MS`.
+/// Synchronous handoff GET timeout. Env: `AI_MEMORY_HOOK_HANDOFF_TIMEOUT_MINUTES`.
fn handoff_timeout() -> Duration {
- env_ms(
- "AI_MEMORY_HOOK_HANDOFF_TIMEOUT_MS",
- DEFAULT_HANDOFF_TIMEOUT_MS,
- )
+ handoff_timeout_from(env_lookup)
}
/// Total budget for the `session-start` cleanup drain (kept tight so session
/// start stays snappy even when the server is down — leftovers wait). Env:
-/// `AI_MEMORY_HOOK_START_BUDGET_MS`.
+/// `AI_MEMORY_HOOK_START_BUDGET_MINUTES`.
fn start_drain_budget() -> Duration {
- env_ms("AI_MEMORY_HOOK_START_BUDGET_MS", DEFAULT_START_BUDGET_MS)
+ start_drain_budget_from(env_lookup)
}
/// Total budget for the `session-end` flush (the main delivery point; a session
-/// boundary tolerates more). Env: `AI_MEMORY_HOOK_END_BUDGET_MS`.
+/// boundary tolerates more). Env: `AI_MEMORY_HOOK_END_BUDGET_MINUTES`.
fn end_drain_budget() -> Duration {
- env_ms("AI_MEMORY_HOOK_END_BUDGET_MS", DEFAULT_END_BUDGET_MS)
+ end_drain_budget_from(env_lookup)
}
-/// Read a positive-integer millisecond override from `name`, falling back to
-/// `default_ms` for missing / empty / non-numeric / zero values.
-fn env_ms(name: &str, default_ms: u64) -> Duration {
- parse_ms(std::env::var(name).ok(), default_ms)
+fn drain_event_timeout_from(lookup: impl FnMut(&str) -> Option<String>) -> Duration {
+ env_minutes(DRAIN_TIMEOUT_ENV, DEFAULT_DRAIN_TIMEOUT, lookup)
}
-fn parse_ms(raw: Option<String>, default_ms: u64) -> Duration {
- let ms = raw
+fn handoff_timeout_from(lookup: impl FnMut(&str) -> Option<String>) -> Duration {
+ env_minutes(HANDOFF_TIMEOUT_ENV, DEFAULT_HANDOFF_TIMEOUT, lookup)
+}
+
+fn start_drain_budget_from(lookup: impl FnMut(&str) -> Option<String>) -> Duration {
+ env_minutes(START_BUDGET_ENV, DEFAULT_START_BUDGET, lookup)
+}
+
+fn end_drain_budget_from(lookup: impl FnMut(&str) -> Option<String>) -> Duration {
+ env_minutes(END_BUDGET_ENV, DEFAULT_END_BUDGET, lookup)
+}
+
+fn env_lookup(name: &str) -> Option<String> {
+ std::env::var(name).ok()
+}
+
+/// Read a positive-integer minute override from `name`, falling back to the
+/// built-in short default for missing / empty / non-numeric / zero values. Clamp
+/// large values so a typo cannot block a hook boundary for hours or days.
+fn env_minutes(
+ name: &str,
+ default: Duration,
+ mut lookup: impl FnMut(&str) -> Option<String>,
+) -> Duration {
+ parse_minutes(lookup(name), default)
+}
+
+fn parse_minutes(raw: Option<String>, default: Duration) -> Duration {
+ let minutes = raw
.and_then(|s| s.trim().parse::<u64>().ok())
.filter(|&n| n > 0)
- .unwrap_or(default_ms);
- Duration::from_millis(ms)
+ .map(|n| n.min(MAX_OVERRIDE_MINUTES));
+ match minutes {
+ Some(n) => Duration::from_secs(n * 60),
+ None => default,
+ }
}
/// Run a single hook end-to-end. Always returns Ok and always writes a JSON
@@ -153,32 +184,70 @@ mod tests {
use super::*;
#[test]
- fn parse_ms_falls_back_on_invalid() {
- assert_eq!(parse_ms(None, 3000), Duration::from_millis(3000));
+ fn parse_minutes_falls_back_on_invalid() {
+ assert_eq!(
+ parse_minutes(None, DEFAULT_DRAIN_TIMEOUT),
+ DEFAULT_DRAIN_TIMEOUT
+ );
assert_eq!(
- parse_ms(Some(String::new()), 3000),
- Duration::from_millis(3000)
+ parse_minutes(Some(String::new()), DEFAULT_DRAIN_TIMEOUT),
+ DEFAULT_DRAIN_TIMEOUT
);
assert_eq!(
- parse_ms(Some("abc".into()), 3000),
- Duration::from_millis(3000)
+ parse_minutes(Some("abc".into()), DEFAULT_DRAIN_TIMEOUT),
+ DEFAULT_DRAIN_TIMEOUT
);
- // Zero is rejected (a 0ms timeout would drop every request).
+ // Zero is rejected (a 0-minute timeout would drop every request).
assert_eq!(
- parse_ms(Some("0".into()), 3000),
- Duration::from_millis(3000)
+ parse_minutes(Some("0".into()), DEFAULT_DRAIN_TIMEOUT),
+ DEFAULT_DRAIN_TIMEOUT
);
}
#[test]
- fn parse_ms_honours_valid_override() {
+ fn parse_minutes_honours_valid_override() {
+ assert_eq!(
+ parse_minutes(Some("2".into()), DEFAULT_DRAIN_TIMEOUT),
+ Duration::from_secs(120)
+ );
+ assert_eq!(
+ parse_minutes(Some(" 3 ".into()), DEFAULT_DRAIN_TIMEOUT),
+ Duration::from_secs(180)
+ );
+ }
+
+ #[test]
+ fn parse_minutes_clamps_large_values() {
+ assert_eq!(
+ parse_minutes(Some("999".into()), DEFAULT_DRAIN_TIMEOUT),
+ Duration::from_secs(MAX_OVERRIDE_MINUTES * 60)
+ );
+ }
+
+ #[test]
+ fn timing_accessors_read_the_expected_env_vars() {
+ fn one_minute_for(expected_name: &'static str) -> impl FnMut(&str) -> Option<String> {
+ move |actual_name| {
+ assert_eq!(actual_name, expected_name);
+ Some("1".to_string())
+ }
+ }
+
+ assert_eq!(
+ drain_event_timeout_from(one_minute_for(DRAIN_TIMEOUT_ENV)),
+ Duration::from_secs(60)
+ );
+ assert_eq!(
+ handoff_timeout_from(one_minute_for(HANDOFF_TIMEOUT_ENV)),
+ Duration::from_secs(60)
+ );
assert_eq!(
- parse_ms(Some("8000".into()), 3000),
- Duration::from_millis(8000)
+ start_drain_budget_from(one_minute_for(START_BUDGET_ENV)),
+ Duration::from_secs(60)
);
assert_eq!(
- parse_ms(Some(" 6000 ".into()), 3000),
- Duration::from_millis(6000)
+ end_drain_budget_from(one_minute_for(END_BUDGET_ENV)),
+ Duration::from_secs(60)
);
}
}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 31c9dbad..cefd27a4 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -76,9 +76,12 @@ markdown stays the source of truth.
**Steady-state loop:**
1. Agent CLI emits a lifecycle hook (SessionStart, UserPromptSubmit,
- PostToolUse, …) → vendored shell script `curl`s the event JSON to
- `POST /hook` with a sub-second timeout. Agent never blocks; saturated
- servers return HTTP 429 instead of queueing unbounded work.
+ PostToolUse, …). Shell-script hooks `curl` event JSON to `POST /hook`
+ with a short timeout. Native `ai-memory hook --event ...` commands spool
+ events locally and drain them at session boundaries; high-latency
+ operators can raise the drain/handoff caps with minute-based env vars.
+ Agent hot paths never block on the network; saturated servers return HTTP
+ 429 instead of queueing unbounded work.
2. Server's hook router sanitises the payload (the only path from
untrusted text into the store), assigns an [`ObservationKind`], and
enqueues a `WriteCmd` to the writer actor. `log.md` gets an
diff --git a/docs/install.md b/docs/install.md
index ddd2ab7f..017983be 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -324,6 +324,21 @@ then stages runnable copies under `~/.local/share/ai-memory/hooks/<agent>/` so
the agent can execute files owned by your user. Re-run `install-hooks --apply`
after package upgrades to refresh those staged copies.
+Native `ai-memory hook --event ...` commands spool events locally and drain them
+at session boundaries. The built-in timings stay short by default, but
+high-latency or large-backlog instances can raise them with whole-minute runtime
+env vars in the agent's environment; no `install-hooks` rerun is needed:
+
+| Env var | Built-in default | Max override | What it caps |
+|---|---:|---:|---|
+| `AI_MEMORY_HOOK_DRAIN_TIMEOUT_MINUTES` | 3 seconds | 60 minutes | each event POST during a drain |
+| `AI_MEMORY_HOOK_HANDOFF_TIMEOUT_MINUTES` | 3 seconds | 60 minutes | the synchronous `session-start` handoff GET |
+| `AI_MEMORY_HOOK_START_BUDGET_MINUTES` | 3 seconds | 60 minutes | total time the `session-start` cleanup drain may spend |
+| `AI_MEMORY_HOOK_END_BUDGET_MINUTES` | 10 seconds | 60 minutes | total time the `session-end` flush may spend |
+
+Values must be positive whole minutes. Missing, empty, non-numeric, or zero
+values fall back to the built-in defaults; values above 60 are clamped.
+
### Native service operations
```bash
diff --git a/docs/windows.md b/docs/windows.md
index 8614e64a..b5991f30 100644
--- a/docs/windows.md
+++ b/docs/windows.md
@@ -227,21 +227,22 @@ native on an i7-6700HQ). Notes:
### Tuning the spool timings (high-latency instances)
The native hook spools events locally and drains them to the server at session
-boundaries. The drain/handoff timings default to sane values and can be raised
-(in milliseconds) for a very high-latency instance or a large backlog. Unlike
+boundaries. The built-in timings stay short by default, but high-latency or
+large-backlog instances can raise them with whole-minute overrides. Unlike
`AI_MEMORY_HOOK_PLATFORM`, these are read by the hook **at runtime**, so they
apply to the agent's environment (no re-`install-hooks` needed):
-| Env var | Default | What it caps |
-|---|---|---|
-| `AI_MEMORY_HOOK_DRAIN_TIMEOUT_MS` | `3000` | each event POST during a drain |
-| `AI_MEMORY_HOOK_HANDOFF_TIMEOUT_MS` | `3000` | the synchronous `session-start` handoff GET |
-| `AI_MEMORY_HOOK_START_BUDGET_MS` | `3000` | total time the `session-start` cleanup drain may spend |
-| `AI_MEMORY_HOOK_END_BUDGET_MS` | `10000` | total time the `session-end` flush may spend |
-
-A non-numeric or zero value falls back to the default. The budgets cap how long
-a session boundary blocks, so leave headroom over the per-request timeout for
-several events to drain per boundary.
+| Env var | Built-in default | Max override | What it caps |
+|---|---:|---:|---|
+| `AI_MEMORY_HOOK_DRAIN_TIMEOUT_MINUTES` | 3 seconds | 60 minutes | each event POST during a drain |
+| `AI_MEMORY_HOOK_HANDOFF_TIMEOUT_MINUTES` | 3 seconds | 60 minutes | the synchronous `session-start` handoff GET |
+| `AI_MEMORY_HOOK_START_BUDGET_MINUTES` | 3 seconds | 60 minutes | total time the `session-start` cleanup drain may spend |
+| `AI_MEMORY_HOOK_END_BUDGET_MINUTES` | 10 seconds | 60 minutes | total time the `session-end` flush may spend |
+
+Values must be positive whole minutes. Missing, empty, non-numeric, or zero
+values fall back to the built-in defaults; values above 60 are clamped. The
+budgets cap how long a session boundary blocks, so leave headroom over the
+per-request timeout for several events to drain per boundary.
## Current Harness Caveats