termify-agent 1.0.39 → 1.0.41

package/plugins/memsearch/hooks/common.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# Shared setup for memsearch command hooks.
+# Sourced by all hook scripts — not executed directly.
+
+set -euo pipefail
+
+# Read stdin JSON into $INPUT
+INPUT="$(cat)"
+
+# Ensure common user bin paths are in PATH (hooks may run in a minimal env)
+for p in "$HOME/.local/bin" "$HOME/.cargo/bin" "$HOME/bin" "/usr/local/bin"; do
+  [[ -d "$p" ]] && [[ ":$PATH:" != *":$p:"* ]] && export PATH="$p:$PATH"
+done
+
+# Memory directory and memsearch state directory are project-scoped
+MEMSEARCH_DIR="${CLAUDE_PROJECT_DIR:-.}/.memsearch"
+MEMORY_DIR="$MEMSEARCH_DIR/memory"
+
+# Find memsearch binary: prefer PATH, fallback to uvx
+_detect_memsearch() {
+  MEMSEARCH_CMD=""
+  if command -v memsearch &>/dev/null; then
+    MEMSEARCH_CMD="memsearch"
+  elif command -v uvx &>/dev/null; then
+    MEMSEARCH_CMD="uvx memsearch"
+  fi
+}
+_detect_memsearch
+
+# Short command prefix for injected instructions (falls back to "memsearch" even if unavailable)
+MEMSEARCH_CMD_PREFIX="${MEMSEARCH_CMD:-memsearch}"
+
+# Derive per-project collection name from project directory
+COLLECTION_NAME=$("$(dirname "${BASH_SOURCE[0]}")/../scripts/derive-collection.sh" "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null || true)
+
+# --- JSON helpers (jq preferred, python3 fallback) ---
+
+# _json_val <json_string> <dotted_key> [default]
+# Extract a value from JSON. Key supports dotted notation (e.g. "info.version").
+# Returns the default (or empty string) if the key is missing or extraction fails.
+_json_val() {
+  local json="$1" key="$2" default="${3:-}"
+  local result=""
+
+  if command -v jq &>/dev/null; then
+    # Build jq filter from dotted key: "info.version" → ".info.version"
+    result=$(printf '%s' "$json" | jq -r ".${key} // empty" 2>/dev/null) || true
+  else
+    result=$(python3 -c "
+import json, sys
+try:
+    obj = json.loads(sys.argv[1])
+    val = obj
+    for k in sys.argv[2].split('.'):
+        val = val[k]
+    if val is None:
+        print('')
+    elif isinstance(val, bool):
+        print(str(val).lower())
+    else:
+        print(val)
+except Exception:
+    print('')
+" "$json" "$key" 2>/dev/null) || true
+  fi
+
+  if [ -z "$result" ]; then
+    printf '%s' "$default"
+  else
+    printf '%s' "$result"
+  fi
+  return 0
+}
+
+# _json_encode_str <string>
+# Encode a string as a JSON string (with surrounding quotes).
+_json_encode_str() {
+  local str="$1"
+  if command -v jq &>/dev/null; then
+    printf '%s' "$str" | jq -Rs . 2>/dev/null && return 0
+  fi
+  printf '%s' "$str" | python3 -c "import json,sys; print(json.dumps(sys.stdin.read()))" 2>/dev/null && return 0
+  # Last resort: simple quoting (no special char escaping)
+  printf '"%s"' "$str"
+  return 0
+}
+
+# Helper: ensure memory directory exists
+ensure_memory_dir() {
+  mkdir -p "$MEMORY_DIR"
+}
+
+# Helper: run memsearch with arguments, silently fail if not available
+run_memsearch() {
+  if [ -n "$MEMSEARCH_CMD" ] && [ -n "$COLLECTION_NAME" ]; then
+    $MEMSEARCH_CMD "$@" --collection "$COLLECTION_NAME" 2>/dev/null || true
+  elif [ -n "$MEMSEARCH_CMD" ]; then
+    $MEMSEARCH_CMD "$@" 2>/dev/null || true
+  fi
+}
+
+# --- Watch singleton management ---
+
+WATCH_PIDFILE="$MEMSEARCH_DIR/.watch.pid"
+
+# Kill a process and its entire process group to avoid orphans
+_kill_tree() {
+  local pid="$1"
+  # Kill the process group (negative PID) to catch child processes
+  kill -- -"$pid" 2>/dev/null || kill "$pid" 2>/dev/null || true
+}
+
+# Stop the watch process: pidfile first, then sweep for orphans
+stop_watch() {
+  # 1. Kill the process recorded in pidfile
+  if [ -f "$WATCH_PIDFILE" ]; then
+    local pid
+    pid=$(cat "$WATCH_PIDFILE" 2>/dev/null)
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+      _kill_tree "$pid"
+    fi
+    rm -f "$WATCH_PIDFILE"
+  fi
+
+  # 2. Sweep for orphaned watch processes targeting this MEMORY_DIR
+  local orphans
+  orphans=$(pgrep -f "memsearch watch $MEMORY_DIR" 2>/dev/null || true)
+  if [ -n "$orphans" ]; then
+    echo "$orphans" | while read -r opid; do
+      kill "$opid" 2>/dev/null || true
+    done
+  fi
+}
+
+# Start memsearch watch — always stop-then-start to pick up config changes
+start_watch() {
+  if [ -z "$MEMSEARCH_CMD" ]; then
+    return 0
+  fi
+  ensure_memory_dir
+
+  # Always restart: ensures latest config (milvus_uri, etc.) is used
+  stop_watch
+
+  if [ -n "$COLLECTION_NAME" ]; then
+    nohup $MEMSEARCH_CMD watch "$MEMORY_DIR" --collection "$COLLECTION_NAME" &>/dev/null &
+  else
+    nohup $MEMSEARCH_CMD watch "$MEMORY_DIR" &>/dev/null &
+  fi
+  echo $! > "$WATCH_PIDFILE"
+}

package/plugins/memsearch/hooks/hooks.json

@@ -0,0 +1,50 @@
+{
+  "description": "memsearch memory hooks — automatic capture, search, and recall",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-submit.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/stop.sh",
+            "async": true,
+            "timeout": 120
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/session-end.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/memsearch/hooks/parse-transcript.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# Parse a Claude Code JSONL transcript into a concise text summary
+# suitable for AI summarization.
+#
+# Usage: bash parse-transcript.sh <transcript_path>
+#
+# Truncation rules:
+#   - Only process the last MAX_LINES lines (default 200)
+#   - User/assistant text content > MAX_CHARS chars (default 500) is truncated to tail
+#   - Tool calls: only output tool name + truncated input summary
+#   - Tool results: only output a one-line truncated preview
+#   - Skip file-history-snapshot entries entirely
+
+set -euo pipefail
+
+# parse-transcript requires jq for JSON processing; gracefully degrade if missing
+if ! command -v jq &>/dev/null; then
+  echo "(transcript parsing skipped — jq not installed)"
+  exit 0
+fi
+
+TRANSCRIPT_PATH="${1:-}"
+MAX_LINES="${MEMSEARCH_MAX_LINES:-200}"
+MAX_CHARS="${MEMSEARCH_MAX_CHARS:-500}"
+
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  echo "ERROR: transcript not found: $TRANSCRIPT_PATH" >&2
+  exit 1
+fi
+
+# Count total lines for context
+TOTAL_LINES=$(wc -l < "$TRANSCRIPT_PATH")
+
+if [ "$TOTAL_LINES" -eq 0 ]; then
+  echo "(empty transcript)"
+  exit 0
+fi
+
+# Helper: truncate text to last N chars
+truncate_tail() {
+  local text="$1"
+  local max="$2"
+  local len=${#text}
+  if [ "$len" -le "$max" ]; then
+    printf '%s' "$text"
+  else
+    printf '...%s' "${text: -$max}"
+  fi
+}
+
+# Print header
+if [ "$TOTAL_LINES" -gt "$MAX_LINES" ]; then
+  echo "=== Transcript (last $MAX_LINES of $TOTAL_LINES lines) ==="
+else
+  echo "=== Transcript ($TOTAL_LINES lines) ==="
+fi
+echo ""
+
+# Process JSONL — take the last MAX_LINES, parse with jq line by line
+tail -n "$MAX_LINES" "$TRANSCRIPT_PATH" | while IFS= read -r line; do
+  # Extract type
+  entry_type=$(printf '%s' "$line" | jq -r '.type // empty' 2>/dev/null) || continue
+
+  # Skip file snapshots
+  [ "$entry_type" = "file-history-snapshot" ] && continue
+
+  # Extract timestamp
+  ts=$(printf '%s' "$line" | jq -r '.timestamp // empty' 2>/dev/null)
+  ts_short=""
+  if [ -n "$ts" ]; then
+    # Extract HH:MM:SS from ISO timestamp
+    ts_short=$(printf '%s' "$ts" | sed -n 's/.*T\([0-9][0-9]:[0-9][0-9]:[0-9][0-9]\).*/\1/p' 2>/dev/null || echo "")
+  fi
+
+  if [ "$entry_type" = "user" ]; then
+    # Check if it's a tool_result or a normal user message
+    content_type=$(printf '%s' "$line" | jq -r '.message.content | if type == "array" then .[0].type // "text" else "text" end' 2>/dev/null) || content_type="text"
+
+    if [ "$content_type" = "tool_result" ]; then
+      # Tool result — one-line preview
+      result_text=$(printf '%s' "$line" | jq -r '.message.content[0].content // "" | if type == "array" then .[0].text // "" else . end' 2>/dev/null)
+      result_short=$(truncate_tail "$result_text" "$MAX_CHARS")
+      echo "[${ts_short}] TOOL RESULT: ${result_short}"
+    else
+      # Normal user message
+      user_text=$(printf '%s' "$line" | jq -r '.message.content // "" | if type == "array" then map(select(.type == "text") | .text) | join("\n") else . end' 2>/dev/null)
+      user_short=$(truncate_tail "$user_text" "$MAX_CHARS")
+      echo ""
+      echo "[${ts_short}] USER: ${user_short}"
+    fi
+
+  elif [ "$entry_type" = "assistant" ]; then
+    # Process each content block
+    num_blocks=$(printf '%s' "$line" | jq -r '.message.content | length' 2>/dev/null) || num_blocks=0
+
+    for (( i=0; i<num_blocks; i++ )); do
+      block_type=$(printf '%s' "$line" | jq -r ".message.content[$i].type // empty" 2>/dev/null)
+
+      if [ "$block_type" = "text" ]; then
+        text=$(printf '%s' "$line" | jq -r ".message.content[$i].text // empty" 2>/dev/null)
+        [ -z "$text" ] && continue
+        text_short=$(truncate_tail "$text" "$MAX_CHARS")
+        echo "[${ts_short}] ASSISTANT: ${text_short}"
+
+      elif [ "$block_type" = "tool_use" ]; then
+        tool_name=$(printf '%s' "$line" | jq -r ".message.content[$i].name // \"unknown\"" 2>/dev/null)
+        # One-line summary of tool input
+        tool_input_summary=$(printf '%s' "$line" | jq -r ".message.content[$i].input | to_entries | map(\"\(.key)=\(.value | tostring | .[0:80])\") | join(\", \")" 2>/dev/null || echo "")
+        tool_input_short=$(truncate_tail "$tool_input_summary" 200)
+        echo "[${ts_short}] TOOL USE: ${tool_name}(${tool_input_short})"
+      fi
+    done
+  fi
+done
+
+echo ""
+echo "=== End of transcript ==="

package/plugins/memsearch/hooks/session-end.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# SessionEnd hook: stop the memsearch watch singleton.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+stop_watch
+
+exit 0

package/plugins/memsearch/hooks/session-start.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# SessionStart hook: start watch singleton + inject recent memory context.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Bootstrap: if memsearch not available, install uv and warm up uvx cache
+if [ -z "$MEMSEARCH_CMD" ]; then
+  if ! command -v uvx &>/dev/null; then
+    curl -LsSf https://astral.sh/uv/install.sh | sh 2>/dev/null
+    export PATH="$HOME/.local/bin:$PATH"
+  fi
+  # Warm up uvx cache with --upgrade to pull latest version
+  # First run downloads packages (~2s); subsequent runs use cache (<0.3s)
+  uvx --upgrade memsearch --version &>/dev/null || true
+  _detect_memsearch
+fi
+
+# Read resolved config and version for status display
+PROVIDER="openai"; MODEL=""; MILVUS_URI=""; VERSION=""
+if [ -n "$MEMSEARCH_CMD" ]; then
+  PROVIDER=$($MEMSEARCH_CMD config get embedding.provider 2>/dev/null || echo "openai")
+  MODEL=$($MEMSEARCH_CMD config get embedding.model 2>/dev/null || echo "")
+  MILVUS_URI=$($MEMSEARCH_CMD config get milvus.uri 2>/dev/null || echo "")
+  # "memsearch, version 0.1.10" → "0.1.10"
+  VERSION=$($MEMSEARCH_CMD --version 2>/dev/null | sed 's/.*version //' || echo "")
+fi
+
+# Determine required API key for the configured provider
+_required_env_var() {
+  case "$1" in
+    openai) echo "OPENAI_API_KEY" ;;
+    google) echo "GOOGLE_API_KEY" ;;
+    voyage) echo "VOYAGE_API_KEY" ;;
+    *) echo "" ;;  # ollama, local — no API key needed
+  esac
+}
+REQUIRED_KEY=$(_required_env_var "$PROVIDER")
+
+KEY_MISSING=false
+if [ -n "$REQUIRED_KEY" ] && [ -z "${!REQUIRED_KEY:-}" ]; then
+  KEY_MISSING=true
+fi
+
+# Check PyPI for newer version (2s timeout, non-blocking on failure)
+UPDATE_HINT=""
+if [ -n "$VERSION" ]; then
+  _PYPI_JSON=$(curl -s --max-time 2 https://pypi.org/pypi/memsearch/json 2>/dev/null || true)
+  LATEST=$(_json_val "$_PYPI_JSON" "info.version" "")
+  if [ -n "$LATEST" ] && [ "$LATEST" != "$VERSION" ]; then
+    UPDATE_HINT=" | UPDATE: v${LATEST} available"
+  fi
+fi
+
+# Build status line: version | provider/model | milvus | optional update/error
+VERSION_TAG="${VERSION:+ v${VERSION}}"
+COLLECTION_HINT=""
+if [ -n "$COLLECTION_NAME" ]; then
+  COLLECTION_HINT=" | collection: ${COLLECTION_NAME}"
+fi
+status="[memsearch${VERSION_TAG}] embedding: ${PROVIDER}/${MODEL:-unknown} | milvus: ${MILVUS_URI:-unknown}${COLLECTION_HINT}${UPDATE_HINT}"
+if [ "$KEY_MISSING" = true ]; then
+  status+=" | ERROR: ${REQUIRED_KEY} not set — memory search disabled"
+fi
+
+# Write session heading to today's memory file
+ensure_memory_dir
+TODAY=$(date +%Y-%m-%d)
+NOW=$(date +%H:%M)
+MEMORY_FILE="$MEMORY_DIR/$TODAY.md"
+echo -e "\n## Session $NOW\n" >> "$MEMORY_FILE"
+
+# If API key is missing, show status and exit early (watch/search would fail)
+if [ "$KEY_MISSING" = true ]; then
+  json_status=$(_json_encode_str "$status")
+  echo "{\"systemMessage\": $json_status}"
+  exit 0
+fi
+
+# Start memsearch watch as a singleton background process.
+# This is the ONLY place indexing is managed — all other hooks just write .md files.
+start_watch
+
+# Always include status in systemMessage
+json_status=$(_json_encode_str "$status")
+
+# If memory dir has no .md files (other than the one we just created), nothing to inject
+if [ ! -d "$MEMORY_DIR" ] || ! ls "$MEMORY_DIR"/*.md &>/dev/null; then
+  echo "{\"systemMessage\": $json_status}"
+  exit 0
+fi
+
+context=""
+
+# Find the 2 most recent daily log files (sorted by filename descending)
+recent_files=$(ls -1 "$MEMORY_DIR"/*.md 2>/dev/null | sort -r | head -2)
+
+if [ -n "$recent_files" ]; then
+  context="# Recent Memory\n\n"
+  for f in $recent_files; do
+    basename_f=$(basename "$f")
+    # Read last ~30 lines from each file
+    content=$(tail -30 "$f" 2>/dev/null || true)
+    if [ -n "$content" ]; then
+      context+="## $basename_f\n$content\n\n"
+    fi
+  done
+fi
+
+# Note: Detailed memory search is handled by the memory-recall skill (pull-based).
+# The cold-start context above gives Claude enough awareness of recent sessions
+# to decide when to invoke the skill for deeper recall.
+
+if [ -n "$context" ]; then
+  json_context=$(_json_encode_str "$context")
+  echo "{\"systemMessage\": $json_status, \"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": $json_context}}"
+else
+  echo "{\"systemMessage\": $json_status}"
+fi

package/plugins/memsearch/hooks/stop.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# Stop hook: parse transcript, summarize with claude -p, and save to memory.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Prevent infinite loop: if this Stop was triggered by a previous Stop hook, bail out
+STOP_HOOK_ACTIVE=$(_json_val "$INPUT" "stop_hook_active" "false")
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Skip summarization when the required API key is missing — embedding/search
+# would fail, and the session likely only contains the "key not set" warning.
+_required_env_var() {
+  case "$1" in
+    openai) echo "OPENAI_API_KEY" ;;
+    google) echo "GOOGLE_API_KEY" ;;
+    voyage) echo "VOYAGE_API_KEY" ;;
+    *) echo "" ;;  # ollama, local — no API key needed
+  esac
+}
+_PROVIDER=$($MEMSEARCH_CMD config get embedding.provider 2>/dev/null || echo "openai")
+_REQ_KEY=$(_required_env_var "$_PROVIDER")
+if [ -n "$_REQ_KEY" ] && [ -z "${!_REQ_KEY:-}" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Extract transcript path from hook input
+TRANSCRIPT_PATH=$(_json_val "$INPUT" "transcript_path" "")
+
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Check if transcript is empty (< 3 lines = no real content)
+LINE_COUNT=$(wc -l < "$TRANSCRIPT_PATH" 2>/dev/null || echo "0")
+if [ "$LINE_COUNT" -lt 3 ]; then
+  echo '{}'
+  exit 0
+fi
+
+ensure_memory_dir
+
+# Parse transcript into concise text
+PARSED=$("$SCRIPT_DIR/parse-transcript.sh" "$TRANSCRIPT_PATH" 2>/dev/null || true)
+
+if [ -z "$PARSED" ] || [ "$PARSED" = "(empty transcript)" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Determine today's date and current time
+TODAY=$(date +%Y-%m-%d)
+NOW=$(date +%H:%M)
+MEMORY_FILE="$MEMORY_DIR/$TODAY.md"
+
+# Extract session ID and last user turn UUID for progressive disclosure anchors
+SESSION_ID=$(basename "$TRANSCRIPT_PATH" .jsonl)
+LAST_USER_TURN_UUID=$(python3 -c "
+import json, sys
+uuid = ''
+with open(sys.argv[1]) as f:
+    for line in f:
+        try:
+            obj = json.loads(line)
+            if obj.get('type') == 'user' and isinstance(obj.get('message', {}).get('content'), str):
+                uuid = obj.get('uuid', '')
+        except: pass
+print(uuid)
+" "$TRANSCRIPT_PATH" 2>/dev/null || true)
+
+# Use claude -p to summarize the parsed transcript into concise bullet points.
+# --model haiku: cheap and fast model for summarization
+# --no-session-persistence: don't save this throwaway session to disk
+# --no-chrome: skip browser integration
+# --system-prompt: separate role instructions from data (transcript via stdin)
+SUMMARY=""
+if command -v claude &>/dev/null; then
+  SUMMARY=$(printf '%s' "$PARSED" | claude -p \
+    --model haiku \
+    --no-session-persistence \
+    --no-chrome \
+    --system-prompt "You are a session memory writer. Your ONLY job is to output bullet-point summaries. Output NOTHING else — no greetings, no questions, no offers to help, no preamble, no closing remarks.
+
+Rules:
+- Output 3-8 bullet points, each starting with '- '
+- Focus on: decisions made, problems solved, code changes, key findings
+- Be specific and factual — mention file names, function names, and concrete details
+- Do NOT include timestamps, headers, or any formatting beyond bullet points
+- Do NOT add any text before or after the bullet points" \
+    2>/dev/null || true)
+fi
+
+# If claude is not available or returned empty, fall back to raw parsed output
+if [ -z "$SUMMARY" ]; then
+  SUMMARY="$PARSED"
+fi
+
+# Append as a sub-heading under the session heading written by SessionStart
+# Include HTML comment anchor for progressive disclosure (L3 transcript lookup)
+{
+  echo "### $NOW"
+  if [ -n "$SESSION_ID" ]; then
+    echo "<!-- session:${SESSION_ID} turn:${LAST_USER_TURN_UUID} transcript:${TRANSCRIPT_PATH} -->"
+  fi
+  echo "$SUMMARY"
+  echo ""
+} >> "$MEMORY_FILE"
+
+# Index immediately — don't rely on watch (which may be killed by SessionEnd before debounce fires)
+run_memsearch index "$MEMORY_DIR"
+
+echo '{}'

package/plugins/memsearch/hooks/user-prompt-submit.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook: lightweight hint reminding Claude about the memory-recall skill.
+# The actual search + expand is handled by the memory-recall skill (pull-based, context: fork).
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Skip short prompts (greetings, single words, etc.)
+PROMPT=$(_json_val "$INPUT" "prompt" "")
+if [ -z "$PROMPT" ] || [ "${#PROMPT}" -lt 10 ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Need memsearch available
+if [ -z "$MEMSEARCH_CMD" ]; then
+  echo '{}'
+  exit 0
+fi
+
+echo '{"systemMessage": "[memsearch] Memory available"}'

package/plugins/memsearch/scripts/derive-collection.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Derive a unique Milvus collection name from a project directory path.
+# Used by hooks (via common.sh) and skill (via SKILL.md ! syntax).
+#
+# Usage: derive-collection.sh [project_dir]
+#   If no argument given, uses pwd.
+#
+# Output: ms_<sanitized_basename>_<8char_sha256>
+#   e.g. /home/user/my-app → ms_my_app_a1b2c3d4
+
+set -euo pipefail
+
+PROJECT_DIR="${1:-$(pwd)}"
+
+# Resolve to absolute path (realpath preferred, cd fallback, raw last resort)
+if command -v realpath &>/dev/null; then
+  PROJECT_DIR="$(realpath -m "$PROJECT_DIR")"
+elif [ -d "$PROJECT_DIR" ]; then
+  PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)"
+else
+  # If directory doesn't exist and no realpath, ensure it starts with /
+  case "$PROJECT_DIR" in
+    /*) ;; # already absolute
+    *)  PROJECT_DIR="$(pwd)/$PROJECT_DIR" ;;
+  esac
+fi
+
+# Extract basename and sanitize:
+# - lowercase
+# - replace non-alphanumeric with underscore
+# - collapse consecutive underscores
+# - trim leading/trailing underscores
+# - truncate to 40 chars
+sanitized=$(basename "$PROJECT_DIR" \
+  | tr '[:upper:]' '[:lower:]' \
+  | sed 's/[^a-z0-9]/_/g' \
+  | sed 's/__*/_/g' \
+  | sed 's/^_//;s/_$//' \
+  | cut -c1-40)
+
+# Compute 8-char SHA-256 hash of the full absolute path
+if command -v sha256sum &>/dev/null; then
+  hash=$(printf '%s' "$PROJECT_DIR" | sha256sum | cut -c1-8)
+elif command -v shasum &>/dev/null; then
+  hash=$(printf '%s' "$PROJECT_DIR" | shasum -a 256 | cut -c1-8)
+else
+  hash=$(python3 -c "import hashlib,sys; print(hashlib.sha256(sys.argv[1].encode()).hexdigest()[:8])" "$PROJECT_DIR")
+fi
+
+echo "ms_${sanitized}_${hash}"

