eagle-mem 4.4.0 → 4.6.0

package/README.md

@@ -1,23 +1,22 @@
 ```
 ======================================
-Eagle Mem
+       Eagle Mem
 ======================================
 ```
 
 # Eagle Mem
 
-Persistent memory for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Every session starts with context from previous sessions — summaries, memories, tasks, and project overviews — injected automatically via hooks.
+## The Problem
 
-**Zero per-instance overhead.** No daemon, no vector DB, no MCP server. Just bash scripts, sqlite3, and jq.
+Claude Code starts every session with amnesia. It doesn't remember what you built yesterday, what decisions you made, what files matter, or what broke last time. Every `/compact` wipes context. Every new session is a cold start. You waste tokens re-explaining your project, re-reading files, and watching Claude repeat mistakes you already corrected.
 
-## Getting started
+The longer you work with Claude Code, the worse this gets. Projects accumulate history — decisions, gotchas, architectural patterns, feature dependencies — and none of it survives across sessions.
 
-```bash
-npm install -g eagle-mem
-eagle-mem install
-```
+## The Solution
 
-That's it. Open Claude Code in any project directory. Eagle Mem activates automatically:
+Eagle Mem gives Claude Code persistent memory. Every session starts with context from previous sessions — summaries, decisions, memories, tasks, project overviews, and relevant code — injected automatically via hooks. No commands to run, no prompts to write. It just works.
+
+**Zero per-instance overhead.** No daemon, no vector DB, no MCP server. Just bash scripts, sqlite3 (WAL mode, FTS5 full-text search), and jq.
 
 ```
 ======================================
@@ -32,66 +31,46 @@ That's it. Open Claude Code in any project directory. Eagle Mem activates automa
 ======================================
 ```
 
-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
-
-Six commands. Three for lifecycle, three for lookup and troubleshooting.
+## Getting Started
 
