eagle-mem 3.1.1 → 3.3.0

package/README.md

@@ -159,16 +159,27 @@ The `update` command copies new files, runs any pending database migrations, and
 
 ## How it works
 
-Five hooks fire automatically at different points in Claude Code's lifecycle:
+Six hooks fire automatically at different points in Claude Code's lifecycle:
 
 | Hook | Fires when | What it does |
 |------|-----------|--------------|
 | **SessionStart** | startup, resume, clear, compact | Injects overview, summaries, memories, tasks |
+| **PreToolUse** | before Bash and Read calls | Rewrites noisy commands (learned rules), detects redundant reads |
 | **UserPromptSubmit** | user sends a message | FTS5 search for relevant past context |
-| **PostToolUse** | after tool calls | Records file touches, mirrors memory/plan/task writes |
+| **PostToolUse** | after tool calls | Records file touches, mirrors memory/plan/task writes, tracks modifications |
 | **Stop** | Claude's turn ends | Extracts `<eagle-summary>`, strips `<private>` tags |
 | **SessionEnd** | session closes | Re-syncs tasks, marks session completed |
 
+### Token savings
+
+Eagle Mem actively reduces token consumption:
+
+- **Command rewriting** — PreToolUse rewrites noisy Bash commands (e.g., `find`, `grep`) to pipe through `head -N`, using `updatedInput` to modify the command before execution. Rules are learned by the curator from real usage, not hardcoded.
+- **Read-after-modify detection** — If you just edited or wrote a file, Eagle Mem nudges that the diff is already in context before a redundant Read.
+- **Read dedup tracking** — Files read 3+ times in a session get a soft nudge that contents are likely already in context.
+
+### Data
+
 Data lives in a single SQLite database at `~/.eagle-mem/memory.db` (WAL mode, FTS5 full-text search):
 
 | Table | What it stores |
@@ -178,6 +189,7 @@ Data lives in a single SQLite database at `~/.eagle-mem/memory.db` (WAL mode, FT
 | observations | Per-tool-use file touch records |
 | overviews | One overview per project (scan or manual) |
 | code_chunks | FTS5-indexed source file chunks |
+| command_rules | Curator-learned command output rules |
 | claude_memories | Mirror of Claude Code auto-memories |
 | claude_plans | Mirror of Claude Code plans |
 | claude_tasks | Mirror of Claude Code tasks |

package/db/018_command_rules_not_null.sql

@@ -0,0 +1,23 @@
+-- Fix: command_rules.project has same NULL uniqueness flaw as eagle_meta had.
+-- Change to NOT NULL DEFAULT '' for consistent UNIQUE constraint behavior.
+CREATE TABLE IF NOT EXISTS command_rules_new (
+    id INTEGER PRIMARY KEY,
+    project TEXT NOT NULL DEFAULT '',
+    pattern TEXT NOT NULL,
+    strategy TEXT NOT NULL DEFAULT 'summary' CHECK (strategy IN ('summary', 'truncate')),
+    max_lines INTEGER,
+    reason TEXT,
+    times_seen INTEGER DEFAULT 0,
+    avg_output_bytes INTEGER DEFAULT 0,
+    enabled INTEGER DEFAULT 1,
+    created_at TIMESTAMP DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    updated_at TIMESTAMP DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    UNIQUE(project, pattern)
+);
+
+INSERT OR REPLACE INTO command_rules_new (id, project, pattern, strategy, max_lines, reason, times_seen, avg_output_bytes, enabled, created_at, updated_at)
+SELECT id, COALESCE(project, ''), pattern, strategy, max_lines, reason, times_seen, avg_output_bytes, enabled, created_at, updated_at FROM command_rules;
+
+DROP TABLE command_rules;
+ALTER TABLE command_rules_new RENAME TO command_rules;
+CREATE INDEX IF NOT EXISTS idx_command_rules_pattern ON command_rules(pattern);

package/db/020_drop_seeded_rules.sql

@@ -0,0 +1,12 @@
+-- Migration 020: Remove seeded global command rules.
+-- Self-learning pipeline (curator) now generates rules from real usage.
+-- Per-project rules created by the curator are preserved.
+--
+-- Safety: back up any existing global rules before deleting so they
+-- can be restored if a user manually created rules they want to keep.
+-- The backup table is left in place intentionally.
+
+CREATE TABLE IF NOT EXISTS _backup_020_global_rules AS
+    SELECT * FROM command_rules WHERE project = '';
+
+DELETE FROM command_rules WHERE project = '';

package/hooks/post-tool-use.sh

@@ -68,7 +68,7 @@ case "$tool_name" in
         cmd=$(echo "$cmd" | eagle_redact)
         tool_summary="Bash: $cmd"
 
-        tool_output=$(echo "$input" | jq -r '.tool_result.stdout // empty' 2>/dev/null)
+        tool_output=$(echo "$input" | jq -r '.tool_response.stdout // empty' 2>/dev/null)
         if [ -n "$tool_output" ]; then
             output_bytes=${#tool_output}
             output_lines=$(echo "$tool_output" | wc -l | tr -d ' ')
@@ -98,6 +98,25 @@ case "$tool_name" in
         ;;
 esac
 
+# ─── Track recent Edit/Write targets for Read-after-modify detection ──
+
+if [ -n "$fp" ] && [ -n "$session_id" ] && eagle_validate_session_id "$session_id"; then
+    case "$tool_name" in
+        Edit|Write)
+            mod_dir="$EAGLE_MEM_DIR/mod-tracker"
+            mkdir -p "$mod_dir" 2>/dev/null
+            mod_file="$mod_dir/${session_id}"
+            echo "$fp" >> "$mod_file"
+            # Keep only last 3 entries — use per-process tmp to avoid
+            # race when parallel PostToolUse hooks fire on same session
+            if [ -f "$mod_file" ]; then
+                _mod_tmp=$(mktemp "${mod_file}.XXXXXX" 2>/dev/null) || _mod_tmp="${mod_file}.$$"
+                tail -3 "$mod_file" > "$_mod_tmp" && mv "$_mod_tmp" "$mod_file" || rm -f "$_mod_tmp"
+            fi
+            ;;
+    esac
+fi
+
 # ─── Dispatch to extracted responsibilities ───────────────
 
 eagle_posttool_mirror_writes "$tool_name" "$fp" "$session_id" "$project"

package/hooks/pre-tool-use.sh

@@ -1,9 +1,11 @@
 #!/usr/bin/env bash
 # ═══════════════════════════════════════════════════════════
 # Eagle Mem — PreToolUse hook
-# Fires before every Bash tool use
+# Fires before Bash and Read tool calls
 # 1. Surfaces feature verification checklists before git push
-# 2. Applies learned command filtering rules (RTK-style adaptive)
+# 2. Truncates noisy commands via updatedInput (curator-learned rules)
+# 3. Detects Read-after-Edit/Write (content already in context)
+# 4. Nudges on repeated file reads (dedup tracker)
 # ═══════════════════════════════════════════════════════════
 set +e
 
@@ -17,12 +19,13 @@ input=$(eagle_read_stdin)
 [ -z "$input" ] && exit 0
 
 tool_name=$(echo "$input" | jq -r '.tool_name // empty')
-[ "$tool_name" != "Bash" ] && exit 0
 
-[ ! -f "$EAGLE_MEM_DB" ] && exit 0
+case "$tool_name" in
+    Bash|Read) ;;
+    *) exit 0 ;;
+esac
 
-cmd=$(echo "$input" | jq -r '.tool_input.command // empty')
-[ -z "$cmd" ] && exit 0
+[ ! -f "$EAGLE_MEM_DB" ] && exit 0
 
 session_id=$(echo "$input" | jq -r '.session_id // empty')
 cwd=$(echo "$input" | jq -r '.cwd // empty')
@@ -30,77 +33,120 @@ project=$(eagle_project_from_cwd "$cwd")
 [ -z "$project" ] && exit 0
 
 context=""
