eagle-mem 1.0.3 → 1.2.0

package/bin/eagle-mem

@@ -21,6 +21,10 @@ case "$command" in
     update)     bash "$SCRIPTS_DIR/update.sh" "$PACKAGE_DIR" "$@" ;;
     scan)       bash "$SCRIPTS_DIR/scan.sh" "$@" ;;
     index)      bash "$SCRIPTS_DIR/index.sh" "$@" ;;
+    search)     bash "$SCRIPTS_DIR/search.sh" "$@" ;;
+    tasks)      bash "$SCRIPTS_DIR/tasks.sh" "$@" ;;
+    overview)   bash "$SCRIPTS_DIR/overview.sh" "$@" ;;
+    prune)      bash "$SCRIPTS_DIR/prune.sh" "$@" ;;
     help|--help|-h)
                 bash "$SCRIPTS_DIR/help.sh" ;;
     version|--version|-v|-V)

package/db/004_observation_indexes.sql

@@ -0,0 +1,9 @@
+-- ═══════════════════════════════════════════════════════════
+-- Eagle Mem — Migration 004: Observation indexes
+-- Adds created_at index for efficient pruning and time-bound queries
+-- ═══════════════════════════════════════════════════════════
+
+PRAGMA foreign_keys = ON;
+
+CREATE INDEX IF NOT EXISTS idx_observations_created_at ON observations(created_at);
+CREATE INDEX IF NOT EXISTS idx_sessions_ended_at ON sessions(status, ended_at);

package/db/migrate.sh

@@ -44,4 +44,7 @@ run_migration "002_overviews" "$SCRIPT_DIR/002_overviews.sql"
 # ─── Migration 003: Code chunks ───────────────────────────
 run_migration "003_code_chunks" "$SCRIPT_DIR/003_code_chunks.sql"
 
+# ─── Migration 004: Observation indexes ──────────────────
+run_migration "004_observation_indexes" "$SCRIPT_DIR/004_observation_indexes.sql"
+
 echo "  Eagle Mem database ready: $DB"

package/db/schema.sql

@@ -20,6 +20,8 @@ CREATE TABLE IF NOT EXISTS _migrations (
 );
 
 -- ─── Sessions ──────────────────────────────────────────────
+-- Sessions are parent rows for summaries, tasks, and observations (FK).
+-- Never delete sessions — prune children instead.
 
 CREATE TABLE IF NOT EXISTS sessions (
     id              TEXT PRIMARY KEY,

package/hooks/post-tool-use.sh

@@ -19,7 +19,7 @@ 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')
 
-[ -z "$session_id" ] || [ -z "$tool_name" ] && exit 0
+if [ -z "$session_id" ] || [ -z "$tool_name" ]; then exit 0; fi
 
 # Only track file-related tools
 case "$tool_name" in
@@ -38,17 +38,17 @@ tool_summary=""
 case "$tool_name" in
     Read)
         fp=$(echo "$input" | jq -r '.tool_input.file_path // empty')
-        [ -n "$fp" ] && files_read="[\"$fp\"]"
+        [ -n "$fp" ] && files_read=$(printf '%s' "$fp" | jq -Rsc '[.]')
         tool_summary="Read $fp"
         ;;
     Write)
         fp=$(echo "$input" | jq -r '.tool_input.file_path // empty')
-        [ -n "$fp" ] && files_modified="[\"$fp\"]"
+        [ -n "$fp" ] && files_modified=$(printf '%s' "$fp" | jq -Rsc '[.]')
         tool_summary="Write $fp"
         ;;
     Edit)
         fp=$(echo "$input" | jq -r '.tool_input.file_path // empty')
-        [ -n "$fp" ] && files_modified="[\"$fp\"]"
+        [ -n "$fp" ] && files_modified=$(printf '%s' "$fp" | jq -Rsc '[.]')
         tool_summary="Edit $fp"
         ;;
     Bash)

package/hooks/session-start.sh

@@ -25,7 +25,6 @@ model=$(echo "$input" | jq -r '.model // empty')
 [ -z "$session_id" ] && exit 0
 
 project=$(eagle_project_from_cwd "$cwd")
-project_sql=$(eagle_sql_escape "$project")
 
 eagle_log "INFO" "SessionStart: session=$session_id project=$project source=$source_type"
 
