chat-recall 0.0.1 → 0.4.8

package/hooks/chat_recall_escalate_hook.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# chat-recall escalate hook — fires on SessionEnd.
+#
+# The write half of the Context Engineering loop: the SessionStart wake-up
+# hook injects prior knowledge INTO a new session; this hook escalates the
+# finished session's learnings (decisions the agent announced, corrections
+# the user gave, and the outcome) OUT into the temporal knowledge graph via
+# `chat-recall escalate`, so the next wake-up already knows them.
+#
+# Runs asynchronously: the work is backgrounded and detached, so session end
+# never waits on network writes. The delay gives the collector a chance to
+# sync the session's final events before extraction.
+#
+# Always exits 0. A hook must never break session end.
+#
+# Configurable via env:
+#   CHAT_RECALL_BIN              — path to the chat-recall binary (default: which chat-recall)
+#   CHAT_RECALL_ESCALATE_TIMEOUT — seconds before the background run gives up (default 60)
+#   CHAT_RECALL_ESCALATE_DELAY   — seconds to wait for the final sync (default 20)
+
+set -uo pipefail
+
+# Claude Code passes the hook payload as JSON on stdin; cwd is the project dir.
+INPUT="$(cat 2>/dev/null || true)"
+CWD=""
+SESSION_ID=""
+if command -v jq >/dev/null 2>&1; then
+  CWD="$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)"
+  SESSION_ID="$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null || true)"
+fi
+[[ -z "$CWD" ]] && CWD="$PWD"
+
+CHAT_RECALL_BIN="${CHAT_RECALL_BIN:-$(command -v chat-recall || true)}"
+if [[ -z "$CHAT_RECALL_BIN" ]] || [[ ! -x "$CHAT_RECALL_BIN" ]]; then exit 0; fi
+
+TIMEOUT="${CHAT_RECALL_ESCALATE_TIMEOUT:-60}"
+DELAY="${CHAT_RECALL_ESCALATE_DELAY:-20}"
+
+# Detach completely: no stdio ties back to the session, so Claude Code's
+# hook runner returns immediately and the escalation happens in the background.
+(
+  sleep "$DELAY"
+  cd "$CWD" 2>/dev/null || true
+  if [[ -n "$SESSION_ID" ]]; then
+    timeout "$TIMEOUT" "$CHAT_RECALL_BIN" escalate "$SESSION_ID" >/dev/null 2>&1 || true
+  else
+    timeout "$TIMEOUT" "$CHAT_RECALL_BIN" escalate --latest >/dev/null 2>&1 || true
+  fi
+) </dev/null >/dev/null 2>&1 &
+
+exit 0