-| 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` | Single lookup command — see modes below |
-| `eagle-mem health` | Diagnose pipeline health and background automation |
-| `eagle-mem config` | View or change LLM provider settings |
+```bash
+npm install -g eagle-mem
+eagle-mem install
+```
 
-### Search modes
+That's it. Open Claude Code in any project directory. Eagle Mem activates automatically.
 
-| Mode | What it does |
-|------|-------------|
-| `eagle-mem search "query"` | FTS5 keyword search across session summaries |
-| `eagle-mem search --timeline` | Recent sessions in chronological order |
-| `eagle-mem search --overview` | View project overview |
-| `eagle-mem search --memories` | Mirrored Claude Code memories |
-| `eagle-mem search --tasks` | In-flight tasks (pending/in-progress) |
-| `eagle-mem search --files` | Most frequently modified files |
-| `eagle-mem search --stats` | Project statistics (counts) |
-| `eagle-mem search --session <id>` | Full observation trail for one session |
+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.
 
-## Skills (inside Claude Code)
+### Prerequisites
 
-| Skill | What it does |
-|-------|-------------|
-| `/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` |
+- `sqlite3` with FTS5 support (ships with macOS; the installer offers to install if missing)
+- `jq` (the installer offers to install if missing)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed (`~/.claude/` must exist)
 
-## How it works
+## How It Works
 
 Six hooks fire automatically at different points in Claude Code's lifecycle:
 
-| Hook | Fires when | What it does |
+| Hook | Fires When | What It Does |
 |------|-----------|--------------|
 | **SessionStart** | startup, resume, clear, compact | Injects overview, summaries, memories, tasks, core files, working set. Auto-provisions new projects (scan, index). |
-| **PreToolUse** | before Bash, Read, Edit, and Write calls | Rewrites noisy commands (learned rules), detects redundant reads, nudges co-edit partners |
-| **UserPromptSubmit** | user sends a message | FTS5 search for relevant past context |
-| **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 |
+| **PreToolUse** | before Bash, Read, Edit, Write | Surfaces guardrails and decisions before edits. Rewrites noisy commands (learned rules). Detects redundant reads, nudges co-edit partners, detects stuck loops. |
+| **UserPromptSubmit** | user sends a message | FTS5 search across past sessions and indexed code for relevant context |
+| **PostToolUse** | after tool calls | Records file touches, mirrors memory/plan/task writes, surfaces decision history on reads |
+| **Stop** | Claude's turn ends | Extracts `<eagle-summary>` blocks for rich session summaries |
 | **SessionEnd** | session closes | Re-syncs tasks, marks session completed |
 
-### Background automation
+### 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 command rules, co-edit patterns, and hot file detection (partially requires LLM provider)
+- **Auto-curate** — the self-learning curator analyzes observation data and generates command rules, co-edit patterns, hot file detection, and guardrails (partially requires LLM provider)
 
-### Token savings
+### Token Savings
 
 Eagle Mem actively reduces token consumption:
 
@@ -104,28 +83,94 @@ Eagle Mem actively reduces token consumption:
 - **Working set recovery** — on compact, SessionStart injects the files you were actively editing so you resume without re-reading everything
 - **Stuck loop detection** — if the same file is edited 5+ times in one session, PreToolUse nudges to reconsider the approach
 
-### Data
+### Anti-Regression
+
+Eagle Mem prevents Claude from repeating past mistakes:
+
+- **Decision surfacing** — when you edit a file that has past decisions recorded (from `<eagle-summary>` blocks), PreToolUse reminds Claude not to revert without asking
+- **Guardrails** — file-level rules (manual or curator-discovered) that fire before every Edit/Write
+- **Feature verification** — tracks features with smoke tests and dependencies; reminds you to verify on `git push`
+- **Gotcha surfacing** — past surprises and gotchas are surfaced when editing related files
+
+## Commands
+
+| 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` | Search past sessions, memories, and code |
+| `eagle-mem health` | Diagnose pipeline health and background automation |
+| `eagle-mem config` | View or change LLM provider settings |
+| `eagle-mem guard` | Manage regression guardrails for files |
+| `eagle-mem overview` | Build or view project overview |
+| `eagle-mem memories` | View/sync Claude Code memories |
+| `eagle-mem tasks` | View mirrored tasks |
+| `eagle-mem curate` | Run curator (co-edits, hot files, guardrails) |
+| `eagle-mem feature` | Track and verify features |
+| `eagle-mem prune` | Clean old sessions and stale data |
+| `eagle-mem scan` | Scan codebase and generate overview |
+| `eagle-mem index` | Index source files for FTS5 code search |
+
+### Search Modes
+
+```bash
+eagle-mem search "auth bug"        # keyword search across summaries
+eagle-mem search --timeline        # recent sessions in chronological order
+eagle-mem search --overview        # project overview
+eagle-mem search --memories        # mirrored Claude Code memories
+eagle-mem search --tasks           # in-flight tasks (pending/in-progress)
+eagle-mem search --files           # most frequently modified files
+eagle-mem search --stats           # project statistics
+eagle-mem search --session <id>    # full observation trail for one session
+```
+
+## Skills (Inside Claude Code)
+
+| Skill | What It Does |
+|-------|-------------|
+| `/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` |
+
+## Data
 
 Single SQLite database at `~/.eagle-mem/memory.db` (WAL mode, FTS5 full-text search):
 
-| Table | What it stores |
+| 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 (auto-scan or manual) |
-| code_chunks | FTS5-indexed source file chunks |
-| command_rules | Curator-learned command output rules |
-| file_hints | Curator-learned file access patterns (co-edit pairs) |
-| claude_memories | Mirror of Claude Code auto-memories |
-| claude_plans | Mirror of Claude Code plans |
-| claude_tasks | Mirror of Claude Code tasks |
-
-## Prerequisites
+| `sessions` | Active/completed sessions per project |
+| `summaries` | Per-session summaries with decisions, gotchas, key files (FTS5-indexed) |
+| `observations` | Per-tool-use file touch records |
+| `overviews` | One overview per project (auto-scan or manual) |
+| `code_chunks` | FTS5-indexed source file chunks |
+| `command_rules` | Curator-learned command output rules |
+| `file_hints` | Curator-learned file access patterns (co-edit pairs, hot files) |
+| `guardrails` | File-level regression rules (manual or curator-discovered) |
+| `features` | Feature tracking with smoke tests and dependencies |
+| `eagle_meta` | Internal metadata (last scan, last curate, etc.) |
+| `claude_memories` | Mirror of Claude Code auto-memories |
+| `claude_plans` | Mirror of Claude Code plans |
+| `claude_tasks` | Mirror of Claude Code tasks |
 