+updated_input=""
+
+case "$tool_name" in
+Bash)
+    cmd=$(echo "$input" | jq -r '.tool_input.command // empty')
+    [ -z "$cmd" ] && exit 0
+
+    # ─── Feature verification on git push ─────────────────────
+
+    case "$cmd" in
+        *"git push"*|*"gh pr create"*)
+            has_features=$(eagle_count_active_features "$project")
+            if [ "${has_features:-0}" -gt 0 ]; then
+                changed_files=""
+                if [ -n "$cwd" ] && [ -d "$cwd" ]; then
+                    changed_files=$(git -C "$cwd" diff --name-only HEAD 2>/dev/null)
+                    [ -z "$changed_files" ] && changed_files=$(git -C "$cwd" diff --cached --name-only 2>/dev/null)
+                fi
 
-# ─── Feature verification on git push ─────────────────────
-
-case "$cmd" in
-    *"git push"*|*"gh pr create"*)
-        has_features=$(eagle_count_active_features "$project")
-        if [ "${has_features:-0}" -gt 0 ]; then
-            changed_files=""
-            if [ -n "$cwd" ] && [ -d "$cwd" ]; then
-                changed_files=$(git -C "$cwd" diff --name-only HEAD 2>/dev/null)
-                [ -z "$changed_files" ] && changed_files=$(git -C "$cwd" diff --cached --name-only 2>/dev/null)
-            fi
-
-            if [ -n "$changed_files" ]; then
-                seen_features=""
-                while IFS= read -r changed_file; do
-                    [ -z "$changed_file" ] && continue
-                    fname=$(basename "$changed_file")
-                    fname_esc=$(eagle_sql_escape "$fname")
-
-                    feature_hits=$(eagle_find_feature_for_push "$project" "$fname_esc")
-
-                    while IFS='|' read -r feat_name feat_smoke feat_deps feat_verified; do
-                        [ -z "$feat_name" ] && continue
-                        case "$seen_features" in *"|$feat_name|"*) continue ;; esac
-                        seen_features+="|$feat_name|"
-
-                        context+="  - $feat_name"
-                        [ -n "$feat_smoke" ] && context+=" | smoke: $feat_smoke"
-                        [ -n "$feat_deps" ] && context+=" | deps: $feat_deps"
-                        if [ -n "$feat_verified" ]; then
-                            context+=" | last verified: $feat_verified"
-                        else
-                            context+=" | never verified"
-                        fi
-                        context+=$'\n'
-                    done <<< "$feature_hits"
-                done <<< "$changed_files"
-
-                if [ -n "$context" ]; then
-                    context="Eagle Mem: This push affects the following features. After deploy, verify each works and run 'eagle-mem feature verify <name>'.
+                if [ -n "$changed_files" ]; then
+                    seen_features=""
+                    while IFS= read -r changed_file; do
+                        [ -z "$changed_file" ] && continue
+                        fname=$(basename "$changed_file")
+
+                        feature_hits=$(eagle_find_feature_for_push "$project" "$fname")
+
+                        while IFS='|' read -r feat_name feat_smoke feat_deps feat_verified; do
+                            [ -z "$feat_name" ] && continue
+                            case "$seen_features" in *"|$feat_name|"*) continue ;; esac
+                            seen_features+="|$feat_name|"
+
+                            context+="  - $feat_name"
+                            [ -n "$feat_smoke" ] && context+=" | smoke: $feat_smoke"
+                            [ -n "$feat_deps" ] && context+=" | deps: $feat_deps"
+                            if [ -n "$feat_verified" ]; then
+                                context+=" | last verified: $feat_verified"
+                            else
+                                context+=" | never verified"
+                            fi
+                            context+=$'\n'
+                        done <<< "$feature_hits"
+                    done <<< "$changed_files"
+
+                    if [ -n "$context" ]; then
+                        context="Eagle Mem: This push affects the following features. After deploy, verify each works and run 'eagle-mem feature verify <name>'.
 ${context}"
+                    fi
                 fi
             fi
-        fi
-        ;;
-esac
+            ;;
+    esac
 
-# ─── Command output filtering (learned rules) ─────────────
+    # ─── Command output filtering (learned rules) ─────────────
+
+    base_cmd=$(echo "$cmd" | awk '{print $1}' | sed 's|.*/||')
+    rule=$(eagle_get_command_rule "$project" "$base_cmd")
+
+    if [ -n "$rule" ]; then
+        IFS='|' read -r strategy max_lines reason <<< "$rule"
+        case "$strategy" in
+            truncate)
+                if [ -n "$max_lines" ] && [ "$max_lines" -gt 0 ] 2>/dev/null; then
+                    case "$cmd" in
+                        *"&&"*|*"||"*|*";"*)
+                            context+="Eagle Mem: '${base_cmd}' produces long output (${reason}). Consider: | head -${max_lines}"
+                            ;;
+                        *"| head"*|*"| tail"*|*"| wc"*|*"| grep"*|*">"*|*">>"*)
+                            ;;
+                        *)
+                            updated_input=$(jq -nc --arg cmd "${cmd} | head -${max_lines}" '{"command":$cmd}')
+                            context+="Eagle Mem: '${base_cmd}' output is typically long (${reason}). Piped through head -${max_lines}."
+                            ;;
+                    esac
+                fi
+                ;;
+            summary)
+                context+="Eagle Mem: '${base_cmd}' is typically noisy (${reason}). Consider piping through tail or checking exit code only."
+                ;;
+        esac
+    fi
+    ;;
+
+Read)
+    fp=$(echo "$input" | jq -r '.tool_input.file_path // empty')
+    if [ -n "$fp" ] && [ -n "$session_id" ] && eagle_validate_session_id "$session_id"; then
+
+        # ─── Read-after-modify detection ──────────────────────
+        mod_file="$EAGLE_MEM_DIR/mod-tracker/${session_id}"
+        if [ -f "$mod_file" ] && grep -qFx -- "$fp" "$mod_file" 2>/dev/null; then
+            context+="Eagle Mem: '$(basename "$fp")' was just edited/written — the diff is already in context from the tool output. "
+        fi
 
-# Extract the base command for rule matching
-base_cmd=$(echo "$cmd" | awk '{print $1}' | sed 's|.*/||')
+        # ─── Read dedup tracker (soft nudge) ──────────────────
+        tracker_dir="$EAGLE_MEM_DIR/read-tracker"
+        mkdir -p "$tracker_dir" 2>/dev/null
+        tracker_file="$tracker_dir/${session_id}"
+        echo "$fp" >> "$tracker_file"
+        read_count=$(grep -cFx -- "$fp" "$tracker_file" 2>/dev/null)
+        read_count=${read_count:-0}
+        if [ "$read_count" -ge 3 ]; then
+            context+="Eagle Mem: '$(basename "$fp")' has been read ${read_count} times this session. Its contents are likely already in context."
+        fi
+    fi
+    ;;
+esac
 
-rule=$(eagle_get_command_rule "$project" "$base_cmd")
+[ -z "$context" ] && [ -z "$updated_input" ] && exit 0
 
-if [ -n "$rule" ]; then
-    IFS='|' read -r strategy max_lines reason <<< "$rule"
-    case "$strategy" in
-        summary)
-            context+="Eagle Mem command hint: '${base_cmd}' output is typically noisy (${reason}). Consider piping through 'tail -5' or checking exit code only."
-            ;;
-        truncate)
-            if [ -n "$max_lines" ] && [ "$max_lines" -gt 0 ] 2>/dev/null; then
-                context+="Eagle Mem command hint: '${base_cmd}' produces long output (${reason}). Consider: ${cmd} | head -${max_lines}"
-            fi
-            ;;
-    esac
+if [ -n "$updated_input" ]; then
+    jq -nc --arg ctx "$context" --argjson ui "$updated_input" \
+        '{"hookSpecificOutput":{"hookEventName":"PreToolUse","updatedInput":$ui,"additionalContext":$ctx}}'
+else
+    jq -nc --arg ctx "$context" '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":$ctx}}'
 fi
 
-[ -z "$context" ] && exit 0
-
-jq -nc --arg ctx "$context" '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":$ctx}}'
-
 exit 0

package/hooks/session-end.sh

@@ -2,17 +2,15 @@
 # ═══════════════════════════════════════════════════════════
 # Eagle Mem — SessionEnd hook
 # Fires when the Claude Code session ends
