Skip to content

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

Rust

fix(hooks): send the [briefing] keys on the session-start handoff GET (#998)

Felipe Neves Ricardo2c0fab6155e1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 439e4426..0071b607 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Fixed
+- The shell and PowerShell session-start hooks for Claude Code, Codex,
+ Cursor, Gemini CLI, OpenCode, Command Code, Devin and Antigravity CLI now
+ send the marker's `[briefing]` keys (`briefing`, `briefing_budget`) on the
+ handoff request, so a repository with `inject_on_session_start = true` gets
+ its compiled brief at session start on script installs too, as
+ `docs/marker-file.md` describes. Only the native `ai-memory hook` command
+ and the Kiro CLI and Kimi Code scripts sent them before, so Docker and
+ `setup-agent` installs silently received the handoff without the brief.
+ (#998)
+
## [2.5.0] - 2026-09-30
### Added
diff --git a/hooks/antigravity-cli/session-start.sh b/hooks/antigravity-cli/session-start.sh
index 9dbe861f..7792c7e1 100755
--- a/hooks/antigravity-cli/session-start.sh
+++ b/hooks/antigravity-cli/session-start.sh
@@ -14,6 +14,8 @@ if ! ai_memory_antigravity_is_initial_invocation "$PAYLOAD"; then
fi
CWD=$(ai_memory_extract_cwd "$PAYLOAD")
QS=$(ai_memory_marker_qs "$CWD")
+# The `[briefing]` opt-in rides the handoff GET, as in the native hook.
+BRIEF_QS=$(ai_memory_briefing_qs "$CWD")
SESSION_ID=$(ai_memory_extract_session_id "$PAYLOAD")
SESSION_QS=""
if [ -n "$SESSION_ID" ]; then
@@ -22,7 +24,7 @@ fi
printf '%s' "$PAYLOAD" \
| ai_memory_post_hook "$SERVER/hook?event=session-start&agent=antigravity-cli${QS}" >/dev/null 2>&1 || true
-HANDOFF=$(ai_memory_get_handoff "$SERVER/handoff?agent=antigravity-cli${QS}${SESSION_QS}" 2>/dev/null || true)
+HANDOFF=$(ai_memory_get_handoff "$SERVER/handoff?agent=antigravity-cli${QS}${SESSION_QS}${BRIEF_QS}" 2>/dev/null || true)
if [ -n "$HANDOFF" ]; then
printf '{"injectSteps":[{"ephemeralMessage":'
printf '%s' "$HANDOFF" | ai_memory_json_string
diff --git a/hooks/claude-code/session-start.sh b/hooks/claude-code/session-start.sh
index 1ec0b3f8..d0c0218c 100755
--- a/hooks/claude-code/session-start.sh
+++ b/hooks/claude-code/session-start.sh
@@ -20,6 +20,8 @@ SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"
PAYLOAD=$(cat)
CWD=$(ai_memory_extract_cwd "$PAYLOAD")
QS=$(ai_memory_marker_qs "$CWD")
+# The `[briefing]` opt-in rides the handoff GET, as in the native hook.
+BRIEF_QS=$(ai_memory_briefing_qs "$CWD")
SESSION_ID=$(ai_memory_extract_session_id "$PAYLOAD")
SESSION_QS=""
[ -n "$SESSION_ID" ] && SESSION_QS="&session_id=$(ai_memory_url_encode "$SESSION_ID")"
@@ -33,7 +35,7 @@ printf '%s' "$PAYLOAD" \
# does not start with "{", so Claude Code logs every session start as
# "Hook output does not start with {, treating as plain text". JSON
# injects the same handoff with a clean debug log; no handoff -> "{}".
-HANDOFF=$(ai_memory_get_handoff "$SERVER/handoff?agent=claude-code${QS}${SESSION_QS}" 2>/dev/null || true)
+HANDOFF=$(ai_memory_get_handoff "$SERVER/handoff?agent=claude-code${QS}${SESSION_QS}${BRIEF_QS}" 2>/dev/null || true)
if [ -n "$HANDOFF" ]; then
printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":%s}}\n' \
"$(printf '%s' "$HANDOFF" | ai_memory_json_string)"
diff --git a/hooks/codex/session-start.sh b/hooks/codex/session-start.sh
index 37ccb4cc..16c7e869 100755
--- a/hooks/codex/session-start.sh
+++ b/hooks/codex/session-start.sh
@@ -14,11 +14,13 @@ SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"
PAYLOAD=$(cat)
CWD=$(ai_memory_extract_cwd "$PAYLOAD")
QS=$(ai_memory_marker_qs "$CWD")
+# The `[briefing]` opt-in rides the handoff GET, as in the native hook.
+BRIEF_QS=$(ai_memory_briefing_qs "$CWD")
SESSION_ID=$(ai_memory_extract_session_id "$PAYLOAD")
SESSION_QS=""
[ -n "$SESSION_ID" ] && SESSION_QS="&session_id=$(ai_memory_url_encode "$SESSION_ID")"
printf '%s' "$PAYLOAD" \
| ai_memory_post_hook "$SERVER/hook?event=session-start&agent=codex${QS}" >/dev/null 2>&1 || true
-ai_memory_get_handoff "$SERVER/handoff?agent=codex${QS}${SESSION_QS}" 2>/dev/null || true
+ai_memory_get_handoff "$SERVER/handoff?agent=codex${QS}${SESSION_QS}${BRIEF_QS}" 2>/dev/null || true
exit 0
diff --git a/hooks/command-code/session-start.sh b/hooks/command-code/session-start.sh
index 08a6b215..946d3dd2 100755
--- a/hooks/command-code/session-start.sh
+++ b/hooks/command-code/session-start.sh
@@ -9,6 +9,8 @@ SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"
PAYLOAD=$(cat)
CWD=$(ai_memory_extract_cwd "$PAYLOAD")
QS=$(ai_memory_marker_qs "$CWD")
+# The `[briefing]` opt-in rides the handoff GET, as in the native hook.
+BRIEF_QS=$(ai_memory_briefing_qs "$CWD")
SESSION_ID=$(ai_memory_extract_session_id "$PAYLOAD")
SESSION_QS=""
[ -n "$SESSION_ID" ] && SESSION_QS="&session_id=$(ai_memory_url_encode "$SESSION_ID")"
@@ -16,7 +18,7 @@ SESSION_QS=""
printf '%s' "$PAYLOAD" \
| ai_memory_post_hook "$SERVER/hook?event=session-start&agent=command-code${QS}" >/dev/null 2>&1 || true
-HANDOFF=$(ai_memory_get_handoff "$SERVER/handoff?agent=command-code${QS}${SESSION_QS}" 2>/dev/null || true)
+HANDOFF=$(ai_memory_get_handoff "$SERVER/handoff?agent=command-code${QS}${SESSION_QS}${BRIEF_QS}" 2>/dev/null || true)
if [ -n "$HANDOFF" ]; then
printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":%s}}\n' \
"$(printf '%s' "$HANDOFF" | ai_memory_json_string)"
diff --git a/hooks/cursor/session-start.sh b/hooks/cursor/session-start.sh
index 9652eee6..0242d948 100755
--- a/hooks/cursor/session-start.sh
+++ b/hooks/cursor/session-start.sh
@@ -14,11 +14,13 @@ SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"
PAYLOAD=$(cat)
CWD=$(ai_memory_extract_cwd "$PAYLOAD")
QS=$(ai_memory_marker_qs "$CWD")
+# The `[briefing]` opt-in rides the handoff GET, as in the native hook.
+BRIEF_QS=$(ai_memory_briefing_qs "$CWD")
SESSION_ID=$(ai_memory_extract_session_id "$PAYLOAD")
SESSION_QS=""
[ -n "$SESSION_ID" ] && SESSION_QS="&session_id=$(ai_memory_url_encode "$SESSION_ID")"
printf '%s' "$PAYLOAD" \
| ai_memory_post_hook "$SERVER/hook?event=session-start&agent=cursor${QS}" >/dev/null 2>&1 || true
-ai_memory_get_handoff "$SERVER/handoff?agent=cursor${QS}${SESSION_QS}" 2>/dev/null || true
+ai_memory_get_handoff "$SERVER/handoff?agent=cursor${QS}${SESSION_QS}${BRIEF_QS}" 2>/dev/null || true
exit 0
diff --git a/hooks/devin/session-start.sh b/hooks/devin/session-start.sh
index d3d8021c..55d11ff3 100644
--- a/hooks/devin/session-start.sh
+++ b/hooks/devin/session-start.sh
@@ -12,12 +12,14 @@ SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"
PAYLOAD=$(cat)
CWD=$(ai_memory_resolve_cwd "$PAYLOAD")
QS=$(ai_memory_marker_qs "$CWD")
+# The `[briefing]` opt-in rides the handoff GET, as in the native hook.
+BRIEF_QS=$(ai_memory_briefing_qs "$CWD")
SID_QS=$(ai_memory_session_id_qs devin session-start)
printf '%s' "$PAYLOAD" \
| ai_memory_post_hook "$SERVER/hook?event=session-start&agent=devin${QS}${SID_QS}" >/dev/null 2>&1 || true
-HANDOFF=$(ai_memory_get_handoff "$SERVER/handoff?agent=devin${QS}${SID_QS}" 2>/dev/null || true)
+HANDOFF=$(ai_memory_get_handoff "$SERVER/handoff?agent=devin${QS}${SID_QS}${BRIEF_QS}" 2>/dev/null || true)
if [ -n "$HANDOFF" ]; then
printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":%s}}\n' \
"$(printf '%s' "$HANDOFF" | ai_memory_json_string)"
diff --git a/hooks/gemini-cli/session-start.sh b/hooks/gemini-cli/session-start.sh
index 9520ad06..1655014f 100755
--- a/hooks/gemini-cli/session-start.sh
+++ b/hooks/gemini-cli/session-start.sh
@@ -14,11 +14,13 @@ SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"
PAYLOAD=$(cat)
CWD=$(ai_memory_extract_cwd "$PAYLOAD")
QS=$(ai_memory_marker_qs "$CWD")
+# The `[briefing]` opt-in rides the handoff GET, as in the native hook.
+BRIEF_QS=$(ai_memory_briefing_qs "$CWD")
SESSION_ID=$(ai_memory_extract_session_id "$PAYLOAD")
SESSION_QS=""
[ -n "$SESSION_ID" ] && SESSION_QS="&session_id=$(ai_memory_url_encode "$SESSION_ID")"
printf '%s' "$PAYLOAD" \
| ai_memory_post_hook "$SERVER/hook?event=session-start&agent=gemini-cli${QS}" >/dev/null 2>&1 || true
-ai_memory_get_handoff "$SERVER/handoff?agent=gemini-cli${QS}${SESSION_QS}" 2>/dev/null || true
+ai_memory_get_handoff "$SERVER/handoff?agent=gemini-cli${QS}${SESSION_QS}${BRIEF_QS}" 2>/dev/null || true
exit 0
diff --git a/hooks/lib/ai-memory-hook.ps1 b/hooks/lib/ai-memory-hook.ps1
index 30611af8..fb535796 100644
--- a/hooks/lib/ai-memory-hook.ps1
+++ b/hooks/lib/ai-memory-hook.ps1
@@ -584,6 +584,11 @@ function Invoke-AiMemoryHook {
if ($GrokPostTool -and -not $BriefQS) {
$BriefQS = Get-AiMemoryBriefingQuery -Cwd $Cwd
}
+ # A session-start handoff GET carries the `[briefing]` opt-in on every
+ # start, as in the native hook. Kiro keeps its own once-per-session gate.
+ if ($Event -eq "session-start" -and -not $BriefingOncePerSession) {
+ $BriefQS = Get-AiMemoryBriefingQuery -Cwd $Cwd
+ }
try {
$Response = Invoke-WebRequest `
-UseBasicParsing `
diff --git a/hooks/opencode/session-start.sh b/hooks/opencode/session-start.sh
index 98420f98..dd0456db 100755
--- a/hooks/opencode/session-start.sh
+++ b/hooks/opencode/session-start.sh
@@ -14,11 +14,13 @@ SERVER="${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}"
PAYLOAD=$(cat)
CWD=$(ai_memory_extract_cwd "$PAYLOAD")
QS=$(ai_memory_marker_qs "$CWD")
+# The `[briefing]` opt-in rides the handoff GET, as in the native hook.
+BRIEF_QS=$(ai_memory_briefing_qs "$CWD")
SESSION_ID=$(ai_memory_extract_session_id "$PAYLOAD")
SESSION_QS=""
[ -n "$SESSION_ID" ] && SESSION_QS="&session_id=$(ai_memory_url_encode "$SESSION_ID")"
printf '%s' "$PAYLOAD" \
| ai_memory_post_hook "$SERVER/hook?event=session-start&agent=open-code${QS}" >/dev/null 2>&1 || true
-ai_memory_get_handoff "$SERVER/handoff?agent=open-code${QS}${SESSION_QS}" 2>/dev/null || true
+ai_memory_get_handoff "$SERVER/handoff?agent=open-code${QS}${SESSION_QS}${BRIEF_QS}" 2>/dev/null || true
exit 0
diff --git a/tests/hooks/test_lib.sh b/tests/hooks/test_lib.sh
index ccec7453..8e92929c 100755
--- a/tests/hooks/test_lib.sh
+++ b/tests/hooks/test_lib.sh
@@ -734,6 +734,63 @@ assert_eq "a routed post is not spooled" "0" \
assert_eq "a routed handoff fetch prints nothing" "" "$ROUTED_HANDOFF"
unset AI_MEMORY_DATA_DIR
+# --- session-start bundles forward the [briefing] opt-in -----------------
+# docs/marker-file.md: when the marker opts in, the handoff GET carries
+# `briefing` and `briefing_budget`, as the native hook's does. The bundles are
+# discovered from their scripts, so a new bundle that fetches the handoff at
+# session start is held to the same contract without editing this test.
+BRIEF_REPO="$TMP/brief-on"
+PLAIN_REPO="$TMP/brief-off"
+mkdir -p "$BRIEF_REPO" "$PLAIN_REPO"
+printf '[briefing]\ninject_on_session_start = true\nmax_chars = 6000\n' >"$BRIEF_REPO/.ai-memory.toml"
+printf '[briefing]\ninject_on_session_start = false\nmax_chars = 6000\n' >"$PLAIN_REPO/.ai-memory.toml"
+
+# Runs bundle "$1" from repository "$2" with a fresh state dir and prints the
+# handoff GET it sent. The payload carries every cwd and session field the
+# bundles read, plus Antigravity's first-invocation marker.
+session_start_handoff_get() {
+ rm -rf "$TMP/brief-data" "$FAKE_CURL_LOG"
+ printf '{"cwd":"%s","workspacePaths":["%s"],"invocationNum":0,"session_id":"brief-s","conversationId":"brief-s"}' "$2" "$2" \
+ | PATH="$FAKE_CURL_BIN:$PATH" AI_MEMORY_CURL_LOG="$FAKE_CURL_LOG" \
+ AI_MEMORY_DATA_DIR="$TMP/brief-data" AI_MEMORY_HOOK_URL='http://memory.test' \
+ sh "$(dirname "$0")/../../hooks/$1/session-start.sh" >/dev/null 2>&1
+ grep '/handoff?' "$FAKE_CURL_LOG" 2>/dev/null || true
+}
+
+BRIEF_BUNDLES=0
+for script in "$(dirname "$0")"/../../hooks/*/session-start.sh; do
+ grep -q 'ai_memory_get_handoff' "$script" || continue
+ bundle=$(basename "$(dirname "$script")")
+ BRIEF_BUNDLES=$((BRIEF_BUNDLES + 1))
+ GET=$(session_start_handoff_get "$bundle" "$BRIEF_REPO")
+ case "$GET" in
+ *'&briefing=true&briefing_budget=6000'*)
+ PASS=$((PASS + 1)); printf ' ok %s\n' "$bundle: opted-in handoff GET carries the briefing keys" ;;
+ *) FAIL=$((FAIL + 1)); printf ' FAIL %s: opted-in handoff GET carries the briefing keys\n got =%s\n' "$bundle" "$GET" ;;
+ esac
+ GET=$(session_start_handoff_get "$bundle" "$PLAIN_REPO")
+ case "$GET" in
+ *'/handoff?'*briefing*)
+ FAIL=$((FAIL + 1)); printf ' FAIL %s: opted-out handoff GET omits the briefing keys\n got =%s\n' "$bundle" "$GET" ;;
+ *'/handoff?'*)
+ PASS=$((PASS + 1)); printf ' ok %s\n' "$bundle: opted-out handoff GET omits the briefing keys" ;;
+ *) FAIL=$((FAIL + 1)); printf ' FAIL %s: opted-out session start still fetches the handoff\n got =%s\n' "$bundle" "$GET" ;;
+ esac
+done
+# Guards the discovery itself: an empty glob or a renamed helper would
+# otherwise pass with nothing checked.
+assert_eq "session-start bundles that fetch the handoff were found" "yes" \
+ "$([ "$BRIEF_BUNDLES" -ge 9 ] && printf 'yes' || printf 'no (%s)' "$BRIEF_BUNDLES")"
+
+# The PowerShell bundle builds every session-start handoff GET in one place.
+PS_BRIEF_STATIC=$(grep -Fq 'if ($Event -eq "session-start" -and -not $BriefingOncePerSession) {' hooks/lib/ai-memory-hook.ps1 \
+ && awk '/if \(\$Event -eq "session-start" -and -not \$BriefingOncePerSession\)/ {f=1; next}
+ f && /Get-AiMemoryBriefingQuery -Cwd \$Cwd/ {ok=1}
+ f && /^[[:space:]]*}/ {exit}
+ END {exit !ok}' hooks/lib/ai-memory-hook.ps1 \
+ && printf 'ok' || printf 'missing')
+assert_eq "powershell session-start handoff GET carries the briefing keys" "ok" "$PS_BRIEF_STATIC"
+
# --- summary ----------------------------------------------------------
printf '\n%d passed, %d failed\n' "$PASS" "$FAIL"
[ "$FAIL" -eq 0 ]