eagle-mem 3.2.0 → 4.0.0

package/README.md

@@ -12,183 +12,97 @@ Persistent memory for [Claude Code](https://docs.anthropic.com/en/docs/claude-co
 
 ## Getting started
 
-**1. Install** (once — this is the only setup step):
-
 ```bash
 npm install -g eagle-mem
 eagle-mem install
 ```
 
-**2. Open Claude Code** in any project directory. Eagle Mem activates and shows what it loaded:
+That's it. Open Claude Code in any project directory. Eagle Mem activates automatically:
 
 ```
 ======================================
        Eagle Mem Loaded
 ======================================
  Project      | my-app
- Sessions     | 42 total (18 with summaries)
+ Sessions     | 42 (18 with summaries)
  Memories     | 7 stored
- Plans        | 2 saved
- Tasks        | 1 in progress, 3 pending, 12 completed
- Code Index   | 156 chunks indexed
- Observations | 340 captured
- Last Active  | 2026-04-28
+ Tasks        | 1 in progress, 3 pending
+ Code Index   | 156 chunks
  Last Work    | Added auth middleware with JWT validation
 ======================================
 ```
 
-From here, everything is automatic. You don't run any commands — Eagle Mem captures session summaries, mirrors Claude's memories and tasks, and re-injects context after every `/compact` or new session.
-
-**3. Already have Claude Code history on a project?** Run this inside the project directory:
-
-```bash
-cd ~/projects/my-app
-eagle-mem refresh
-```
-
-This backfills everything into Eagle Mem:
-
-```
-Eagle Mem  Refresh
-─────────────────────────────────────
-
-Step 1/4: Scanning codebase structure...
-  ✓  120 files found
-  ✓  Languages: TypeScript (15k lines), CSS (2k lines)
-  ✓  Frameworks: Next.js, React, Tailwind, Prisma
-  ✓  Scan complete
-
-Step 2/4: Indexing source files...
-  ✓  Index complete
-
-Step 3/4: Syncing Claude Code memories, plans, and tasks...
-  ✓  Memory sync complete
-
-Step 4/4: Verifying...
-  Sessions:    12
-  Code chunks: 340
-  Memories:    8
-  Tasks:       15
-```
-
-Now open Claude Code in that project — it sees your full history from the start.
+Everything is automatic from here. Eagle Mem scans your codebase, indexes source files, captures session summaries, mirrors Claude's memories and tasks, learns which commands are noisy, and prunes stale data — all in the background via hooks.
 
 ## Commands
 
-Eagle Mem gives you terminal commands for when you need to look something up or manage your data outside of Claude Code.
-
-### Search past sessions
-
-```bash
-eagle-mem search "auth middleware"
-```
-
-Searches across session summaries, Claude memories, and indexed code using FTS5. Use this when you know you worked on something last week but can't remember the details.
-
-```bash
-eagle-mem search --timeline
-```
-
-Shows your most recent sessions in chronological order — useful for catching up after a break.
-
-### View or set your project overview
-
-```bash
-eagle-mem overview
-```
-
-Shows the overview that gets injected into every Claude Code session. This is what Claude reads first to understand your project.
-
-```bash
-eagle-mem overview set "My app is a Next.js dashboard for monitoring API health..."
-```
-
-Set a custom overview. You can also let Claude write one for you by running `/eagle-mem-overview` inside a Claude Code session — it reads your README, entry points, and git history to synthesize one.
-
-### Sync everything
+Six commands. Three for lifecycle, three for when you need to look something up or troubleshoot.
 
-```bash
-eagle-mem refresh
-```
-
-Run this inside a project directory after major changes (new packages, restructured directories, pulling a large branch). It re-scans the codebase, re-indexes source files, and syncs any new Claude Code memories and tasks.
-
-### Other commands
-
-| Command | When to use it |
-|---------|---------------|
-| `eagle-mem scan` | Re-analyze codebase structure (languages, frameworks, entry points) |
-| `eagle-mem index` | Re-index source files for code search |
-| `eagle-mem memories` | View or sync mirrored Claude Code memories and plans |
-| `eagle-mem tasks` | View mirrored Claude Code tasks |
-| `eagle-mem prune` | Clean up old observations and orphaned code chunks |
+| Command | What it does |
+|---------|-------------|
+| `eagle-mem install` | First-time setup: hooks, database, skills |
+| `eagle-mem update` | Re-deploy hooks and run migrations after `npm update` |
+| `eagle-mem uninstall` | Remove hooks and optionally delete data |
+| `eagle-mem search "query"` | Search past sessions, memories, and code (FTS5) |
+| `eagle-mem health` | Diagnose pipeline health and background automation |
+| `eagle-mem config` | View or change LLM provider settings |
 
 ## Skills (inside Claude Code)
 
-Inside a Claude Code session, you have slash commands that let Claude do the work for you:
-
-### `/eagle-mem-search`
-
-Search past sessions from within Claude Code. Claude interprets results and connects them to your current work — better than raw terminal search when you need context, not just a match.
-
-### `/eagle-mem-overview`
-
-Build a rich project briefing. Claude reads your README, entry points, recent git history, and current codebase to write a 2-3 paragraph overview that captures what the project *does*, not just its file counts. This overview is injected at every session start.
-
-### `/eagle-mem-tasks`
-
-Break complex work into tasks that survive `/compact`. Uses Claude Code's native `TaskCreate`/`TaskUpdate` with dependency support. When context fills up and you compact, Eagle Mem re-injects the task state so Claude picks up where it left off.
-
-### Other skills
-
 | Skill | What it does |
 |-------|-------------|
-| `/eagle-mem-scan` | Analyze codebase structure — languages, frameworks, entry points |
-| `/eagle-mem-index` | Index source files for FTS5 code search |
-| `/eagle-mem-memories` | View, search, and sync Claude Code's mirrored memories and plans |
-| `/eagle-mem-prune` | Database hygiene — graduated cleanup of stale data |
-
-## Updating
-
-```bash
-npm update -g eagle-mem
-eagle-mem update
-```
-
-The `update` command copies new files, runs any pending database migrations, and re-registers hooks. Your data is preserved.
+| `/eagle-mem-search` | Search memory and past sessions — Claude interprets results in context |
+| `/eagle-mem-overview` | Build a rich project briefing from README, entry points, and git history |
+| `/eagle-mem-memories` | View and search mirrored Claude Code memories and plans |
+| `/eagle-mem-tasks` | TaskAware Compact Loop — break complex work into tasks that survive `/compact` |
 
 ## 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 |
+| **SessionStart** | startup, resume, clear, compact | Injects overview, summaries, memories, tasks. Auto-provisions new projects (scan, index). |
+| **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 |
 
-Data lives in a single SQLite database at `~/.eagle-mem/memory.db` (WAL mode, FTS5 full-text search):
+### Background automation
+
+These run automatically via SessionStart — no commands needed:
+
+- **Auto-scan** — new project with no overview triggers a codebase scan
+- **Auto-index** — new or stale project triggers FTS5 source indexing
+- **Auto-prune** — observations over 10K rows trigger cleanup
+- **Auto-curate** — the self-learning curator analyzes observation data and generates project-specific command rules (requires LLM provider)
+
+### Token savings
+
+Eagle Mem actively reduces token consumption:
+
+- **Injection compression** — zero-value stats are elided from the banner, overview is capped, compact reloads get 1 recent session instead of 3
+- **Command rewriting** — PreToolUse rewrites noisy Bash commands to pipe through `head -N` via `updatedInput`. Rules are learned by the curator from real usage, not hardcoded.
+- **Read-after-modify detection** — detects when you read a file that was just edited or written, nudges that the diff is already in context
+- **Read dedup tracking** — files read 3+ times in a session get a soft nudge
+
+### Data
+
+Single SQLite database at `~/.eagle-mem/memory.db` (WAL mode, FTS5 full-text search):
 
 | Table | What it stores |
 |-------|---------------|
 | sessions | Active/completed sessions per project |
 | summaries | Per-session summaries (FTS5-indexed) |
 | observations | Per-tool-use file touch records |
-| overviews | One overview per project (scan or manual) |
+| overviews | One overview per project (auto-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 |
 
-## Uninstall
-
-```bash
-eagle-mem uninstall
-npm uninstall -g eagle-mem
-```
-
 ## Prerequisites
 
 - `sqlite3` with FTS5 support (ships with macOS; the installer offers to install if missing)

package/bin/eagle-mem

@@ -17,20 +17,11 @@ shift 2>/dev/null || true
 
 case "$command" in
     install)    bash "$SCRIPTS_DIR/install.sh" "$PACKAGE_DIR" "$@" ;;
-    uninstall)  bash "$SCRIPTS_DIR/uninstall.sh" "$@" ;;
     update)     bash "$SCRIPTS_DIR/update.sh" "$PACKAGE_DIR" "$@" ;;