-- `sqlite3` with FTS5 support (ships with macOS; the installer offers to install if missing)
-- `jq` (the installer offers to install if missing)
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed (`~/.claude/` must exist)
+### Project Identity
+
+Projects are identified by their HOME-relative path (e.g., `personal_projects/eagle-mem`). This ensures uniqueness even when multiple projects share the same directory name. Git repositories use the repo root; non-git directories use the working directory.
+
+### Namespace Migration
+
+When upgrading from older versions, `eagle-mem update` automatically migrates project data to the new namespace format. The migration preserves newer data when conflicts exist and cleans up stale entries.
+
+## LLM Provider (Optional)
+
+Some features (curator auto-enrichment, overview generation) can use an LLM for richer output. Configure with:
+
+```bash
+eagle-mem config
+```
+
+Supported providers: Ollama (auto-detected), Anthropic, OpenAI. Eagle Mem works fully without a provider — LLM features gracefully degrade to heuristic fallbacks.
 
 ## License
 

package/hooks/post-tool-use.sh

@@ -24,14 +24,43 @@ hook_event=$(echo "$input" | jq -r '.hook_event_name // empty')
 
 if [ -z "$session_id" ]; then exit 0; fi
 
-# TaskCreated/TaskCompleted dedicated events — mirror tasks and exit
+# TaskCreated/TaskCompleted dedicated events — parse top-level fields and exit
 case "$hook_event" in
     TaskCreated|TaskCompleted)
         [ ! -f "$EAGLE_MEM_DB" ] && exit 0
         project=$(eagle_project_from_cwd "$cwd")
         [ -z "$project" ] && exit 0
         eagle_upsert_session "$session_id" "$project" "$cwd" "" ""
-        eagle_posttool_mirror_tasks "TaskCreate" "$session_id" "$project" "$input"
+
+        task_id=$(echo "$input" | jq -r '.task_id // empty')
+        task_subject=$(echo "$input" | jq -r '.task_subject // empty')
+        task_desc=$(echo "$input" | jq -r '.task_description // empty')
+
+        if [ -n "$task_id" ] && [ -n "$task_subject" ]; then
+            local_status="pending"
+            [ "$hook_event" = "TaskCompleted" ] && local_status="completed"
+
+            # Synthetic file_path keyed on session+task — file_path is the UNIQUE column
+            synthetic_fp="event://${session_id}/${task_id}"
+
+            tid_sql=$(eagle_sql_escape "$task_id")
+            fp_sql=$(eagle_sql_escape "$synthetic_fp")
+            proj_sql=$(eagle_sql_escape "$project")
+            sid_sql=$(eagle_sql_escape "$session_id")
+            subj_sql=$(eagle_sql_escape "$task_subject")
+            desc_sql=$(eagle_sql_escape "$task_desc")
+            stat_sql=$(eagle_sql_escape "$local_status")
+
+            eagle_db_pipe <<SQL
+INSERT INTO claude_tasks (project, source_session_id, source_task_id, file_path, subject, description, status)
+VALUES ('$proj_sql', '$sid_sql', '$tid_sql', '$fp_sql', '$subj_sql', '$desc_sql', '$stat_sql')
+ON CONFLICT(file_path) DO UPDATE SET
+    subject     = excluded.subject,
+    description = excluded.description,
+    status      = excluded.status,
+    updated_at  = strftime('%Y-%m-%dT%H:%M:%fZ', 'now');
+SQL
+        fi
         exit 0
         ;;
 esac

package/hooks/pre-tool-use.sh

@@ -80,8 +80,9 @@ Bash)
                     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}"
+                        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
@@ -91,7 +92,7 @@ ${context}"
     # ─── Command output filtering (learned rules) ─────────────
 
     base_cmd=$(echo "$cmd" | awk '{print $1}' | sed 's|.*/||')
-    rule=$(eagle_get_command_rule "$project" "$base_cmd")
+    rule=$(eagle_get_command_rule "$project" "$base_cmd" "$cmd")
 
     if [ -n "$rule" ]; then
         IFS='|' read -r strategy max_lines reason <<< "$rule"
@@ -105,7 +106,7 @@ ${context}"
                         *"| head"*|*"| tail"*|*"| wc"*|*"| grep"*|*">"*|*">>"*)
                             ;;
                         *)
-                            updated_input=$(jq -nc --arg cmd "${cmd} | head -${max_lines}" '{"command":$cmd}')
+                            updated_input=$(echo "$input" | jq --arg cmd "${cmd} | head -${max_lines}" '.tool_input + {"command":$cmd}')
                             context+="Eagle Mem: '${base_cmd}' output is typically long (${reason}). Piped through head -${max_lines}."
                             ;;
                     esac
@@ -146,12 +147,12 @@ Edit|Write)
                     while IFS= read -r ctx_line; do
                         case "$ctx_line" in
                             GR:*)  gr_block+="  - ${ctx_line#GR:}"$'\n' ;;
