eagle-mem 3.3.0 → 4.0.0

package/README.md

@@ -12,150 +12,49 @@ 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
-
-```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
+Six commands. Three for lifecycle, three for when you need to look something up or troubleshoot.
 
-| 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
 
@@ -163,44 +62,47 @@ 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, tracks modifications |
 | **Stop** | Claude's turn ends | Extracts `<eagle-summary>`, strips `<private>` tags |
 | **SessionEnd** | session closes | Re-syncs tasks, marks session completed |
 
+### 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:
 
-- **Command rewriting** — PreToolUse rewrites noisy Bash commands (e.g., `find`, `grep`) to pipe through `head -N`, using `updatedInput` to modify the command before execution. Rules are learned by the curator from real usage, not hardcoded.
-- **Read-after-modify detection** — If you just edited or wrote a file, Eagle Mem nudges that the diff is already in context before a redundant Read.
-- **Read dedup tracking** — Files read 3+ times in a session get a soft nudge that contents are likely already in context.
+- **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
 
-Data lives in a single SQLite database at `~/.eagle-mem/memory.db` (WAL mode, FTS5 full-text search):
+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/hooks/session-start.sh

@@ -13,6 +13,7 @@ SCRIPTS_DIR="$SCRIPT_DIR/../scripts"
 . "$LIB_DIR/common.sh"
 . "$LIB_DIR/db.sh"
 . "$LIB_DIR/provider.sh"
+. "$LIB_DIR/hooks-sessionstart.sh"
 
 eagle_ensure_db
 
@@ -27,8 +28,6 @@ model=$(echo "$input" | jq -r '.model // empty')
 [ -z "$session_id" ] && exit 0
 
 project=$(eagle_project_from_cwd "$cwd")
-
-# Skip ephemeral directories (tmp, Downloads, etc.) — no tracking
 [ -z "$project" ] && exit 0
 
 p_esc=$(eagle_sql_escape "$project")
@@ -36,36 +35,18 @@ p_esc=$(eagle_sql_escape "$project")
 eagle_log "INFO" "SessionStart: session=$session_id project=$project source=$source_type"
 
 eagle_upsert_session "$session_id" "$project" "$cwd" "$model" "$source_type"
-
-# ─── Sweep stuck sessions (no activity for 7 days) ─────────
-# Uses last_activity_at (updated by trigger on every observation insert)
-# so long-lived sessions with regular compactions aren't falsely abandoned
 eagle_abandon_stale_sessions "$session_id"
 
-# ─── Auto-curate trigger (background, non-blocking) ──────────
-# Moved here from SessionEnd because SessionEnd rarely fires in long-lived sessions.
-# SessionStart fires on every new session, resume, and compaction — reliable trigger.
-curator_schedule=$(eagle_config_get "curator" "schedule" "manual")
-if [ "$curator_schedule" = "auto" ]; then
-    _curator_provider=$(eagle_config_get "provider" "type" "none")
-    if [ "$_curator_provider" != "none" ]; then
-        _min_sessions=$(eagle_config_get "curator" "min_sessions" "5")
-        _min_sessions=$(eagle_sql_int "$_min_sessions")
-        _last_curated=$(eagle_meta_get "last_curated_at" "$project")
-        _since="${_last_curated:-1970-01-01T00:00:00Z}"
-        _sessions_since=$(eagle_count_sessions_since "$project" "$_since")
-        if [ "${_sessions_since:-0}" -ge "$_min_sessions" ]; then
-            eagle_log "INFO" "SessionStart: auto-curate triggered (${_sessions_since} sessions since last curate)"
-            nohup bash "$SCRIPTS_DIR/curate.sh" -p "$project" >> "$EAGLE_MEM_LOG" 2>&1 &
-        fi
-    fi
-fi
+# ─── Background automation (non-blocking) ────────────────
+
+eagle_sessionstart_auto_provision "$project" "$cwd" "$SCRIPTS_DIR"
+eagle_sessionstart_auto_prune "$project" "$SCRIPTS_DIR" "$(eagle_db "SELECT COUNT(*) FROM observations WHERE session_id IN (SELECT id FROM sessions WHERE project='$p_esc');")"
+eagle_sessionstart_auto_curate "$project" "$SCRIPTS_DIR"
 
-# ─── Cleanup stale tracker files (non-blocking) ─────────────
 find "$EAGLE_MEM_DIR/read-tracker" -type f -mtime +1 -delete 2>/dev/null &
 find "$EAGLE_MEM_DIR/mod-tracker" -type f -mtime +1 -delete 2>/dev/null &
 
-# ─── Version check (non-blocking) ────────────────────────────
+# ─── Version check (non-blocking) ────────────────────────
 
 update_notice=""
 version_file="$EAGLE_MEM_DIR/.version"
@@ -93,7 +74,7 @@ if [ -f "$version_file" ] && [ -s "$version_file" ]; then
     fi
 fi
 
-# ─── Gather stats ───────────────────────────────────────────
+# ─── Gather stats ────────────────────────────────────────
 
 stat_sessions=0; stat_summaries=0; stat_with_summaries=0; stat_memories=0
 stat_tasks_pending=0; stat_tasks_progress=0; stat_tasks_done=0
@@ -117,7 +98,8 @@ while IFS='|' read -r key val; do
     esac
 done <<< "$(eagle_get_project_stats "$project")"
 
-# Build task summary line
+# ─── Build compressed banner (elide zero-value lines) ────
+
 task_parts=""
 [ "$stat_tasks_progress" -gt 0 ] && task_parts="${stat_tasks_progress} in progress"
 if [ "$stat_tasks_pending" -gt 0 ]; then
@@ -128,27 +110,26 @@ if [ "$stat_tasks_done" -gt 0 ]; then
     [ -n "$task_parts" ] && task_parts+=", "
     task_parts+="${stat_tasks_done} completed"
 fi
-[ -z "$task_parts" ] && task_parts="none"
 
-# Truncate last summary for display
 stat_last_display="${stat_last_summary:0:60}"
 [ ${#stat_last_summary} -gt 60 ] && stat_last_display+="..."
-[ -z "$stat_last_display" ] && stat_last_display="(no sessions yet)"
-
-# ─── Build context injection ────────────────────────────────
 
 eagle_banner="======================================
        Eagle Mem Loaded
 ======================================
  Project      | $project
- Sessions     | $stat_sessions total ($stat_with_summaries with summaries)
- Memories     | $stat_memories stored
- Plans        | $stat_plans saved
- Tasks        | $task_parts
- Code Index   | $stat_chunks chunks indexed
- Observations | $stat_observations captured
- Last Active  | $stat_last_active
- Last Work    | $stat_last_display
+ Sessions     | $stat_sessions ($stat_with_summaries with summaries)"
+[ "$stat_memories" -gt 0 ] && eagle_banner+="
+ Memories     | $stat_memories stored"
+[ "$stat_plans" -gt 0 ] && eagle_banner+="
+ Plans        | $stat_plans saved"
+[ -n "$task_parts" ] && eagle_banner+="
+ Tasks        | $task_parts"
+[ "$stat_chunks" -gt 0 ] && eagle_banner+="
+ Code Index   | $stat_chunks chunks"
+[ -n "$stat_last_display" ] && eagle_banner+="
+ Last Work    | $stat_last_display"
+eagle_banner+="
 ======================================"
 
 context="$eagle_banner
@@ -160,22 +141,33 @@ if [ -n "$update_notice" ]; then
 "
 fi
 
-# Project overview
+# ─── Project overview (capped at 500 chars) ──────────────
+
 overview=$(eagle_get_overview "$project")
 if [ -n "$overview" ]; then
+    if [ ${#overview} -gt 500 ]; then
+        overview="${overview:0:497}..."
+    fi
     context+="
-=== Project Overview ===
+=== Overview ===
 $overview
 "
 else
     context+="
-=== Action Required ===
-No overview exists for '$project'. Run /eagle-mem-overview to build one.
+=== New Project ===
+No overview yet — auto-scan is running. Run /eagle-mem-overview for a richer briefing.
 "
 fi
 
-# Recent summaries for this project (last 5 sessions)
-recent=$(eagle_get_recent_summaries "$project" 5)
+# ─── Recent sessions (1 on compact, 3 on startup) ────────
+
+if [ "$source_type" = "compact" ] || [ "$source_type" = "clear" ]; then
+    _summary_limit=1
+else
+    _summary_limit=3
+fi
+
+recent=$(eagle_get_recent_summaries "$project" "$_summary_limit")
 
 if [ -n "$recent" ]; then
     context+="
@@ -204,7 +196,7 @@ Next steps: $next_steps"
 "
 fi
 
-# ─── Mirrored Claude memories (with age) ─────────────────
+# ─── Memories (skip if none) ─────────────────────────────
 
 memories=$(eagle_db "SELECT memory_name, memory_type, description, file_path, updated_at,
     CAST(julianday('now') - julianday(updated_at) AS INTEGER) as days_ago
@@ -233,7 +225,7 @@ if [ -n "$memories" ]; then
     done <<< "$memories"
 fi
 
-# ─── Mirrored Claude plans ────────────────────────────────
+# ─── Plans (skip if none) ────────────────────────────────
 
 plans=$(eagle_list_claude_plans "$project" 3)
 if [ -n "$plans" ]; then
@@ -247,7 +239,7 @@ if [ -n "$plans" ]; then
     done <<< "$plans"
 fi
 
-# ─── Claude Code tasks ───────────────────────────────────
+# ─── Tasks (skip if none) ────────────────────────────────
 
 synced_tasks=$(eagle_db "SELECT subject, status, blocked_by FROM claude_tasks
     WHERE project = '$p_esc'
@@ -272,39 +264,27 @@ if [ -n "$synced_tasks" ]; then
     done <<< "$synced_tasks"
 fi
 
-# ─── Instructions (full on startup, minimal on compact) ──
+# ─── Instructions (compressed) ───────────────────────────
 
 if [ "$source_type" = "compact" ] || [ "$source_type" = "clear" ]; then
     context+="
-=== Eagle Mem (compact reload) ===
-Persistent memory active. Attribute recalled context to Eagle Mem. Do not revert past decisions surfaced by PostToolUse without asking the user. Emit <eagle-summary> before your final response.
+=== Eagle Mem ===
+Memory active. Attribute recalled context to Eagle Mem. Do not revert PostToolUse-surfaced decisions without asking. Emit <eagle-summary> before final response.
 "
 else
     context+="
 === Eagle Mem ===
-Persistent memory active for '$project'. Attribute recalled context: \"Eagle Mem recalls:\" When PostToolUse surfaces past decisions about a file, do not revert without explicit user request. Never include raw secrets in eagle-summary fields. If you change something that contradicts a loaded memory, update that memory file.
-
-Emit an <eagle-summary> block before your FINAL response:
+Memory active for '$project'. Scan, index, prune, and self-learning run automatically — never ask the user to run these. Attribute recalled context: \"Eagle Mem recalls:\" Do not revert PostToolUse-surfaced decisions without user request. No raw secrets in summaries. If you contradict a loaded memory, update the memory file.
 
+Before your final response, emit:
 <eagle-summary>
-request: [what the user asked for]
-investigated: [file paths read or explored]
-learned: [non-obvious discoveries a future session couldn't guess from code]
-completed: [what shipped — be specific]
-next_steps: [concrete actions for next session]
-decisions:
-  - [choice] Why: [reason]
-gotchas:
-  - [what failed or surprised — \"X doesn't work because Y\"]
-key_files:
-  - [path] — [role in this work]
-files_read: [file1, file2]
-files_modified: [file1, file2]
+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: [...]
 </eagle-summary>
 "
 fi
 
-# Output context (plain text stdout = additionalContext for SessionStart)
 if [ -n "$context" ]; then
     echo "$context"
 fi

package/lib/hooks-sessionstart.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — SessionStart extracted automation
+# Source from hooks/session-start.sh after common.sh + db.sh
+# ═══════════════════════════════════════════════════════════
+[ -n "${_EAGLE_HOOKS_SESSIONSTART_LOADED:-}" ] && return 0
+_EAGLE_HOOKS_SESSIONSTART_LOADED=1
+
+_state_dir="$EAGLE_MEM_DIR/state"
+
+_eagle_state_fresh() {
+    local key="$1" project="$2" max_age_days="${3:-1}"
+    local state_file="$_state_dir/${key}-${project}"
+    [ -f "$state_file" ] && [ -z "$(find "$state_file" -mtime +${max_age_days} 2>/dev/null)" ]
+}
+
+_eagle_state_touch() {
+    local key="$1" project="$2"
+    mkdir -p "$_state_dir" 2>/dev/null
+    touch "$_state_dir/${key}-${project}"
+}
+
+eagle_sessionstart_auto_provision() {
+    local project="$1" cwd="$2" scripts_dir="$3"
+    local needs_scan=false needs_index=false
+
+    # Auto-scan: no overview exists
+    local overview
+    overview=$(eagle_get_overview "$project")
+    if [ -z "$overview" ] && ! _eagle_state_fresh "scan" "$project" 1; then
+        needs_scan=true
+    fi
+
+    # Auto-index: 0 chunks or stale > 7 days
+    local chunk_count
+    chunk_count=$(eagle_db "SELECT COUNT(*) FROM code_chunks WHERE project = '$(eagle_sql_escape "$project")';" 2>/dev/null)
+    chunk_count=${chunk_count:-0}
+    if [ "$chunk_count" -eq 0 ] && ! _eagle_state_fresh "index" "$project" 1; then
+        needs_index=true
+    elif [ "$chunk_count" -gt 0 ] && ! _eagle_state_fresh "index" "$project" 7; then
+        needs_index=true
+    fi
+
+    if [ "$needs_scan" = true ] && [ "$needs_index" = true ]; then
+        eagle_log "INFO" "SessionStart: first-session provision — scan then index"
+        _eagle_state_touch "scan" "$project"
+        _eagle_state_touch "index" "$project"
+        nohup bash -c "bash '$scripts_dir/scan.sh' '$cwd' >> '$EAGLE_MEM_LOG' 2>&1; bash '$scripts_dir/index.sh' '$cwd' >> '$EAGLE_MEM_LOG' 2>&1" &
+    elif [ "$needs_scan" = true ]; then
+        eagle_log "INFO" "SessionStart: auto-scan triggered"
+        _eagle_state_touch "scan" "$project"
+        nohup bash "$scripts_dir/scan.sh" "$cwd" >> "$EAGLE_MEM_LOG" 2>&1 &
+    elif [ "$needs_index" = true ]; then
+        eagle_log "INFO" "SessionStart: auto-index triggered"
+        _eagle_state_touch "index" "$project"
+        nohup bash "$scripts_dir/index.sh" "$cwd" >> "$EAGLE_MEM_LOG" 2>&1 &
+    fi
+}
+
+eagle_sessionstart_auto_prune() {
+    local project="$1" scripts_dir="$2" observation_count="$3"
+    if [ "${observation_count:-0}" -gt 10000 ] && ! _eagle_state_fresh "prune" "$project" 1; then
+        eagle_log "INFO" "SessionStart: auto-prune triggered (${observation_count} observations)"
+        _eagle_state_touch "prune" "$project"
+        nohup bash "$scripts_dir/prune.sh" -p "$project" >> "$EAGLE_MEM_LOG" 2>&1 &
+    fi
+}
+
+eagle_sessionstart_auto_curate() {
+    local project="$1" scripts_dir="$2"
+    local curator_schedule
+    curator_schedule=$(eagle_config_get "curator" "schedule" "manual")
+    if [ "$curator_schedule" = "auto" ]; then
+        local _provider
+        _provider=$(eagle_config_get "provider" "type" "none")
+        if [ "$_provider" != "none" ]; then
+            local _min_sessions _last_curated _since _sessions_since
+            _min_sessions=$(eagle_config_get "curator" "min_sessions" "5")
+            _min_sessions=$(eagle_sql_int "$_min_sessions")
+            _last_curated=$(eagle_meta_get "last_curated_at" "$project")
+            _since="${_last_curated:-1970-01-01T00:00:00Z}"
+            _sessions_since=$(eagle_count_sessions_since "$project" "$_since")
+            if [ "${_sessions_since:-0}" -ge "$_min_sessions" ]; then
+                eagle_log "INFO" "SessionStart: auto-curate triggered (${_sessions_since} sessions since last curate)"
+                nohup bash "$scripts_dir/curate.sh" -p "$project" >> "$EAGLE_MEM_LOG" 2>&1 &
+            fi
+        fi
+    fi
+}

package/lib/provider.sh

@@ -151,8 +151,8 @@ model = "claude-haiku-4-5-20251001"
 model = "gpt-4o-mini"
 
 [curator]
-# "auto" = triggers at session end after min_sessions; "manual" = CLI only
-schedule = "manual"
+# "auto" = triggers at session start after min_sessions; "manual" = CLI only
+schedule = "auto"
 min_sessions = 5
 
 [redaction]

package/package.json

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

package/scripts/help.sh

@@ -16,38 +16,26 @@ echo -e "  ${BOLD}Eagle Mem${RESET} ${DIM}v${version}${RESET}"
 echo -e "  ${DIM}Persistent memory for Claude Code${RESET}"
 echo ""
 echo -e "  ${BOLD}Commands:${RESET}"
-echo -e "    ${CYAN}search${RESET}      Search past sessions, memories, and code"
-echo -e "    ${CYAN}overview${RESET}    View or set project overview"
-echo -e "    ${CYAN}scan${RESET}        Analyze codebase structure"
-echo -e "    ${CYAN}index${RESET}       Index source files for FTS5 code search"
-echo -e "    ${CYAN}memories${RESET}    View/sync mirrored Claude Code memories"
-echo -e "    ${CYAN}tasks${RESET}       View mirrored Claude Code tasks"
-echo -e "    ${CYAN}refresh${RESET}     Full project sync: scan (if needed) + index + memories"
-echo -e "    ${CYAN}prune${RESET}       Remove old observations and orphaned chunks"
-echo -e "    ${CYAN}config${RESET}      View or change LLM provider settings"
-echo -e "    ${CYAN}curate${RESET}      Run the self-learning curator (LLM-powered analysis)"
-echo -e "    ${CYAN}feature${RESET}     Manage feature graph (list/show/verify/add)"
-echo -e "    ${CYAN}health${RESET}      Diagnose self-learning pipeline health"
 echo -e "    ${CYAN}install${RESET}     First-time setup: hooks, database, skills"
 echo -e "    ${CYAN}update${RESET}      Re-deploy hooks and run migrations"
 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 ""
 echo -e "  ${BOLD}Examples:${RESET}"
-echo -e "    ${DIM}\$${RESET} eagle-mem search \"auth bug\"  ${DIM}# keyword search${RESET}"
-echo -e "    ${DIM}\$${RESET} eagle-mem search --timeline  ${DIM}# recent sessions${RESET}"
-echo -e "    ${DIM}\$${RESET} eagle-mem refresh             ${DIM}# full project sync${RESET}"
-echo -e "    ${DIM}\$${RESET} eagle-mem overview           ${DIM}# view overview${RESET}"
-echo -e "    ${DIM}\$${RESET} eagle-mem prune --dry-run    ${DIM}# preview cleanup${RESET}"
 echo -e "    ${DIM}\$${RESET} eagle-mem install            ${DIM}# first-time setup${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem search \"auth bug\"  ${DIM}# keyword search${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem health              ${DIM}# check pipeline${RESET}"
 echo ""
 echo -e "  ${BOLD}Skills${RESET} ${DIM}(inside Claude Code sessions):${RESET}"
 echo -e "    ${CYAN}/eagle-mem-search${RESET}      Search memory and past sessions"
 echo -e "    ${CYAN}/eagle-mem-overview${RESET}    Build or update project overview"
-echo -e "    ${CYAN}/eagle-mem-scan${RESET}        Analyze codebase structure"
-echo -e "    ${CYAN}/eagle-mem-index${RESET}       Index source files for code search"
 echo -e "    ${CYAN}/eagle-mem-memories${RESET}    View/sync Claude Code memories"
 echo -e "    ${CYAN}/eagle-mem-tasks${RESET}       TaskAware Compact Loop for multi-step work"
-echo -e "    ${CYAN}/eagle-mem-prune${RESET}       Clean up stale data"
+echo ""
+echo -e "  ${DIM}Everything else is automatic — scan, index, prune, and${RESET}"
+echo -e "  ${DIM}curator all run in the background via hooks.${RESET}"
 echo ""
 echo -e "  ${DIM}https://github.com/eagleisbatman/eagle-mem${RESET}"
 echo ""

package/skills/eagle-mem-overview/SKILL.md

@@ -17,11 +17,12 @@ description: >
 ## Judgment
 
 **Build an overview when:**
-- SessionStart says "No overview exists" — build on the user's first prompt
-- The current overview reads like scan metadata (file counts, directory listings) — upgrade it
+- SessionStart shows a scan-generated overview (file counts, directory listings) — upgrade it to a rich briefing
 - The user asks: "update overview", "summarize this project", "what is this project"
 - The project has changed significantly since the last overview (new major feature, architecture shift)
 
+Note: New projects are auto-scanned at SessionStart. The scan produces structural metadata. This skill upgrades that into a briefing with intent, architecture, and current state.
+
 **Don't rebuild when:**
 - The overview is already rich and current — just use it
 - The user needs help with a specific task — do the task first, update overview after if needed
@@ -64,11 +65,7 @@ If the output is empty or doesn't match what you wrote, the save failed. Retry o
 
 ### 4. Fallback for empty repos
 
-If no readable source files exist (fresh repo, no README), run a structural scan as a starting point:
-```bash
-eagle-mem scan .
-```
-Then tell the user: "I've generated a structural overview from scan. Once you add a README or source code, re-run `/eagle-mem-overview` for a richer briefing."
+If no readable source files exist (fresh repo, no README), Eagle Mem's auto-scan has already generated a structural overview in the background. Tell the user: "Auto-scan has captured the project structure. Once you add a README or source code, re-run `/eagle-mem-overview` for a richer briefing."
 
 ## What makes a good overview
 
@@ -86,6 +83,10 @@ A good overview lets a fresh Claude Code context window give useful answers with
 **Bad:**
 > eagle-mem: Node.js project (42 files, ~5k lines). Structure: bin/ (1), db/ (10), hooks/ (5), lib/ (3), scripts/ (13), skills/ (7). Entry: bin/eagle-mem. No tests detected.
 
+## How automation works
+
+Eagle Mem v4.0 auto-scans new projects at SessionStart — no user action needed. This skill exists to *upgrade* that scan into a rich, multi-paragraph briefing that captures intent, architecture, and current state.
+
 ## Reference
 
 ```bash
