eagle-mem 4.2.0 → 4.4.0

package/bin/eagle-mem

@@ -22,6 +22,15 @@ case "$command" in
     search)     bash "$SCRIPTS_DIR/search.sh" "$@" ;;
     health)     bash "$SCRIPTS_DIR/health.sh" "$@" ;;
     config)     bash "$SCRIPTS_DIR/config.sh" "$@" ;;
+    guard)      bash "$SCRIPTS_DIR/guard.sh" "$@" ;;
+    overview)   bash "$SCRIPTS_DIR/overview.sh" "$@" ;;
+    memories)   bash "$SCRIPTS_DIR/memories.sh" "$@" ;;
+    tasks)      bash "$SCRIPTS_DIR/tasks.sh" "$@" ;;
+    curate)     bash "$SCRIPTS_DIR/curate.sh" "$@" ;;
+    feature)    bash "$SCRIPTS_DIR/feature.sh" "$@" ;;
+    prune)      bash "$SCRIPTS_DIR/prune.sh" "$@" ;;
+    scan)       bash "$SCRIPTS_DIR/scan.sh" "$@" ;;
+    index)      bash "$SCRIPTS_DIR/index.sh" "$@" ;;
     help|--help|-h)
                 bash "$SCRIPTS_DIR/help.sh" ;;
     version|--version|-v|-V)

package/db/022_cleanup_fossils.sql

@@ -0,0 +1,12 @@
+-- Clear fossil placeholder data that the COALESCE upsert preserves forever.
+-- These rows block real data from being written on future Stop hook fires.
+PRAGMA trusted_schema=ON;
+
+UPDATE summaries SET completed = ''
+WHERE completed LIKE '%(auto-captured%';
+
+UPDATE summaries SET request = ''
+WHERE request LIKE '%<local-command-caveat>%';
+
+UPDATE summaries SET request = ''
+WHERE request LIKE '%<system-reminder>%';

package/db/023_guardrails.sql

@@ -0,0 +1,18 @@
+-- ═══════════════════════════════════════════════════════════
+-- Migration 023: Guardrails table
+-- Persistent per-project rules surfaced at Edit/Write time
+-- ═══════════════════════════════════════════════════════════
+
+CREATE TABLE IF NOT EXISTS guardrails (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    project      TEXT NOT NULL,
+    file_pattern TEXT NOT NULL DEFAULT '',
+    rule         TEXT NOT NULL,
+    source       TEXT NOT NULL DEFAULT 'manual',
+    active       INTEGER NOT NULL DEFAULT 1,
+    created_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    updated_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    UNIQUE(project, source, file_pattern, rule)
+);
+
+CREATE INDEX IF NOT EXISTS idx_guardrails_project ON guardrails(project, active);

package/hooks/post-tool-use.sh

@@ -20,7 +20,23 @@ session_id=$(echo "$input" | jq -r '.session_id // empty')
 cwd=$(echo "$input" | jq -r '.cwd // empty')
 tool_name=$(echo "$input" | jq -r '.tool_name // empty')
 
-if [ -z "$session_id" ] || [ -z "$tool_name" ]; then exit 0; fi
+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
+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"
+        exit 0
+        ;;
+esac
+
+[ -z "$tool_name" ] && exit 0
 
 # Only track relevant tools
 case "$tool_name" in

package/hooks/pre-tool-use.sh

@@ -121,6 +121,42 @@ ${context}"
 Edit|Write)
     fp=$(echo "$input" | jq -r '.tool_input.file_path // empty')
     if [ -n "$fp" ]; then
+        # ─── Guardrail + decision/gotcha surfacing ────────
+        fname=$(basename "$fp")
+        fname_stem="${fname%.*}"
+        case "$fp" in
+            "$HOME/.claude/"*) ;;
+            *)
+                # Guardrails use GLOB on full filename — no stem length minimum needed.
+                # FTS decision/gotcha lookups need a meaningful stem (>= 3 chars).
+                if [ ${#fname_stem} -ge 3 ]; then
+                    fts_query=$(eagle_fts_sanitize "$fname_stem")
+                    fts_query=${fts_query:-"$fname_stem"}
+                    edit_ctx=$(eagle_get_edit_context "$project" "$fname" "$fts_query" 2>/dev/null)
+                else
+                    # Short stem (e.g. db.sh) — only fetch guardrails, skip FTS queries
+                    edit_ctx=$(eagle_get_guardrails_for_file "$project" "$fname" 2>/dev/null)
+                    if [ -n "$edit_ctx" ]; then
+                        # Prefix with GR: to match batched output format; strip empty lines
+                        edit_ctx=$(echo "$edit_ctx" | grep -v '^$' | sed 's/^/GR:/')
+                    fi
+                fi
+                if [ -n "$edit_ctx" ]; then
+                    gr_block=""
+                    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:} " ;;
+                        esac
+                    done <<< "$edit_ctx"
+                    if [ -n "$gr_block" ]; then
+                        context+="Eagle Mem guardrails for '${fname}':"$'\n'"${gr_block}"
+                    fi
+                fi
+                ;;
+        esac
+
         # ─── Stuck loop detection ─────────────────────────
         if [ -n "$session_id" ] && eagle_validate_session_id "$session_id"; then
             edit_tracker="$EAGLE_MEM_DIR/edit-tracker/${session_id}"

package/hooks/stop.sh

@@ -42,7 +42,13 @@ eagle_upsert_session "$session_id" "$project" "$cwd" "" ""
 
 # ─── 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)
+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 \
+    | grep -v '<local-command-caveat>' \
+    | grep -v '<system-reminder>' \
+    | grep -v '<command-name>' \
+    | grep -v '<command-message>' \
+    | grep -v '^\[{' \
+    | 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)
@@ -124,59 +130,132 @@ if [ -n "$summary_block" ]; then
     eagle_log "INFO" "Stop: eagle-summary block merged over heuristic data"
 fi
 