-                            DEC:*) context+="Eagle Mem decisions for '${fname}': ${ctx_line#DEC:} — Do not revert without asking. " ;;
-                            GOT:*) context+="Eagle Mem gotchas for '${fname}': ${ctx_line#GOT:} " ;;
+                            DEC:*) context+="=== Eagle Mem ==="$'\n'"Decisions for '${fname}': ${ctx_line#DEC:} — Do not revert without asking."$'\n'"================"$'\n' ;;
+                            GOT:*) context+="=== Eagle Mem ==="$'\n'"Gotchas for '${fname}': ${ctx_line#GOT:}"$'\n'"================"$'\n' ;;
                         esac
                     done <<< "$edit_ctx"
                     if [ -n "$gr_block" ]; then
-                        context+="Eagle Mem guardrails for '${fname}':"$'\n'"${gr_block}"
+                        context+="=== Eagle Mem ==="$'\n'"Guardrails for '${fname}':"$'\n'"${gr_block}================"$'\n'
                     fi
                 fi
                 ;;

package/hooks/session-start.sh

@@ -322,9 +322,15 @@ Memory active for '$project'. Scan, index, prune, and self-learning run automati
 
 Before your final response, emit:
 <eagle-summary>
-request: [what user asked] | completed: [what shipped] | learned: [non-obvious discoveries]
-next_steps: [concrete actions] | decisions: [choice — why] | gotchas: [what surprised]
-key_files: [path — role] | files_read: [...] | files_modified: [...]
+request: [what user asked]
+completed: [what shipped]
+learned: [non-obvious discoveries]
+decisions: [choice — why]
+gotchas: [what surprised]
+next_steps: [concrete actions]
+key_files: [path — role]
+files_read: [path, ...]
+files_modified: [path, ...]
 </eagle-summary>
 "
 fi

package/hooks/stop.sh

@@ -231,6 +231,31 @@ else
     eagle_log "INFO" "Stop: LLM enrichment skipped — rich data already present"
 fi
 
+# ─── Heuristic fallback: derive fields from tool activity when no LLM ──
+# Fills key_files and completed from files_modified when both are empty
+
+if [ -z "$key_files" ] && [ -n "$files_modified" ] && [ "$files_modified" != "[]" ]; then
+    key_files=$(echo "$files_modified" | jq -r '.[]?' 2>/dev/null | while read -r f; do basename "$f"; done | sort -u | head -10 | paste -sd ', ' -)
+fi
+
+if [ -z "$completed" ] && [ -n "$files_modified" ] && [ "$files_modified" != "[]" ]; then
+    mod_count=$(echo "$files_modified" | jq -r '.[]?' 2>/dev/null | wc -l | tr -d ' ')
+    mod_names=$(echo "$files_modified" | jq -r '.[]?' 2>/dev/null | while read -r f; do basename "$f"; done | sort -u | head -5 | paste -sd ', ' -)
+    if [ "${mod_count:-0}" -gt 0 ]; then
+        completed="Modified ${mod_count} files: ${mod_names}"
+    fi
+elif [ -z "$completed" ] && [ -n "$files_read" ] && [ "$files_read" != "[]" ]; then
+    read_count=$(echo "$files_read" | jq -r '.[]?' 2>/dev/null | wc -l | tr -d ' ')
+    read_names=$(echo "$files_read" | jq -r '.[]?' 2>/dev/null | while read -r f; do basename "$f"; done | sort -u | head -5 | paste -sd ', ' -)
+    if [ "${read_count:-0}" -gt 0 ]; then
+        completed="Reviewed ${read_count} files: ${read_names}"
+    fi
+fi
+
+if [ -z "$key_files" ] && [ -n "$files_read" ] && [ "$files_read" != "[]" ]; then
+    key_files=$(echo "$files_read" | jq -r '.[]?' 2>/dev/null | while read -r f; do basename "$f"; done | sort -u | head -10 | paste -sd ', ' -)
+fi
+
 # ─── Test reminder for guardrailed files ─────────────────
 
 if [ -n "$files_modified" ] && [ "$files_modified" != "[]" ]; then

package/hooks/user-prompt-submit.sh