-# Marks the session as completed + triggers auto-curate
+# Marks the session as completed
 # ═══════════════════════════════════════════════════════════
 set +e
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 LIB_DIR="$SCRIPT_DIR/../lib"
-SCRIPTS_DIR="$SCRIPT_DIR/../scripts"
 
 . "$LIB_DIR/common.sh"
 . "$LIB_DIR/db.sh"
-. "$LIB_DIR/provider.sh"
 
 input=$(eagle_read_stdin)
 [ -z "$input" ] && exit 0
@@ -44,23 +42,4 @@ eagle_log "INFO" "SessionEnd: session=$session_id marked completed"
 # Prune observations older than 90 days (keeps DB size bounded)
 eagle_prune_observations 90 "$project"
 
-# ─── Auto-curate trigger ─────────────────────────────────
-curator_schedule=$(eagle_config_get "curator" "schedule" "manual")
-if [ "$curator_schedule" = "auto" ]; then
-    provider=$(eagle_config_get "provider" "type" "none")
-    if [ "$provider" != "none" ]; then
-        min_sessions=$(eagle_config_get "curator" "min_sessions" "5")
-        min_sessions=$(eagle_sql_int "$min_sessions")
-
-        last_curated=$(eagle_meta_get "last_curated_at" "$project")
-        since="${last_curated:-1970-01-01T00:00:00Z}"
-
-        sessions_since=$(eagle_count_sessions_since "$project" "$since")
-        if [ "${sessions_since:-0}" -ge "$min_sessions" ]; then
-            eagle_log "INFO" "SessionEnd: auto-curate triggered (${sessions_since} sessions since last curate)"
-            nohup bash "$SCRIPTS_DIR/curate.sh" -p "$project" >> "$EAGLE_MEM_LOG" 2>&1 &
-        fi
-    fi
-fi
-
 exit 0

package/hooks/session-start.sh

@@ -8,9 +8,11 @@ set +e
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 LIB_DIR="$SCRIPT_DIR/../lib"
+SCRIPTS_DIR="$SCRIPT_DIR/../scripts"
 
 . "$LIB_DIR/common.sh"
 . "$LIB_DIR/db.sh"
+. "$LIB_DIR/provider.sh"
 
 eagle_ensure_db
 
@@ -40,6 +42,29 @@ eagle_upsert_session "$session_id" "$project" "$cwd" "$model" "$source_type"
 # so long-lived sessions with regular compactions aren't falsely abandoned
 eagle_abandon_stale_sessions "$session_id"
 
+# ─── Auto-curate trigger (background, non-blocking) ──────────
+# Moved here from SessionEnd because SessionEnd rarely fires in long-lived sessions.
+# SessionStart fires on every new session, resume, and compaction — reliable trigger.
+curator_schedule=$(eagle_config_get "curator" "schedule" "manual")
+if [ "$curator_schedule" = "auto" ]; then
+    _curator_provider=$(eagle_config_get "provider" "type" "none")
+    if [ "$_curator_provider" != "none" ]; then
+        _min_sessions=$(eagle_config_get "curator" "min_sessions" "5")
+        _min_sessions=$(eagle_sql_int "$_min_sessions")
+        _last_curated=$(eagle_meta_get "last_curated_at" "$project")
+        _since="${_last_curated:-1970-01-01T00:00:00Z}"
+        _sessions_since=$(eagle_count_sessions_since "$project" "$_since")
+        if [ "${_sessions_since:-0}" -ge "$_min_sessions" ]; then
+            eagle_log "INFO" "SessionStart: auto-curate triggered (${_sessions_since} sessions since last curate)"
+            nohup bash "$SCRIPTS_DIR/curate.sh" -p "$project" >> "$EAGLE_MEM_LOG" 2>&1 &
+        fi
+    fi
+fi
+
+# ─── Cleanup stale tracker files (non-blocking) ─────────────
+find "$EAGLE_MEM_DIR/read-tracker" -type f -mtime +1 -delete 2>/dev/null &
+find "$EAGLE_MEM_DIR/mod-tracker" -type f -mtime +1 -delete 2>/dev/null &
+
 # ─── Version check (non-blocking) ────────────────────────────
 
 update_notice=""
@@ -127,38 +152,25 @@ eagle_banner="======================================
 ======================================"
 
 context="$eagle_banner
