Skip to content

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

Rust

docs(install): document hook latency expectations (#472)

YANGYU2b4a0238d3b1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1060bafa..4c90947b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
text. A newer CLI against an older server renders the rest of `status` and
omits the section rather than failing to parse.
+### Docs
+- Documented the order of magnitude reported for lifecycle-hook overhead,
+ including the fact that a completed tool call normally pays for both pre- and
+ post-tool hooks, the measured native-versus-script figures, and the host
+ factors that make them reference data rather than a performance guarantee
+ (#446).
+
## [1.31.1] - 2026-08-23
### Fixed
diff --git a/docs/install.md b/docs/install.md
index 457c632e..0be07008 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -421,6 +421,24 @@ 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.
+### Hook latency expectations
+
+Hook-capable agents launch one short-lived hook process per lifecycle event. A
+successful tool call normally fires both a pre-tool and a post-tool event, so
+per-invocation overhead is paid twice. As an order-of-magnitude reference, one
+independent v1.29.0 evaluation on native macOS aarch64 measured about 145 ms per
+`posix-native` invocation (about 290 ms per completed tool call) and about 172
+ms per legacy `.sh` invocation.
+
+Those figures are one host's measurements, not a benchmark or performance
+guarantee. Process startup, filesystem and security software, the selected
+data directory, authentication, and host load can all change the result. The
+native hook fast path skips full config loading and tracing, and normally
+spools locally instead of waiting for the server, so keep the installer's
+native default where supported. Latency-sensitive deployments should measure
+their own agent host before opting into additional captured events or choosing
+a script fallback.
+
### Capture-policy capability and refresh
`[capture] ignore_paths` is enforced only by native `ai-memory hook` commands