@@ -81,7 +81,7 @@ fts_query=$(echo "$user_prompt" | tr -cs '[:alnum:]' ' ' | tr '[:upper:]' '[:low
 results=$(eagle_search_summaries "$fts_query" "$project" 3)
 
 if [ -n "$results" ]; then
-    context+="=== EAGLE MEM — Relevant Memory ===
+    context+="=== Eagle Mem — Relevant Memory ===
 "
     while IFS='|' read -r req completed learned _next_steps created_at _proj decisions gotchas key_files; do
         [ -z "$req" ] && [ -z "$completed" ] && continue
@@ -106,7 +106,7 @@ if [ "${has_chunks:-0}" -gt 0 ]; then
     code_results=$(eagle_search_code_chunks "$fts_query" "$project" 5)
 
     if [ -n "$code_results" ]; then
-        context+="=== EAGLE MEM — Relevant Code ===
+        context+="=== Eagle Mem — Relevant Code ===
 "
         while IFS='|' read -r fpath sline eline lang; do
             [ -z "$fpath" ] && continue
@@ -123,7 +123,7 @@ fi
 context+="
 IMPORTANT: When Eagle Mem finds relevant memories or code for the user's prompt, briefly mention it at the start of your response: \"Eagle Mem recalled N relevant sessions\" or \"Eagle Mem found related code in [files]\". One line max — then proceed with the answer.
 
-— Eagle Mem (persistent memory across sessions)
+=== Eagle Mem (persistent memory across sessions) ===
 "
 
 echo "$context"

package/lib/common.sh

@@ -39,18 +39,27 @@ eagle_project_from_cwd() {
         "$HOME/Desktop"|"$HOME/Desktop/"*) echo ""; return ;;
     esac
 
+    local target_dir
     local git_root
     git_root=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null)
     if [ -n "$git_root" ]; then