@@ -48,13 +47,7 @@ $overview
 fi
 
 # Recent summaries for this project (last 5 sessions)
-recent=$(eagle_db "
-    SELECT s.request, s.completed, s.learned, s.next_steps, s.created_at
-    FROM summaries s
-    WHERE s.project = '$project_sql'
-    ORDER BY s.created_at DESC
-    LIMIT 5;
-")
+recent=$(eagle_get_recent_summaries "$project" 5)
 
 if [ -n "$recent" ]; then
     context+="=== EAGLE MEM ===
@@ -78,13 +71,7 @@ Next steps: $next_steps"
 fi
 
 # Pending tasks from TaskAware loop
-pending_tasks=$(eagle_db "
-    SELECT id, title, instructions, status
-    FROM tasks
-    WHERE project = '$project_sql' AND status IN ('pending', 'active')
-    ORDER BY ordinal ASC, id ASC
-    LIMIT 10;
-")
+pending_tasks=$(eagle_get_pending_tasks "$project")
 
 if [ -n "$pending_tasks" ]; then
     context+="
@@ -92,7 +79,7 @@ if [ -n "$pending_tasks" ]; then
 Pending tasks for '$project':
 "
     first_pending=""
-    while IFS='|' read -r tid title instructions status; do
+    while IFS='|' read -r tid title instructions status _ordinal; do
         [ -z "$tid" ] && continue
         local_marker=""
         if [ "$status" = "active" ]; then
@@ -108,22 +95,12 @@ Pending tasks for '$project':
     done <<< "$pending_tasks"
 
     # Load context snapshot for the active/next task
-    active_task=$(eagle_db "
-        SELECT id, title, instructions, context_snapshot
-        FROM tasks
-        WHERE project = '$project_sql' AND status = 'active'
-        ORDER BY ordinal ASC, id ASC
-        LIMIT 1;
-    ")
+    active_task=$(eagle_get_active_task "$project")
 
     if [ -z "$active_task" ] && [ -n "$first_pending" ]; then
         # Auto-activate the next pending task
-        eagle_db "UPDATE tasks SET status = 'active', started_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = $first_pending;"
-        active_task=$(eagle_db "
-            SELECT id, title, instructions, context_snapshot
-            FROM tasks
-            WHERE id = $first_pending;
-        ")
+        eagle_activate_task "$first_pending"
+        active_task=$(eagle_get_active_task "$project")
     fi
 
     if [ -n "$active_task" ]; then

package/hooks/stop.sh

@@ -29,7 +29,6 @@ agent_type=$(echo "$input" | jq -r '.agent_type // empty')
 [ -n "$agent_type" ] && [ "$agent_type" != "main" ] && exit 0
 
 project=$(eagle_project_from_cwd "$cwd")
-project_sql=$(eagle_sql_escape "$project")
 
 eagle_log "INFO" "Stop: session=$session_id project=$project transcript=$transcript_path"
 
@@ -137,10 +136,9 @@ fi
 
 # Mark active task as done if eagle-summary mentions completion
 if [ -n "$completed" ]; then
-    active_task_id=$(eagle_db "SELECT id FROM tasks WHERE project = '$project_sql' AND status = 'active' LIMIT 1;")
-    if [ -n "$active_task_id" ]; then
-        eagle_db "UPDATE tasks SET status = 'done', completed_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = $active_task_id;"
-        eagle_log "INFO" "Stop: marked task #$active_task_id as done"
+    completed_task_id=$(eagle_complete_active_task "$project")
+    if [ -n "$completed_task_id" ]; then
+        eagle_log "INFO" "Stop: marked task #$completed_task_id as done"
     fi
 fi
 

package/hooks/user-prompt-submit.sh

@@ -24,7 +24,6 @@ user_prompt=$(echo "$input" | jq -r '.prompt // empty')
 [ -z "$user_prompt" ] && exit 0
 
 project=$(eagle_project_from_cwd "$cwd")
-project_sql=$(eagle_sql_escape "$project")
 
 # Skip short prompts — not enough signal for meaningful search
 word_count=$(echo "$user_prompt" | wc -w | tr -d ' ')
@@ -45,23 +44,15 @@ fts_query=$(echo "$user_prompt" | tr -cs '[:alnum:]' ' ' | tr '[:upper:]' '[:low
 
 [ -z "$fts_query" ] && exit 0
 
-fts_query_escaped=$(eagle_sql_escape "$fts_query")
-
 # Search for relevant past summaries (cross-session)
-results=$(eagle_db "SELECT s.request, s.learned, s.completed, s.created_at
-                    FROM summaries s
-                    JOIN summaries_fts f ON f.rowid = s.id
-                    WHERE summaries_fts MATCH '$fts_query_escaped'
-                    AND s.project = '$project_sql'
-                    ORDER BY rank
-                    LIMIT 3;")
+results=$(eagle_search_summaries "$fts_query" "$project" 3)
 
 context=""
 
 if [ -n "$results" ]; then
     context+="=== EAGLE MEM — Relevant Memory ===
 "
-    while IFS='|' read -r req learned completed created_at; do
+    while IFS='|' read -r req completed learned _next_steps created_at _proj; do
         [ -z "$req" ] && [ -z "$completed" ] && continue
         context+="[$created_at] "
         [ -n "$req" ] && context+="$req"
@@ -73,15 +64,9 @@ if [ -n "$results" ]; then
 fi
 
 # Search indexed code chunks (if any exist for this project)
-has_chunks=$(eagle_db "SELECT COUNT(*) FROM code_chunks WHERE project = '$project_sql' LIMIT 1;")
+has_chunks=$(eagle_count_code_chunks "$project")
 if [ "${has_chunks:-0}" -gt 0 ]; then
-    code_results=$(eagle_db "SELECT c.file_path, c.start_line, c.end_line, c.language
-                             FROM code_chunks c
-                             JOIN code_chunks_fts f ON f.rowid = c.id
-                             WHERE code_chunks_fts MATCH '$fts_query_escaped'
-                             AND c.project = '$project_sql'
-                             ORDER BY rank
-                             LIMIT 5;")
+    code_results=$(eagle_search_code_chunks "$fts_query" "$project" 5)
 
     if [ -n "$code_results" ]; then
         context+="=== EAGLE MEM — Relevant Code ===

package/lib/common.sh

@@ -7,6 +7,8 @@
 EAGLE_MEM_DIR="${EAGLE_MEM_DIR:-$HOME/.eagle-mem}"
 EAGLE_MEM_DB="$EAGLE_MEM_DIR/memory.db"
 EAGLE_MEM_LOG="$EAGLE_MEM_DIR/eagle-mem.log"
+EAGLE_SETTINGS="${EAGLE_SETTINGS:-$HOME/.claude/settings.json}"
+EAGLE_SKILLS_DIR="$HOME/.claude/skills"
 
 eagle_log() {
     local level="$1"
@@ -23,6 +25,17 @@ eagle_sql_escape() {
     printf '%s' "$1" | sed "s/'/''/g"
 }
 
+eagle_sql_int() {
+    case "$1" in
+        ''|*[!0-9]*) echo "0" ;;
+        *) printf '%s' "$1" ;;
+    esac
+}
+
+eagle_fts_sanitize() {
+    printf '%s' "$1" | sed 's/[*"(){}^~:]/  /g' | sed 's/  */ /g; s/^ //; s/ $//'
+}
+
 eagle_read_stdin() {
     local input=""
     if [ ! -t 0 ]; then

package/lib/db.sh

@@ -34,7 +34,7 @@ eagle_ensure_db() {
 }
 
 eagle_upsert_session() {
-    local session_id="$1"
+    local session_id; session_id=$(eagle_sql_escape "$1")
     local project; project=$(eagle_sql_escape "$2")
     local cwd; cwd=$(eagle_sql_escape "${3:-}")
     local model; model=$(eagle_sql_escape "${4:-}")
@@ -49,17 +49,17 @@ eagle_upsert_session() {
 }
 
 eagle_end_session() {
-    local session_id="$1"
+    local session_id; session_id=$(eagle_sql_escape "$1")
     eagle_db "UPDATE sessions SET status = 'completed', ended_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = '$session_id';"
 }
 
 eagle_insert_observation() {
-    local session_id="$1"
+    local session_id; session_id=$(eagle_sql_escape "$1")
     local project; project=$(eagle_sql_escape "$2")
     local tool_name; tool_name=$(eagle_sql_escape "$3")
     local tool_input_summary; tool_input_summary=$(eagle_sql_escape "$4")
-    local files_read="$5"
-    local files_modified="$6"
+    local files_read; files_read=$(eagle_sql_escape "$5")
+    local files_modified; files_modified=$(eagle_sql_escape "$6")
 
     eagle_db "INSERT INTO observations (session_id, project, tool_name, tool_input_summary, files_read, files_modified)
               VALUES ('$session_id', '$project', '$tool_name', '$tool_input_summary', '$files_read', '$files_modified');"
@@ -96,7 +96,7 @@ SQL
 
 eagle_get_recent_summaries() {
     local project; project=$(eagle_sql_escape "$1")
-    local limit="${2:-5}"
+    local limit; limit=$(eagle_sql_int "${2:-5}")
 
     eagle_db "SELECT s.request, s.completed, s.learned, s.next_steps, s.created_at
               FROM summaries s
@@ -108,7 +108,7 @@ eagle_get_recent_summaries() {
 eagle_search_summaries() {
     local query; query=$(eagle_sql_escape "$1")
     local project="${2:-}"
-    local limit="${3:-10}"
+    local limit; limit=$(eagle_sql_int "${3:-10}")
 
     local where_clause=""
     if [ -n "$project" ]; then
@@ -146,18 +146,19 @@ eagle_get_next_task() {
 
 eagle_get_active_files() {
     local project; project=$(eagle_sql_escape "$1")
-    local limit="${2:-20}"
+    local limit; limit=$(eagle_sql_int "${2:-20}")
 
     eagle_db "SELECT json_each.value
               FROM observations, json_each(observations.files_modified)
               WHERE observations.project = '$project'
+              AND observations.created_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '-30 days')
               GROUP BY json_each.value
               ORDER BY MAX(observations.created_at) DESC
               LIMIT $limit;"
 }
 
 eagle_observation_exists() {
-    local session_id="$1"
+    local session_id; session_id=$(eagle_sql_escape "$1")
     local tool_name; tool_name=$(eagle_sql_escape "$2")
     local tool_summary; tool_summary=$(eagle_sql_escape "$3")
 
@@ -184,3 +185,77 @@ eagle_get_overview() {
 
     eagle_db "SELECT content FROM overviews WHERE project = '$project';"
 }
+
+eagle_activate_task() {
+    local task_id; task_id=$(eagle_sql_int "$1")
+    eagle_db "UPDATE tasks SET status = 'active', started_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = $task_id;"
+}
+
+eagle_complete_active_task() {
+    local project; project=$(eagle_sql_escape "$1")
+    local active_id
+    active_id=$(eagle_db "SELECT id FROM tasks WHERE project = '$project' AND status = 'active' LIMIT 1;")
+    if [ -n "$active_id" ]; then
+        local safe_id; safe_id=$(eagle_sql_int "$active_id")
+        eagle_db "UPDATE tasks SET status = 'done', completed_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = $safe_id;"
+        echo "$active_id"
+    fi
+}
+
+eagle_get_active_task() {
+    local project; project=$(eagle_sql_escape "$1")
+    eagle_db "SELECT id, title, instructions, context_snapshot
+              FROM tasks
+              WHERE project = '$project' AND status = 'active'
+              ORDER BY ordinal ASC, id ASC
+              LIMIT 1;"
+}
+
+eagle_search_code_chunks() {
+    local query; query=$(eagle_sql_escape "$1")
+    local project; project=$(eagle_sql_escape "$2")
+    local limit; limit=$(eagle_sql_int "${3:-5}")
+
+    eagle_db "SELECT c.file_path, c.start_line, c.end_line, c.language
+              FROM code_chunks c
+              JOIN code_chunks_fts f ON f.rowid = c.id
+              WHERE code_chunks_fts MATCH '$query'
+              AND c.project = '$project'
+              ORDER BY rank
+              LIMIT $limit;"
+}
+
+eagle_count_code_chunks() {
+    local project; project=$(eagle_sql_escape "$1")
+    eagle_db "SELECT COUNT(*) FROM code_chunks WHERE project = '$project' LIMIT 1;"
+}
+
+eagle_prune_observations() {
+    local days; days=$(eagle_sql_int "${1:-90}")
+    local project_filter=""
+    if [ -n "${2:-}" ]; then
+        local proj; proj=$(eagle_sql_escape "$2")
+        project_filter="AND session_id IN (SELECT id FROM sessions WHERE project = '$proj')"
+    fi
+    eagle_db "DELETE FROM observations WHERE created_at < strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '-$days days') $project_filter;"
+}
+
+eagle_prune_orphan_chunks() {
+    local project; project=$(eagle_sql_escape "$1")
+    local target_dir="$2"
+
+    # Get all indexed file paths for this project
+    local paths
+    paths=$(eagle_db "SELECT DISTINCT file_path FROM code_chunks WHERE project = '$project';")
+
+    local removed=0
+    while IFS= read -r fpath; do
+        [ -z "$fpath" ] && continue
+        if [ ! -f "$target_dir/$fpath" ]; then
+            local fpath_sql; fpath_sql=$(eagle_sql_escape "$fpath")
+            eagle_db "DELETE FROM code_chunks WHERE project = '$project' AND file_path = '$fpath_sql';"
+            removed=$((removed + 1))
+        fi
+    done <<< "$paths"
+    echo "$removed"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eagle-mem",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "Lightweight persistent memory for Claude Code — SQLite + FTS5, no daemon, no bloat",
   "bin": {
     "eagle-mem": "bin/eagle-mem"

package/scripts/help.sh

@@ -19,20 +19,28 @@ echo -e "  ${BOLD}Usage:${RESET}"
 echo -e "    eagle-mem ${CYAN}<command>${RESET}"
 echo ""
 echo -e "  ${BOLD}Commands:${RESET}"
+echo -e "    ${CYAN}search${RESET}      Search past sessions, files, and observations"
+echo -e "    ${CYAN}tasks${RESET}       Manage tracked tasks (add, done, block, list)"
+echo -e "    ${CYAN}overview${RESET}    View or set project overview"
+echo -e "    ${CYAN}scan${RESET}        Analyze a project and generate an overview"
+echo -e "    ${CYAN}index${RESET}       Index source files for code-level search"
+echo -e "    ${CYAN}prune${RESET}       Remove old observations and orphaned chunks"
 echo -e "    ${CYAN}install${RESET}     Set up hooks, database, and skills"
 echo -e "    ${CYAN}uninstall${RESET}   Remove hooks and optionally delete data"
 echo -e "    ${CYAN}update${RESET}      Re-deploy hooks and run new migrations"
-echo -e "    ${CYAN}scan${RESET}        Analyze a project and generate an overview"
-echo -e "    ${CYAN}index${RESET}       Index source files for code-level search"
 echo -e "    ${CYAN}help${RESET}        Show this help message"
 echo -e "    ${CYAN}version${RESET}     Show version number"
 echo ""
 echo -e "  ${BOLD}Examples:${RESET}"
-echo -e "    ${DIM}\$${RESET} eagle-mem install       ${DIM}# First-time setup${RESET}"
-echo -e "    ${DIM}\$${RESET} eagle-mem update        ${DIM}# After npm update${RESET}"
-echo -e "    ${DIM}\$${RESET} eagle-mem scan .         ${DIM}# Scan current project${RESET}"
-echo -e "    ${DIM}\$${RESET} eagle-mem index .        ${DIM}# Index source files${RESET}"
-echo -e "    ${DIM}\$${RESET} eagle-mem uninstall     ${DIM}# Clean removal${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem search \"auth bug\"  ${DIM}# Search memory${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem search --timeline  ${DIM}# Recent sessions${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem tasks              ${DIM}# List tasks${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem tasks add \"Fix X\"  ${DIM}# Add a task${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem overview           ${DIM}# View overview${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem scan .             ${DIM}# Scan current project${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem index .            ${DIM}# Index source files${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem prune              ${DIM}# Clean old data${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem install            ${DIM}# First-time setup${RESET}"
 echo ""
 echo -e "  ${BOLD}What it does:${RESET}"
 echo -e "    ${DOT} Saves session summaries to a shared SQLite database"
@@ -46,5 +54,7 @@ echo -e "    ${CYAN}/eagle-mem-search${RESET}    Search past sessions and observ
 echo -e "    ${CYAN}/eagle-mem-tasks${RESET}     Break work into tracked subtasks"
 echo -e "    ${CYAN}/eagle-mem-overview${RESET}  Generate a persistent project summary"
 echo ""
+echo -e "  ${DIM}Skills use these CLI commands under the hood — no raw SQL.${RESET}"
+echo ""
 echo -e "  ${DIM}https://github.com/eagleisbatman/eagle-mem${RESET}"
 echo ""

package/scripts/install.sh

@@ -7,11 +7,12 @@ set -euo pipefail
 
 PACKAGE_DIR="${1:-.}"
 SCRIPTS_DIR="$(cd "$(dirname "$0")" && pwd)"
+LIB_DIR="$SCRIPTS_DIR/../lib"
 
 . "$SCRIPTS_DIR/style.sh"
+. "$LIB_DIR/common.sh"
 
-EAGLE_MEM_DIR="${EAGLE_MEM_DIR:-$HOME/.eagle-mem}"
-SETTINGS="$HOME/.claude/settings.json"
+SETTINGS="$EAGLE_SETTINGS"
 
 eagle_banner
 eagle_header "Install"
@@ -203,22 +204,12 @@ patch_hook "UserPromptSubmit" "" \
 
 # ─── Install skills ────────────────────────────────────────
 
-SKILLS_DIR="$HOME/.claude/skills"
-if [ -d "$SKILLS_DIR" ] && [ -d "$PACKAGE_DIR/skills" ]; then
+if [ -d "$PACKAGE_DIR/skills" ]; then
+    mkdir -p "$EAGLE_SKILLS_DIR"
     for skill_dir in "$PACKAGE_DIR"/skills/*/; do
         [ ! -d "$skill_dir" ] && continue
         skill_name=$(basename "$skill_dir")
-        dst="$SKILLS_DIR/$skill_name"
-        [ -L "$dst" ] && rm "$dst"
-        ln -sf "$skill_dir" "$dst"
-        eagle_ok "Skill: $skill_name"
-    done
-elif [ -d "$PACKAGE_DIR/skills" ]; then
-    mkdir -p "$SKILLS_DIR"
-    for skill_dir in "$PACKAGE_DIR"/skills/*/; do
-        [ ! -d "$skill_dir" ] && continue
-        skill_name=$(basename "$skill_dir")
-        dst="$SKILLS_DIR/$skill_name"
+        dst="$EAGLE_SKILLS_DIR/$skill_name"
         [ -L "$dst" ] && rm "$dst"
         ln -sf "$skill_dir" "$dst"
         eagle_ok "Skill: $skill_name"

package/scripts/overview.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Overview
+# CLI wrapper for project overview management
+# ═══════════════════════════════════════════════════════════
+set -euo pipefail
+
+SCRIPTS_DIR="$(cd "$(dirname "$0")" && pwd)"
+LIB_DIR="$SCRIPTS_DIR/../lib"
+
+. "$SCRIPTS_DIR/style.sh"
+. "$LIB_DIR/common.sh"
+. "$LIB_DIR/db.sh"
+
+eagle_ensure_db
+
+# ─── Parse arguments ──────────────────────────────────────
+
+action="${1:-show}"
+shift 2>/dev/null || true
+
+project=""
+json_output=false
+args=()
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --project|-p)   project="$2"; shift 2 ;;
+        --json|-j)      json_output=true; shift ;;
+        --help|-h)
+            echo -e "  ${BOLD}eagle-mem overview${RESET} — Manage project overviews"
+            echo ""
+            echo -e "  ${BOLD}Usage:${RESET}"
+            echo -e "    eagle-mem overview                    ${DIM}# show current overview${RESET}"
+            echo -e "    eagle-mem overview ${CYAN}set${RESET} <text>         ${DIM}# set/update overview${RESET}"
+            echo -e "    eagle-mem overview ${CYAN}delete${RESET}             ${DIM}# delete overview${RESET}"
+            echo -e "    eagle-mem overview ${CYAN}list${RESET}               ${DIM}# list all overviews${RESET}"
+            echo ""
+            echo -e "  ${BOLD}Options:${RESET}"
+            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 ""
+            exit 0
+            ;;
+        *)  args+=("$1"); shift ;;
+    esac
+done
+
+[ -z "$project" ] && project=$(eagle_project_from_cwd "$(pwd)")
+project_sql=$(eagle_sql_escape "$project")
+
+# ─── Show overview ────────────────────────────────────────
+
+overview_show() {
+    if [ "$json_output" = true ]; then
+        eagle_db_json "SELECT project, content, updated_at FROM overviews WHERE project = '$project_sql';"
+        return
+    fi
+
+    local content
+    content=$(eagle_get_overview "$project")
+
+    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"
+        return
+    fi
+
+    echo ""
+    echo -e "  ${BOLD}Overview${RESET} ${DIM}($project)${RESET}"
+    echo -e "  ${DIM}─────────────────────────────────────${RESET}"
+    echo ""
+    echo -e "  $content"
+    echo ""
+}
+
+# ─── Set overview ─────────────────────────────────────────
+
+overview_set() {
+    local content="${args[*]:-}"
+
+    if [ -z "$content" ]; then
+        eagle_err "Usage: eagle-mem overview set <text>"
+        exit 1
+    fi
+
+    eagle_upsert_overview "$project" "$content"
+
+    if [ "$json_output" = true ]; then
+        jq -nc --arg project "$project" '{project: $project, updated: true}'
+        return
+    fi
+
+    eagle_ok "Overview saved for '$project'"
+}
+
+# ─── Delete overview ──────────────────────────────────────
+
+overview_delete() {
+    eagle_db "DELETE FROM overviews WHERE project = '$project_sql';"
+
+    if [ "$json_output" = true ]; then
+        jq -nc --arg project "$project" '{project: $project, deleted: true}'
+        return
+    fi
+
+    eagle_ok "Overview deleted for '$project'"
+}
+
+# ─── List all overviews ──────────────────────────────────
+
+overview_list() {
+    if [ "$json_output" = true ]; then
+        eagle_db_json "SELECT project, content, updated_at FROM overviews ORDER BY updated_at DESC;"
+        return
+    fi
+
+    local results
+    results=$(eagle_db "SELECT project, substr(content, 1, 80), updated_at FROM overviews ORDER BY updated_at DESC;")
+
+    if [ -z "$results" ]; then
+        eagle_dim "No overviews stored"
+        return
+    fi
+
+    echo ""
+    echo -e "  ${BOLD}All project overviews${RESET}"
+    echo -e "  ${DIM}─────────────────────────────────────${RESET}"
+    echo ""
+
+    while IFS='|' read -r proj snippet updated_at; do
+        [ -z "$proj" ] && continue
+        echo -e "  ${BOLD}$proj${RESET}  ${DIM}$updated_at${RESET}"
+        echo -e "  ${DIM}$snippet...${RESET}"
+        echo ""
+    done <<< "$results"
+}
+
+# ─── Dispatch ─────────────────────────────────────────────
+
+case "$action" in
+    show|view)   overview_show ;;
+    set|update)  overview_set ;;
+    delete|rm)   overview_delete ;;
+    list|ls)     overview_list ;;
+    --help|-h)
+        echo -e "  ${BOLD}eagle-mem overview${RESET} — Manage project overviews"
+        echo ""
+        echo -e "  ${BOLD}Usage:${RESET}"
+        echo -e "    eagle-mem overview                    ${DIM}# show current overview${RESET}"
+        echo -e "    eagle-mem overview ${CYAN}set${RESET} <text>         ${DIM}# set/update overview${RESET}"
+        echo -e "    eagle-mem overview ${CYAN}delete${RESET}             ${DIM}# delete overview${RESET}"
+        echo -e "    eagle-mem overview ${CYAN}list${RESET}               ${DIM}# list all overviews${RESET}"
+        echo ""
+        echo -e "  ${BOLD}Options:${RESET}"
+        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 ""
+        exit 0
+        ;;
+    *)
+        eagle_err "Unknown action: $action"
+        eagle_dim "  Run 'eagle-mem overview --help' for options"
+        exit 1
+        ;;
+esac