package/plugins/memsearch/skills/memory-recall/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: memory-recall
+description: "Search and recall relevant memories from past sessions. Use when the user's question could benefit from historical context, past decisions, debugging notes, previous conversations, or project knowledge. Also use when you see '[memsearch] Memory available' hints."
+context: fork
+allowed-tools: Bash
+---
+
+You are a memory retrieval agent for memsearch. Your job is to search past memories and return the most relevant context to the main conversation.
+
+## Project Collection
+
+Collection: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/derive-collection.sh`
+
+## Your Task
+
+Search for memories relevant to: $ARGUMENTS
+
+## Steps
+
+1. **Search**: Run `memsearch search "<query>" --top-k 5 --json-output --collection <collection name above>` to find relevant chunks.
+   - If `memsearch` is not found, try `uvx memsearch` instead.
+   - Choose a search query that captures the core intent of the user's question.
+
+2. **Evaluate**: Look at the search results. Skip chunks that are clearly irrelevant or too generic.
+
+3. **Expand**: For each relevant result, run `memsearch expand <chunk_hash> --collection <collection name above>` to get the full markdown section with surrounding context.
+
+4. **Deep drill (optional)**: If an expanded chunk contains transcript anchors (JSONL path + turn UUID), and the original conversation seems critical, run:
+   ```
+   memsearch transcript <jsonl_path> --turn <uuid> --context 3
+   ```
+   to retrieve the original conversation turns.
+
+5. **Return results**: Output a curated summary of the most relevant memories. Be concise — only include information that is genuinely useful for the user's current question.
+
+## Output Format
+
+Organize by relevance. For each memory include:
+- The key information (decisions, patterns, solutions, context)
+- Source reference (file name, date) for traceability
+
+If nothing relevant is found, simply say "No relevant memories found."