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.mdindex 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### Addeddiff --git a/docs/install.md b/docs/install.mdindex 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 isretained, 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 startdoes a short bounded cleanup drain before fetching a handoff; cancellation-proneboundary 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 stagedscript 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 handoffis injected at `UserPromptSubmit` through the hook's stdout, which Kimi Codeappends to the model context as a user message before the turn; Kimi Codefires `SessionStart` but discards that hook's stdout, so hooks installed bydiff --git a/hooks/_lib.sh b/hooks/_lib.shindex 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=000elif [ -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=000else- 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=000fi+ 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.shindex 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 ]