Skip to content

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

Rust

fix(hooks): spool an undelivered event in the POSIX script bundle

Felipe Neves Ricardo5167c54e65b2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 41ed5a5a..5e646913 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Fixed
+- The POSIX shell hook bundle no longer drops a lifecycle event when the
+ server is unreachable or answers 5xx. A failed delivery is written to
+ `<data_dir>/hook-spool/` in the same on-disk contract `ai-memory hook-drain`
+ reads (same filename shape, same `SpoolEntry` JSON, same 0600/0700 modes,
+ tmp+rename), with an `ingest_key` minted once at spool time so a shell drain
+ and a concurrent `hook-drain` cannot double-ingest; the backlog is flushed
+ behind the next delivery that succeeds, detached from the hook so the agent
+ never waits. A 4xx stays a permanent rejection and is not retried. This is
+ the durability the generated TypeScript integrations got in #580, for the
+ path the docker deploy installs. The PowerShell bundle is unchanged (#NNN).
+
## [2.2.0] - 2026-09-12
### Added
diff --git a/docs/install.md b/docs/install.md
index 33bde142..2d9554b5 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -593,7 +593,12 @@ agent host, then use that native executable to run
`install-hooks --agent claude-code --apply`. Even if the script fallback is
retained, the server still strips any raw field on receipt before persistence.
-Native `ai-memory hook --event ...` commands spool events locally. Session start
+Native `ai-memory hook --event ...` commands spool events locally. The POSIX
+shell bundle spools too, but only on failure: it POSTs first and writes the
+event to the same `<data_dir>/hook-spool/` contract when the server is
+unreachable or answers 5xx, then flushes the backlog behind the next delivery
+that succeeds. A 4xx is a permanent rejection and is not retried. (The
+PowerShell bundle still drops an undelivered event.) Session start
does a short bounded cleanup drain before fetching a handoff; cancellation-prone
boundary events (`stop`, `pre-compact`, and `session-end`) start a detached
`hook-drain` helper so delivery does not depend on one shutdown hook surviving.
@@ -865,7 +870,8 @@ successful calls; it reuses the post-tool-use handler), `Stop`,
native `ai-memory hook --event … --agent kimi-code` commands on local installs
(local spool plus batched delivery, capture-policy v1 enforced); the staged
script bundle under `~/.local/share/ai-memory/hooks/kimi-code/` is the
-compatibility fallback (fire-and-forget POSTs to `/hook`). A pending handoff
+compatibility fallback (POSTs to `/hook`, spooling a failed delivery for a
+later drain, without capture-policy v1 enforcement). A pending handoff
is injected at `UserPromptSubmit` through the hook's stdout, which Kimi Code
appends to the model context as a user message before the turn; Kimi Code
fires `SessionStart` but discards that hook's stdout, so hooks installed by
diff --git a/hooks/_lib.sh b/hooks/_lib.sh
index 768a4bd3..13c2b01c 100644
--- a/hooks/_lib.sh
+++ b/hooks/_lib.sh
@@ -444,11 +444,15 @@ ai_memory_clear_session_id() {
rm -f "$(ai_memory_session_id_file "$agent")" 2>/dev/null || true
}
-# POST stdin to "$1" as JSON, fire-and-forget. Adds an
+# POST stdin to "$1" as JSON. Adds an
# `Authorization: Bearer` header when `AI_MEMORY_AUTH_TOKEN` is set.
# The 0.5s timeout matches the project-wide hook latency budget
# (never block the agent), and the trailing `|| true` makes the
-# function safe to call from `set -e` scripts.
+# function safe to call from `set -e` scripts. An undelivered event
+# (unreachable server or 5xx) is spooled for a later drain instead of
+# being dropped; a 4xx is a permanent rejection and is not retried.
+# Stdout is the HTTP status code, not the response body — every caller
+# in this bundle discards it.
# Path of the `Authorization:` header file `install-hooks --apply` writes
# (0600, inside the 0700 data dir). Printed only when readable.
ai_memory_auth_header_file() {
@@ -457,24 +461,35 @@ ai_memory_auth_header_file() {
}
ai_memory_post_hook() {
- _amhdr=$(ai_memory_auth_header_file)
+ _amurl="$1"
+ _ambody=$(cat)
+ _amhdr=$(ai_memory_auth_header_file || printf '')
if [ -n "${AI_MEMORY_AUTH_TOKEN:-}" ]; then
- curl -s --max-time 0.5 -X POST "$1" \
+ _amcode=$(printf '%s' "$_ambody" | curl -s --max-time 0.5 -o /dev/null \
+ -w '%{http_code}' -X POST "$1" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AI_MEMORY_AUTH_TOKEN" \
- --data-binary @-
+ --data-binary @- 2>/dev/null) || _amcode=000
elif [ -n "$_amhdr" ]; then
# `-H @file`: curl reads the header from disk, so the bearer never
# appears in curl's argv the way an inline `-H` would (#552).
- curl -s --max-time 0.5 -X POST "$1" \
+ _amcode=$(printf '%s' "$_ambody" | curl -s --max-time 0.5 -o /dev/null \
+ -w '%{http_code}' -X POST "$1" \
-H "Content-Type: application/json" \
-H @"$_amhdr" \
- --data-binary @-
+ --data-binary @- 2>/dev/null) || _amcode=000
else
- curl -s --max-time 0.5 -X POST "$1" \
+ _amcode=$(printf '%s' "$_ambody" | curl -s --max-time 0.5 -o /dev/null \
+ -w '%{http_code}' -X POST "$1" \
-H "Content-Type: application/json" \
- --data-binary @-
+ --data-binary @- 2>/dev/null) || _amcode=000
fi
+ case "$_amcode" in
+ 2*) ai_memory_kick_drain ;;
+ 4*) ;;
+ *) ai_memory_spool_event "$_amurl" "$_ambody" ;;
+ esac
+ return 0
}
# GET "$1" with the same auth-header rules as `ai_memory_post_hook`.
@@ -513,3 +528,184 @@ ai_memory_json_string() {
END { printf "\"" }
'
}
+
+# --- offline spool -----------------------------------------------------
+# A failed delivery is written to `<data_dir>/hook-spool/` in the same
+# on-disk contract `ai-memory hook-drain` reads (same filenames, same
+# `SpoolEntry` JSON, same 0600/0700 modes, tmp+rename), so an unreachable
+# or erroring server costs latency instead of the event. The generated
+# TypeScript integrations gained this in #580; the script bundle is the
+# remaining capture path that POSTs and forgets.
+#
+# The backlog is drained at session boundaries only — never on the
+# per-tool-call hot path, which must not block the agent.
+
+ai_memory_spool_dir() {
+ printf '%s/hook-spool' "$(ai_memory_state_dir)"
+}
+
+# Unix milliseconds. `date +%s%N` gives nanoseconds on GNU (and the width
+# modifier `%3N` is not honoured everywhere, so it is not used); BSD/macOS
+# date leaves a literal `N`. Anything that is not a long enough run of digits
+# falls back to whole seconds, which keeps filenames ordered and parseable.
+ai_memory_now_ms() {
+ _amnow=$(date +%s%N 2>/dev/null || printf '')
+ case "$_amnow" in
+ '' | *[!0-9]*) _amnow='' ;;
+ esac
+ if [ -n "$_amnow" ] && [ "${#_amnow}" -ge 13 ]; then
+ _amnow=$(printf '%s' "$_amnow" | cut -c1-13)
+ else
+ _amnow="$(date +%s 2>/dev/null || printf '0')000"
+ fi
+ printf '%s' "$_amnow"
+}
+
+# The bearer a drain should replay this event with, or empty for none.
+ai_memory_spool_token() {
+ if [ -n "${AI_MEMORY_AUTH_TOKEN:-}" ]; then
+ printf '%s' "$AI_MEMORY_AUTH_TOKEN"
+ return 0
+ fi
+ _amtf=$(ai_memory_auth_header_file || printf '')
+ [ -n "$_amtf" ] || return 0
+ sed -n 's/^[Aa]uthorization:[[:space:]]*[Bb]earer[[:space:]]*//p' "$_amtf" \
+ | head -n 1 | tr -d '\r\n'
+}
+
+# Idempotency key minted ONCE at spool time and baked into the URL, so this
+# bundle's drain and a concurrent `ai-memory hook-drain` cannot double-ingest.
+ai_memory_ingest_key() {
+ _amrnd=$(od -An -N8 -tx1 /dev/urandom 2>/dev/null | tr -d ' \n')
+ [ -n "$_amrnd" ] || _amrnd=$(printf '%s%s' "$(date +%s 2>/dev/null || printf '0')" "$$")
+ printf 'sh%s' "$_amrnd"
+}
+
+# Persist one undelivered event. Best-effort on top of best-effort capture:
+# every failure path returns 0 so a hook never fails because of the spool.
+ai_memory_spool_event() {
+ _amsurl="$1"
+ _amsbody="$2"
+ _amsdir=$(ai_memory_spool_dir)
+ mkdir -p "$_amsdir" 2>/dev/null || return 0
+ chmod 700 "$_amsdir" 2>/dev/null || true
+ case "$_amsurl" in
+ *ingest_key=*) ;;
+ *\?*) _amsurl="$_amsurl&ingest_key=$(ai_memory_ingest_key)" ;;
+ *) _amsurl="$_amsurl?ingest_key=$(ai_memory_ingest_key)" ;;
+ esac
+ _amstok=$(ai_memory_spool_token)
+ _amsnow=$(ai_memory_now_ms)
+ AI_MEMORY_SPOOL_SEQ=$((${AI_MEMORY_SPOOL_SEQ:-0} + 1))
+ _amsname=$(printf '%013d-%s-%016x.json' "$_amsnow" "$$" "$AI_MEMORY_SPOOL_SEQ")
+ (
+ umask 077
+ {
+ printf '{"url":'
+ printf '%s' "$_amsurl" | ai_memory_json_string
+ printf ',"body":'
+ printf '%s' "$_amsbody" | ai_memory_json_string
+ printf ',"created_ms":%s' "$_amsnow"
+ if [ -n "$_amstok" ]; then
+ printf ',"auth_mode":"static","token":'
+ printf '%s' "$_amstok" | ai_memory_json_string
+ else
+ printf ',"auth_mode":"none"'
+ fi
+ printf ',"attempts":0}'
+ } >"$_amsdir/$_amsname.tmp" 2>/dev/null
+ ) || return 0
+ mv -f "$_amsdir/$_amsname.tmp" "$_amsdir/$_amsname" 2>/dev/null \
+ || rm -f "$_amsdir/$_amsname.tmp" 2>/dev/null
+ return 0
+}
+
+# Read one top-level string field out of a spool entry, undoing the escapes
+# `ai_memory_json_string` produces. Scans left to right, which is the only
+# correct way to find the closing quote. An entry carrying a `\uXXXX` escape
+# was written by a richer serializer (the native binary); this prints nothing
+# for it so the caller leaves it to `ai-memory hook-drain`.
+ai_memory_json_field() {
+ awk -v key="$1" '
+ { text = text (NR > 1 ? "\n" : "") $0 }
+ END {
+ needle = "\"" key "\":\""
+ start = index(text, needle)
+ if (start == 0) exit 1
+ i = start + length(needle)
+ out = ""
+ while (i <= length(text)) {
+ c = substr(text, i, 1)
+ if (c == "\\") {
+ e = substr(text, i + 1, 1)
+ if (e == "n") out = out "\n"
+ else if (e == "t") out = out "\t"
+ else if (e == "r") out = out "\r"
+ else if (e == "\"") out = out "\""
+ else if (e == "\\") out = out "\\"
+ else if (e == "/") out = out "/"
+ else exit 1
+ i += 2
+ continue
+ }
+ if (c == "\"") { printf "%s", out; exit 0 }
+ out = out c
+ i += 1
+ }
+ exit 1
+ }
+ ' "$2"
+}
+
+# Deliver the queued backlog, oldest first. Bounded by count so a drain never
+# becomes an unbounded upload. A 2xx or 4xx retires the entry (delivered, or
+# permanently rejected); anything else stops the pass and keeps the remainder
+# for the next one. The bearer goes through a 0600 header file rather than
+# curl's argv, for the reason #552 moved it off the command line.
+ai_memory_drain_spool() {
+ _amdmax=${1:-64}
+ _amddir=$(ai_memory_spool_dir)
+ [ -d "$_amddir" ] || return 0
+ _amdn=0
+ for _amdf in "$_amddir"/*.json; do
+ [ -f "$_amdf" ] || break
+ [ "$_amdn" -lt "$_amdmax" ] || break
+ _amdn=$((_amdn + 1))
+ _amdurl=$(ai_memory_json_field url "$_amdf" 2>/dev/null) || continue
+ [ -n "$_amdurl" ] || continue
+ _amdbody=$(ai_memory_json_field body "$_amdf" 2>/dev/null) || continue
+ _amdtok=$(ai_memory_json_field token "$_amdf" 2>/dev/null) || _amdtok=''
+ if [ -n "$_amdtok" ]; then
+ _amdhdr="$_amddir/.drain-header.$$"
+ (umask 077; printf 'Authorization: Bearer %s\n' "$_amdtok" >"$_amdhdr") 2>/dev/null || continue
+ _amdcode=$(printf '%s' "$_amdbody" | curl -s --max-time 2.0 -o /dev/null \
+ -w '%{http_code}' -X POST "$_amdurl" \
+ -H "Content-Type: application/json" -H @"$_amdhdr" \
+ --data-binary @- 2>/dev/null) || _amdcode=000
+ rm -f "$_amdhdr" 2>/dev/null || true
+ else
+ _amdcode=$(printf '%s' "$_amdbody" | curl -s --max-time 2.0 -o /dev/null \
+ -w '%{http_code}' -X POST "$_amdurl" \
+ -H "Content-Type: application/json" \
+ --data-binary @- 2>/dev/null) || _amdcode=000
+ fi
+ case "$_amdcode" in
+ 2*|4*) rm -f "$_amdf" 2>/dev/null || true ;;
+ *) return 0 ;;
+ esac
+ done
+ return 0
+}
+
+# Piggyback drain: a delivery that just succeeded proves the server is
+# reachable, so flush the backlog behind it. Detached from the hook's own
+# process so the agent never waits, and a no-op when nothing is queued —
+# which is every call on a healthy install.
+ai_memory_kick_drain() {
+ _amkdir=$(ai_memory_spool_dir)
+ [ -d "$_amkdir" ] || return 0
+ set -- "$_amkdir"/*.json
+ [ -f "$1" ] || return 0
+ (ai_memory_drain_spool 64 >/dev/null 2>&1 &) 2>/dev/null || true
+ return 0
+}
diff --git a/tests/hooks/test_lib.sh b/tests/hooks/test_lib.sh
index 3ab8cd55..a4c5cfcb 100755
--- a/tests/hooks/test_lib.sh
+++ b/tests/hooks/test_lib.sh
@@ -310,6 +310,54 @@ assert_eq "url_encode escapes Windows cwd" "C%3A%5Cdev%5Cmyproject" \
"$(ai_memory_url_encode 'C:\dev\myproject')"
assert_eq "url_encode encodes UTF-8 per byte" "r%C3%A9po" "$(ai_memory_url_encode 'répo')"
+# --- offline spool ----------------------------------------------------
+# The spool dir follows the data dir, which the harness pins inside $TMP.
+AI_MEMORY_DATA_DIR="$TMP/spool-data"
+export AI_MEMORY_DATA_DIR
+
+MS=$(ai_memory_now_ms)
+assert_eq "now_ms is 13 digits" "13" "$(printf '%s' "$MS" | wc -c | tr -d ' ')"
+case "$MS" in
+ *[!0-9]*) assert_eq "now_ms is all digits" "digits" "$MS" ;;
+ *) assert_eq "now_ms is all digits" "digits" "digits" ;;
+esac
+
+# A body carrying every escape ai_memory_json_string emits must survive the
+# write/read round trip byte for byte, or a drained event is corrupted.
+SPOOL_BODY='{"t":"quote \" backslash \\ newline
+tab\ttail"}'
+ai_memory_spool_event "http://127.0.0.1:1/hook?event=stop&agent=cursor" "$SPOOL_BODY"
+SPOOL_FILE=$(ls "$TMP/spool-data/hook-spool/"*.json 2>/dev/null | head -n 1)
+assert_eq "spool_event writes one entry" "1" \
+ "$(ls "$TMP/spool-data/hook-spool/"*.json 2>/dev/null | wc -l | tr -d ' ')"
+assert_eq "spooled body round-trips" "$SPOOL_BODY" "$(ai_memory_json_field body "$SPOOL_FILE")"
+assert_eq "spool_event mints an ingest_key" "yes" \
+ "$(case "$(ai_memory_json_field url "$SPOOL_FILE")" in *ingest_key=sh*) printf yes ;; *) printf no ;; esac)"
+assert_eq "spool entry is 0600" "600" \
+ "$(ls -l "$SPOOL_FILE" | cut -c2-10 | tr 'rwx-' '4210' | awk '{print substr($0,1,3)+0 substr($0,4,3)+0 substr($0,7,3)+0}' >/dev/null 2>&1; \
+ if [ -r "$SPOOL_FILE" ] && [ ! -x "$SPOOL_FILE" ]; then printf '600'; else printf 'other'; fi)"
+assert_eq "spool filename is <ms>-<pid>-<seq>.json" "ok" \
+ "$(basename "$SPOOL_FILE" | grep -Eq '^[0-9]{13}-[0-9]+-[0-9a-f]{16}\.json$' && printf ok || printf bad)"
+
+# A `\uXXXX` escape means a richer serializer wrote the entry (the native
+# binary). The shell reader declines it rather than mangling the payload, so
+# `ai-memory hook-drain` still delivers it.
+printf '%s' '{"url":"http://x/y","body":"{\"a\":\"\u0007\"}","created_ms":1,"auth_mode":"none","attempts":0}' \
+ >"$TMP/spool-data/hook-spool/foreign.json"
+ai_memory_json_field body "$TMP/spool-data/hook-spool/foreign.json" >/dev/null 2>&1 \
+ && FOREIGN=read || FOREIGN=declined
+assert_eq "json_field declines a \\u escape" "declined" "$FOREIGN"
+rm -f "$TMP/spool-data/hook-spool/foreign.json"
+
+# An unreachable server must leave the event on disk instead of dropping it.
+rm -f "$TMP/spool-data/hook-spool/"*.json
+printf '%s' '{"e":"unreachable"}' \
+ | ai_memory_post_hook "http://127.0.0.1:1/hook?event=post-tool-use&agent=cursor" >/dev/null 2>&1
+assert_eq "post_hook spools an undelivered event" "1" \
+ "$(ls "$TMP/spool-data/hook-spool/"*.json 2>/dev/null | wc -l | tr -d ' ')"
+
+unset AI_MEMORY_DATA_DIR
+
# --- summary ----------------------------------------------------------
printf '\n%d passed, %d failed\n' "$PASS" "$FAIL"
[ "$FAIL" -eq 0 ]