package/hooks/chat_recall_resume_hook.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# chat-recall resume hint hook — fires on UserPromptSubmit.
+#
+# Reads the user's typed prompt from stdin (Claude Code hook input format) and,
+# if it looks like a "real" task (not a slash command, not a one-word reply),
+# searches chat-recall for sessions that worked on something similar. If high-
+# confidence matches exist, prints a short note that gets injected into the
+# session as additional context.
+#
+# Exit code 0 + stdout → injected as context for the assistant.
+# Exit code 0 + no stdout → silent (the default when nothing useful to say).
+# We never block the prompt (would be exit code 2). This is advisory only.
+#
+# Configurable via env:
+#   CHAT_RECALL_RESUME_THRESHOLD  — min top score to surface (default 0.001 for FTS5)
+#   CHAT_RECALL_RESUME_MAX        — max number of matches to mention (default 3)
+#   CHAT_RECALL_BIN               — path to the chat-recall binary (default: which chat-recall)
+
+set -euo pipefail
+
+# Read the hook payload from stdin. Tolerate non-JSON or missing fields.
+INPUT="$(cat)"
+
+# Extract prompt — bail out cleanly if jq is missing or input is malformed.
+if ! command -v jq >/dev/null 2>&1; then exit 0; fi
+PROMPT="$(echo "$INPUT" | jq -r '.prompt // empty')"
+
+# Skip if there's nothing useful to search on:
+#  - empty / very short prompts
+#  - slash commands (start with /)
+#  - replies that are just confirmations ("yes", "ok", etc.)
+if [[ -z "$PROMPT" ]]; then exit 0; fi
+if [[ "${#PROMPT}" -lt 20 ]]; then exit 0; fi
+if [[ "$PROMPT" == /* ]]; then exit 0; fi
+if [[ "$PROMPT" =~ ^(yes|no|ok|okay|sure|continue|go|next|y|n)[[:space:]\.\!\?]*$ ]]; then exit 0; fi
+
+CHAT_RECALL_BIN="${CHAT_RECALL_BIN:-$(command -v chat-recall || true)}"
+if [[ -z "$CHAT_RECALL_BIN" ]] || [[ ! -x "$CHAT_RECALL_BIN" ]]; then
+    # chat-recall not on PATH — install it first; nothing to do.
+    exit 0
+fi
+
+MAX="${CHAT_RECALL_RESUME_MAX:-3}"
+
+# Search the index. We use the search subcommand (not MCP) because hooks need
+# to be fast and synchronous. Output is plain text we'll grep for session ids.
+# Cap the prompt at 400 chars to avoid blowing up FTS5 query parsing.
+PROMPT_SHORT="${PROMPT:0:400}"
+SEARCH_OUT="$("$CHAT_RECALL_BIN" search "$PROMPT_SHORT" --top "$MAX" 2>/dev/null || true)"
+
+# If we got no results back, exit silently — no context to add.
+if [[ -z "$SEARCH_OUT" ]] || ! echo "$SEARCH_OUT" | grep -qE 'session|score|project'; then
+    exit 0
+fi
+
+# Emit a compact, agent-friendly hint. The leading marker lets the assistant
+# recognize the source of this context.
+{
+    echo "<!-- chat-recall-resume-hint -->"
+    echo "**📚 You've worked on something similar before** — chat-recall found these sessions:"
+    echo
+    # Take the first ~15 lines of search output as the digest. The CLI already
+    # formats nicely; we just trim.
+    echo "$SEARCH_OUT" | head -n 18
+    echo
+    echo "_Use \`recall_show <session-id>\` or \`recall_smart_resume <session-id>\` to load full context if relevant._"
+} || true
+
+exit 0

package/hooks/chat_recall_save_hook.sh

@@ -0,0 +1,254 @@
+#!/usr/bin/env bash
+# chat-recall save hook — auto-saves memory every 15 messages
+# Installed as a Claude Code hook in ~/.claude/hooks.json
+#
+# This hook fires every 15 messages during a session.
+# It extracts key facts (decisions, topics, tools) and saves them
+# so they're preserved even if the session ends unexpectedly.
+#
+# Setup (one-time):
+#   1. Copy this file to ~/.claude/chat-recall-hooks/
+#   2. Add to ~/.claude/hooks.json:
+#      {
+#        "hooks": {
+#          "Stop": [{"matcher": "", "hooks": [{"type": "command", "command": "/home/YOU/.claude/chat-recall-hooks/chat_recall_save_hook.sh"}]}],
+#          "PreCompact": [{"matcher": "", "hooks": [{"type": "command", "command": "/home/YOU/.claude/chat-recall-hooks/chat_recall_save_hook.sh --precompact"}]}]
+#        }
+#      }
+
+set -euo pipefail
+
+HOOKS_DIR="${HOME}/.claude/chat-recall-hooks"
+MEMORY_DIR="${HOME}/.claude/chat-recall-memory"
+STATE_FILE="${MEMORY_DIR}/last_save.json"
+SESSION_ID=""
+
+log() {
+    echo "[chat-recall-save] $(date +%H:%M:%S) $*" >&2
+}
+
+init() {
+    mkdir -p "${MEMORY_DIR}"
+    mkdir -p "${HOOKS_DIR}"
+}
+
+# Detect current session from transcript
+detect_session() {
+    local projects_dir="${HOME}/.claude/projects"
+    
+    # Find the most recently modified session file
+    local latest_file=""
+    local latest_time=0
+    
+    if [[ -d "$projects_dir" ]]; then
+        for dir in "$projects_dir"/*/; do
+            if [[ -d "$dir" ]]; then
+                for file in "$dir"/*.jsonl; do
+                    if [[ -f "$file" ]]; then
+                        local mtime
+                        mtime=$(stat -c %Y "$file" 2>/dev/null || stat -f %m "$file" 2>/dev/null || echo 0)
+                        if [[ "$mtime" -gt "$latest_time" ]]; then
+                            latest_time="$mtime"
+                            latest_file="$file"
+                        fi
+                    fi
+                done
+            fi
+        done
+    fi
+    
+    if [[ -n "$latest_file" && -f "$latest_file" ]]; then
+        SESSION_ID=$(basename "$latest_file" .jsonl)
+    fi
+}
+
+# Extract key facts from a session file
+extract_facts() {
+    local session_file="$1"
+    local session_id="$2"
+    
+    if [[ ! -f "$session_file" ]]; then
+        echo "{}"
+        return
+    fi
+    
+    # Count messages
+    local msg_count
+    msg_count=$(wc -l < "$session_file" 2>/dev/null || echo 0)
+    
+    # Extract unique tools used
+    local tools
+    tools=$(grep -o '"type":"tool_use"' "$session_file" 2>/dev/null | wc -l | tr -d ' ')
+    
+    # Extract topics from first user message
+    local first_topic
+    first_topic=$(grep -m1 '"type":"user"' "$session_file" 2>/dev/null | \
+        sed 's/.*"text":"//' | sed 's/".*//' | head -c 200 | tr -d '\n' | tr -d '"')
+    
+    # Extract decisions (heuristic)
+    local decisions=""
+    decisions=$(grep -i "decided\|chose\|going with\|recommend\|prefer" "$session_file" 2>/dev/null | \
+        head -3 | sed 's/.*"text":"//' | sed 's/".*//' | head -c 300 | tr -d '\n')
+    
+    # Get project path
+    local project_path=""
+    for dir in "${HOME}"/.claude/projects/*/; do
+        if [[ -d "$dir" && -f "${dir}${session_id}.jsonl" ]]; then
+            project_path=$(echo "$dir" | sed "s|${HOME}/.claude/projects/||" | sed 's|/||g' | sed 's|^|/|')
+            project_path=$(echo "$project_path" | sed "s|-|/|g")
+            break
+        fi
+    done
+    
+    # Output JSON
+    cat <<EOF
+{
+  "session_id": "$session_id",
+  "project_path": "$project_path",
+  "message_count": $msg_count,
+  "tool_uses": $tools,
+  "first_topic": "$(echo "$first_topic" | jq -Rs '.' 2>/dev/null || echo "\"$first_topic\"")",
+  "decisions": "$(echo "$decisions" | jq -Rs '.' 2>/dev/null || echo "\"\"")",
+  "saved_at": "$(date -Iseconds)"
+}
+EOF
+}
+
+# Count messages in current session
+count_messages() {
+    local session_file="$1"
+    if [[ ! -f "$session_file" ]]; then
+        echo 0
+        return
+    fi
+    grep -c '"type":"user"\|\|"type":"assistant"' "$session_file" 2>/dev/null || echo 0
+}
+
+# Main save logic
+do_save() {
+    local precompact="${1:-false}"
+    
+    detect_session
+    
+    if [[ -z "$SESSION_ID" ]]; then
+        log "No active session found"
+        return
+    fi
+    
+    # Find the session file
+    local session_file=""
+    for dir in "${HOME}"/.claude/projects/*/; do
+        if [[ -f "${dir}${SESSION_ID}.jsonl" ]]; then
+            session_file="${dir}${SESSION_ID}.jsonl"
+            break
+        fi
+    done
+    
+    if [[ -z "$session_file" || ! -f "$session_file" ]]; then
+        log "Session file not found for $SESSION_ID"
+        return
+    fi
+    
+    # Extract and save facts
+    local facts
+    facts=$(extract_facts "$session_file" "$SESSION_ID")
+    
+    local output_file="${MEMORY_DIR}/sessions/${SESSION_ID}.json"
+    mkdir -p "$(dirname "$output_file")"
+    
+    # Merge with existing data if present
+    if [[ -f "$output_file" ]]; then
+        # Simple merge: update fields but preserve accumulated data
+        local existing_msg_count
+        existing_msg_count=$(jq -r '.accumulated_messages // 0' "$output_file" 2>/dev/null || echo 0)
+        local new_msg_count
+        new_msg_count=$(echo "$facts" | jq -r '.message_count')
+        local total_msgs=$((existing_msg_count + new_msg_count))
+        
+        # Update but preserve accumulated decisions
+        local existing_decisions
+        existing_decisions=$(jq -r '.accumulated_decisions // []' "$output_file" 2>/dev/null || echo '[]')
+        
+        echo "$facts" | jq --argjson decisions "$existing_decisions" --argjson total "$total_msgs" \
+            '. + {accumulated_messages: $total, accumulated_decisions: $decisions}' > "$output_file"
+    else
+        echo "$facts" | jq '. + {accumulated_messages: .message_count, accumulated_decisions: []}' > "$output_file"
+    fi
+    
+    # Track this save
+    echo "{\"session_id\": \"$SESSION_ID\", \"saved_at\": \"$(date -Iseconds)\", \"precompact\": $precompact}" > "${STATE_FILE}"
+    
+    if [[ "$precompact" == "true" ]]; then
+        log "[PRECOMPACT] Emergency save for $SESSION_ID"
+    else
+        log "Saved facts for $SESSION_ID ($(echo "$facts" | jq -r '.message_count') messages)"
+    fi
+}
+
+# Check if we should save (throttle to avoid too frequent saves)
+should_save() {
+    local session_file="$1"
+    
+    if [[ ! -f "${STATE_FILE}" ]]; then
+        return 0
+    fi
+    
+    # Check last save time
+    local last_save
+    last_save=$(jq -r '.saved_at // empty' "${STATE_FILE}" 2>/dev/null || echo "")
+    
+    if [[ -z "$last_save" ]]; then
+        return 0
+    fi
+    
+    # Don't save more than once per 30 seconds
+    local last_save_epoch
+    last_save_epoch=$(date -d "$last_save" +%s 2>/dev/null || echo 0)
+    local now_epoch
+    now_epoch=$(date +%s)
+    
+    if (( now_epoch - last_save_epoch < 30 )); then
+        return 1
+    fi
+    
+    return 0
+}
+
+main() {
+    init
+    
+    local precompact="false"
+    if [[ "${1:-}" == "--precompact" ]]; then
+        precompact="true"
+    fi
+    
+    detect_session
+    
+    if [[ -z "$SESSION_ID" ]]; then
+        log "No session detected, skipping"
+        exit 0
+    fi
+    
+    # Find session file
+    local session_file=""
+    for dir in "${HOME}"/.claude/projects/*/; do
+        if [[ -f "${dir}${SESSION_ID}.jsonl" ]]; then
+            session_file="${dir}${SESSION_ID}.jsonl"
+            break
+        fi
+    done
+    
+    if [[ -z "$session_file" ]]; then
+        log "Session file not found"
+        exit 1
+    fi
+    
+    if ! should_save "$session_file"; then
+        log "Throttled (recent save)"
+        exit 0
+    fi
+    
+    do_save "$precompact"
+}
+
+main "$@"

package/hooks/chat_recall_wakeup_hook.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# chat-recall wake-up hook — fires on SessionStart (matcher: startup|clear).
+#
+# Prints the project-scoped wake-up bundle (high-importance facts + current
+# knowledge-graph facts) to stdout. Claude Code injects stdout into the new
+# session's context. This gives manual sessions the same preamble that
+# coolcode injects into its spawned sessions.
+#
+# Exit code 0 + stdout → injected as context.
+# Any failure → silent exit 0. This hook is advisory and never blocks a session.
+#
+# Configurable via env:
+#   CHAT_RECALL_BIN            — path to the chat-recall binary (default: which chat-recall)
+#   CHAT_RECALL_WAKEUP_TIMEOUT — seconds before we give up (default 10)
+
+set -uo pipefail
+
+if ! command -v jq >/dev/null 2>&1; then exit 0; fi
+
+# Claude Code passes the hook payload as JSON on stdin; cwd is the project dir.
+INPUT="$(cat 2>/dev/null || true)"
+CWD="$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)"
+[[ -z "$CWD" ]] && CWD="$PWD"
+PROJECT="$(basename "$CWD")"
+
+CHAT_RECALL_BIN="${CHAT_RECALL_BIN:-$(command -v chat-recall || true)}"
+if [[ -z "$CHAT_RECALL_BIN" ]] || [[ ! -x "$CHAT_RECALL_BIN" ]]; then exit 0; fi
+
+TIMEOUT="${CHAT_RECALL_WAKEUP_TIMEOUT:-10}"
+OUT="$(timeout "$TIMEOUT" "$CHAT_RECALL_BIN" memory wake-up -p "$PROJECT" 2>/dev/null || true)"
+[[ -z "$OUT" ]] && exit 0
+
+{
+    echo "<!-- chat-recall-wake-up -->"
+    echo "--- Prior knowledge (chat-recall wake-up, project: $PROJECT) ---"
+    echo "$OUT"
+}
+
+exit 0

package/package.json

@@ -1,7 +1,41 @@
 {
   "name": "chat-recall",
-  "version": "0.0.1",
-  "description": "Cross-tool memory for AI coding sessions. Name reserved — first release coming shortly.",
-  "license": "UNLICENSED",
-  "homepage": "https://chatrecall.dev"
+  "version": "0.4.8",
+  "description": "Local-first memory for AI coding tools \u2014 indexes Claude Code / Gemini CLI / OpenCode / Codex sessions, exposes them over MCP, optionally syncs redacted history to a chat-recall server",
+  "type": "module",
+  "license": "Elastic-2.0",
+  "bin": {
+    "chat-recall": "./dist/cli.js",
+    "chat-recall-mcp": "./dist/mcp.js",
+    "chat-recall-watch": "./dist/watch.js"
+  },
+  "files": [
+    "dist",
+    "hooks",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b && node scripts/bundle.mjs && node scripts/postbuild.mjs",
+    "build:types": "tsc -b",
+    "auto-indexer": "tsx auto-indexer/indexer.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@noble/ciphers": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "chalk": "^5.3.0",
+    "chokidar": "^3.5.3",
+    "commander": "^12.0.0",
+    "diff": "^9.0.0",
+    "dotenv": "^17.2.3",
+    "zod": "^3.22.0"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "12.9.0"
+  },
+  "devDependencies": {
+    "@chat-recall/engine": "*"
+  }
 }

package/skills/chat-recall/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: chat-recall
+description: >-
+  Recall past AI-coding work — prior sessions, decisions, and project history —
+  through the chat-recall MCP tools (mcp__chat-recall__recall_*). Use when the
+  user says "continue" / "pick up where we left off", "did we decide X",
+  "remember when we…", "what was I doing", "what do you know about this
+  project/me", or otherwise references earlier work that is not in the current
+  context. Also the entry point for the surfaces no focused skill owns: leaked
+  secrets ("did I paste an API key"), the shared task board and team activity
+  ("what are my open tasks", "what is my team working on"), and index health
+  ("is chat-recall working", "re-index my sessions"). This is the hub: it routes
+  to the focused chat-recall skills and lists every recall_* tool. Reach for it
+  whenever the answer lives in PAST work rather than the files in front of you.
+---
+
+# chat-recall — cross-session memory for AI coding
+
+chat-recall indexes your Claude Code, Gemini, OpenCode, Codex and Antigravity
+sessions — plus plans, tasks, CLAUDE.md files, shell history and agent diaries —
+into a searchable server with a temporal knowledge graph. When a request depends
+on something that happened in an *earlier* session (a decision, a past fix, "what
+were we doing"), don't guess or ask the user to re-explain — recall it.
+
+All tools are MCP tools on the `chat-recall` server, named
+`mcp__chat-recall__<tool>`.
+
+**Reads are safe to call proactively. Writes are not.** Everything below is a
+read except these, which change stored memory or state — treat each as an edit
+and apply the test in `chat-recall-memory` before calling one:
+`recall_kg_add`, `recall_kg_invalidate`, `recall_decision_record`,
+`recall_diary_write`, `recall_set`, `recall_task_create`, `recall_task_update`,
+`recall_security_dismiss`, `recall_rename_session`, `recall_regenerate_summary`,
+`recall_reclassify`, `recall_index`, `recall_code_index`.
+
+## Route to the right skill
+
+Match the intent, then read that skill and follow its workflow:
+
+| The user wants… | Read skill |
+| --- | --- |
+| Continue / resume / pick up prior work; cold start on an ongoing task | `chat-recall-resume` |
+| Find past conversations — "remember when", "have we done X", "find my notes on…" | `chat-recall-find` |
+| Store or recall a decision / fact; "what do you know about…", "did we decide…" | `chat-recall-memory` |
+| The state of a project — "what's been happening in X", cost, findings | `chat-recall-project` |
+| What changed — edits, diffs, commits; "what was I doing 2h ago" | `chat-recall-changes` |
+
+Leaked secrets, the shared task board, team activity and index health have no
+focused skill — use the catalog below directly.
+
+## Tool catalog
+
+Every `recall_*` tool. `packages/cli/src/skills-catalog.test.ts` fails when a
+tool is registered and never named here, so adding a tool means placing it.
+
+**Resume / cold start** — `recall_smart_resume` (structured resume bundle; needs a session id), `recall_recent` (list recent sessions), `recall_wake_up` (identity + high-signal facts), `recall_context` (structured dump of one session), `recall_show` (raw slice — returns 10 messages unless you raise `max_messages`), `recall_summary` (AI summary + outcome).
+**Search** — `recall_search` (sessions; `include_outcome`, `like_session`), `recall_memory_search` (every memory type), `recall_memory_item` (read ONE item found by search, or browse a source type), `recall_user_prompts` (what the user actually typed), `recall_subagent_search` (inside subagent transcripts, whose work never reaches the main conversation), `recall_redundant_files` (before writing a new file, check you have not written one like it already).
+**Project** — `recall_project_context` (rich dump), `recall_weekly_digest`, `recall_analytics_summary`, `recall_outcome_summary` (how many recent sessions actually shipped), `recall_code_findings` / `recall_code_actions` / `recall_code_projects` / `recall_code_index` / `recall_recommendations`.
+**What changed** — `recall_edits_timeline` (cross-tool edits), `recall_diff` (per-session diffs), `recall_commits` (did it actually land), `recall_markers` (where a session went sideways).
+**Durable memory / KG** — `recall_kg_query` / `recall_kg_add` / `recall_kg_invalidate` / `recall_kg_timeline` / `recall_kg_stats`, `recall_decision_record`, `recall_diary_write` / `recall_diary_read`, `recall_set` / `recall_get`.
+**Team** — `recall_tasks` (the shared task board), `recall_task_create`, `recall_task_update` (status, assignee, comment; task ids look like `t_…`), `recall_team_activity` (per-teammate × per-project rollup), `recall_shares` (which projects are shared — private by default, nothing is visible to teammates until shared).
+**Security** — `recall_security_summary` (leaked secrets that still need action — start here for "did I paste a key somewhere"), `recall_security_session` (findings for one session), `recall_security_dismiss` (mark rotated / false positive — do this only when the user confirms which), `recall_security_rules` (tenant detection rules; also tests a regex).
+**Health / maintenance** — `recall_status` (is the index alive, what is synced), `recall_index` (sync now), `recall_heal_audit` (sessions whose rendered text is thinner than the raw archive, i.e. truncated upstream), `recall_regenerate_summary` (stored summary is stale or wrong), `recall_reclassify` (re-run the classifier over old chunks), `recall_rename_session`.
+
+## If you're unsure where to start
+
+- Free-text "is there past work relevant to this?" → `recall_search` with `include_outcome: true`.
+- Broader ("plans, tasks, CLAUDE.md, diaries too") → `recall_memory_search`.
+- "What do you know about me / this project right now?" → `recall_wake_up` (add a project filter) or `recall_project_context`.
+- "Continue where we left off" → you need a session id first. `recall_smart_resume`
+  takes one and REQUIRES it, so get the id from `recall_recent` (most recent work)
+  or `recall_search` (`include_outcome: true`, when the user described the task),
+  then resume. See `chat-recall-resume`.
+
+Prefer one targeted recall over asking the user to recap. Cite what you found
+(session id / decision) so the user can verify.

package/skills/chat-recall-changes/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: chat-recall-changes
+description: >-
+  See what changed across past AI-coding sessions with chat-recall. Use when the
+  user asks "what did I change 2h ago", "what files did we touch", "what happened
+  in that session", "did that session actually ship", "which sessions edited
+  <file>", or wants diffs/commits/edit-history that isn't in the current working
+  tree. Reconstructs edits, diffs, commits, and outcomes from indexed sessions.
+---
+
+# What-changed with chat-recall
+
+## Recent edits across everything
+
+`mcp__chat-recall__recall_edits_timeline` — chronological file edits across
+every AI tool chat-recall indexes, read live from each tool's own session store.
+`since_hours: 2` for "what was I doing recently"; `pattern` to filter by path;
+`group_by: "session"` (+ wide `since_hours`) to answer "which sessions edited
+<file> this month".
+
+## One session's changes
+
+Every tool here takes a NAMED `session_id` (not a positional argument).
+
+- `mcp__chat-recall__recall_diff` — per-file unified diffs of what a session
+  actually changed (detects reverts). `files_only: true` = just the touched-files
+  list; `context_only: true` = per-file add/remove stats.
+- `mcp__chat-recall__recall_commits` — git commits that landed in the
+  session's edit window, grouped by repo. Use to verify "shipped" claims: many
+  edits but no commit = work stayed local.
+- `mcp__chat-recall__recall_summary` — AI summary + outcome classification
+  (shipped / interrupted / abandoned) + last-claim-vs-user-reaction.
+- `mcp__chat-recall__recall_markers` — per-prompt sentiment/correction
+  markers (frustrated, correction, approval) to spot where a session went sideways.
+
+## Across many sessions
+
+`mcp__chat-recall__recall_outcome_summary` — how sessions ended over the last N
+days (shipped / interrupted / abandoned / in_progress). Use for "am I finishing
+what I start", never for one session — `recall_summary` answers that.
+
+## Workflow
+
+1. "What was I doing recently" → `recall_edits_timeline` (`since_hours`).
+2. "Which sessions touched <file>" → `recall_edits_timeline`
+   (`pattern`, `group_by: "session"`, wide window).
+3. "What did session X change / did it ship" → `recall_diff` + `recall_commits`
+   (+ `recall_summary` for the outcome).
+4. Don't claim a session shipped without `recall_commits` confirming a matching
+   commit — edits alone can be local-only.

package/skills/chat-recall-find/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: chat-recall-find
+description: >-
+  Find past AI-coding work with chat-recall. Use when the user asks "remember
+  when we…", "have we done X before", "find my notes/sessions on…", "where did we
+  discuss Y", "what did I ask about Z", or otherwise wants to locate earlier
+  conversations, plans, tasks, or notes across all their AI tools. Searches the
+  unified memory (sessions, plans, tasks, CLAUDE.md, history, diaries).
+---
+
+# Finding past work with chat-recall
+
+## Pick the search tool
+
+- `mcp__chat-recall__recall_search` — search SESSIONS. Free-text query.
+  - `include_outcome: true` → each hit gets a shipped/interrupted/abandoned line
+    so you can judge relevance fast.
+  - `like_session: <id>` → find sessions similar to a given one.
+  - `project_filter`, `top_k` to narrow.
+- `mcp__chat-recall__recall_memory_search` — search ALL memory types, not just
+  sessions. Use this when the answer might be in a plan, task list, CLAUDE.md, or
+  an agent diary — not only a conversation. Omit `source_types` to search
+  everything; pass it to narrow. The conversation-ish types are
+  `['session','plan','task','claude_md','paste','history','diary','agent_memory']`,
+  and the toolkit types — what is CONFIGURED rather than what was said — are
+  `['skill','mcp','command','agent','hook','plugin']`.
+- `mcp__chat-recall__recall_user_prompts` — search only what the USER actually
+  typed (assistant output stripped). Best for "what did I ask about X",
+  "what was I requesting yesterday".
+- `mcp__chat-recall__recall_subagent_search` — search inside SUBAGENT
+  transcripts. Explore/compact/aside sub-tasks run within a session and their
+  work never appears in the main conversation, so a normal session search cannot
+  find it. Reach for this when a session clearly did work you cannot locate.
+- `mcp__chat-recall__recall_redundant_files` — before creating a file, check
+  whether you have written one like it before. Scores a filename against every
+  file in the synced history.
+
+## From a hit to the content
+
+Every tool here takes a NAMED `session_id` (not a positional argument).
+
+- `mcp__chat-recall__recall_show` — read the session slice (`around_line`,
+  `from_end`, `include_code: true` for diffs/commands). It returns **10 messages
+  by default**: raise `max_messages` before telling the user what a session
+  contains, or you will describe a tenth of it as the whole.
+- `mcp__chat-recall__recall_summary` — AI summary + outcome.
+- `mcp__chat-recall__recall_memory_item` — read ONE item in full (or its links)
+  once search has found it. `mode=browse` lists a whole source type.
+- Plans/tasks: `recall_memory_search(source_types: ['plan','task'])` to find,
+  then `recall_show` with the plan id to read the full plan.
+
+## Strategy
+
+1. Sessions-only question → `recall_search` (add `include_outcome: true`).
+2. Might be a plan/task/note/diary → `recall_memory_search` (set `source_types`).
+3. "What did *I* ask" → `recall_user_prompts`.
+4. Zero results → broaden the query by dropping qualifiers, drop or widen
+   `project_filter`, or try the other search tool. Neither search tool has a
+   date/time filter, so do NOT try to narrow by time here — for a time window
+   use `recall_recent` (`since_hours`) or `recall_edits_timeline` instead.
+   Then open the best hit with `recall_show`.
+5. Work you cannot find in the session itself → `recall_subagent_search`.
+
+Report the session id / source of each result so the user can jump to it.