-# ─── LLM enrichment: fill in decisions/gotchas/key_files ─────
-# Check both local vars (from eagle-summary block) AND existing DB enrichment.
-# Skip LLM call if either source already has enrichment data.
-# Exception: under context pressure, force re-enrichment for richest summary.
+# ─── LLM enrichment: extract structured data when eagle-summary absent ──
+# Runs when: (a) no eagle-summary block, OR (b) heuristic data is thin
+# Skips when: eagle-summary already provided rich data, OR no text to analyze
 
 context_pressure=0
 if [ -f "$EAGLE_MEM_DIR/.context-pressure" ]; then
     context_pressure=1
 fi
 
-existing_enrichment=""
-if [ -z "$decisions" ] && [ -z "$gotchas" ] && [ -z "$key_files" ]; then
-    s_esc=$(eagle_sql_escape "$session_id")
-    existing_enrichment=$(eagle_db "SELECT decisions||gotchas||key_files FROM summaries WHERE session_id='$s_esc';")
+has_rich_data=0
+if [ -n "$decisions" ] || [ -n "$gotchas" ] || [ -n "$key_files" ]; then
+    has_rich_data=1
 fi
 
-if [ -z "$decisions" ] && [ -z "$gotchas" ] && [ -z "$key_files" ] && { [ -z "$existing_enrichment" ] || [ "$context_pressure" -eq 1 ]; }; then
+request_is_polluted=0
+if echo "$request" | grep -qE '<(local-command-caveat|system-reminder|command-name)>' 2>/dev/null; then
+    request_is_polluted=1
+fi
+
+needs_enrichment=0
+if [ "$has_rich_data" -eq 0 ]; then
+    needs_enrichment=1
+elif [ "$context_pressure" -eq 1 ]; then
+    needs_enrichment=1
+elif [ -z "$completed" ] && [ -z "$learned" ]; then
+    needs_enrichment=1
+elif [ "$request_is_polluted" -eq 1 ]; then
+    needs_enrichment=1
+fi
+
+if [ "$needs_enrichment" -eq 1 ]; 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)
+        excerpt=$(echo "$text_content" | tail -c 3000)
 
-        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.
+        enrich_prompt="Extract facts from this Claude Code session. Only include items with clear evidence in the session text. Do NOT invent or repeat example content.
 
-SESSION EXCERPT:
-$excerpt
+Respond with EXACTLY these sections (omit sections with no evidence):
+
+REQUEST:
+One-line summary of what the user asked for. No system tags or XML.
+
+COMPLETED:
+What was actually accomplished. Be specific about changes made.
+
+LEARNED:
+Non-obvious discoveries or insights from the session.
 
-Output EXACTLY this format (omit sections with nothing to report):
 DECISIONS:
-- <decision> — why: <reason>
+Each as: <what was decided> — why: <reason>
+
 GOTCHAS:
-- <gotcha>
+Each as: <surprising finding or pitfall>
+
 KEY_FILES:
-- <filepath>"
+Each as: <filepath>
+
+SESSION TEXT:
+$excerpt"
 
-        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
+        enrich_system="You extract structured facts from development sessions. Output format for decisions: '- Did X — why: Y'. Output format for gotchas: '- Gotcha description'. Be concise. Only include items with clear evidence in the session text. Never fabricate content."
+        enrich_result=$(eagle_llm_call "$enrich_prompt" "$enrich_system" 768 2>/dev/null)
+        llm_rc=$?
 
-        if [ -n "$enrich_result" ]; then
+        if [ $llm_rc -ne 0 ] || [ -z "$enrich_result" ]; then
+            eagle_log "WARN" "Stop: LLM enrichment failed (rc=$llm_rc) for session=$session_id provider=$provider"
+        else
             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 }
