Skip to content

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.md
index 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.0
healthy DB). Optional `?workspace=&project=` scope; reports only, never
mutates, 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 any
instance running scope-guard. `rename-project` is unaffected (it runs no
admission 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
### Changed
diff --git a/docs/install.md b/docs/install.md
index 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 operations
diff --git a/docs/windows.md b/docs/windows.md
index 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 the
per-request timeout for several events to drain per boundary.
## Current Harness Caveats