-    scan)       bash "$SCRIPTS_DIR/scan.sh" "$@" ;;
-    index)      bash "$SCRIPTS_DIR/index.sh" "$@" ;;
+    uninstall)  bash "$SCRIPTS_DIR/uninstall.sh" "$@" ;;
     search)     bash "$SCRIPTS_DIR/search.sh" "$@" ;;
-    tasks)      bash "$SCRIPTS_DIR/tasks.sh" "$@" ;;
-    overview)   bash "$SCRIPTS_DIR/overview.sh" "$@" ;;
-    refresh)    bash "$SCRIPTS_DIR/refresh.sh" "$@" ;;
-    prune)      bash "$SCRIPTS_DIR/prune.sh" "$@" ;;
-    memories)   bash "$SCRIPTS_DIR/memories.sh" "$@" ;;
-    config)     bash "$SCRIPTS_DIR/config.sh" "$@" ;;
-    curate)     bash "$SCRIPTS_DIR/curate.sh" "$@" ;;
-    feature)    bash "$SCRIPTS_DIR/feature.sh" "$@" ;;
     health)     bash "$SCRIPTS_DIR/health.sh" "$@" ;;
+    config)     bash "$SCRIPTS_DIR/config.sh" "$@" ;;
     help|--help|-h)
                 bash "$SCRIPTS_DIR/help.sh" ;;
     version|--version|-v|-V)

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