+                    found && /^[[:space:]]*$/ { next }
+                    found && /^- / { sub(/^- /, ""); lines[++n] = $0; next }
+                    found { 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"
+            _req=$(extract_section "$enrich_result" "REQUEST")
+            _comp=$(extract_section "$enrich_result" "COMPLETED")
+            _learn=$(extract_section "$enrich_result" "LEARNED")
+            _dec=$(extract_section "$enrich_result" "DECISIONS")
+            _got=$(extract_section "$enrich_result" "GOTCHAS")
+            _kf=$(extract_section "$enrich_result" "KEY_FILES")
+
+            [ -z "$request" ] || [ "$request_is_polluted" -eq 1 ] && [ -n "$_req" ] && request="$_req"
+            [ -z "$completed" ] && [ -n "$_comp" ] && completed="$_comp"
+            [ -z "$learned" ] && [ -n "$_learn" ] && learned="$_learn"
+            [ -z "$decisions" ] && [ -n "$_dec" ] && decisions="$_dec"
+            [ -z "$gotchas" ] && [ -n "$_got" ] && gotchas="$_got"
+            [ -z "$key_files" ] && [ -n "$_kf" ] && key_files="$_kf"
+
+            eagle_log "INFO" "Stop: LLM enrichment extracted for session=$session_id (req=${#_req} comp=${#_comp} dec=${#_dec})"
+        fi
+    else
+        eagle_log "INFO" "Stop: LLM enrichment skipped — provider=$provider text_len=${#text_content}"
+    fi
+else
+    eagle_log "INFO" "Stop: LLM enrichment skipped — rich data already present"
+fi
+
+# ─── Test reminder for guardrailed files ─────────────────
+
+if [ -n "$files_modified" ] && [ "$files_modified" != "[]" ]; then
+    # Short-circuit: skip per-file loop if project has no guardrails at all
+    has_gr=$(eagle_has_any_guardrails "$project" 2>/dev/null)
+    if [ -n "$has_gr" ]; then
+        guardrailed_files=""
+        while IFS= read -r mod_file; do
+            [ -z "$mod_file" ] && continue
+            mod_basename=$(basename "$mod_file")
+            gr_check=$(eagle_get_guardrails_for_file "$project" "$mod_basename" 2>/dev/null)
+            if [ -n "$gr_check" ]; then
+                guardrailed_files+="${mod_basename}, "
+            fi
+        done < <(echo "$files_modified" | jq -r '.[]?' 2>/dev/null)
+
+        if [ -n "$guardrailed_files" ]; then
+            guardrailed_files=${guardrailed_files%, }
+            test_reminder="Run affected tests for guardrailed files: ${guardrailed_files}"
+            if [ -n "$next_steps" ]; then
+                next_steps="${next_steps}; ${test_reminder}"
+            else
+                next_steps="$test_reminder"
+            fi
+            eagle_log "INFO" "Stop: added test reminder for guardrailed files: $guardrailed_files"
         fi
     fi
 fi

package/hooks/user-prompt-submit.sh

@@ -25,9 +25,42 @@ user_prompt=$(echo "$input" | jq -r '.prompt // empty')
 
 project=$(eagle_project_from_cwd "$cwd")
 
+# ─── Context pressure detection (turn counter since last compact) ──
+# Must run before any early exits so every prompt is counted
+
+context=""
+
+if [ -n "$session_id" ] && eagle_validate_session_id "$session_id"; then
+    counter_file="$EAGLE_MEM_DIR/.turn-counter.${session_id}"
+    turn_count=0
+    [ -f "$counter_file" ] && turn_count=$(cat "$counter_file" 2>/dev/null | tr -d '[:space:]')
+    turn_count=${turn_count:-0}
+    turn_count=$((turn_count + 1))
+    echo "$turn_count" > "$counter_file" 2>/dev/null
+    eagle_log "INFO" "UserPromptSubmit: turn=$turn_count session=$session_id"
+
+    if [ "$turn_count" -ge 30 ]; then
+        context+="
+=== EAGLE MEM — Context Pressure: CRITICAL ($turn_count turns since compact) ===
+IMMEDIATELY emit a detailed <eagle-summary> covering ALL work this session.
+Tell the user to run /compact NOW to avoid losing context.
+"
+        echo "$turn_count" > "$EAGLE_MEM_DIR/.context-pressure"
+    elif [ "$turn_count" -ge 20 ]; then
+        context+="
+=== EAGLE MEM — Context Pressure: HIGH ($turn_count turns since compact) ===
+Include a thorough <eagle-summary> in your next response — capture all decisions, gotchas, and learned context before compaction.
+Suggest the user run /compact to free context for continued work.
+"
+        echo "$turn_count" > "$EAGLE_MEM_DIR/.context-pressure"
+    else
+        rm -f "$EAGLE_MEM_DIR/.context-pressure" 2>/dev/null
+    fi
+fi
+
 # Skip short prompts — not enough signal for meaningful search
 word_count=$(echo "$user_prompt" | wc -w | tr -d ' ')
-[ "$word_count" -lt 3 ] && exit 0
+[ "$word_count" -lt 3 ] && { [ -n "$context" ] && echo "$context"; exit 0; }
 
 # Build FTS5 query from significant words (drop stop words, take first 6)
 fts_query=$(echo "$user_prompt" | tr -cs '[:alnum:]' ' ' | tr '[:upper:]' '[:lower:]' | \
@@ -42,13 +75,11 @@ fts_query=$(echo "$user_prompt" | tr -cs '[:alnum:]' ' ' | tr '[:upper:]' '[:low
         }
     }')
 
-[ -z "$fts_query" ] && exit 0
+[ -z "$fts_query" ] && { [ -n "$context" ] && echo "$context"; exit 0; }
 
 # Search for relevant past summaries (cross-session)
 results=$(eagle_search_summaries "$fts_query" "$project" 3)
 
-context=""
-
 if [ -n "$results" ]; then
     context+="=== EAGLE MEM — Relevant Memory ===
 "
@@ -87,35 +118,6 @@ if [ "${has_chunks:-0}" -gt 0 ]; then
     fi
 fi
 
-# ─── Context pressure detection (turn counter since last compact) ──
-
-if [ -n "$session_id" ] && eagle_validate_session_id "$session_id"; then
-    counter_file="$EAGLE_MEM_DIR/.turn-counter.${session_id}"
-    turn_count=0
-    [ -f "$counter_file" ] && turn_count=$(cat "$counter_file" 2>/dev/null | tr -d '[:space:]')
-    turn_count=${turn_count:-0}
-    turn_count=$((turn_count + 1))
-    echo "$turn_count" > "$counter_file" 2>/dev/null
-
-    if [ "$turn_count" -ge 30 ]; then
-        context+="
-=== EAGLE MEM — Context Pressure: CRITICAL ($turn_count turns since compact) ===
-IMMEDIATELY emit a detailed <eagle-summary> covering ALL work this session.
-Tell the user to run /compact NOW to avoid losing context.
-"
-        echo "$turn_count" > "$EAGLE_MEM_DIR/.context-pressure"
-    elif [ "$turn_count" -ge 20 ]; then
-        context+="
-=== EAGLE MEM — Context Pressure: HIGH ($turn_count turns since compact) ===
-Include a thorough <eagle-summary> in your next response — capture all decisions, gotchas, and learned context before compaction.
-Suggest the user run /compact to free context for continued work.
-"
-        echo "$turn_count" > "$EAGLE_MEM_DIR/.context-pressure"
-    else
-        rm -f "$EAGLE_MEM_DIR/.context-pressure" 2>/dev/null
-    fi
-fi
-
 [ -z "$context" ] && exit 0
 
 context+="

package/lib/db-core.sh

@@ -7,8 +7,9 @@ _EAGLE_DB_CORE_LOADED=1
 
 EAGLE_DB_SETUP=".headers off
 .output /dev/null
+PRAGMA busy_timeout=10000;
+PRAGMA journal_mode=WAL;
 PRAGMA synchronous=NORMAL;
-PRAGMA busy_timeout=5000;
 PRAGMA foreign_keys=ON;
 PRAGMA trusted_schema=ON;
 .output stdout"

package/lib/db-guardrails.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Guardrails helpers
+# Persistent per-project rules surfaced at Edit/Write time
+# ═══════════════════════════════════════════════════════════
+[ -n "${_EAGLE_DB_GUARDRAILS_LOADED:-}" ] && return 0
+_EAGLE_DB_GUARDRAILS_LOADED=1
+
+eagle_add_guardrail() {
+    local raw_rule="$2"
+    # Cap rule length to 2048 chars to prevent unbounded storage
+    if [ ${#raw_rule} -gt 2048 ]; then
+        raw_rule="${raw_rule:0:2048}"
+    fi
+
+    local project; project=$(eagle_sql_escape "$1")
+    local rule; rule=$(eagle_sql_escape "$raw_rule")
+    local file_pattern="${3:-}"
+    local source; source=$(eagle_sql_escape "${4:-manual}")
+
+    file_pattern=$(eagle_sql_escape "$file_pattern")
+    eagle_db "INSERT INTO guardrails (project, file_pattern, rule, source)
+        VALUES ('$project', '$file_pattern', '$rule', '$source')
+        ON CONFLICT(project, source, file_pattern, rule) DO UPDATE SET
+            updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now');"
+}
+
+eagle_get_guardrails_for_file() {
+    local project; project=$(eagle_sql_escape "$1")
+    local filename; filename=$(eagle_sql_escape "$2")
+
+    eagle_db "SELECT rule FROM guardrails
+        WHERE project = '$project'
+        AND active = 1
+        AND (
+            file_pattern = ''
+            OR '$filename' GLOB file_pattern
+            OR file_pattern = '$filename'
+        )
+        ORDER BY file_pattern = '', created_at DESC
+        LIMIT 3;"
+}
+
+eagle_get_edit_context() {
+    local project; project=$(eagle_sql_escape "$1")
+    local filename; filename=$(eagle_sql_escape "$2")
+    local fts_query; fts_query=$(eagle_sql_escape "$3")
+
+    # Batched query: guardrails + decisions + gotchas in one sqlite3 call.
+    # Results tagged with TYPE: prefix for caller to parse.
+    eagle_db_pipe <<SQL
+SELECT 'GR:' || rule FROM guardrails
+    WHERE project = '$project'
+    AND active = 1
+    AND (
+        file_pattern = ''
+        OR '$filename' GLOB file_pattern
+        OR file_pattern = '$filename'
+    )
+    ORDER BY file_pattern = '', created_at DESC
+    LIMIT 3;
+SELECT 'DEC:' || s.decisions
+    FROM summaries s
+    JOIN summaries_fts f ON f.rowid = s.id
+    WHERE summaries_fts MATCH '$fts_query'
+    AND s.project = '$project'
+    AND s.decisions IS NOT NULL AND s.decisions != ''
+    ORDER BY s.created_at DESC LIMIT 1;
+SELECT 'GOT:' || s.gotchas
+    FROM summaries s
+    JOIN summaries_fts f ON f.rowid = s.id
+    WHERE summaries_fts MATCH '$fts_query'
+    AND s.project = '$project'
+    AND s.gotchas IS NOT NULL AND s.gotchas != ''
+    ORDER BY s.created_at DESC LIMIT 2;
+SQL
+}
+
+eagle_list_guardrails() {
+    local project; project=$(eagle_sql_escape "$1")
+
+    eagle_db "SELECT id, file_pattern, rule, source, active, created_at
+        FROM guardrails
+        WHERE project = '$project'
+        ORDER BY active DESC, created_at DESC;"
+}
+
+eagle_remove_guardrail() {
+    local id; id=$(eagle_sql_int "$1")
+
+    eagle_db "DELETE FROM guardrails WHERE id = $id;"
+}
+
+eagle_has_any_guardrails() {
+    local project; project=$(eagle_sql_escape "$1")
+    eagle_db "SELECT 1 FROM guardrails
+        WHERE project = '$project' AND active = 1
+        LIMIT 1;"
+}
+
+eagle_deactivate_guardrail() {
+    local id; id=$(eagle_sql_int "$1")
+
+    eagle_db "UPDATE guardrails SET active = 0,
+        updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+        WHERE id = $id;"
+}

package/lib/db-summaries.sh

@@ -81,6 +81,7 @@ eagle_search_summaries() {
               FROM summaries s
               JOIN summaries_fts f ON f.rowid = s.id
               WHERE summaries_fts MATCH '$query'
+              AND s.request NOT LIKE '%<local-command-caveat>%'
               $where_clause
               ORDER BY rank
               LIMIT $limit;"
@@ -141,6 +142,20 @@ eagle_last_session_enriched() {
         ORDER BY created_at DESC LIMIT 1;"
 }
 
+eagle_search_gotchas_for_file() {
+    local project; project=$(eagle_sql_escape "$1")
+    local fts_query; fts_query=$(eagle_sql_escape "$2")
+    eagle_db "SELECT s.gotchas
+        FROM summaries s
+        JOIN summaries_fts f ON f.rowid = s.id
+        WHERE summaries_fts MATCH '$fts_query'
+        AND s.project = '$project'
+        AND s.gotchas IS NOT NULL
+        AND s.gotchas != ''
+        ORDER BY s.created_at DESC
+        LIMIT 2;"
+}
+
 eagle_search_stale_memories() {
     local project; project=$(eagle_sql_escape "$1")
     local fts_query; fts_query=$(eagle_sql_escape "$2")

package/lib/db.sh

@@ -16,3 +16,4 @@ _eagle_db_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "$_eagle_db_dir/db-features.sh"
 . "$_eagle_db_dir/db-hints.sh"
 . "$_eagle_db_dir/db-backfill.sh"
+. "$_eagle_db_dir/db-guardrails.sh"

package/lib/provider.sh

@@ -65,13 +65,22 @@ eagle_config_set() {
     safe_value=$(printf '%s' "$value" | sed 's/[|&/\]/\\&/g')
 
     if grep -q "^\[${section}\]" "$EAGLE_CONFIG_FILE" 2>/dev/null; then
-        if grep -q "^[[:space:]]*${key}[[:space:]]*=" "$EAGLE_CONFIG_FILE" 2>/dev/null; then
-            sed -i '' "s|^[[:space:]]*${key}[[:space:]]*=.*|${key} = \"${safe_value}\"|" "$EAGLE_CONFIG_FILE"
-        else
-            sed -i '' "/^\[${section}\]/a\\
-${key} = \"${safe_value}\"
-" "$EAGLE_CONFIG_FILE"
-        fi
+        local tmp_cfg="${EAGLE_CONFIG_FILE}.tmp.$$"
+        awk -v sect="[${section}]" -v k="$key" -v v="$safe_value" '
+            BEGIN { in_sect=0; replaced=0 }
+            /^\[/ {
+                if (in_sect && !replaced) {
+                    print k" = \""v"\""
+                    replaced=1
+                }
+                in_sect=($0 == sect)
+            }
+            in_sect && !replaced && $0 ~ "^[[:space:]]*"k"[[:space:]]*=" {
+                print k" = \""v"\""; replaced=1; next
+            }
+            { print }
+            END { if (in_sect && !replaced) print k" = \""v"\"" }
+        ' "$EAGLE_CONFIG_FILE" > "$tmp_cfg" && mv "$tmp_cfg" "$EAGLE_CONFIG_FILE"
     else
         # printf is safe — no sed interpolation needed for append
         printf '\n[%s]\n%s = "%s"\n' "$section" "$key" "$value" >> "$EAGLE_CONFIG_FILE"
@@ -95,7 +104,7 @@ eagle_ollama_best_model() {
     models=$(eagle_ollama_models "$1")
     [ -z "$models" ] && return 1
 
-    local preferred="mistral qwen3-coder gemma4 llama3 phi3 deepseek-coder"
+    local preferred="gemma4 gemma3 gemma2 mistral llama3 phi3 deepseek-coder"
     for pref in $preferred; do
         if echo "$models" | grep -qi "$pref"; then
             echo "$models" | grep -i "$pref" | head -1

package/package.json

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

package/scripts/curate.sh

@@ -89,7 +89,8 @@ If none qualify, output: NONE"
                     if [ "$DRY_RUN" -eq 1 ]; then
                         eagle_info "  Would promote: $gotcha_text"
                     else
-                        eagle_log "INFO" "Curator: promoting gotcha: $gotcha_text"
+                        eagle_add_guardrail "$project" "$gotcha_text" "" "promoted"
+                        eagle_log "INFO" "Curator: promoted gotcha to guardrail: $gotcha_text"
                     fi
                     promoted=$((promoted + 1))
                     ;;

package/scripts/guard.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Guardrails management
+# eagle-mem guard [add|list|remove]
+# ═══════════════════════════════════════════════════════════
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LIB_DIR="$SCRIPT_DIR/../lib"
+
+. "$LIB_DIR/common.sh"
+. "$LIB_DIR/db.sh"
+. "$SCRIPT_DIR/style.sh"
+
+eagle_ensure_db
+
+project=$(eagle_project_from_cwd "$(pwd)")
+if [ -z "$project" ]; then
+    eagle_err "Not in a recognized project directory"
+    exit 1
+fi
+
+eagle_header "Guardrails"
+
+subcommand="${1:-list}"
+shift 2>/dev/null || true
+
+case "$subcommand" in
+    add)
+        rule="${1:-}"
+        if [ -z "$rule" ]; then
+            eagle_err "Usage: eagle-mem guard add \"rule text\" [--file pattern]"
+            eagle_info "Examples:"
+            eagle_info "  eagle-mem guard add \"PRAGMA busy_timeout must precede synchronous\" --file \"db-core.sh\""
+            eagle_info "  eagle-mem guard add \"Never manually copy files to ~/.eagle-mem\""
+            eagle_info "  eagle-mem guard add \"Always validate session IDs\" --file \"*.sh\""
+            exit 1
+        fi
+        shift
+
+        file_pattern=""
+        while [ $# -gt 0 ]; do
+            case "$1" in
+                --file|-f)
+                    if [ $# -lt 2 ] || [ -z "${2:-}" ]; then
+                        eagle_err "--file requires a pattern argument"
+                        exit 1
+                    fi
+                    file_pattern="$2"
+                    shift 2
+                    ;;
+                *)
+                    shift
+                    ;;
+            esac
+        done
+
+        eagle_add_guardrail "$project" "$rule" "$file_pattern" "manual"
+        eagle_ok "Guardrail added for project: $project"
+        if [ -n "$file_pattern" ]; then
+            eagle_info "File pattern: $file_pattern"
+        else
+            eagle_info "Scope: project-wide"
+        fi
+        eagle_dim "Rule: $rule"
+        ;;
+
+    list|ls)
+        results=$(eagle_list_guardrails "$project")
+        if [ -z "$results" ]; then
+            eagle_info "No guardrails for project: $project"
+            eagle_dim "Add one: eagle-mem guard add \"rule\" [--file pattern]"
+            exit 0
+        fi
+
+        echo -e "  ${BOLD}ID   File Pattern         Rule                                     Source   Active${RESET}"
+        echo -e "  ${DIM}──── ──────────────────── ──────────────────────────────────────── ──────── ──────${RESET}"
+
+        while IFS='|' read -r id pat rule source active _created; do
+            [ -z "$id" ] && continue
+            pat="${pat:-(all)}"
+            rule_display="${rule:0:40}"
+            [ ${#rule} -gt 40 ] && rule_display="${rule_display}..."
+            if [ "$active" = "1" ]; then
+                active_display="${GREEN}yes${RESET}"
+            else
+                active_display="${DIM}no${RESET}"
+            fi
+            printf "  %-4s %-20s %-40s %-8s %b\n" "$id" "$pat" "$rule_display" "$source" "$active_display"
+        done <<< "$results"
+        echo ""
+        ;;
+
+    remove|rm|delete)
+        id="${1:-}"
+        if [ -z "$id" ]; then
+            eagle_err "Usage: eagle-mem guard remove <id>"
+            exit 1
+        fi
+        case "$id" in
+            *[!0-9]*)
+                eagle_err "Invalid ID: '$id' (must be numeric)"
+                exit 1
+                ;;
+        esac
+        eagle_remove_guardrail "$id"
+        eagle_ok "Guardrail #$id removed"
+        ;;
+
+    sync)
+        eagle_info "Syncing rules from CLAUDE.md files..."
+
+        # Collect rules first, then delete+insert in a single transaction
+        # to prevent data loss if interrupted mid-sync
+        sync_sql=""
+        synced=0
+        p_esc=$(eagle_sql_escape "$project")
+
+        for claude_md in "$HOME/.claude/CLAUDE.md" ".claude/CLAUDE.md" "CLAUDE.md"; do
+            [ ! -f "$claude_md" ] && continue
+            eagle_dim "  Reading: $claude_md"
+
+            # Extract lines that look like imperative rules
+            while IFS= read -r line; do
+                # Strip markdown formatting
+                clean=$(printf '%s\n' "$line" | sed 's/^[[:space:]]*[-*>]*[[:space:]]*//' | sed 's/\*\*//g' | sed 's/`//g')
+                [ -z "$clean" ] && continue
+                # Skip headings, short lines, and non-rule content
+                [ ${#clean} -lt 15 ] && continue
+                case "$clean" in \#*) continue ;; esac
+
+                # Cap rule length
+                [ ${#clean} -gt 2048 ] && clean="${clean:0:2048}"
+                rule_esc=$(eagle_sql_escape "$clean")
+                sync_sql+="INSERT OR IGNORE INTO guardrails (project, file_pattern, rule, source) VALUES ('$p_esc', '', '$rule_esc', 'claude-md');"$'\n'
+                synced=$((synced + 1))
+            done < <(grep -iE '^[[:space:]]*[-*>]*[[:space:]]*(never |always |do not |don'\''t |must |rule:|important:)' "$claude_md" 2>/dev/null)
+        done
+
+        # Atomic: always delete stale + insert new in one transaction
+        # Even when synced=0, DELETE must run to clear removed rules
+        eagle_db_pipe <<SQL
+BEGIN;
+DELETE FROM guardrails WHERE project = '$p_esc' AND source = 'claude-md';
+$sync_sql
+COMMIT;
+SQL
+        if [ "$synced" -gt 0 ]; then
+            eagle_ok "$synced rules synced from CLAUDE.md"
+        else
+            eagle_info "No imperative rules found in CLAUDE.md files (stale rules cleared)"
+        fi
+        ;;
+
+    *)
+        eagle_err "Unknown guard command: $subcommand"
+        eagle_info "Usage: eagle-mem guard [add|list|remove|sync]"
+        exit 1
+        ;;
+esac

package/scripts/help.sh

@@ -22,6 +22,13 @@ echo -e "    ${CYAN}uninstall${RESET}   Remove hooks and optionally delete data"
 echo -e "    ${CYAN}search${RESET}      Search past sessions, memories, and code"
 echo -e "    ${CYAN}health${RESET}      Diagnose pipeline health and background automation"
 echo -e "    ${CYAN}config${RESET}      View or change LLM provider settings"
+echo -e "    ${CYAN}guard${RESET}       Manage regression guardrails for files"
+echo -e "    ${CYAN}overview${RESET}    Build or view project overview"
+echo -e "    ${CYAN}memories${RESET}    View/sync Claude Code memories"
+echo -e "    ${CYAN}tasks${RESET}       View mirrored tasks"
+echo -e "    ${CYAN}curate${RESET}      Run curator (co-edits, hot files, guardrails)"
+echo -e "    ${CYAN}feature${RESET}     Track and verify features"
+echo -e "    ${CYAN}prune${RESET}       Clean old sessions and stale data"
 echo ""
 echo -e "  ${BOLD}Search modes:${RESET}"
 echo -e "    ${DIM}\$${RESET} eagle-mem search \"auth bug\"    ${DIM}# keyword search${RESET}"

package/scripts/install.sh

@@ -176,6 +176,14 @@ eagle_patch_hook "$SETTINGS" "PostToolUse" "Read|Write|Edit|Bash|TaskCreate|Task
     "$EAGLE_MEM_DIR/hooks/post-tool-use.sh" \
     "PostToolUse hook"
 
+eagle_patch_hook "$SETTINGS" "TaskCreated" "" \
+    "$EAGLE_MEM_DIR/hooks/post-tool-use.sh" \
+    "TaskCreated hook"
+
+eagle_patch_hook "$SETTINGS" "TaskCompleted" "" \
+    "$EAGLE_MEM_DIR/hooks/post-tool-use.sh" \
+    "TaskCompleted hook"
+
 eagle_patch_hook "$SETTINGS" "SessionEnd" "" \
     "$EAGLE_MEM_DIR/hooks/session-end.sh" \
     "SessionEnd hook"

package/scripts/overview.sh

@@ -16,8 +16,12 @@ eagle_ensure_db
 
 # ─── Parse arguments ──────────────────────────────────────
 
-action="${1:-show}"
-shift 2>/dev/null || true
+action="show"
+case "${1:-}" in
+    -*)  ;; # flags parsed below
+    "")  ;;
+    *)   action="$1"; shift ;;
+esac
 
 project=""
 json_output=false
@@ -36,7 +40,7 @@ show_help() {
     echo -e "    ${CYAN}-p, --project${RESET} <name>    Project name (default: current dir)"
     echo -e "    ${CYAN}-j, --json${RESET}              Output as JSON"
     echo ""
-    echo -e "  ${BOLD}Tip:${RESET} Use ${CYAN}eagle-mem scan${RESET} to auto-generate an overview from code."
+    echo -e "  ${BOLD}Tip:${RESET} Overviews are auto-generated during ${CYAN}eagle-mem install${RESET} and background scans."
     echo ""
     exit 0
 }
@@ -66,7 +70,7 @@ overview_show() {
 
     if [ -z "$content" ]; then
         eagle_dim "No overview for project '$project'"
-        eagle_dim "Run 'eagle-mem scan' or 'eagle-mem overview set <text>' to create one"
+        eagle_dim "Use 'eagle-mem overview set <text>' to create one, or run install/update to auto-generate"
         return
     fi
 

package/scripts/search.sh

@@ -78,7 +78,13 @@ limit=$(eagle_sql_int "$limit")
 # ─── Keyword search ──────────────────────────────────────
 
 search_keyword() {
-    local q; q=$(eagle_sql_escape "$(eagle_fts_sanitize "$query")")
+    local sanitized_q
+    sanitized_q=$(eagle_fts_sanitize "$query")
+    if [ -z "$sanitized_q" ]; then
+        eagle_err "Search query contains no valid search terms"
+        exit 1
+    fi
+    local q; q=$(eagle_sql_escape "$sanitized_q")
     local p; p=$(eagle_sql_escape "$project")
 
     local where_project=""
@@ -328,7 +334,13 @@ search_memories() {
     fi
 
     if [ -n "$query" ]; then
-        local q; q=$(eagle_sql_escape "$(eagle_fts_sanitize "$query")")
+        local sanitized_mq
+        sanitized_mq=$(eagle_fts_sanitize "$query")
+        if [ -z "$sanitized_mq" ]; then
+            eagle_err "Search query contains no valid search terms"
+            exit 1
+        fi
+        local q; q=$(eagle_sql_escape "$sanitized_mq")
         local where_match="WHERE claude_memories_fts MATCH '$q'"
         if [ "$cross_project" = false ]; then
             where_match="$where_match AND m.project = '$p'"
@@ -409,7 +421,13 @@ search_tasks() {
     fi
 
     if [ -n "$query" ]; then
-        local q; q=$(eagle_sql_escape "$(eagle_fts_sanitize "$query")")
+        local sanitized_tq
+        sanitized_tq=$(eagle_fts_sanitize "$query")
+        if [ -z "$sanitized_tq" ]; then
+            eagle_err "Search query contains no valid search terms"
+            exit 1
+        fi
+        local q; q=$(eagle_sql_escape "$sanitized_tq")
 
         if [ "$json_output" = true ]; then
             eagle_db_json "SELECT t.subject, t.status, t.project, t.updated_at

package/scripts/tasks.sh

@@ -17,8 +17,12 @@ eagle_ensure_db
 
 # ─── Parse arguments ──────────────────────────────────────
 
-action="${1:-pending}"
-shift 2>/dev/null || true
+action="pending"
+case "${1:-}" in
+    -*)  ;; # flags parsed below
+    "")  ;;
+    *)   action="$1"; shift ;;
+esac
 
 project=""
 json_output=false
@@ -123,9 +127,15 @@ tasks_search() {
         exit 1
     fi
 
+    local sanitized_query
+    sanitized_query=$(eagle_fts_sanitize "$query")
+    if [ -z "$sanitized_query" ]; then
+        eagle_err "Search query contains no valid search terms"
+        exit 1
+    fi
+
     if [ "$json_output" = true ]; then
-        local query_sql; query_sql=$(eagle_fts_sanitize "$query")
-        query_sql=$(eagle_sql_escape "$query_sql")
+        local query_sql; query_sql=$(eagle_sql_escape "$sanitized_query")
         eagle_db_json "SELECT t.source_task_id, t.subject, t.status, t.description, t.updated_at
                        FROM claude_tasks t
                        JOIN claude_tasks_fts f ON f.rowid = t.id
@@ -137,8 +147,7 @@ tasks_search() {
     fi
 
     local results
-    local query_sql; query_sql=$(eagle_fts_sanitize "$query")
-    query_sql=$(eagle_sql_escape "$query_sql")
+    local query_sql; query_sql=$(eagle_sql_escape "$sanitized_query")
     results=$(eagle_db "SELECT t.source_task_id, t.subject, t.status, t.description
                         FROM claude_tasks t
                         JOIN claude_tasks_fts f ON f.rowid = t.id

package/scripts/update.sh

@@ -73,6 +73,8 @@ if [ -f "$SETTINGS" ] && command -v jq &>/dev/null; then
     eagle_patch_hook "$SETTINGS" "SessionStart" "" "$EAGLE_MEM_DIR/hooks/session-start.sh"
     eagle_patch_hook "$SETTINGS" "Stop" "" "$EAGLE_MEM_DIR/hooks/stop.sh"
     eagle_patch_hook "$SETTINGS" "PostToolUse" "Read|Write|Edit|Bash|TaskCreate|TaskUpdate" "$EAGLE_MEM_DIR/hooks/post-tool-use.sh"
+    eagle_patch_hook "$SETTINGS" "TaskCreated" "" "$EAGLE_MEM_DIR/hooks/post-tool-use.sh"
+    eagle_patch_hook "$SETTINGS" "TaskCompleted" "" "$EAGLE_MEM_DIR/hooks/post-tool-use.sh"
     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"