Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(hooks): document incremental spool drain
AkitaOnRailse7891e1fb447
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 69630cdd..1392699d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -17,6 +17,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0healthy DB). Optional `?workspace=&project=` scope; reports only, nevermutates, so it is safe to run on any cadence. Purely semantic mislandings(no cwd/session anomaly) are out of scope by design.+- Mid-session hook-spool drain: on `post-tool-use`, once the local spool backlog+ crosses a threshold, the hook runs a tightly time-boxed (~250 ms) catch-up+ drain so a heavy session keeps the backlog flat instead of waiting for the next+ session boundary. Tunable via `AI_MEMORY_HOOK_INCREMENTAL_THRESHOLD`+ (default 32 events).++### Fixed+- Hook spool no longer counts a server `429` (saturation / `hook queue full`)+ against a spooled event's `MAX_ATTEMPTS` retry budget: transient backpressure+ keeps the event queued without burning an attempt (`MAX_AGE_MS` still bounds+ it), so a saturation burst no longer silently discards real observations.## [1.1.0] - 2026-06-16@@ -120,18 +131,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0`403 user '' not allowed to purge_project`, making purge/move unusable on anyinstance running scope-guard. `rename-project` is unaffected (it runs noadmission chain).-- Hook spool no longer counts a server `429` (saturation / `hook queue full`)- against a spooled event's `MAX_ATTEMPTS` retry budget: transient backpressure- keeps the event queued without burning an attempt (`MAX_AGE_MS` still bounds- it), so a saturation burst no longer silently discards real observations.--### Added-- Mid-session hook-spool drain: on `post-tool-use`, once the local spool backlog- crosses a threshold, the hook runs a tightly time-boxed (~250 ms) catch-up- drain so a heavy session keeps the backlog flat instead of waiting for the next- session boundary. Tunable via `AI_MEMORY_HOOK_INCREMENTAL_THRESHOLD`- (default 32 events).-## [1.0.6] - 2026-06-14### Changeddiff --git a/docs/install.md b/docs/install.mdindex be2fb6a2..51562833 100644--- a/docs/install.md+++ b/docs/install.md@@ -343,9 +343,11 @@ env vars in the agent's environment; no `install-hooks` rerun is needed:| `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 |+| `AI_MEMORY_HOOK_INCREMENTAL_THRESHOLD` | 32 events | positive integer | spool backlog size that triggers a 250 ms `post-tool-use` catch-up drain |-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.+Timing 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+incremental threshold is a positive event count; invalid values fall back to 32.### Native service operationsdiff --git a/docs/windows.md b/docs/windows.mdindex 5bff4125..ca9a1c4b 100644--- a/docs/windows.md+++ b/docs/windows.md@@ -238,10 +238,12 @@ apply to the agent's environment (no re-`install-hooks` needed):| `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 |+| `AI_MEMORY_HOOK_INCREMENTAL_THRESHOLD` | 32 events | positive integer | spool backlog size that triggers a 250 ms `post-tool-use` catch-up drain |-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+Timing 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+incremental threshold is a positive event count; invalid values fall back to 32.+The budgets cap how long a session boundary blocks, so leave headroom over theper-request timeout for several events to drain per boundary.## Current Harness Caveats