-        basename "$git_root"
+        target_dir="$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"
+        target_dir="$cwd"
+    fi
+
+    local name
+    name=$(basename "$target_dir")
+    if [ ${#name} -le 1 ]; then
+        echo ""; return
+    fi
+
+    if [[ "$target_dir" == "$HOME/"* ]]; then
+        echo "${target_dir#$HOME/}"
+    elif [ "$target_dir" = "$HOME" ]; then
+        echo "$name"
+    else
+        echo "${target_dir#/}"
     fi
 }
 
@@ -66,7 +75,7 @@ eagle_sql_int() {
 }
 
 eagle_fts_sanitize() {
-    printf '%s' "$1" | sed 's/[*"(){}^~:]/  /g' | sed 's/  */ /g; s/^ //; s/ $//'
+    printf '%s' "$1" | sed 's/[^A-Za-z0-9_]/ /g' | sed 's/  */ /g; s/^ //; s/ $//'
 }
 
 # Escape SQL LIKE wildcards (% and _) so literal filenames match exactly.
@@ -158,17 +167,8 @@ eagle_collect_files() {
     fi
 }
 
-eagle_patch_claude_md() {
-    local claude_md="$HOME/.claude/CLAUDE.md"
-    local marker="## Eagle Mem — Persistent Memory"
-
-    if [ -f "$claude_md" ] && grep -qF "$marker" "$claude_md" 2>/dev/null; then
-        return 1
-    fi
-
-    mkdir -p "$HOME/.claude"
-
-    cat >> "$claude_md" << 'EAGLE_MD'
+_eagle_claude_md_section() {
+    cat << 'EAGLE_MD'
 
 ---
 
@@ -180,9 +180,15 @@ Eagle Mem hooks are active in every project. SessionStart injects context (overv
 
 ```
 <eagle-summary>
-request: [what user asked] | completed: [what shipped] | learned: [non-obvious discoveries]
-next_steps: [concrete actions] | decisions: [choice — why] | gotchas: [what surprised]
-key_files: [path — role] | files_read: [...] | files_modified: [...]
+request: [what user asked]
+completed: [what shipped]
+learned: [non-obvious discoveries]
+decisions: [choice — why]
+gotchas: [what surprised]
+next_steps: [concrete actions]
+key_files: [path — role]
+files_read: [path, ...]
+files_modified: [path, ...]
 </eagle-summary>
 ```
 
@@ -196,3 +202,34 @@ key_files: [path — role] | files_read: [...] | files_modified: [...]
 - If you contradict a loaded memory, update the memory file
 EAGLE_MD
 }
+
+eagle_patch_claude_md() {
+    local claude_md="$HOME/.claude/CLAUDE.md"
+    local marker="## Eagle Mem — Persistent Memory"
+
+    mkdir -p "$HOME/.claude"
+
+    if [ -f "$claude_md" ] && grep -qF "$marker" "$claude_md" 2>/dev/null; then
+        # Check if section has outdated pipe-separated format
+        if grep -qF 'request: \[what user asked\] | completed:' "$claude_md" 2>/dev/null; then
+            # Replace the outdated section: remove old, append new
+            local tmp_md
+            tmp_md=$(mktemp)
+            awk -v marker="$marker" '
+                $0 ~ marker { skip=1; next }
+                skip && /^---$/ && !seen_end { seen_end=1; next }
+                skip && /^## / { skip=0 }
+                !skip { print }
+            ' "$claude_md" > "$tmp_md"
+            # Remove trailing blank lines left by section removal
+            sed -e :a -e '/^[[:space:]]*$/{ $d; N; ba; }' "$tmp_md" > "${tmp_md}.clean"
+            mv "${tmp_md}.clean" "$claude_md"
+            rm -f "$tmp_md"
+            _eagle_claude_md_section >> "$claude_md"
+            return 0
+        fi
+        return 1
+    fi
+
+    _eagle_claude_md_section >> "$claude_md"
+}

package/lib/db-backfill.sh

@@ -39,16 +39,28 @@ eagle_backfill_projects() {
     map=$(eagle_build_session_project_map)
     [ -z "$map" ] && echo "0" && return 0
 
+    # Phase 1: Build old→new project mapping BEFORE mutating any rows.
+    # Collect from sessions table so non-session tables can be migrated.
+    local rename_map_file
+    rename_map_file=$(mktemp)
+    while IFS='|' read -r sid project; do
+        [ -z "$sid" ] || [ -z "$project" ] && continue
+        local sid_sql
+        sid_sql=$(eagle_sql_escape "$sid")
+        local old_project
+        old_project=$(eagle_db "SELECT project FROM sessions WHERE id = '$sid_sql';")
+        if [ -n "$old_project" ] && [ "$old_project" != "$project" ]; then
+            echo "$old_project|$project" >> "$rename_map_file"
+        fi
+    done <<< "$map"
+
+    # Phase 2: Update session-linked tables
     while IFS='|' read -r sid project; do
         [ -z "$sid" ] || [ -z "$project" ] && continue
         local sid_sql proj_sql
         sid_sql=$(eagle_sql_escape "$sid")
         proj_sql=$(eagle_sql_escape "$project")
 
-        # All six tables updated atomically per session to prevent
-        # partial backfill if the process is interrupted.
-        # Note: total_changes() includes FTS trigger changes, so the
-        # reported count may be higher than actual rows updated.
         local ch
         ch=$(eagle_db_pipe <<SQL
 BEGIN;
@@ -65,6 +77,52 @@ SQL
         [ "${ch:-0}" -gt 0 ] && updated=$((updated + ch))
     done <<< "$map"
 
+    # Phase 3: Update non-session tables using the old→new mapping.
+    # Skip ambiguous mappings (one old name → multiple new names).
+    if [ -s "$rename_map_file" ]; then
+        local uniq_map
+        uniq_map=$(sort -u "$rename_map_file")
+        local prev_old=""
+        local ambiguous=""
+        while IFS='|' read -r old_proj new_proj; do
+            [ -z "$old_proj" ] && continue
+            if [ "$old_proj" = "$prev_old" ]; then
+                ambiguous+="$old_proj|"
+            fi
+            prev_old="$old_proj"
+        done <<< "$(echo "$uniq_map" | sort -t'|' -k1,1)"
+
+        while IFS='|' read -r old_proj new_proj; do
+            [ -z "$old_proj" ] || [ -z "$new_proj" ] && continue
+            case "$ambiguous" in *"$old_proj|"*) continue ;; esac
+
+            local old_sql new_sql
+            old_sql=$(eagle_sql_escape "$old_proj")
+            new_sql=$(eagle_sql_escape "$new_proj")
+
+            eagle_db_pipe <<SQL 2>/dev/null
+BEGIN;
+UPDATE OR IGNORE overviews SET project = '$new_sql' WHERE project = '$old_sql';
+DELETE FROM overviews WHERE project = '$old_sql';
+DELETE FROM code_chunks WHERE project = '$old_sql'
+  AND EXISTS (SELECT 1 FROM code_chunks WHERE project = '$new_sql' LIMIT 1);
+UPDATE code_chunks SET project = '$new_sql' WHERE project = '$old_sql';
+UPDATE OR IGNORE features SET project = '$new_sql' WHERE project = '$old_sql';
+DELETE FROM features WHERE project = '$old_sql';
+UPDATE OR IGNORE command_rules SET project = '$new_sql' WHERE project = '$old_sql';
+DELETE FROM command_rules WHERE project = '$old_sql';
+UPDATE OR IGNORE eagle_meta SET project = '$new_sql' WHERE project = '$old_sql';
+DELETE FROM eagle_meta WHERE project = '$old_sql';
+UPDATE OR IGNORE file_hints SET project = '$new_sql' WHERE project = '$old_sql';
+DELETE FROM file_hints WHERE project = '$old_sql';
+UPDATE OR IGNORE guardrails SET project = '$new_sql' WHERE project = '$old_sql';
+DELETE FROM guardrails WHERE project = '$old_sql';
+COMMIT;
+SQL
+        done <<< "$uniq_map"
+    fi
+    rm -f "$rename_map_file"
+
     echo "$updated"
 }
 

package/lib/db-mirrors.sh

@@ -55,6 +55,10 @@ SQL
 
 eagle_search_claude_memories() {
     local query; query=$(eagle_fts_sanitize "$1")
+    if [ -z "$query" ]; then
+        echo "Search query is empty after sanitization. Try a different search term." >&2
+        return 1
+    fi
     query=$(eagle_sql_escape "$query")
     local project="${2:-}"
     local limit; limit=$(eagle_sql_int "${3:-10}")
@@ -131,6 +135,10 @@ SQL
 
 eagle_search_claude_plans() {
     local query; query=$(eagle_fts_sanitize "$1")
+    if [ -z "$query" ]; then
+        echo "Search query is empty after sanitization. Try a different search term." >&2
+        return 1
+    fi
     query=$(eagle_sql_escape "$query")
     local project="${2:-}"
     local limit; limit=$(eagle_sql_int "${3:-10}")
@@ -242,6 +250,10 @@ eagle_list_claude_tasks() {
 
 eagle_search_claude_tasks() {
     local query; query=$(eagle_fts_sanitize "$1")
+    if [ -z "$query" ]; then
+        echo "Search query is empty after sanitization. Try a different search term." >&2
+        return 1
+    fi
     query=$(eagle_sql_escape "$query")
     local project="${2:-}"
     local limit; limit=$(eagle_sql_int "${3:-10}")

package/lib/db-observations.sh

@@ -46,12 +46,13 @@ eagle_prune_observations() {
 
 eagle_get_command_rule() {
     local project; project=$(eagle_sql_escape "$1")
-    local cmd; cmd=$(eagle_sql_escape "$2")
+    local base_cmd; base_cmd=$(eagle_sql_escape "$2")
+    local full_cmd; full_cmd=$(eagle_sql_escape "${3:-$2}")
     eagle_db "SELECT strategy, max_lines, reason
         FROM command_rules
         WHERE enabled = 1
         AND (project = '$project' OR project = '')
-        AND ('$cmd' LIKE pattern OR '$cmd' = pattern)
+        AND ('$base_cmd' = pattern OR '$full_cmd' = pattern OR '$full_cmd' LIKE pattern || ' %')
         ORDER BY CASE WHEN project != '' THEN 0 ELSE 1 END,
             LENGTH(pattern) DESC
         LIMIT 1;"

package/lib/hooks-posttool.sh

@@ -75,7 +75,9 @@ eagle_posttool_stale_hint() {
                                 local stale_hit
                                 stale_hit=$(eagle_search_stale_memories "$project" "$fts_query")
                                 if [ -n "$stale_hit" ]; then
-                                    local stale_msg="Eagle Mem: Memory '${stale_hit}' may reference '${fname}'. If your edit contradicts it, update the memory."
+                                    local stale_msg="=== Eagle Mem ===
+Memory '${stale_hit}' may reference '${fname}'. If your edit contradicts it, update the memory.
+================"
                                     jq -nc --arg ctx "$stale_msg" '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":$ctx}}'
                                 fi
                             fi
@@ -106,7 +108,10 @@ eagle_posttool_decision_surface() {
                                 local decision_hit
                                 decision_hit=$(eagle_search_decisions_for_file "$project" "$fts_query")
                                 if [ -n "$decision_hit" ]; then
-                                    read_context+="Eagle Mem decision history for '${fname}': ${decision_hit} — Do not revert without explicit user request. "
+                                    read_context+="=== Eagle Mem ===
+Decision history for '${fname}': ${decision_hit} — Do not revert without explicit user request.
+================
+"
                                 fi
                             fi
                         fi
@@ -116,14 +121,17 @@ eagle_posttool_decision_surface() {
                         if [ -n "$feature_hit" ]; then
                             while IFS='|' read -r feat_name feat_desc feat_verified _role feat_deps feat_other_files feat_smoke; do
                                 [ -z "$feat_name" ] && continue
-                                read_context+="Eagle Mem: '${fname}' is part of feature '${feat_name}'"
+                                read_context+="=== Eagle Mem ===
+'${fname}' is part of feature '${feat_name}'"
                                 [ -n "$feat_desc" ] && read_context+=" ($feat_desc)"
                                 read_context+="."
                                 [ -n "$feat_verified" ] && read_context+=" Last verified: ${feat_verified}."
                                 [ -n "$feat_deps" ] && read_context+=" Dependencies: ${feat_deps}."
                                 [ -n "$feat_other_files" ] && read_context+=" Other files in pipeline: ${feat_other_files}."
                                 [ -n "$feat_smoke" ] && read_context+=" Smoke tests: ${feat_smoke}."
-                                read_context+=" Changes require re-testing after deploy. "
+                                read_context+=" Changes require re-testing after deploy.
+================
+"
                             done <<< "$feature_hit"
                         fi
 

package/lib/hooks-sessionstart.sh

@@ -8,16 +8,22 @@ _EAGLE_HOOKS_SESSIONSTART_LOADED=1
 
 _state_dir="$EAGLE_MEM_DIR/state"
 
+_eagle_state_slug() {
+    printf '%s' "$1" | shasum | cut -c1-12
+}
+
 _eagle_state_fresh() {
     local key="$1" project="$2" max_age_days="${3:-1}"
-    local state_file="$_state_dir/${key}-${project}"
+    local safe_project; safe_project=$(_eagle_state_slug "$project")
+    local state_file="$_state_dir/${key}-${safe_project}"
     [ -f "$state_file" ] && [ -z "$(find "$state_file" -mtime +${max_age_days} 2>/dev/null)" ]
 }
 
 _eagle_state_touch() {
     local key="$1" project="$2"
+    local safe_project; safe_project=$(_eagle_state_slug "$project")
     mkdir -p "$_state_dir" 2>/dev/null
-    touch "$_state_dir/${key}-${project}"
+    touch "$_state_dir/${key}-${safe_project}"
 }
 
 eagle_sessionstart_auto_provision() {

package/package.json

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

package/scripts/health.sh

@@ -54,8 +54,8 @@ 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 != '');")
+heuristic_summaries=$(eagle_db "SELECT COUNT(*) FROM summaries WHERE project = '$p_esc' AND (decisions IS NULL OR decisions = '') AND (gotchas IS NULL OR gotchas = '');")
+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 != '');")
 
 if [ "${total_sessions:-0}" -eq 0 ]; then
     capture_pct=0
@@ -92,7 +92,7 @@ fi
 
 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"
+        eagle_ok "Enriched: ${enriched_summaries}/${total_summaries} (${enrich_pct}%) have decisions/gotchas"
         score=$((score + 25))
     elif [ "$enrich_pct" -ge 20 ]; then
         eagle_warn "Enriched: ${enriched_summaries}/${total_summaries} (${enrich_pct}%) — LLM extraction may need tuning"
@@ -101,9 +101,9 @@ if [ "${total_summaries:-0}" -gt 0 ]; then
     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.")
+        issues+=("${enrich_pct}% enrichment. Decisions/gotchas mostly missing.")
     else
-        eagle_fail "Enriched: 0/${total_summaries} — no summaries have decisions/gotchas/key_files"
+        eagle_fail "Enriched: 0/${total_summaries} — no summaries have decisions/gotchas"
         issues+=("Zero enrichment. Check provider config: eagle-mem config")
     fi
 else

package/scripts/memories.sh

@@ -16,8 +16,12 @@ eagle_ensure_db
 
 # ─── Parse arguments ──────────────────────────────────────
 
-action="${1:-list}"
-shift 2>/dev/null || true
+action="list"
+case "${1:-}" in
+    -*)  ;; # flags parsed below
+    "")  ;;
+    *)   action="$1"; shift ;;
+esac
 
 project=""
 limit=20

package/scripts/statusline-em.sh

@@ -8,12 +8,14 @@ eagle_mem_statusline() {
     local em_db="$HOME/.eagle-mem/memory.db"
     [ -f "$em_db" ] || return
 
+    local SCRIPT_DIR; SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    . "$SCRIPT_DIR/../lib/common.sh"
+
     local proj
-    proj=$(basename "$project_dir")
+    proj=$(eagle_project_from_cwd "$project_dir")
     [ -z "$proj" ] && return
 
-    # Escape single quotes for safe SQL interpolation
-    proj=$(printf '%s' "$proj" | sed "s/'/''/g")
+    proj=$(eagle_sql_escape "$proj")
 
     local cnt mem
     cnt=$(echo ".headers off