@dosx/agent-memory 0.0.13

package/hooks/agent-memory-hooks/agent-memory-session.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+# agent-memory sessionStart / NewSession hook — inject context + deterministic
+# memory refresh. Captures session_id from harness stdin JSON when provided.
+# On new session: refresh current.md In progress from active-work/ + log state.
+# No-op when .agents/memory/ is absent.
+#
+# Set AGENT_MEMORY_HOST: cursor | claude | codex | copilot | opencode | gemini
+
+set -u
+
+host="${AGENT_MEMORY_HOST:-}"
+
+script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+_common_sh="$script_dir/agent-memory-common.sh"
+if [ ! -f "$_common_sh" ]; then
+  printf 'agent-memory: missing agent-memory-common.sh beside %s; install all three hooks/agent-memory-hooks/*.sh together (see hooks/README.md)\n' \
+    "$(basename -- "$0")" >&2
+  exit 0
+fi
+# shellcheck source=agent-memory-common.sh
+. "$_common_sh"
+
+agent_memory_init_context || exit 0
+
+[ -d "$memory" ] || exit 0
+
+session_id=$(resolve_session_id "$hook_stdin_session_id" 0)
+[ -n "$session_id" ] || write_state current_session_id ""
+persist_session_id "$session_id"
+reset_logged_files_if_session_changed "$session_id" sessionStart
+
+# New session: ensure active-work, log heading, current.md in-progress list.
+if command -v git >/dev/null 2>&1 && git -C "$cwd" rev-parse --git-dir >/dev/null 2>&1; then
+  refresh_branch_cache
+  aw=$(ensure_active_work)
+  update_task_stub "$aw"
+  ensure_session_log_heading "$session_id" sessionStart
+  refresh_current_in_progress
+fi
+
+msg="Agent Memory (.agents/memory/). Before tasks: read instructions.md, index.md, current.md, and your branch active-work file. As you work: refine active-work Task/Progress, append semantic bullets under the current session heading in log.md, and record every architecture/design decision in decisions.md. Hooks keep Touched files, log file-bullets, and current.md In progress synced — you own task meaning, log type/summary, and decisions.md. Run /agent-memory sync at checkpoints (end of task, before commit/compaction)."
+
+json_escape() {
+  local s=$1
+  s=${s//\\/\\\\}
+  s=${s//\"/\\\"}
+  s=${s//$'\n'/\\n}
+  s=${s//$'\r'/\\r}
+  s=${s//$'\t'/\\t}
+  printf '%s' "$s"
+}
+
+case "$host" in
+  cursor)
+    if [ -n "$session_id" ]; then
+      printf '{"env":{"AGENT_MEMORY_SESSION_ID":"%s"},"additional_context":"%s"}\n' \
+        "$(json_escape "$session_id")" "$(json_escape "$msg")"
+    else
+      printf '{"additional_context":"%s"}\n' "$(json_escape "$msg")"
+    fi
+    ;;
+  claude)
+    if [ -n "$session_id" ]; then
+      printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"},"env":{"AGENT_MEMORY_SESSION_ID":"%s"}}\n' \
+        "$(json_escape "$msg")" "$(json_escape "$session_id")"
+    else
+      printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' \
+        "$(json_escape "$msg")"
+    fi
+    ;;
+  codex)
+    [ -n "$session_id" ] && export AGENT_MEMORY_SESSION_ID="$session_id"
+    printf '%s\n' "$msg"
+    ;;
+  copilot)
+    if [ -n "$session_id" ]; then
+      printf '{"additionalContext":"%s","env":{"AGENT_MEMORY_SESSION_ID":"%s"}}\n' \
+        "$(json_escape "$msg")" "$(json_escape "$session_id")"
+    else
+      printf '{"additionalContext":"%s"}\n' "$(json_escape "$msg")"
+    fi
+    ;;
+  opencode)
+    [ -n "$session_id" ] && export AGENT_MEMORY_SESSION_ID="$session_id"
+    printf '%s\n' "$msg"
+    ;;
+  gemini)
+    # Gemini CLI requires strict JSON-only stdout for hooks (no stray text).
+    # We return the memory guidance as context. The deterministic work
+    # (heading, current.md, etc.) happens as side effects before this output.
+    printf '{"context":"%s"}\n' "$(json_escape "$msg")"
+    ;;
+  *)
+    [ -n "$session_id" ] && export AGENT_MEMORY_SESSION_ID="$session_id"
+    printf '%s\n' "$msg"
+    ;;
+esac
+exit 0

