Skip to content

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

Rust

docs(deploy): document the status hook-spool section

AkitaOnRails2d765c33b38a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index eab3fb4f..4bdd4eee 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Fixed
+- Documented the `ai-memory status` hook-spool section in
+ `docs/deploy.md`. It shipped with no operator-facing description, in the
+ one document whose troubleshooting list is where someone looks when
+ capture seems delayed. (#428)
- The Windows packaging test for the PowerShell wrapper now runs it with
`-ExecutionPolicy Bypass`. `-File` loads a script from disk and execution
policy governs script files, so on a machine at the Windows client default
diff --git a/docs/deploy.md b/docs/deploy.md
index 34d9a539..53b6b94e 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -253,6 +253,30 @@ ssh "$SERVER" "tail -100 $DEPLOY_DIR/data/logs/ai-memory.log.$(date +%F)"
every project in the workspace, or add `--project <name>` to scope
the rebuild. Scheduled embedding backfill can also fill missing
rows when enabled.
+- **Capture looks delayed, or observations are missing**: `ai-memory
+ status` reports local hook-spool health — how many events are queued
+ client-side, the age of the oldest one, and the total failed-delivery
+ attempts:
+
+ ```
+ spool:
+ pending: 2
+ oldest: 15m 0s
+ retries: 4
+ ```
+
+ A non-empty spool with an aging oldest entry means hooks are reaching
+ the local queue but not the server; events are not lost, they drain
+ once it is reachable. `pending: 0` means capture is keeping up.
+
+ The spool is **client-side**, so this section reflects the machine you
+ run the command on, not the server — it is the local data dir even when
+ `AI_MEMORY_SERVER_URL` points at a homelab. It is also printed when the
+ server cannot be reached at all (to stderr, so `--json` consumers still
+ get a single object on stdout), which is precisely when a backlog is
+ worth seeing. `--json` carries the same numbers under a `spool` object
+ (`pending`, `oldest_age_ms`, `retries_total`).
+
- **Provider failures**: `ai-memory status` reports passive LLM and
embedding health from the last real provider call. A fresh process
reports `unknown` until the server actually uses that role; it does