-
-=== EAGLE MEM — Active (trigger: $source_type) ===
-Eagle Mem (https://github.com/eagleisbatman/eagle-mem) is providing persistent memory for this session. It tracks summaries, observations, tasks, and code context across sessions via SQLite + FTS5. Mention Eagle Mem by name when referencing recalled context.
-
 "
 
 if [ -n "$update_notice" ]; then
-    context+="=== EAGLE MEM — $update_notice ===
-
-"
-fi
-
-# Nudge if last session lacked enrichment
-last_enriched=$(eagle_last_session_enriched "$project")
-if [ "${last_enriched:-1}" = "0" ] && [ "$stat_with_summaries" -gt 0 ]; then
-    context+="=== EAGLE MEM — Enrichment Reminder ===
-The previous session's summary did NOT include decisions, gotchas, or key_files. These fields power Eagle Mem's self-learning (feature discovery, anti-regression, command intelligence). Please emit an <eagle-summary> block at the end of this session with these fields populated.
-
+    context+="
+=== $update_notice ===
 "
 fi
 
 # Project overview
 overview=$(eagle_get_overview "$project")
 if [ -n "$overview" ]; then
-    context+="=== EAGLE MEM — Project Overview ===
+    context+="
+=== Project Overview ===
 $overview
-
 "
 else
-    context+="=== EAGLE MEM — Action Required ===
-No overview exists for '$project'. On the user's first prompt, run /eagle-mem-overview to build a structured project briefing. The skill has full instructions for what to read and how to write a rich overview.
-
+    context+="
+=== Action Required ===
+No overview exists for '$project'. Run /eagle-mem-overview to build one.
 "
 fi
 
@@ -166,8 +178,8 @@ fi
 recent=$(eagle_get_recent_summaries "$project" 5)
 
 if [ -n "$recent" ]; then
-    context+="=== EAGLE MEM ===
-Recent sessions for project '$project':
+    context+="
+=== Recent Sessions ===
 "
     while IFS='|' read -r request completed learned next_steps created_at decisions gotchas key_files; do
         [ -z "$request" ] && [ -z "$completed" ] && continue
@@ -202,8 +214,7 @@ memories=$(eagle_db "SELECT memory_name, memory_type, description, file_path, up
     LIMIT 5;")
 if [ -n "$memories" ]; then
     context+="
-=== EAGLE MEM — Memories ===
-Recent memories for '$project':
+=== Memories ===
 "
     while IFS='|' read -r mname mtype mdesc _fpath _updated days_ago; do
         [ -z "$mname" ] && continue
@@ -227,8 +238,7 @@ fi
 plans=$(eagle_list_claude_plans "$project" 3)
 if [ -n "$plans" ]; then
     context+="
-=== EAGLE MEM — Plans ===
-Recent plans for '$project':
+=== Plans ===
 "
     while IFS='|' read -r ptitle _pproj _fpath _updated; do
         [ -z "$ptitle" ] && continue
@@ -249,8 +259,7 @@ synced_tasks=$(eagle_db "SELECT subject, status, blocked_by FROM claude_tasks
     LIMIT 10;")
 if [ -n "$synced_tasks" ]; then
     context+="
-=== EAGLE MEM — Tasks ===
-Tasks for '$project':
+=== Tasks ===
 "
     while IFS='|' read -r tsubject tstatus tblocked; do
         [ -z "$tsubject" ] && continue
@@ -263,72 +272,37 @@ Tasks for '$project':
     done <<< "$synced_tasks"
 fi
 
-# Emit the eagle-summary instruction
-context+="
-=== EAGLE MEM INSTRUCTIONS ===
-You have persistent memory powered by Eagle Mem. When you recall context from a previous session or use injected memory, attribute it: \"From Eagle Mem:\" or \"Eagle Mem recalls:\". This helps the user understand where the context came from.
-
-IMPORTANT: At the start of your VERY NEXT response (this fires on session start, /clear, AND context compaction — always show this block, even if you think you showed it before, because prior context may have been compressed away). Show the user what Eagle Mem loaded by reproducing this exact banner:
+# ─── Instructions (full on startup, minimal on compact) ──
 
-\`\`\`
-$eagle_banner
-\`\`\`
-
-This gives the user visibility into the full context Eagle Mem loaded for this session.
-
-ANTI-REGRESSION: When Eagle Mem surfaces decision history about a file you are reading (via PostToolUse context), those decisions were made deliberately in past sessions. Do NOT revert or change the implementation approach without explicit user request. If you believe a past decision should change, state why and ask the user before proceeding. This prevents the common regression where Claude 'improves' code back to an older approach that was already rejected.
-
-SECRET SAFETY: Never include raw API keys, tokens, passwords, or secrets in eagle-summary fields or any text that Eagle Mem stores. Reference secrets by name (e.g., 'the Stripe API key', 'GOOGLE_APPLICATION_CREDENTIALS_JSON') not by value. Eagle Mem redacts common patterns automatically, but prevention is better than redaction.
-
-MEMORY FRESHNESS: The memories above include age indicators. If you make a change (edit a file, update a config, change a pattern) that contradicts what a loaded memory says, you MUST update that memory file immediately. Read the memory file, edit it to reflect the new reality, and the PostToolUse hook will sync the update to Eagle Mem. Stale memories mislead future sessions — keeping them current is as important as writing good code.
-
-=== EAGLE MEM — SESSION SUMMARY (MANDATORY) ===
-You MUST emit an <eagle-summary> block before your FINAL response in this session. This is how Eagle Mem captures what happened — without it, the next session starts blind and wastes tokens rediscovering context.
-
-FORMAT — emit this block exactly. Every field is REQUIRED. Do not skip fields, do not leave them empty, do not write \"N/A\".
-
-<eagle-summary>
-request: [One sentence: what did the user ask for?]
-investigated: [Comma-separated file paths you read or explored]
-learned: [Non-obvious technical discoveries — things a future session could not guess from reading the code]
-completed: [What was accomplished — be specific about what shipped, not what was \"worked on\"]
-next_steps: [Concrete actions for the next session, not vague aspirations]
-decisions:
-  - [Choice made] Why: [the reason — what constraint or tradeoff drove this choice]
-  - [Choice made] Why: [reason]
-gotchas:
-  - [What failed, surprised, or does not work the obvious way. Be specific — \"X does not work because Y\" not just \"X was tricky\"]
-key_files:
-  - [path/to/file.ext] — [one-line role: what this file does in the context of this work]
-  - [path/to/other.ext] — [role]
-files_read: [file1, file2, ...]
-files_modified: [file1, file2, ...]
-</eagle-summary>
+if [ "$source_type" = "compact" ] || [ "$source_type" = "clear" ]; then
+    context+="
+=== Eagle Mem (compact reload) ===
+Persistent memory active. Attribute recalled context to Eagle Mem. Do not revert past decisions surfaced by PostToolUse without asking the user. Emit <eagle-summary> before your final response.
+"
+else
+    context+="
+=== Eagle Mem ===
+Persistent memory active for '$project'. Attribute recalled context: \"Eagle Mem recalls:\" When PostToolUse surfaces past decisions about a file, do not revert without explicit user request. Never include raw secrets in eagle-summary fields. If you change something that contradicts a loaded memory, update that memory file.
 
-EXAMPLE — this is what a well-written summary looks like:
+Emit an <eagle-summary> block before your FINAL response:
 
 <eagle-summary>
-request: Add JWT authentication middleware to the API
-investigated: src/middleware/auth.ts, src/routes/users.ts, package.json, src/config/env.ts
-learned: express-jwt v8 changed its API — req.auth replaces req.user. The error handler must check err.name === 'UnauthorizedError', not err.status === 401.
-completed: JWT middleware deployed on all /api routes. Token validation, role-based guards, and 401/403 error responses all working. Added JWKS endpoint support for key rotation.
-next_steps: Add refresh token rotation; rate-limit the /auth/token endpoint
+request: [what the user asked for]
+investigated: [file paths read or explored]
+learned: [non-obvious discoveries a future session couldn't guess from code]
+completed: [what shipped — be specific]
+next_steps: [concrete actions for next session]
 decisions:
-  - Chose RS256 over HS256 for JWT signing. Why: allows key rotation via JWKS without redeploying; HS256 requires shared secret on every service.
-  - Put auth middleware at router level, not app level. Why: healthcheck and public routes must remain unauthenticated; per-router mounting is explicit about what is protected.
+  - [choice] Why: [reason]
 gotchas:
-  - express-jwt v8 is ESM-only — require() fails silently and returns undefined. Must use dynamic import().
-  - Setting token expiry below 5 min causes refresh storms under load — the refresh endpoint itself requires a valid (but expired) token, creating a chicken-and-egg problem.
+  - [what failed or surprised — \"X doesn't work because Y\"]
 key_files:
-  - src/middleware/auth.ts — JWT validation + role guard middleware
-  - src/config/env.ts — JWKS_URI and JWT_ISSUER environment config
-  - src/routes/users.ts — first route to use the new auth guard (reference implementation)
-files_read: [src/middleware/auth.ts, src/routes/users.ts, package.json, src/config/env.ts]
-files_modified: [src/middleware/auth.ts, src/config/env.ts, src/routes/users.ts, package.json]
+  - [path] — [role in this work]
+files_read: [file1, file2]
+files_modified: [file1, file2]
 </eagle-summary>
-
-WHY THIS MATTERS: Eagle Mem re-injects this summary at the start of future sessions. The 'decisions' field prevents re-debating settled choices. The 'gotchas' field prevents repeating the same mistakes. The 'key_files' field tells the next session exactly where to start reading instead of exploring blindly. Write these fields as if you are briefing a colleague who will pick up your work tomorrow — because that is exactly what happens.
 "
+fi
 
 # Output context (plain text stdout = additionalContext for SessionStart)
 if [ -n "$context" ]; then

package/hooks/stop.sh

@@ -2,8 +2,9 @@
 # ═══════════════════════════════════════════════════════════
 # Eagle Mem — Stop hook
 # Fires when Claude's turn ends
-# Parses <eagle-summary> from transcript, saves to DB
-# Falls back to heuristic extraction if no summary block
+# Primary: extracts summary from transcript heuristically
+# Bonus: eagle-summary block overrides where present
+# LLM enrichment fills in decisions/gotchas/key_files
 # ═══════════════════════════════════════════════════════════
 set +e
 
@@ -37,122 +38,109 @@ eagle_log "INFO" "Stop: session=$session_id project=$project transcript=$transcr
 # Ensure session exists (may not if SessionStart didn't fire)
 eagle_upsert_session "$session_id" "$project" "$cwd" "" ""
 
-# ─── Try to parse <eagle-summary> from transcript ──────────
+# ─── Guard: skip if summary already exists for this session ──
+# Stop fires every assistant turn. Only process once per session.
 
-summary_block=""
-if [ -n "$transcript_path" ] && [ -f "$transcript_path" ]; then
-    # Extract all text from the last assistant message using jq on JSONL
-    # Real transcript format: top-level .type == "assistant", content in .message.content[]
-    text_content=$(jq -rs '
-        [.[] | select(.type == "assistant")] | last |
-        if . then
-            [.message.content[]? | select(.type == "text") | .text] | join("\n")
-        else "" end
-    ' "$transcript_path" 2>/dev/null)
-
-    # Strip <private>...</private> blocks before processing (case-insensitive, tolerates attributes/whitespace)
-    text_content=$(echo "$text_content" | sed -E '/<[Pp][Rr][Ii][Vv][Aa][Tt][Ee][^>]*>/,/<\/[Pp][Rr][Ii][Vv][Aa][Tt][Ee][[:space:]]*>/d')
-
-    # Parse <eagle-summary> block
-    if [ -n "$text_content" ] && echo "$text_content" | grep -q '<eagle-summary>' 2>/dev/null; then
-        summary_block=$(echo "$text_content" | sed -n '/<eagle-summary>/,/<\/eagle-summary>/p' | sed '1d;$d')
-    fi
+existing_count=$(eagle_count_session_summaries "$session_id")
+if [ "${existing_count:-0}" -gt 0 ]; then
+    eagle_log "INFO" "Stop: summary already exists for session=$session_id — skipping"
+    exit 0
+fi
+
+[ -z "$transcript_path" ] || [ ! -f "$transcript_path" ] && exit 0
+
+# ─── Primary: heuristic extraction from transcript ───────────
+
+request=$(jq -r 'select(.type == "user") | .message.content | if type == "string" then . elif type == "array" then [.[] | select(.type == "text") | .text] | join(" ") else "" end' "$transcript_path" 2>/dev/null | head -1 | cut -c1-500)
+
+heuristic_reads=$(jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | select(.name == "Read") | .input.file_path // empty' "$transcript_path" 2>/dev/null | sort -u | head -20)
+heuristic_writes=$(jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | select(.name == "Write" or .name == "Edit") | .input.file_path // empty' "$transcript_path" 2>/dev/null | sort -u | head -20)
+
+files_read="[]"
+files_modified="[]"
+if [ -n "$heuristic_reads" ]; then
+    files_read=$(echo "$heuristic_reads" | jq -Rsc 'split("\n") | map(select(. != ""))')
+fi
+if [ -n "$heuristic_writes" ]; then
+    files_modified=$(echo "$heuristic_writes" | jq -Rsc 'split("\n") | map(select(. != ""))')
 fi
 
-# ─── Extract fields from summary block ─────────────────────
-
-parse_field() {
-    local block="$1"
-    local field="$2"
-    echo "$block" | awk -v f="$field" '
-        BEGIN { IGNORECASE=1; found=0 }
-        $0 ~ "^"f":" {
-            sub("^"f":[[:space:]]*", ""); found=1; val=$0; next
-        }
-        found && /^(request|investigated|learned|completed|next_steps|files_read|files_modified|notes|decisions|gotchas|key_files):/ { exit }
-        found { val = val " " $0 }
-        END { if (found) print val }
-    '
-}
-
-request=""
 investigated=""
 learned=""
-completed=""
+completed="(auto-captured)"
 next_steps=""
-files_read="[]"
-files_modified="[]"
 notes=""
 decisions=""
 gotchas=""
 key_files=""
 
-if [ -n "$summary_block" ]; then
-    request=$(parse_field "$summary_block" "request")
-    investigated=$(parse_field "$summary_block" "investigated")
-    learned=$(parse_field "$summary_block" "learned")
-    completed=$(parse_field "$summary_block" "completed")
-    next_steps=$(parse_field "$summary_block" "next_steps")
-    decisions=$(parse_field "$summary_block" "decisions")
-    gotchas=$(parse_field "$summary_block" "gotchas")
-    key_files=$(parse_field "$summary_block" "key_files")
+eagle_log "INFO" "Stop: heuristic extraction complete"
 
-    raw_fr=$(parse_field "$summary_block" "files_read")
-    raw_fm=$(parse_field "$summary_block" "files_modified")
+# ─── Bonus: eagle-summary block overrides where present ──────
+
+text_content=$(jq -rs '
+    [.[] | select(.type == "assistant")] | last |
+    if . then
+        [.message.content[]? | select(.type == "text") | .text] | join("\n")
+    else "" end
+' "$transcript_path" 2>/dev/null)
+
+# Strip <private>...</private> blocks
+text_content=$(echo "$text_content" | sed -E '/<[Pp][Rr][Ii][Vv][Aa][Tt][Ee][^>]*>/,/<\/[Pp][Rr][Ii][Vv][Aa][Tt][Ee][[:space:]]*>/d')
+
+summary_block=""
+if [ -n "$text_content" ] && echo "$text_content" | grep -q '<eagle-summary>' 2>/dev/null; then
+    summary_block=$(echo "$text_content" | sed -n '/<eagle-summary>/,/<\/eagle-summary>/p' | sed '1d;$d')
+fi
 
-    # Convert bracket-list to JSON array (handles special chars safely)
+if [ -n "$summary_block" ]; then
+    parse_field() {
+        local block="$1"
+        local field="$2"
+        echo "$block" | awk -v f="$field" '
+            BEGIN { IGNORECASE=1; found=0 }
+            $0 ~ "^"f":" {
+                sub("^"f":[[:space:]]*", ""); found=1; val=$0; next
+            }
+            found && /^(request|investigated|learned|completed|next_steps|files_read|files_modified|notes|decisions|gotchas|key_files):/ { exit }
+            found { val = val " " $0 }
+            END { if (found) print val }
+        '
+    }
+
+    # Override heuristic fields with eagle-summary where non-empty
+    _val=$(parse_field "$summary_block" "request");       [ -n "$_val" ] && request="$_val"
+    _val=$(parse_field "$summary_block" "investigated");  [ -n "$_val" ] && investigated="$_val"
+    _val=$(parse_field "$summary_block" "learned");       [ -n "$_val" ] && learned="$_val"
+    _val=$(parse_field "$summary_block" "completed");     [ -n "$_val" ] && completed="$_val"
+    _val=$(parse_field "$summary_block" "next_steps");    [ -n "$_val" ] && next_steps="$_val"
+    _val=$(parse_field "$summary_block" "decisions");     [ -n "$_val" ] && decisions="$_val"
+    _val=$(parse_field "$summary_block" "gotchas");       [ -n "$_val" ] && gotchas="$_val"
+    _val=$(parse_field "$summary_block" "key_files");     [ -n "$_val" ] && key_files="$_val"
+
+    # Convert bracket-list to JSON array
     to_json_array() {
         local raw="$1"
         raw=$(echo "$raw" | sed 's/^\[//;s/\]$//')
         echo "$raw" | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | grep -v '^$' | jq -Rsc 'split("\n") | map(select(. != ""))'
     }
 
+    raw_fr=$(parse_field "$summary_block" "files_read")
+    raw_fm=$(parse_field "$summary_block" "files_modified")
     [ -n "$raw_fr" ] && files_read=$(to_json_array "$raw_fr")
     [ -n "$raw_fm" ] && files_modified=$(to_json_array "$raw_fm")
 
-    eagle_log "INFO" "Stop: parsed eagle-summary block"
+    eagle_log "INFO" "Stop: eagle-summary block merged over heuristic data"
 fi
 
-# ─── Guard: skip fallback work if summary already exists ──
-# Stop fires every assistant turn. Without this, the heuristic and LLM
-# enrichment blocks fire on turn 2+ — wasting tokens and producing
-# empty inserts that get rejected.
-
-existing_count=0
-if [ -z "$summary_block" ] && [ -n "$transcript_path" ] && [ -f "$transcript_path" ]; then
-    existing_count=$(eagle_count_session_summaries "$session_id")
-fi
-
-if [ -z "$summary_block" ] && [ "${existing_count:-0}" -eq 0 ]; then
-
-    # ─── Heuristic fallback: extract from tool calls ───────────
+# ─── LLM enrichment: fill in decisions/gotchas/key_files ─────
 
-    if [ -z "$request" ] && [ -n "$transcript_path" ] && [ -f "$transcript_path" ]; then
-        eagle_log "INFO" "Stop: no eagle-summary found, using heuristic fallback"
+if [ -z "$decisions" ] && [ -z "$gotchas" ] && [ -z "$key_files" ]; then
+    provider=$(eagle_config_get "provider" "type" "none" 2>/dev/null)
+    if [ "$provider" != "none" ] && [ -n "$text_content" ]; then
+        excerpt=$(echo "$text_content" | tail -c 2000)
 
-        request=$(jq -r 'select(.type == "user") | .message.content | if type == "string" then . elif type == "array" then [.[] | select(.type == "text") | .text] | join(" ") else "" end' "$transcript_path" 2>/dev/null | head -1 | cut -c1-500)
-
-        heuristic_reads=$(jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | select(.name == "Read") | .input.file_path // empty' "$transcript_path" 2>/dev/null | sort -u | head -20)
-        heuristic_writes=$(jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | select(.name == "Write" or .name == "Edit") | .input.file_path // empty' "$transcript_path" 2>/dev/null | sort -u | head -20)
-
-        if [ -n "$heuristic_reads" ]; then
-            files_read=$(echo "$heuristic_reads" | jq -Rsc 'split("\n") | map(select(. != ""))')
-        fi
-        if [ -n "$heuristic_writes" ]; then
-            files_modified=$(echo "$heuristic_writes" | jq -Rsc 'split("\n") | map(select(. != ""))')
-        fi
-
-        completed="(auto-captured from tool usage)"
-    fi
-
-    # ─── LLM enrichment: extract decisions/gotchas/key_files ──
-
-    if [ -z "$decisions" ] && [ -z "$gotchas" ] && [ -z "$key_files" ]; then
-        provider=$(eagle_config_get "provider" "type" "none" 2>/dev/null)
-        if [ "$provider" != "none" ] && [ -n "$text_content" ]; then
-            excerpt=$(echo "$text_content" | tail -c 2000)
-
-            enrich_prompt="Extract from this Claude Code session excerpt:
+        enrich_prompt="Extract from this Claude Code session excerpt:
 1. DECISIONS: architectural or design choices made (with WHY). One per line.
 2. GOTCHAS: non-obvious pitfalls, bugs found, things that surprised. One per line.
 3. KEY_FILES: important files that were central to the work. One per line.
@@ -168,28 +156,24 @@ GOTCHAS:
 KEY_FILES:
 - <filepath>"
 
-            enrich_result=$(eagle_llm_call "$enrich_prompt" "Extract structured facts from development sessions. Be concise. Only include items with clear evidence." 512 2>/dev/null) || true
-
-            if [ -n "$enrich_result" ]; then
-                extract_section() {
-                    local result="$1" header="$2"
-                    echo "$result" | awk -v h="$header:" '
-                        $0 == h || $0 ~ "^"h { found=1; next }
-                        found && /^[A-Z_]+:/ { exit }
-                        found && /^- / { sub(/^- /, ""); lines[++n] = $0 }
-                        END { for (i=1; i<=n; i++) { printf "%s", lines[i]; if (i<n) printf "; " } }
-                    '
-                }
-                decisions=$(extract_section "$enrich_result" "DECISIONS")
-                gotchas=$(extract_section "$enrich_result" "GOTCHAS")
-                key_files=$(extract_section "$enrich_result" "KEY_FILES")
-                [ -n "$decisions" ] || [ -n "$gotchas" ] || [ -n "$key_files" ] && eagle_log "INFO" "Stop: LLM enrichment extracted for session=$session_id"
-            fi
+        enrich_result=$(eagle_llm_call "$enrich_prompt" "Extract structured facts from development sessions. Be concise. Only include items with clear evidence." 512 2>/dev/null) || true
+
+        if [ -n "$enrich_result" ]; then
+            extract_section() {
+                local result="$1" header="$2"
+                echo "$result" | awk -v h="$header:" '
+                    $0 == h || $0 ~ "^"h { found=1; next }
+                    found && /^[A-Z_]+:/ { exit }
+                    found && /^- / { sub(/^- /, ""); lines[++n] = $0 }
+                    END { for (i=1; i<=n; i++) { printf "%s", lines[i]; if (i<n) printf "; " } }
+                '
+            }
+            decisions=$(extract_section "$enrich_result" "DECISIONS")
+            gotchas=$(extract_section "$enrich_result" "GOTCHAS")
+            key_files=$(extract_section "$enrich_result" "KEY_FILES")
+            [ -n "$decisions" ] || [ -n "$gotchas" ] || [ -n "$key_files" ] && eagle_log "INFO" "Stop: LLM enrichment extracted for session=$session_id"
         fi
     fi
-
-elif [ -z "$summary_block" ] && [ "${existing_count:-0}" -gt 0 ]; then
-    eagle_log "INFO" "Stop: skipping fallback — summary already exists for session=$session_id (count=$existing_count)"
 fi
 
 # ─── Redact secrets from all text fields before storage ────

package/lib/common.sh

@@ -27,12 +27,14 @@ eagle_project_from_cwd() {
     local cwd="${1:-$(pwd)}"
     local resolved="$cwd"
 
-    # Resolve /private/tmp → /tmp on macOS
+    # Normalize macOS /private prefixes
     case "$resolved" in /private/tmp*) resolved="/tmp${resolved#/private/tmp}" ;; esac
+    case "$resolved" in /private/var/*) resolved="/var${resolved#/private/var}" ;; esac
 
     # Skip ephemeral directories — return empty so hooks early-exit
     case "$resolved" in
         /tmp|/tmp/*|/var/tmp|/var/tmp/*) echo ""; return ;;
+        /var/folders|/var/folders/*) echo ""; return ;;
         "$HOME/Downloads"|"$HOME/Downloads/"*) echo ""; return ;;
         "$HOME/Desktop"|"$HOME/Desktop/"*) echo ""; return ;;
     esac
@@ -42,6 +44,12 @@ eagle_project_from_cwd() {
     if [ -n "$git_root" ]; then
         basename "$git_root"
     else
+        local name
+        name=$(basename "$cwd")
+        # Reject single-character project names (likely temp dir fragments)
+        if [ ${#name} -le 1 ]; then
+            echo ""; return
+        fi
         basename "$cwd"
     fi
 }

package/lib/db-observations.sh

@@ -50,9 +50,10 @@ eagle_get_command_rule() {
     eagle_db "SELECT strategy, max_lines, reason
         FROM command_rules
         WHERE enabled = 1
-        AND (project = '$project' OR project IS NULL)
+        AND (project = '$project' OR project = '')
         AND ('$cmd' LIKE pattern OR '$cmd' = pattern)
-        ORDER BY CASE WHEN project IS NOT NULL THEN 0 ELSE 1 END
+        ORDER BY CASE WHEN project != '' THEN 0 ELSE 1 END,
+            LENGTH(pattern) DESC
         LIMIT 1;"
 }
 

package/lib/db-sessions.sh

@@ -15,9 +15,9 @@ eagle_upsert_session() {
     eagle_db "INSERT INTO sessions (id, project, cwd, model, source, last_activity_at)
               VALUES ('$session_id', '$project', '$cwd', '$model', '$source', strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
               ON CONFLICT(id) DO UPDATE SET
-                  cwd = COALESCE(excluded.cwd, sessions.cwd),
-                  model = COALESCE(excluded.model, sessions.model),
-                  source = COALESCE(excluded.source, sessions.source),
+                  cwd = COALESCE(NULLIF(excluded.cwd, ''), sessions.cwd),
+                  model = COALESCE(NULLIF(excluded.model, ''), sessions.model),
+                  source = COALESCE(NULLIF(excluded.source, ''), sessions.source),
                   status = 'active',
                   last_activity_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now');"
 }

package/lib/hooks.sh

@@ -11,7 +11,15 @@ eagle_patch_hook() {
     local command="$4"
     local description="${5:-}"
 
-    if jq -e ".hooks.${event}[]? | select(.hooks[]?.command == \"$command\")" "$settings" &>/dev/null; then
+    # Check both command AND matcher to avoid skipping entries with different matchers
+    # (e.g. PreToolUse with "Bash" vs "Read" matcher using the same script)
+    local match_query
+    if [ -n "$matcher" ]; then
+        match_query=".hooks.${event}[]? | select(.matcher == \"$matcher\" and (.hooks[]?.command == \"$command\"))"
+    else
+        match_query=".hooks.${event}[]? | select(.matcher == null and (.hooks[]?.command == \"$command\"))"
+    fi
+    if jq -e "$match_query" "$settings" &>/dev/null; then
         [ -n "$description" ] && eagle_ok "$description ${DIM}(already registered)${RESET}"
         return 0
     fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eagle-mem",
-  "version": "3.1.1",
+  "version": "3.3.0",
   "description": "Persistent memory for Claude Code — SQLite + FTS5, no daemon, no bloat",
   "bin": {
     "eagle-mem": "bin/eagle-mem"

package/scripts/curate.sh

@@ -222,6 +222,13 @@ If no rules needed, output: NONE"
                             eagle_log "WARN" "Curator: skipping RULE with invalid strategy '$strategy'"
                             continue
                         ;; esac
+                        # Guard: reject dangerous LLM-generated patterns that match everything
+                        # Require at least 2 literal characters (not just wildcards)
+                        _literal_chars=$(printf '%s' "$pattern" | sed 's/[%_]//g')
+                        if [ ${#_literal_chars} -lt 2 ]; then
+                            eagle_log "WARN" "Curator: skipping overly broad pattern '$pattern' (needs >=2 literal chars)"
+                            continue
+                        fi
 
                         [ "$max_lines" = "-" ] && max_lines=""
 

package/scripts/health.sh

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
-# ═══════════════════════════════════════════════════════════
+# ════════��══════════��═══════════════════════════════════════
 # Eagle Mem — Health Check
 # Diagnoses how well the self-learning pipeline is working
-# ═══════════════════════════════════════════════════════════
+# ════════���══════════════════════════════════════════════════
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -24,7 +24,6 @@ while [ $# -gt 0 ]; do
     esac
 done
 
-# In JSON mode, redirect all text output to stderr so stdout is clean JSON
 if [ "$JSON_OUT" -eq 1 ]; then
     exec 3>&1 1>&2
 fi
@@ -49,135 +48,148 @@ score=0
 max_score=0
 issues=()
 
-# ─── 1. Summary enrichment rate ──────────────────────────
+# ─��─ 1. Summary capture rate (25 pts) ───────────────────
 
-max_score=$((max_score + 30))
+max_score=$((max_score + 25))
 
+total_sessions=$(eagle_db "SELECT COUNT(*) FROM sessions WHERE project = '$p_esc';")
 total_summaries=$(eagle_db "SELECT COUNT(*) FROM summaries WHERE project = '$p_esc';")
+heuristic_summaries=$(eagle_db "SELECT COUNT(*) FROM summaries WHERE project = '$p_esc' AND completed = '(auto-captured)';")
 enriched_summaries=$(eagle_db "SELECT COUNT(*) FROM summaries WHERE project = '$p_esc' AND (decisions IS NOT NULL AND decisions != '' OR gotchas IS NOT NULL AND gotchas != '' OR key_files IS NOT NULL AND key_files != '');")
 
-if [ "${total_summaries:-0}" -eq 0 ]; then
-    enrich_pct=0
+if [ "${total_sessions:-0}" -eq 0 ]; then
+    capture_pct=0
 else
-    enrich_pct=$((enriched_summaries * 100 / total_summaries))
+    capture_pct=$((total_summaries * 100 / total_sessions))
 fi
 
-if [ "$enrich_pct" -ge 50 ]; then
-    eagle_ok "Enriched summaries: ${enriched_summaries}/${total_summaries} (${enrich_pct}%)"
-    score=$((score + 30))
-elif [ "$enrich_pct" -ge 20 ]; then
-    eagle_warn "Enriched summaries: ${enriched_summaries}/${total_summaries} (${enrich_pct}%) — aim for 50%+"
-    score=$((score + 15))
-    issues+=("Low enrichment rate (${enrich_pct}%). Eagle-summary blocks aren't being emitted reliably.")
-elif [ "${total_summaries:-0}" -gt 0 ]; then
-    eagle_fail "Enriched summaries: ${enriched_summaries}/${total_summaries} (${enrich_pct}%) — self-learning not working"
-    issues+=("Critical: ${enrich_pct}% enrichment. Decisions/gotchas/key_files are not being captured.")
+model_summaries=$((total_summaries - heuristic_summaries))
+
+if [ "${total_summaries:-0}" -gt 0 ]; then
+    if [ "$capture_pct" -ge 50 ]; then
+        eagle_ok "Capture: ${total_summaries}/${total_sessions} sessions (${capture_pct}%) — ${model_summaries} from model, ${heuristic_summaries} heuristic"
+        score=$((score + 25))
+    elif [ "$capture_pct" -ge 20 ]; then
+        eagle_warn "Capture: ${total_summaries}/${total_sessions} sessions (${capture_pct}%) — ${heuristic_summaries} heuristic"
+        score=$((score + 15))
+    else
+        eagle_fail "Capture: ${total_summaries}/${total_sessions} sessions (${capture_pct}%)"
+        score=$((score + 5))
+    fi
 else
     eagle_dim "  No summaries yet"
 fi
 
-# ─── 2. Feature discovery ────────────────────────────────
+# ─── 2. Enrichment rate (25 pts) ────────────────────────
 
-max_score=$((max_score + 20))
+max_score=$((max_score + 25))
 
-feature_count=$(eagle_db "SELECT COUNT(*) FROM features WHERE project = '$p_esc' AND status = 'active';")
-feature_file_count=$(eagle_db "SELECT COUNT(*) FROM feature_files ff JOIN features f ON ff.feature_id = f.id WHERE f.project = '$p_esc' AND f.status = 'active';")
+if [ "${total_summaries:-0}" -eq 0 ]; then
+    enrich_pct=0
+else
+    enrich_pct=$((enriched_summaries * 100 / total_summaries))
+fi
 
-if [ "${feature_count:-0}" -ge 3 ]; then
-    eagle_ok "Features tracked: ${feature_count} (${feature_file_count} files mapped)"
-    score=$((score + 20))
-elif [ "${feature_count:-0}" -ge 1 ]; then
-    eagle_warn "Features tracked: ${feature_count} — curator needs more sessions"
-    score=$((score + 10))
-    issues+=("Only ${feature_count} features discovered. Run curator more often.")
+if [ "${total_summaries:-0}" -gt 0 ]; then
+    if [ "$enrich_pct" -ge 50 ]; then
+        eagle_ok "Enriched: ${enriched_summaries}/${total_summaries} (${enrich_pct}%) have decisions/gotchas/key_files"
+        score=$((score + 25))
+    elif [ "$enrich_pct" -ge 20 ]; then
+        eagle_warn "Enriched: ${enriched_summaries}/${total_summaries} (${enrich_pct}%) — LLM extraction may need tuning"
+        score=$((score + 12))
+        issues+=("Low enrichment (${enrich_pct}%). Check LLM provider is responsive: eagle-mem config")
+    elif [ "${enriched_summaries:-0}" -gt 0 ]; then
+        eagle_fail "Enriched: ${enriched_summaries}/${total_summaries} (${enrich_pct}%)"
+        score=$((score + 5))
+        issues+=("${enrich_pct}% enrichment. Decisions/gotchas/key_files mostly missing.")
+    else
+        eagle_fail "Enriched: 0/${total_summaries} — no summaries have decisions/gotchas/key_files"
+        issues+=("Zero enrichment. Check provider config: eagle-mem config")
+    fi
 else
-    eagle_fail "Features tracked: 0 — feature graph is empty"
-    issues+=("No features discovered. Run: eagle-mem curate")
+    eagle_dim "  No summaries to enrich"
 fi
 
-# ─── 3. Command intelligence ─────────────────────────────
+# ─── 3. Feature discovery (15 pts) ─────────────────────
 
 max_score=$((max_score + 15))
 
-rule_count=$(eagle_db "SELECT COUNT(*) FROM command_rules WHERE (project = '$p_esc' OR project IS NULL) AND enabled = 1;")
-obs_with_metrics=$(eagle_db "SELECT COUNT(*) FROM observations WHERE project = '$p_esc' AND tool_name = 'Bash' AND output_bytes IS NOT NULL AND output_bytes > 0;")
+feature_count=$(eagle_db "SELECT COUNT(*) FROM features WHERE project = '$p_esc' AND status = 'active';")
 
-if [ "${rule_count:-0}" -ge 2 ]; then
-    eagle_ok "Command rules: ${rule_count} active (${obs_with_metrics} observations with metrics)"
+if [ "${feature_count:-0}" -ge 3 ]; then
+    eagle_ok "Features: ${feature_count} tracked"
     score=$((score + 15))
-elif [ "${rule_count:-0}" -ge 1 ]; then
-    eagle_warn "Command rules: ${rule_count} — learning in progress"
+elif [ "${feature_count:-0}" -ge 1 ]; then
+    eagle_warn "Features: ${feature_count} — curator needs more sessions"
     score=$((score + 8))
-elif [ "${obs_with_metrics:-0}" -gt 20 ]; then
-    eagle_fail "Command rules: 0 (but ${obs_with_metrics} observations available — run curator)"
-    issues+=("Command metrics collected but no rules generated yet.")
 else
-    eagle_dim "  Command metrics: ${obs_with_metrics} observations (need more data)"
-    score=$((score + 5))
+    eagle_fail "Features: 0 — run: eagle-mem curate"
+    issues+=("No features discovered. Run: eagle-mem curate")
 fi
 
-# ─── 4. Provider configured ──────────────────────────────
+# ─── 4. Provider configured (15 pts) ───────────────────
 
 max_score=$((max_score + 15))
 
 provider=$(eagle_config_get "provider" "type" "none")
 if [ "$provider" != "none" ]; then
     model=$(eagle_config_get "$provider" "model" "default")
-    eagle_ok "LLM provider: ${provider} (${model})"
+    eagle_ok "Provider: ${provider} (${model})"
     score=$((score + 15))
 else
-    eagle_fail "No LLM provider — curator and enrichment extraction disabled"
+    eagle_fail "No LLM provider — curator and enrichment disabled"
     issues+=("Configure a provider: eagle-mem config init")
 fi
 
-# ─── 5. Project data quality ─────────────────────────────
+# ─── 5. Data quality (10 pts) ──────────────────────────
 
 max_score=$((max_score + 10))
 
-tmp_sessions=$(eagle_db "SELECT COUNT(*) FROM sessions WHERE project IN ('tmp', 'private', '');")
-total_sessions=$(eagle_db "SELECT COUNT(*) FROM sessions;")
+# Count noise: ephemeral projects + single-char project names
+noise_sessions=$(eagle_db "SELECT COUNT(*) FROM sessions WHERE project IN ('tmp', 'private', '', 'T') OR LENGTH(project) <= 1;")
+all_sessions=$(eagle_db "SELECT COUNT(*) FROM sessions;")
 
-if [ "${total_sessions:-0}" -eq 0 ]; then
+if [ "${all_sessions:-0}" -eq 0 ]; then
     noise_pct=0
 else
-    noise_pct=$((tmp_sessions * 100 / total_sessions))
+    noise_pct=$((noise_sessions * 100 / all_sessions))
 fi
 
 if [ "$noise_pct" -le 5 ]; then
-    eagle_ok "Data quality: ${tmp_sessions} ephemeral sessions (${noise_pct}% noise)"
+    eagle_ok "Data quality: ${noise_pct}% noise (${noise_sessions} ephemeral sessions)"
     score=$((score + 10))
 elif [ "$noise_pct" -le 20 ]; then
-    eagle_warn "Data quality: ${tmp_sessions} ephemeral sessions (${noise_pct}% noise)"
+    eagle_warn "Data quality: ${noise_pct}% noise (${noise_sessions}/${all_sessions})"
     score=$((score + 5))
-    issues+=("${noise_pct}% of sessions from ephemeral dirs. Skiplist should prevent new ones.")
+    issues+=("${noise_pct}% noise. Skiplist prevents new pollution; prune old: eagle-mem prune")
 else
-    eagle_fail "Data quality: ${noise_pct}% noise — ${tmp_sessions}/${total_sessions} sessions from ephemeral dirs"
-    issues+=("Heavy ephemeral pollution. Update Eagle Mem to get skiplist protection.")
+    eagle_fail "Data quality: ${noise_pct}% noise (${noise_sessions}/${all_sessions})"
+    issues+=("Heavy noise. Run: eagle-mem prune to clean ephemeral data.")
 fi
 
-# ─── 6. Curator activity ─────────────────────────────────
+# ─── 6. Curator activity (10 pts) ──────────────────────
 
 max_score=$((max_score + 10))
 
 curator_schedule=$(eagle_config_get "curator" "schedule" "manual")
-last_curated=$(eagle_db "SELECT value FROM eagle_meta WHERE key = 'last_curated_at' AND (project = '$p_esc' OR project IS NULL) ORDER BY CASE WHEN project IS NOT NULL THEN 0 ELSE 1 END LIMIT 1;" 2>/dev/null || echo "")
+last_curated=$(eagle_db "SELECT value FROM eagle_meta WHERE key = 'last_curated_at' AND project = '$p_esc' LIMIT 1;" 2>/dev/null || echo "")
 
 if [ -n "$last_curated" ]; then
     eagle_ok "Curator: last run ${last_curated} (schedule: ${curator_schedule})"
     score=$((score + 10))
 elif [ "$curator_schedule" = "auto" ]; then
-    eagle_warn "Curator: auto-scheduled but hasn't run yet"
+    eagle_warn "Curator: auto-scheduled, hasn't run yet (triggers on session start)"
     score=$((score + 5))
-    issues+=("Auto-curate is configured but hasn't run. It triggers at session end.")
+    issues+=("Auto-curate configured but hasn't fired. Needs ${_min_sessions:-5}+ sessions since last run.")
 else
     eagle_fail "Curator: never run (schedule: ${curator_schedule})"
-    issues+=("Curator has never run. Try: eagle-mem curate --dry-run")
+    issues+=("Run: eagle-mem curate --dry-run")
 fi
 
-# ─── Score ────────────────────────────────────────────────
+# ─── Score ───────���────────────────────────────────────────
 
 echo ""
-echo -e "  ${DIM}─────────────────────────────────────${RESET}"
+echo -e "  ${DIM}────���────────────────────────────────${RESET}"
 
 pct=$((score * 100 / max_score))
 if [ "$pct" -ge 80 ]; then
@@ -210,14 +222,17 @@ if [ "$JSON_OUT" -eq 1 ]; then
         --argjson max_score "$max_score" \
         --argjson pct "$pct" \
         --arg grade "$grade" \
+        --argjson total_sessions "${total_sessions:-0}" \
         --argjson total_summaries "${total_summaries:-0}" \
+        --argjson heuristic_summaries "${heuristic_summaries:-0}" \
         --argjson enriched_summaries "${enriched_summaries:-0}" \
         --argjson features "${feature_count:-0}" \
-        --argjson command_rules "${rule_count:-0}" \
         --arg provider "$provider" \
         --argjson noise_pct "$noise_pct" \
+        --arg last_curated "${last_curated:-never}" \
         '{project:$project, score:$score, max:$max_score, pct:$pct, grade:$grade,
-          enrichment:{total:$total_summaries, enriched:$enriched_summaries},
-          features:$features, command_rules:$command_rules,
-          provider:$provider, noise_pct:$noise_pct}' >&3
+          capture:{sessions:$total_sessions, summaries:$total_summaries, heuristic:$heuristic_summaries},
+          enrichment:$enriched_summaries,
+          features:$features, provider:$provider,
+          noise_pct:$noise_pct, last_curated:$last_curated}' >&3
 fi

package/scripts/install.sh

@@ -186,7 +186,11 @@ eagle_patch_hook "$SETTINGS" "UserPromptSubmit" "" \
 
 eagle_patch_hook "$SETTINGS" "PreToolUse" "Bash" \
     "$EAGLE_MEM_DIR/hooks/pre-tool-use.sh" \
-    "PreToolUse hook"
+    "PreToolUse hook (Bash)"
+
+eagle_patch_hook "$SETTINGS" "PreToolUse" "Read" \
+    "$EAGLE_MEM_DIR/hooks/pre-tool-use.sh" \
+    "PreToolUse hook (Read)"
 
 # ─── Install skills ────────────────────────────────────────
 

package/scripts/update.sh

@@ -76,6 +76,7 @@ if [ -f "$SETTINGS" ] && command -v jq &>/dev/null; then
     eagle_patch_hook "$SETTINGS" "SessionEnd" "" "$EAGLE_MEM_DIR/hooks/session-end.sh"
     eagle_patch_hook "$SETTINGS" "UserPromptSubmit" "" "$EAGLE_MEM_DIR/hooks/user-prompt-submit.sh"
     eagle_patch_hook "$SETTINGS" "PreToolUse" "Bash" "$EAGLE_MEM_DIR/hooks/pre-tool-use.sh"
+    eagle_patch_hook "$SETTINGS" "PreToolUse" "Read" "$EAGLE_MEM_DIR/hooks/pre-tool-use.sh"
 
     eagle_ok "Hooks registered"
 fi