package/hooks/agent-memory-hooks/agent-memory-sync.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+# agent-memory deterministic checkpoint (all harnesses).
+#
+# Evidence-backed updates from git + session ID — no LLM, no invented semantics.
+# Maintains: active-work (Touched files, Task stub), log.md (session heading +
+# file-change bullets on full checkpoints). current.md is refreshed on sessionStart only.
+#
+# Reads harness stdin JSON when present (session_id, cwd, tool_name,
+# tool_input.file_path / tool_input.path / file_path — Claude, Cursor, Copilot,
+# Codex, Gemini). Session ID also from AGENT_MEMORY_SESSION_ID env or state.
+#
+# Set AGENT_MEMORY_EVENT (any host naming):
+#   postToolUse | PostToolUse | AfterTool | afterFileEdit
+#       — accumulate touched paths from stdin (git-free; no log.md bullets)
+#   afterAgentResponse | Stop | agentStop | AfterAgent — end of turn; full git
+#       reconciliation (session-cumulative Touched files, log bullets)
+#   preCompact | PreCompact | precommit | PreCompress — before compaction or
+#       git commit; same as afterAgentResponse
+#
+# Git runs only at afterAgentResponse/preCompact (+ sessionStart in session.sh);
+# postToolUse/afterFileEdit use the branch cache and stdin file path only.
+#
+# Install per host — see hooks/README.md.
+
+set -u
+
+script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+_common_sh="$script_dir/agent-memory-common.sh"
+if [ ! -f "$_common_sh" ]; then
+  printf 'agent-memory: missing agent-memory-common.sh beside %s; install all three hooks/agent-memory-hooks/*.sh together (see hooks/README.md)\n' \
+    "$(basename -- "$0")" >&2
+  exit 0
+fi
+# shellcheck source=agent-memory-common.sh
+. "$_common_sh"
+
+raw_event="${AGENT_MEMORY_EVENT:-afterAgentResponse}"
+case "$raw_event" in
+  postToolUse|PostToolUse|posttool|AfterTool|aftertool|afterFileEdit|afterfileedit)
+    event=postToolUse
+    ;;
+  afterAgentResponse|Stop|stop|agentStop|afterresponse|AfterAgent|afteragent)
+    event=afterAgentResponse
+    ;;
+  preCompact|PreCompact|precompact|precommit|PreCompress|precompress)
+    event=preCompact
+    ;;
+  *) event=afterAgentResponse ;;
+esac
+
+agent_memory_init_context || exit 0
+
+[ -d "$memory" ] || exit 0
+command -v git >/dev/null 2>&1 || exit 0
+git -C "$cwd" rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+# Normalize harness file path to a repo-relative path, or return non-zero to skip.
+normalize_repo_rel_path() {
+  local rel=$1
+  case "$rel" in
+    *$'\n'* | *$'\r'* | *$'\x1e'*) return 1 ;;
+  esac
+  case "$rel" in
+    "$cwd"/*) rel=${rel#"$cwd"/} ;;
+    /*) return 1 ;;
+  esac
+  case "$rel" in
+    .agents/memory/*) return 1 ;;
+  esac
+  case "/$rel/" in
+    */../*) return 1 ;;
+  esac
+  [ -n "$rel" ] || return 1
+  printf '%s' "$rel"
+}
+
+case "$event" in
+  postToolUse)
+    agent_memory_include_commit_files=0
+    [ -n "$hook_stdin_tool_file" ] || exit 0
+    run_posttool_checkpoint "$hook_stdin_tool_file"
+    exit 0
+    ;;
+esac
+
+session_id=$(resolve_session_id "$hook_stdin_session_id")
+log_session_id=$(normalize_session_id_for_checkpoint "$session_id")
+persist_session_id "$session_id"
+
+mark_head_processed() {
+  local current_head
+  current_head=$(git -C "$cwd" rev-parse HEAD 2>/dev/null || true)
+  [ -n "$current_head" ] || return 0
+  write_state last_processed_head "$current_head"
+}
+
+# Git-free: merge stdin path into session touched set; no log.md bullets.
+run_posttool_checkpoint() {
+  local rel=$1 aw accumulated
+  rel=$(normalize_repo_rel_path "$rel") || return 0
+  accumulated=$(read_state session_touched_files "")
+  file_already_logged "$rel" "$accumulated" && return 0
+  aw=$(ensure_active_work)
+  add_touched_file "$aw" "$rel"
+  update_task_stub "$aw"
+}
+
+run_full_checkpoint() {
+  local list_file=$1 aw resolved_sid filtered_tmp
+  aw=$(ensure_active_work)
+  update_task_stub "$aw"
+  resolved_sid=$(ensure_log_heading_for_checkpoint "$log_session_id")
+  if [ -s "$list_file" ]; then
+    filtered_tmp=$(mktemp)
+    while IFS= read -r f || [ -n "$f" ]; do
+      [ -n "$f" ] || continue
+      f=$(normalize_repo_rel_path "$f") || continue
+      printf '%s\n' "$f" >>"$filtered_tmp"
+    done <"$list_file"
+    if [ -s "$filtered_tmp" ]; then
+      update_touched_files "$aw" "$filtered_tmp"
+      append_log_file_bullets "$resolved_sid" "$filtered_tmp"
+    else
+      write_active_work_touched_from_session "$aw"
+    fi
+    rm -f "$filtered_tmp"
+  else
+    write_active_work_touched_from_session "$aw"
+  fi
+}
+
+case "$event" in
+  afterAgentResponse|preCompact)
+    agent_memory_include_commit_files=1
+    refresh_branch_cache
+    list_tmp=$(mktemp)
+    list_non_memory_changes >"$list_tmp"
+    run_full_checkpoint "$list_tmp"
+    rm -f "$list_tmp"
+    mark_head_processed
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+exit 0

package/hooks/claude-code/settings.json

@@ -0,0 +1,51 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_MEMORY_HOST=claude .claude/hooks/agent-memory-session.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_MEMORY_EVENT=PostToolUse .claude/hooks/agent-memory-sync.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_MEMORY_EVENT=Stop .claude/hooks/agent-memory-sync.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "auto|manual",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_MEMORY_EVENT=PreCompact .claude/hooks/agent-memory-sync.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/codex/config.toml.snippet

@@ -0,0 +1,38 @@
+# Codex hooks can live in a sidecar hooks.json (see hooks.json) OR inline in
+# config.toml under [hooks]. Inline form (project: .codex/config.toml):
+#
+#   [features]
+#   hooks = true   # enabled by default
+#
+# Copy hooks/agent-memory-hooks/agent-memory-sync.sh and agent-memory-session.sh to
+# .codex/hooks/ first (see hooks/README.md).
+#
+#   [[hooks.SessionStart]]
+#   matcher = "startup|resume"
+#     [[hooks.SessionStart.hooks]]
+#     type    = "command"
+#     command = ["sh", "-c", "AGENT_MEMORY_HOST=codex .codex/hooks/agent-memory-session.sh"]
+#     timeout = 5
+#
+#   [[hooks.PostToolUse]]
+#   matcher = "Bash|apply_patch"
+#     [[hooks.PostToolUse.hooks]]
+#     type    = "command"
+#     command = ["sh", "-c", "AGENT_MEMORY_EVENT=PostToolUse .codex/hooks/agent-memory-sync.sh"]
+#     timeout = 15
+#
+#   [[hooks.Stop]]
+#     [[hooks.Stop.hooks]]
+#     type    = "command"
+#     command = ["sh", "-c", "AGENT_MEMORY_EVENT=Stop .codex/hooks/agent-memory-sync.sh"]
+#     timeout = 15
+#
+#   [[hooks.PreCompact]]
+#   matcher = "auto|manual"
+#     [[hooks.PreCompact.hooks]]
+#     type    = "command"
+#     command = ["sh", "-c", "AGENT_MEMORY_EVENT=PreCompact .codex/hooks/agent-memory-sync.sh"]
+#     timeout = 15
+#
+# After adding project hooks, run `/hooks` in the Codex TUI to trust them.
+# Codex hooks are disabled on Windows.

package/hooks/codex/hooks.json

@@ -0,0 +1,51 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_MEMORY_HOST=codex .codex/hooks/agent-memory-session.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash|apply_patch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_MEMORY_EVENT=PostToolUse .codex/hooks/agent-memory-sync.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_MEMORY_EVENT=Stop .codex/hooks/agent-memory-sync.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "auto|manual",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_MEMORY_EVENT=PreCompact .codex/hooks/agent-memory-sync.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/copilot/agent-memory.json

@@ -0,0 +1,34 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "type": "command",
+        "bash": "AGENT_MEMORY_HOST=copilot .github/hooks/agent-memory-session.sh",
+        "timeoutSec": 5
+      }
+    ],
+    "postToolUse": [
+      {
+        "type": "command",
+        "bash": "AGENT_MEMORY_EVENT=postToolUse .github/hooks/agent-memory-sync.sh",
+        "matcher": "bash|edit|write|apply_patch",
+        "timeoutSec": 15
+      }
+    ],
+    "agentStop": [
+      {
+        "type": "command",
+        "bash": "AGENT_MEMORY_EVENT=agentStop .github/hooks/agent-memory-sync.sh",
+        "timeoutSec": 15
+      }
+    ],
+    "preCompact": [
+      {
+        "type": "command",
+        "bash": "AGENT_MEMORY_EVENT=preCompact .github/hooks/agent-memory-sync.sh",
+        "timeoutSec": 15
+      }
+    ]
+  }
+}

package/hooks/cursor/hooks.json

@@ -0,0 +1,36 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "AGENT_MEMORY_HOST=cursor .cursor/hooks/agent-memory-session.sh",
+        "timeout": 5
+      }
+    ],
+    "postToolUse": [
+      {
+        "command": "AGENT_MEMORY_EVENT=postToolUse .cursor/hooks/agent-memory-sync.sh",
+        "matcher": "Write|Shell",
+        "timeout": 15
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "command": "AGENT_MEMORY_EVENT=afterFileEdit .cursor/hooks/agent-memory-sync.sh",
+        "timeout": 15
+      }
+    ],
+    "afterAgentResponse": [
+      {
+        "command": "AGENT_MEMORY_EVENT=afterAgentResponse .cursor/hooks/agent-memory-sync.sh",
+        "timeout": 15
+      }
+    ],
+    "preCompact": [
+      {
+        "command": "AGENT_MEMORY_EVENT=preCompact .cursor/hooks/agent-memory-sync.sh",
+        "timeout": 15
+      }
+    ]
+  }
+}

package/hooks/gemini/settings.json

@@ -0,0 +1,50 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_MEMORY_HOST=gemini .gemini/hooks/agent-memory-session.sh",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "AfterTool": [
+      {
+        "matcher": "write_file|edit|shell|bash|apply_patch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_MEMORY_EVENT=AfterTool .gemini/hooks/agent-memory-sync.sh",
+            "timeout": 15000
+          }
+        ]
+      }
+    ],
+    "AfterAgent": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_MEMORY_EVENT=AfterAgent .gemini/hooks/agent-memory-sync.sh",
+            "timeout": 15000
+          }
+        ]
+      }
+    ],
+    "PreCompress": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_MEMORY_EVENT=PreCompress .gemini/hooks/agent-memory-sync.sh",
+            "timeout": 15000
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/git/pre-commit

@@ -0,0 +1,45 @@
+#!/bin/sh
+# agent-memory git pre-commit hook (host-agnostic).
+#
+# Runs the deterministic sync script when co-installed, then reminds when
+# staged work has no .agents/memory/ change (semantic fields may still need
+# /agent-memory sync). Never blocks the commit. Fails open.
+#
+# Install:
+#   cp hooks/git/pre-commit .git/hooks/pre-commit
+#   cp hooks/agent-memory-hooks/agent-memory-*.sh .git/hooks/
+#   chmod +x .git/hooks/pre-commit .git/hooks/agent-memory-*.sh
+
+# GIT_PREFIX is the subdirectory where the user ran `git commit`, not the repo
+# root — never use it as PROJECT_DIR (would skip memory when committing from src/).
+cwd=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+[ -d "$cwd/.agents/memory" ] || exit 0
+
+hook_dir=$(dirname "$0")
+if [ -x "$hook_dir/agent-memory-sync.sh" ]; then
+  AGENT_MEMORY_EVENT=precommit AGENT_MEMORY_PROJECT_DIR="$cwd" "$hook_dir/agent-memory-sync.sh" || true
+fi
+
+staged=$(git diff --cached --name-only 2>/dev/null | grep -v '^\.agents/memory/' || true)
+[ -n "$staged" ] || exit 0
+
+# Branch sanitization must mirror common.sh:sanitize_branch so the reminder
+# path matches the file ensure_active_work writes. (This hook is /bin/sh and
+# does not source common.sh, so the logic is duplicated by necessity.)
+branch=$(git branch --show-current 2>/dev/null)
+branch=$(printf '%s' "$branch" | tr -c 'A-Za-z0-9._-' '-')
+[ -n "$branch" ] || branch="local"
+
+memory_staged=$(git diff --cached --name-only 2>/dev/null | grep '^\.agents/memory/' || true)
+
+if [ -z "$memory_staged" ]; then
+  cat <<EOF
+
+[agent-memory] Staged work on branch '$branch' but no .agents/memory/ change in this commit.
+Hooks updated Touched files from git; review task/progress in
+\`.agents/memory/active-work/$branch.md\` and run \`/agent-memory sync\` if needed.
+(This is a reminder, not a block — the commit will proceed.)
+
+EOF
+fi
+exit 0