Skip to content

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

Rust

feat(hooks): claude-code scripts walk-up .ai-memory.toml

Pablo Winterdd7c5f6a5fd9
diff --git a/hooks/claude-code/_lib.sh b/hooks/claude-code/_lib.sh
new file mode 100644
index 00000000..9dd9bb58
--- /dev/null
+++ b/hooks/claude-code/_lib.sh
@@ -0,0 +1,74 @@
+# COPY of ../_lib.sh — do not edit directly.
+# Source of truth: hooks/_lib.sh.
+# Keep in sync by re-running install-hooks or copying manually.
+# ai-memory hook helper — find marker file + parse minimal TOML.
+# Sourced by per-agent lifecycle hook scripts. POSIX shell only —
+# no bash-isms, no external deps (no jq, no toml crate). Keep changes
+# byte-trivial because every supported agent (claude-code, codex,
+# cursor, gemini-cli, opencode, omp) sources this same file.
+
+# Walk up from "$1" toward $HOME (or /) looking for `.ai-memory.toml`.
+# Prints the absolute path of the first marker found, or nothing.
+# Stops at $HOME to avoid leaking declarations from a shared system
+# user's home into another user's session on multi-user boxes.
+ai_memory_find_marker() {
+ dir="$1"
+ [ -z "$dir" ] && return 0
+ while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+ if [ -f "$dir/.ai-memory.toml" ]; then
+ printf '%s\n' "$dir/.ai-memory.toml"
+ return 0
+ fi
+ if [ -n "${HOME:-}" ] && [ "$dir" = "$HOME" ]; then
+ return 0
+ fi
+ parent=$(dirname "$dir")
+ [ "$parent" = "$dir" ] && return 0
+ dir="$parent"
+ done
+}
+
+# Parse `key = "value"` at the TOML root (no nesting, no arrays, no
+# tables). Returns the first match or nothing. Ignores comments and
+# blank lines by construction (the regex only matches the `key = "..."`
+# shape).
+ai_memory_parse_toml_key() {
+ file="$1"; key="$2"
+ [ -f "$file" ] || return 0
+ sed -n -E "s/^[[:space:]]*${key}[[:space:]]*=[[:space:]]*\"([^\"]*)\".*/\1/p" \
+ "$file" | head -n 1
+}
+
+# Extract `cwd` from a JSON payload on stdin or in $1. Returns the
+# value or nothing. Tolerates leading whitespace and escaped quotes
+# inside other keys by anchoring on the `cwd` key explicitly.
+ai_memory_extract_cwd() {
+ payload="${1:-$(cat)}"
+ printf '%s' "$payload" \
+ | sed -n -E 's/.*"cwd"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p' \
+ | head -n 1
+}
+
+# URL-encode the minimal set of characters that have meaning in a query
+# string. Sufficient for the schema's value regex (`^[a-z0-9][a-z0-9._-]*$`)
+# plus a defensive pass for anything a hand-edited marker might contain.
+ai_memory_url_encode() {
+ printf '%s' "$1" \
+ | sed 's/%/%25/g; s/&/%26/g; s/=/%3D/g; s/?/%3F/g; s/#/%23/g; s/ /%20/g'
+}
+
+# Build a `&workspace=X&project=Y` suffix from the marker file walked up
+# from "$1". Returns the suffix (with the leading `&`) or nothing. The
+# server tolerates either key being absent.
+ai_memory_marker_qs() {
+ cwd="$1"
+ [ -z "$cwd" ] && return 0
+ marker=$(ai_memory_find_marker "$cwd")
+ [ -z "$marker" ] && return 0
+ ws=$(ai_memory_parse_toml_key "$marker" workspace)
+ pr=$(ai_memory_parse_toml_key "$marker" project)
+ qs=""
+ [ -n "$ws" ] && qs="${qs}&workspace=$(ai_memory_url_encode "$ws")"
+ [ -n "$pr" ] && qs="${qs}&project=$(ai_memory_url_encode "$pr")"
+ printf '%s' "$qs"
+}
diff --git a/hooks/claude-code/post-tool-use.sh b/hooks/claude-code/post-tool-use.sh
index 462037b6..3fbb9c74 100755
--- a/hooks/claude-code/post-tool-use.sh
+++ b/hooks/claude-code/post-tool-use.sh
@@ -1,9 +1,17 @@
#!/bin/sh
# Claude Code post-tool-use hook.
-# Forwards the event JSON to the ai-memory server. Adds an
-# Authorization: Bearer header when AI_MEMORY_AUTH_TOKEN is set in
-# this hook's environment (set it via install-hooks --auth-token).
+# Forwards the event JSON to the ai-memory server, fire-and-forget.
+# Walks up from the payload's cwd for a .ai-memory.toml marker file;
+# if found, appends `&workspace=X&project=Y` to the URL so the server
+# routes the event to the declared workspace/project pair instead of
+# bucketing by basename(cwd) under the default workspace.
+. "$(dirname "$0")/_lib.sh"
+
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")
+
post_hook() {
if [ -n "${AI_MEMORY_AUTH_TOKEN:-}" ]; then
curl -s --max-time 0.5 -X POST "$1" \
@@ -16,5 +24,7 @@ post_hook() {
--data-binary @-
fi
}
-post_hook "$SERVER/hook?event=post-tool-use&agent=claude-code" >/dev/null 2>&1 || true
+
+printf '%s' "$PAYLOAD" \
+ | post_hook "$SERVER/hook?event=post-tool-use&agent=claude-code${QS}" >/dev/null 2>&1 || true
exit 0
diff --git a/hooks/claude-code/pre-compact.sh b/hooks/claude-code/pre-compact.sh
index 3c97d83e..f1dda770 100755
--- a/hooks/claude-code/pre-compact.sh
+++ b/hooks/claude-code/pre-compact.sh
@@ -1,9 +1,17 @@
#!/bin/sh
# Claude Code pre-compact hook.
-# Forwards the event JSON to the ai-memory server. Adds an
-# Authorization: Bearer header when AI_MEMORY_AUTH_TOKEN is set in
-# this hook's environment (set it via install-hooks --auth-token).
+# Forwards the event JSON to the ai-memory server, fire-and-forget.
+# Walks up from the payload's cwd for a .ai-memory.toml marker file;
+# if found, appends `&workspace=X&project=Y` to the URL so the server
+# routes the event to the declared workspace/project pair instead of
+# bucketing by basename(cwd) under the default workspace.
+. "$(dirname "$0")/_lib.sh"
+
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")
+
post_hook() {
if [ -n "${AI_MEMORY_AUTH_TOKEN:-}" ]; then
curl -s --max-time 0.5 -X POST "$1" \
@@ -16,5 +24,7 @@ post_hook() {
--data-binary @-
fi
}
-post_hook "$SERVER/hook?event=pre-compact&agent=claude-code" >/dev/null 2>&1 || true
+
+printf '%s' "$PAYLOAD" \
+ | post_hook "$SERVER/hook?event=pre-compact&agent=claude-code${QS}" >/dev/null 2>&1 || true
exit 0
diff --git a/hooks/claude-code/pre-tool-use.sh b/hooks/claude-code/pre-tool-use.sh
index 020cf3a1..e288467d 100755
--- a/hooks/claude-code/pre-tool-use.sh
+++ b/hooks/claude-code/pre-tool-use.sh
@@ -1,9 +1,17 @@
#!/bin/sh
# Claude Code pre-tool-use hook.
-# Forwards the event JSON to the ai-memory server. Adds an
-# Authorization: Bearer header when AI_MEMORY_AUTH_TOKEN is set in
-# this hook's environment (set it via install-hooks --auth-token).
+# Forwards the event JSON to the ai-memory server, fire-and-forget.
+# Walks up from the payload's cwd for a .ai-memory.toml marker file;
+# if found, appends `&workspace=X&project=Y` to the URL so the server
+# routes the event to the declared workspace/project pair instead of
+# bucketing by basename(cwd) under the default workspace.
+. "$(dirname "$0")/_lib.sh"
+
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")
+
post_hook() {
if [ -n "${AI_MEMORY_AUTH_TOKEN:-}" ]; then
curl -s --max-time 0.5 -X POST "$1" \
@@ -16,5 +24,7 @@ post_hook() {
--data-binary @-
fi
}
-post_hook "$SERVER/hook?event=pre-tool-use&agent=claude-code" >/dev/null 2>&1 || true
+
+printf '%s' "$PAYLOAD" \
+ | post_hook "$SERVER/hook?event=pre-tool-use&agent=claude-code${QS}" >/dev/null 2>&1 || true
exit 0
diff --git a/hooks/claude-code/session-end.sh b/hooks/claude-code/session-end.sh
index 6c55b6df..45e51b13 100755
--- a/hooks/claude-code/session-end.sh
+++ b/hooks/claude-code/session-end.sh
@@ -1,9 +1,17 @@
#!/bin/sh
# Claude Code session-end hook.
-# Forwards the event JSON to the ai-memory server. Adds an
-# Authorization: Bearer header when AI_MEMORY_AUTH_TOKEN is set in
-# this hook's environment (set it via install-hooks --auth-token).
+# Forwards the event JSON to the ai-memory server, fire-and-forget.
+# Walks up from the payload's cwd for a .ai-memory.toml marker file;
+# if found, appends `&workspace=X&project=Y` to the URL so the server
+# routes the event to the declared workspace/project pair instead of
+# bucketing by basename(cwd) under the default workspace.
+. "$(dirname "$0")/_lib.sh"
+
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")
+
post_hook() {
if [ -n "${AI_MEMORY_AUTH_TOKEN:-}" ]; then
curl -s --max-time 0.5 -X POST "$1" \
@@ -16,5 +24,7 @@ post_hook() {
--data-binary @-
fi
}
-post_hook "$SERVER/hook?event=session-end&agent=claude-code" >/dev/null 2>&1 || true
+
+printf '%s' "$PAYLOAD" \
+ | post_hook "$SERVER/hook?event=session-end&agent=claude-code${QS}" >/dev/null 2>&1 || true
exit 0
diff --git a/hooks/claude-code/session-start.sh b/hooks/claude-code/session-start.sh
index ce064db9..cefa4077 100755
--- a/hooks/claude-code/session-start.sh
+++ b/hooks/claude-code/session-start.sh
@@ -1,16 +1,22 @@
#!/bin/sh
# Claude Code SessionStart hook.
-#
# 1. Forwards the event JSON to the ai-memory server (fire-and-forget).
-# 2. Synchronously fetches any pending cross-agent handoff and prints
-# it to stdout — agent CLIs prepend session-start hook stdout to
-# the next session, so the resuming agent sees prior context with
-# no human in the loop.
+# 2. Synchronously fetches the pending cross-agent handoff and prints
+# it to stdout — Claude Code prepends `session-start` stdout to the
+# next session, so the resuming agent sees prior context with no
+# human in the loop.
#
-# Both calls carry an Authorization: Bearer header when
-# AI_MEMORY_AUTH_TOKEN is set in this hook's environment.
+# Walks up from the payload's cwd for a .ai-memory.toml marker file
+# and appends `&workspace=X&project=Y` to both URLs when found, so the
+# handoff lookup hits the workspace declared by the marker (otherwise
+# a session resuming under a marker would never see the handoff stored
+# under `default`).
+. "$(dirname "$0")/_lib.sh"
+
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")
post_hook() {
if [ -n "${AI_MEMORY_AUTH_TOKEN:-}" ]; then
@@ -34,6 +40,8 @@ get_handoff() {
fi
}
-echo "$PAYLOAD" | post_hook "$SERVER/hook?event=session-start&agent=claude-code" >/dev/null 2>&1 || true
-get_handoff "$SERVER/handoff?agent=claude-code" 2>/dev/null || true
+printf '%s' "$PAYLOAD" \
+ | post_hook "$SERVER/hook?event=session-start&agent=claude-code${QS}" >/dev/null 2>&1 || true
+
+get_handoff "$SERVER/handoff?agent=claude-code${QS}" 2>/dev/null || true
exit 0
diff --git a/hooks/claude-code/stop.sh b/hooks/claude-code/stop.sh
index f748c088..d1bbf263 100755
--- a/hooks/claude-code/stop.sh
+++ b/hooks/claude-code/stop.sh
@@ -1,9 +1,17 @@
#!/bin/sh
# Claude Code stop hook.
-# Forwards the event JSON to the ai-memory server. Adds an
-# Authorization: Bearer header when AI_MEMORY_AUTH_TOKEN is set in
-# this hook's environment (set it via install-hooks --auth-token).
+# Forwards the event JSON to the ai-memory server, fire-and-forget.
+# Walks up from the payload's cwd for a .ai-memory.toml marker file;
+# if found, appends `&workspace=X&project=Y` to the URL so the server
+# routes the event to the declared workspace/project pair instead of
+# bucketing by basename(cwd) under the default workspace.
+. "$(dirname "$0")/_lib.sh"
+
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")
+
post_hook() {
if [ -n "${AI_MEMORY_AUTH_TOKEN:-}" ]; then
curl -s --max-time 0.5 -X POST "$1" \
@@ -16,5 +24,7 @@ post_hook() {
--data-binary @-
fi
}
-post_hook "$SERVER/hook?event=stop&agent=claude-code" >/dev/null 2>&1 || true
+
+printf '%s' "$PAYLOAD" \
+ | post_hook "$SERVER/hook?event=stop&agent=claude-code${QS}" >/dev/null 2>&1 || true
exit 0
diff --git a/hooks/claude-code/user-prompt-submit.sh b/hooks/claude-code/user-prompt-submit.sh
index a77a41e8..eb1de011 100755
--- a/hooks/claude-code/user-prompt-submit.sh
+++ b/hooks/claude-code/user-prompt-submit.sh
@@ -1,9 +1,17 @@
#!/bin/sh
# Claude Code user-prompt hook.
-# Forwards the event JSON to the ai-memory server. Adds an
-# Authorization: Bearer header when AI_MEMORY_AUTH_TOKEN is set in
-# this hook's environment (set it via install-hooks --auth-token).
+# Forwards the event JSON to the ai-memory server, fire-and-forget.
+# Walks up from the payload's cwd for a .ai-memory.toml marker file;
+# if found, appends `&workspace=X&project=Y` to the URL so the server
+# routes the event to the declared workspace/project pair instead of
+# bucketing by basename(cwd) under the default workspace.
+. "$(dirname "$0")/_lib.sh"
+
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")
+
post_hook() {
if [ -n "${AI_MEMORY_AUTH_TOKEN:-}" ]; then
curl -s --max-time 0.5 -X POST "$1" \
@@ -16,5 +24,7 @@ post_hook() {
--data-binary @-
fi
}
-post_hook "$SERVER/hook?event=user-prompt&agent=claude-code" >/dev/null 2>&1 || true
+
+printf '%s' "$PAYLOAD" \
+ | post_hook "$SERVER/hook?event=user-prompt&agent=claude-code${QS}" >/dev/null 2>&1 || true
exit 0