@@ -93,5 +94,4 @@ eagle-mem overview              # view current overview
 eagle-mem overview set "..."    # save new overview
 eagle-mem overview list         # all projects with overviews
 eagle-mem overview delete       # remove current project's overview
-eagle-mem scan .                # structural scan (fallback only)
 ```

package/skills/eagle-mem-index/SKILL.md

@@ -1,120 +0,0 @@
----
-name: eagle-mem-index
-description: >
-  Index source files into FTS5-searchable chunks. Use when: 'eagle index', 'index this project',
-  'make code searchable', 'reindex', 'update index', 'index after pull',
-  'code search setup'. Uses the eagle-mem CLI.
----
-
-# Eagle Mem — Index
-
-## Purpose
-
-**For the user:** Claude Code can find code they wrote weeks ago -- across sessions, without needing to remember which file it was in. Every prompt automatically surfaces relevant code chunks from the index, so past work stays accessible.
-
-**For you (Claude Code):** The UserPromptSubmit hook searches `code_chunks` on every user prompt and injects matching file references into your context. You don't call a search command for this -- it happens automatically. But the index must exist and be current for it to work. That's what this skill manages.
-
-## Judgment
-
-**Index when:**
-- First time setting up Eagle Mem on a project (`eagle-mem index .`)
-- After a `git pull` or branch switch that brought in significant changes
-- After a major refactor (renamed files, moved directories, new modules)
-- The user says "index this project" or "make code searchable"
-- You notice the UserPromptSubmit hook isn't surfacing relevant code -- the index may be stale
-
-**Don't index when:**
-- You just need to read a specific file -- use Read directly
-- The project was recently indexed and no files changed (mtime dedup handles this, but don't waste time running it)
-- You're in the middle of a task -- index at session boundaries, not mid-work
-
-**Decision rule:** Index is a maintenance task, not a search tool. Run it to *prepare* the database, then rely on the automatic hook to *use* it. If the hook isn't surfacing what you expect, the index is stale -- re-run.
-
-## Steps
-
-### 1. Run the indexer
-
-```bash
-eagle-mem index .
-```
-Indexes the current directory. The script:
-- Collects source files (respects `.gitignore`, skips binaries/lockfiles)
-- Filters to known source extensions (sh, js, ts, py, go, rs, java, etc.)
-- Skips files over 1MB
-- Compares mtime against stored mtime -- only re-indexes changed files
-- Chunks each file into segments (default 80 lines) and inserts into `code_chunks` with FTS5
-
-The mtime check makes re-running cheap. On a project with 200 files where 5 changed, it processes only those 5.
-
-### 2. Understand chunk size
-
-Default: 80 lines per chunk. Override with:
-```bash
-EAGLE_MEM_CHUNK_SIZE=40 eagle-mem index .
-```
-
-**Smaller chunks (30-50):** More precise search matches. Better for codebases with many small, distinct functions. Produces more chunks -- larger DB.
-
-**Larger chunks (100-150):** More context per match. Better for files with long, cohesive blocks. Fewer chunks -- smaller DB.
-
-**When to change:** If the hook is surfacing irrelevant matches (chunks too big, mixing unrelated code), shrink. If matches lack context (cutting functions in half), grow. The default of 80 works well for most projects.
-
-### 3. Know what gets indexed
-
-The indexer processes files matching these extensions:
-`sh bash zsh js jsx mjs cjs ts tsx mts py rb go rs java kt kts swift c h cpp cc cxx hpp cs php sql html htm css scss vue svelte dart ex exs zig lua r scala yaml yml toml json md`
-
-Silently skipped: images, binaries, lockfiles (`package-lock.json` etc. are over 1MB), `.git/` contents, anything in `.gitignore`.
-
-### 4. Understand how indexed code reaches the user
-
-The flow is:
-1. You run `eagle-mem index .` -- code is chunked and stored in `code_chunks` table
-2. User submits a prompt in any future session
-3. UserPromptSubmit hook extracts keywords from the prompt
-4. Hook searches `code_chunks` FTS5 index for matches
-5. Matching file paths + line ranges are injected into your context as "EAGLE MEM — Relevant Code"
-
-There is no manual "search code" CLI command. The index feeds the hook, and the hook feeds you. Your job is to keep the index current.
-
-### 5. Verify the index
-
-After indexing, confirm it worked:
-```bash
-eagle-mem search --stats
-```
-Check the "Code chunks" count. For a typical project:
-- 50-file project ~ 200-500 chunks
-- 200-file project ~ 800-2000 chunks
-- 0 chunks after indexing = something went wrong (check file extensions, directory path)
-
-Also verify the hook is using it: on the next user prompt with 3+ words, you should see "EAGLE MEM — Relevant Code" injected if any chunks match.
-
-### 6. When indexing gets stale
-
-The index reflects the state of files *when you last ran it*. It goes stale when:
-- `git pull` brings in changes from others
-- `git checkout` switches branches (different file contents, possibly different files)
-- A major refactor renames or moves files (old paths stay in the index, new paths are missing)
-- Dependencies are updated and source files regenerate
-
-**After any of these, re-run `eagle-mem index .`** The mtime check ensures only changed files are re-processed. Old chunks for unchanged files are kept. Chunks for changed files are atomically replaced (DELETE + INSERT in a transaction).
-
-## What makes a good indexing practice
-
-**Good:**
-> Indexed the project after pulling the team's changes from main. Stats show 1,247 chunks across 189 files. The UserPromptSubmit hook should now surface the new API routes the team added.
-
-**Bad:**
-> Indexed once when Eagle Mem was installed and never again. The hook keeps surfacing stale code from deleted files, and misses the 30 new files added over the past month.
-
-## Reference
-
-| Command / Flag | What it does |
-|---|---|
-| `eagle-mem index .` | Index current directory (incremental via mtime) |
-| `eagle-mem index /path/to/dir` | Index a specific directory |
-| `EAGLE_MEM_CHUNK_SIZE=N` | Override chunk size (default: 80 lines) |
-| `eagle-mem search --stats` | Verify chunk count after indexing |
-| Max file size | 1MB (larger files silently skipped) |
-| Dedup | mtime-based -- re-running is cheap and safe |

package/skills/eagle-mem-prune/SKILL.md

@@ -1,131 +0,0 @@
----
-name: eagle-mem-prune
-description: >
-  Database hygiene — remove stale observations and orphaned code chunks. Use when:
-  'eagle prune', 'clean up memory', 'prune database', 'database too large',
-  'remove old data', 'memory maintenance', search feels slow.
----
-
-# Eagle Mem — Prune
-
-## Purpose
-
-**For the user:** Keep Eagle Mem fast and focused. A database that accumulates months of observations without cleanup gets noisy — search results surface stale context, and queries slow down as row counts grow.
-
-**For you (Claude Code):** Understand what data matters most and what's safe to remove. Pruning is a graduated operation — you're trimming low-value data, never touching the high-value records that give sessions continuity.
-
-## Judgment
-
-**Prune when:**
-- `eagle-mem search --stats` shows high observation counts (1000+ for a single project is worth checking)
-- The user says search feels slow or results are stale
-- After removing a project directory or completing a major refactor that invalidated old code paths
-- Periodic maintenance — monthly is enough for most projects
-
-**Don't prune when:**
-- The database is small and search is fast — pruning a clean database is pointless
-- You're unsure what the observations contain — run `--dry-run` first
-- The user is mid-task — prune between work sessions, not during
-
-**Start conservative.** Default 90 days is right for routine cleanup. Only go aggressive (30 days) when there's a clear reason: project was deleted, architecture was overhauled, or the user explicitly asks for it.
-
-## Data hierarchy — what's protected, what's pruned
-
-**Never pruned (high-value):**
-- `sessions` — your session history, parent rows for everything else
-- `summaries` + `summaries_fts` — what was accomplished each session
-- `claude_tasks` — task state that survives compaction
-- `claude_memories` — mirrored auto-memories
-- `claude_plans` — mirrored plans
-- `overviews` — project overviews injected at SessionStart
-
-**Pruned by age (medium-value):**
-- `observations` — per-tool-use records (which files were read/written). Useful for recent context, but stale observations from 3 months ago rarely help. Default threshold: 90 days.
-
-**Pruned by orphan check (low-value when stale):**
-- `code_chunks` — indexed source code. Chunks for files that no longer exist on disk are orphaned and safe to remove. The prune script checks each file path against the project directory.
-
-## Steps
-
-### 1. Assess — understand the current state
-
-```bash
-eagle-mem search --stats
-```
-
-Look at: total observations, total code chunks, project breakdown. This tells you whether pruning is even needed.
-
-### 2. Preview — always dry-run first
-
-```bash
-eagle-mem prune --dry-run
-```
-
-The output shows:
-- Current counts: "Database: N observations, N chunks"
-- What would be removed: "Would prune N observations older than 90 days"
-- Orphaned chunks: "Would prune N orphaned files from 'project-name'"
-
-**What the numbers mean:**
-- 0 observations to prune: database is already clean, nothing to do
-- 50-200 observations: normal cleanup, proceed
-- 500+ observations: significant cleanup — review the project name to make sure it's correct
-- Orphaned chunks: always safe to remove (the source files don't exist anymore)
-
-### 3. Execute — prune with the right threshold
-
-```bash
-# Standard cleanup (90 days)
-eagle-mem prune
-
-# Conservative (only very old data)
-eagle-mem prune --days 180
-
-# Aggressive (use only with good reason)
-eagle-mem prune --days 30
-
-# Target one project
-eagle-mem prune --project my-app
-```
-
-### 4. Verify — confirm the result
-
-The prune output shows before/after counts:
-```
-Observations: 342 (was 891)
-Code chunks:  45 (was 72)
-```
-
-If the numbers look wrong (pruned too much or too little), there's no undo — but sessions, summaries, tasks, and memories are intact. Observations will rebuild naturally as you keep working.
-
-## When aggressive cleanup is safe
-
-- **Project removed entirely:** The directory is gone, all observations and chunks for it are orphaned. Use `--project <name>` to target just that project.
-- **Major refactor:** You renamed half the files, restructured directories. Old observations reference paths that no longer exist. Prune orphaned chunks, then re-index with `eagle-mem index`.
-- **Fresh start:** The user explicitly wants to clear old noise. `--days 30` removes everything except the last month.
-
-## What makes a good prune decision
-
-**Good:**
-> "eagle-mem search --stats shows 2,400 observations for this project, most from 4 months ago when the architecture was different. I'll dry-run first, then prune with default 90 days."
-
-**Bad:**
-> "Let me clean up the database" [runs `eagle-mem prune --days 7` without checking stats or dry-running first]
-
-The good version assesses before acting. The bad version risks removing recent, useful observations with no preview.
-
-## Reference
-
-| Flag | What it does |
-|------|-------------|
-| `--dry-run`, `-n` | Preview what would be removed, no changes |
-| `--days N`, `-d N` | Age threshold in days (default: 90) |
-| `--project <name>`, `-p` | Target a single project |
-
-```bash
-eagle-mem prune --dry-run           # always start here
-eagle-mem prune                     # standard 90-day cleanup
-eagle-mem prune --days 30           # aggressive (with good reason)
-eagle-mem prune -p my-app -n        # dry-run for one project
-eagle-mem search --stats            # check database health first
-```

package/skills/eagle-mem-scan/SKILL.md

@@ -1,116 +0,0 @@
----
-name: eagle-mem-scan
-description: >
-  Structural codebase analysis — language breakdown, framework detection, entry
-  points, tests, dependencies. Use when: 'eagle scan', 'scan this project',
-  'analyze codebase structure', 'what is this project made of', bootstrapping
-  a new project's overview, empty repo with no README.
----
-
-# Eagle Mem — Scan
-
-## Purpose
-
-**For the user:** Machine-readable project analysis. Answers "what is this project made of?" with hard numbers — languages, line counts, frameworks, entry points, test presence, monorepo structure. No interpretation, just structure.
-
-**For you (Claude Code):** Scan is the structural foundation that overview builds on. It tells you what languages and frameworks are present, how the project is organized, and whether tests exist — all without reading any source files. Use it when you need facts about project composition, not understanding of project purpose.
-
-## Judgment
-
-**Scan when:**
-- No overview exists and the project has no README (scan is the best starting point)
-- You need structural facts: "how many TypeScript files?", "is this a monorepo?", "what test framework?"
-- Bootstrapping a brand-new project in Eagle Mem for the first time
-- After major restructuring — added new packages, new languages, reorganized directories
-
-**Don't scan when:**
-- A rich overview already exists -- scan auto-skips when the overview exceeds 300 chars (use `--force` to override)
-- You need to understand what the project does or why it's built a certain way -- that's overview's job
-- You just want to look at the project -- use `ls` and `Read` instead
-
-**Scan vs overview -- they complement each other:**
-- `eagle-mem scan .` = machine analysis. Counts files, detects frameworks, finds entry points. Fast, no model reasoning. Produces a factual one-liner stored as the overview. Auto-skips if a rich overview exists.
-- `/eagle-mem-overview` = model-driven analysis. You read source files, understand architecture, write a multi-paragraph briefing. Slower, much richer.
-
-The typical flow for a new project: scan first (get the structural snapshot), then build a proper overview on top of it (which replaces the scan output with something richer).
-
-## What scan detects
-
-**Language breakdown:** Top 5 languages by line count. Maps file extensions to language names (`.ts`/`.tsx` = TypeScript, `.py` = Python, etc.). Reports file counts and line counts per language.
-
-**Framework detection:** Checks `package.json` dependencies (React, Next.js, Express, Hono, Prisma, Tailwind, etc.), Python markers (Django, Flask, FastAPI), and ecosystem files (Cargo.toml, go.mod, Gemfile, pubspec.yaml, mix.exs, etc.).
-
-**Structure:** Top-level directories with file counts. Uses `git ls-files` in git repos, falls back to `find` otherwise.
-
-**Entry points:** Looks for `bin/*`, `src/index.*`, `src/main.*`, `src/app.*`, `index.*`, `main.*`, `app.*`, `server.*`, `cli.*`.
-
-**Tests:** Counts files matching test patterns (`test/`, `tests/`, `__tests__/`, `.test.`, `.spec.`, `_test.`). Detects test frameworks (Jest, Vitest, Mocha, pytest).
-
-**Config files:** Finds Dockerfile, docker-compose, tsconfig, ESLint, Biome, Tailwind config, Vite/Next/Webpack config, railway.json, CLAUDE.md, and others.
-
-**Dependencies:** Counts npm deps/devDeps from package.json, Go modules from go.mod.
-
-**Monorepo:** Detects npm workspaces, pnpm-workspace.yaml, Lerna, Turborepo.
-
-## Steps
-
-### 1. Run the scan
-
-```bash
-eagle-mem scan .                 # current directory
-eagle-mem scan /path/to/project  # specific path
-```
-
-### 2. Read the output
-
-Scan prints each detection as it goes:
-```
-  + 47 files found
-  + Languages: TypeScript (12k lines, 35 files), Bash (2k lines, 8 files)
-  + Frameworks: Hono, Prisma, Tailwind
-  + Structure: src/ (28), db/ (10), scripts/ (8), hooks/ (5)
-  + Entry points: bin/eagle-mem, src/index.ts
-  + Tests: 6 test files (Vitest)
-  + Config: tsconfig.json, CLAUDE.md, railway.json
-  + Dependencies: npm: 12 deps, 8 devDeps
-```
-
-**What to look for:**
-- "No tests detected" — notable, worth mentioning to the user
-- 0 entry points — unusual, might mean non-standard project structure
-- Missing framework detection — scan only checks known patterns; niche frameworks won't appear
-- Very high file counts with few lines — lots of config/generated files
-
-### 3. Decide what's next
-
-**If this is a new project with no overview:** The scan output is now stored as the overview. Tell the user: "Structural overview saved. Run `/eagle-mem-overview` for a richer briefing once you're ready."
-
-**If a rich overview already existed:** You just overwrote it. Re-run `/eagle-mem-overview` immediately to rebuild the semantic understanding on top of the new structural data.
-
-## What makes a good scan decision
-
-**Good:**
-> Fresh repo, no README, no overview in Eagle Mem. Running `eagle-mem scan .` to get a structural baseline, then building a proper overview from the source code.
-
-**Bad:**
-> The project already has a detailed 4-paragraph overview from last session. Running `eagle-mem scan --force .` to "refresh the data." [This replaces the rich overview with a one-liner.]
-
-The scan is a starting point, not a maintenance tool. Once a proper overview exists, update it with `/eagle-mem-overview` -- don't overwrite it with scan.
-
-## Reference
-
-```bash
-eagle-mem scan .                 # scan current directory (skips if rich overview exists)
-eagle-mem scan --force .         # scan and overwrite even if rich overview exists
-eagle-mem scan /path/to/project  # scan specific path
-eagle-mem overview               # view the current overview
-eagle-mem overview set "..."     # manually set overview (what /eagle-mem-overview does)
-```
-
-| Detail | Notes |
-|--------|-------|
-| Output stored in | `overviews` table (same as `overview set`) |
-| Overwrites existing overview | Only with `--force` -- auto-skips if overview > 300 chars |
-| Respects .gitignore | Yes, uses `git ls-files` in git repos |
-| Requires model reasoning | No -- pure bash + awk analysis |
-| Typical runtime | Under 2 seconds for most projects |