eagle-mem 1.5.1 → 1.6.1

package/bin/eagle-mem

@@ -29,7 +29,7 @@ case "$command" in
     help|--help|-h)
                 bash "$SCRIPTS_DIR/help.sh" ;;
     version|--version|-v|-V)
-                version=$(node -e "console.log(require('$PACKAGE_DIR/package.json').version)" 2>/dev/null || echo "unknown")
+                version=$(jq -r .version "$PACKAGE_DIR/package.json" 2>/dev/null || echo "unknown")
                 echo -e "  ${BOLD}Eagle Mem${RESET} v${version}"
                 ;;
     *)

package/db/009_drop_dead_tasks.sql

@@ -0,0 +1,29 @@
+-- ═══════════════════════════════════════════════════════════
+-- Migration 009: Drop dead tasks table
+-- The original tasks table (from schema.sql / migration 001)
+-- was replaced by claude_tasks (migration 007). No code
+-- references the old table. This cleans up the vestigial
+-- schema: 3 FTS triggers, the FTS virtual table, 3 indexes,
+-- and the table itself.
+--
+-- NOTE: schema.sql (migration 001) still contains the CREATE
+-- TABLE tasks definition. We do NOT edit applied migrations.
+-- Fresh installs will CREATE (001) then DROP (009). Existing
+-- installs just run 009. Verified 0 rows in production.
+-- ═══════════════════════════════════════════════════════════
+
+-- Drop FTS sync triggers first (they reference the tasks table)
+DROP TRIGGER IF EXISTS tasks_ai;
+DROP TRIGGER IF EXISTS tasks_ad;
+DROP TRIGGER IF EXISTS tasks_au;
+
+-- Drop the FTS virtual table
+DROP TABLE IF EXISTS tasks_fts;
+
+-- Drop indexes (implicit in DROP TABLE, but explicit for clarity)
+DROP INDEX IF EXISTS idx_tasks_project;
+DROP INDEX IF EXISTS idx_tasks_status;
+DROP INDEX IF EXISTS idx_tasks_parent;
+
+-- Drop the dead tasks table
+DROP TABLE IF EXISTS tasks;

package/db/migrate.sh

@@ -25,7 +25,8 @@ run_migration() {
         body=$(grep -v -E '^[[:space:]]*PRAGMA ' "$file")
 
         # Set connection PRAGMAs, then run migration body + tracking insert atomically
-        { echo "PRAGMA trusted_schema=ON;"; echo "PRAGMA foreign_keys=ON;"; echo "PRAGMA busy_timeout=5000;"; echo "BEGIN;"; echo "$body"; echo "INSERT INTO _migrations (name) VALUES ('$name');"; echo "COMMIT;"; } | sqlite3 "$DB"
+        # .bail on ensures sqlite3 stops on the first error instead of continuing
+        { echo ".bail on"; echo "PRAGMA trusted_schema=ON;"; echo "PRAGMA foreign_keys=ON;"; echo "PRAGMA busy_timeout=5000;"; echo "BEGIN;"; echo "$body"; echo "INSERT INTO _migrations (name) VALUES ('$name');"; echo "COMMIT;"; } | sqlite3 "$DB"
         echo "  applied: $name"
     fi
 }
@@ -64,4 +65,7 @@ run_migration "007_claude_tasks" "$SCRIPT_DIR/007_claude_tasks.sql"
 # ─── Migration 008: Summary UPSERT (unique session_id) ───
 run_migration "008_summary_upsert" "$SCRIPT_DIR/008_summary_upsert.sql"
 
+# ─── Migration 009: Drop dead tasks table ────────────────
+run_migration "009_drop_dead_tasks" "$SCRIPT_DIR/009_drop_dead_tasks.sql"
+
 echo "  Eagle Mem database ready: $DB"

package/db/schema.sql

@@ -75,28 +75,6 @@ CREATE TABLE IF NOT EXISTS summaries (
 CREATE INDEX IF NOT EXISTS idx_summaries_session ON summaries(session_id);
 CREATE INDEX IF NOT EXISTS idx_summaries_project ON summaries(project);
 
--- ─── Tasks (TaskAware Compact Loop) ───────────────────────
--- Subtasks for multi-step work with compaction between each
-
-CREATE TABLE IF NOT EXISTS tasks (
-    id              INTEGER PRIMARY KEY AUTOINCREMENT,
-    project         TEXT NOT NULL,
-    session_id      TEXT REFERENCES sessions(id),
-    parent_id       INTEGER REFERENCES tasks(id),
-    title           TEXT NOT NULL,
-    instructions    TEXT,
-    context_snapshot TEXT,
-    status          TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'active', 'done', 'blocked', 'cancelled')),
-    ordinal         INTEGER NOT NULL DEFAULT 0,
-    created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
-    started_at      TEXT,
-    completed_at    TEXT
-);
-
-CREATE INDEX IF NOT EXISTS idx_tasks_project ON tasks(project);
-CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
-CREATE INDEX IF NOT EXISTS idx_tasks_parent ON tasks(parent_id);
-
 -- ─── FTS5: Full-text search on summaries ───────────────────
 
 CREATE VIRTUAL TABLE IF NOT EXISTS summaries_fts USING fts5(
@@ -127,30 +105,3 @@ CREATE TRIGGER IF NOT EXISTS summaries_au AFTER UPDATE ON summaries BEGIN
     INSERT INTO summaries_fts(rowid, request, investigated, learned, completed, next_steps, notes)
     VALUES (new.id, new.request, new.investigated, new.learned, new.completed, new.next_steps, new.notes);
 END;
-
--- ─── FTS5: Full-text search on tasks ──────────────────────
-
-CREATE VIRTUAL TABLE IF NOT EXISTS tasks_fts USING fts5(
-    title,
-    instructions,
-    context_snapshot,
-    content='tasks',
-    content_rowid='id'
-);
-
-CREATE TRIGGER IF NOT EXISTS tasks_ai AFTER INSERT ON tasks BEGIN
-    INSERT INTO tasks_fts(rowid, title, instructions, context_snapshot)
-    VALUES (new.id, new.title, new.instructions, new.context_snapshot);
-END;
-
-CREATE TRIGGER IF NOT EXISTS tasks_ad AFTER DELETE ON tasks BEGIN
-    INSERT INTO tasks_fts(tasks_fts, rowid, title, instructions, context_snapshot)
-    VALUES ('delete', old.id, old.title, old.instructions, old.context_snapshot);
-END;
-
-CREATE TRIGGER IF NOT EXISTS tasks_au AFTER UPDATE ON tasks BEGIN
-    INSERT INTO tasks_fts(tasks_fts, rowid, title, instructions, context_snapshot)
-    VALUES ('delete', old.id, old.title, old.instructions, old.context_snapshot);
-    INSERT INTO tasks_fts(rowid, title, instructions, context_snapshot)
-    VALUES (new.id, new.title, new.instructions, new.context_snapshot);
-END;

package/hooks/post-tool-use.sh

@@ -83,7 +83,11 @@ esac
 case "$tool_name" in
     Write|Edit)
         if [ -n "$fp" ]; then
+            # Reject path traversal: bash case `*` matches `/`, so
+            # patterns like projects/*/memory/*.md would match paths
+            # containing /../ segments. Block any path with `..` first.
             case "$fp" in
+                *..*) ;; # path traversal — skip
                 "$HOME/.claude/projects"/*/memory/*.md)
                     mem_base=$(basename "$fp")
                     if [ "$mem_base" != "MEMORY.md" ] && [ -f "$fp" ]; then

package/hooks/session-start.sh

@@ -31,8 +31,10 @@ eagle_log "INFO" "SessionStart: session=$session_id project=$project source=$sou
 eagle_upsert_session "$session_id" "$project" "$cwd" "$model" "$source_type"
 
 # ─── Sweep stuck sessions (older than 4 hours) ─────────────
+# Exclude the current session — it may be a resumed session older than 4h
 eagle_db "UPDATE sessions SET status = 'abandoned'
     WHERE status = 'active'
+    AND id != '$(eagle_sql_escape "$session_id")'
     AND started_at < strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '-4 hours');"
 
 # ─── Build context injection ────────────────────────────────
@@ -80,57 +82,6 @@ Next steps: $next_steps"
 "
 fi
 
-# Pending tasks from TaskAware loop
-pending_tasks=$(eagle_get_pending_tasks "$project")
-
-if [ -n "$pending_tasks" ]; then
-    context+="
-=== EAGLE MEM — Tasks ===
-Pending tasks for '$project':
-"
-    first_pending=""
-    while IFS='|' read -r tid title instructions status _ordinal; do
-        [ -z "$tid" ] && continue
-        local_marker=""
-        if [ "$status" = "active" ]; then
-            local_marker=" [ACTIVE]"
-        elif [ -z "$first_pending" ]; then
-            local_marker=" [NEXT]"
-            first_pending="$tid"
-        fi
-        context+="  $tid. $title$local_marker"
-        [ -n "$instructions" ] && context+=" — $instructions"
-        context+="
-"
-    done <<< "$pending_tasks"
-
-    # Load context snapshot for the active/next task
-    active_task=$(eagle_get_active_task "$project")
-
-    if [ -z "$active_task" ] && [ -n "$first_pending" ]; then
-        # Auto-activate the next pending task (atomic to prevent races
-        # when multiple sessions start simultaneously)
-        eagle_db "UPDATE tasks SET status = 'active', started_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
-                  WHERE id = $first_pending
-                  AND status = 'pending'
-                  AND NOT EXISTS (SELECT 1 FROM tasks WHERE project = '$(eagle_sql_escape "$project")' AND status = 'active');"
-        active_task=$(eagle_get_active_task "$project")
-    fi
-
-    if [ -n "$active_task" ]; then
-        IFS='|' read -r atid atitle ainstructions asnapshot <<< "$active_task"
-        context+="
-Current task (#$atid): $atitle
-"
-        [ -n "$ainstructions" ] && context+="Instructions: $ainstructions
-"
-        [ -n "$asnapshot" ] && context+="Context: $asnapshot
-"
-        context+="When done, tell the user to run /compact so Eagle Mem can save progress and load the next task.
-"
-    fi
-fi
-
 # ─── Mirrored Claude memories ──────────────────────────────
 
 memories=$(eagle_list_claude_memories "$project" 5)
@@ -161,21 +112,28 @@ Recent plans for '$project':
     done <<< "$plans"
 fi
 
-# ─── Mirrored Claude tasks (synced) ──────────────────────
+# ─── Claude Code tasks ───────────────────────────────────
 
-synced_tasks=$(eagle_db "SELECT subject, status FROM claude_tasks
+synced_tasks=$(eagle_db "SELECT subject, status, blocked_by FROM claude_tasks
     WHERE project = '$(eagle_sql_escape "$project")'
     AND status IN ('in_progress', 'pending')
-    AND updated_at > datetime('now', '-7 days')
-    ORDER BY updated_at DESC LIMIT 5;")
+    AND updated_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '-7 days')
+    ORDER BY
+        CASE status WHEN 'in_progress' THEN 0 ELSE 1 END,
+        updated_at DESC
+    LIMIT 10;")
 if [ -n "$synced_tasks" ]; then
     context+="
-=== EAGLE MEM — Synced Tasks ===
-In-progress/pending tasks for '$project':
+=== EAGLE MEM — Tasks ===
+Tasks for '$project':
 "
-    while IFS='|' read -r tsubject tstatus; do
+    while IFS='|' read -r tsubject tstatus tblocked; do
         [ -z "$tsubject" ] && continue
-        context+="  - [$tstatus] $tsubject
+        local_marker=""
+        if [ "$tblocked" != "[]" ] && [ -n "$tblocked" ]; then
+            local_marker=" (blocked)"
+        fi
+        context+="  - [$tstatus] $tsubject$local_marker
 "
     done <<< "$synced_tasks"
 fi
@@ -188,8 +146,7 @@ You have persistent memory powered by Eagle Mem. When you recall context from a
 IMPORTANT: At the start of your VERY NEXT response (this fires on session start, /clear, AND context compaction — always show this block, even if you think you showed it before, because prior context may have been compressed away). Show the user what Eagle Mem loaded using this exact format:
 
 \`\`\`
-█▀▀ ▄▀█ █▀▀ █   █▀▀   █▀▄▀█ █▀▀ █▀▄▀█
-██▄ █▀█ █▄█ █▄▄ ██▄   █ ▀ █ ██▄ █ ▀ █
+$eagle_logo
 
 Project: <project name>
 Sessions: N recent | Memories: N | Tasks: N pending

package/hooks/stop.sh

@@ -141,12 +141,4 @@ if [ -n "$request" ] || [ -n "$completed" ] || [ -n "$learned" ]; then
     eagle_log "INFO" "Stop: summary saved for session=$session_id"
 fi
 
-# Mark active task as done only when Claude explicitly provided a summary
-if [ -n "$summary_block" ] && [ -n "$completed" ]; then
-    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
-
 exit 0

package/lib/common.sh

@@ -46,6 +46,8 @@ eagle_fts_sanitize() {
 # Claude Code session IDs are UUIDs or hex strings — reject anything else.
 eagle_validate_session_id() {
     local sid="$1"
+    # Length cap: Claude Code IDs are UUIDs/hex (36-64 chars). Reject oversized input.
+    [ ${#sid} -gt 128 ] && return 1
     [[ "$sid" =~ ^[A-Za-z0-9_-]+$ ]]
 }
 

package/lib/db.sh

@@ -18,7 +18,7 @@ eagle_db() {
 }
 
 eagle_db_pipe() {
-    { echo "$EAGLE_DB_SETUP"; cat; } | sqlite3 "$EAGLE_MEM_DB" 2>>"$EAGLE_MEM_LOG"
+    { echo "$EAGLE_DB_SETUP"; echo ".bail on"; cat; } | sqlite3 "$EAGLE_MEM_DB" 2>>"$EAGLE_MEM_LOG"
 }
 
 eagle_db_json() {
@@ -45,7 +45,8 @@ eagle_upsert_session() {
               ON CONFLICT(id) DO UPDATE SET
                   cwd = COALESCE(excluded.cwd, sessions.cwd),
                   model = COALESCE(excluded.model, sessions.model),
-                  source = COALESCE(excluded.source, sessions.source);"
+                  source = COALESCE(excluded.source, sessions.source),
+                  status = 'active';"
 }
 
 eagle_end_session() {
@@ -78,7 +79,7 @@ eagle_insert_summary() {
     local notes; notes=$(eagle_sql_escape "${10:-}")
 
     eagle_db_pipe <<SQL
-INSERT OR REPLACE INTO summaries (session_id, project, request, investigated, learned, completed, next_steps, files_read, files_modified, notes)
+INSERT INTO summaries (session_id, project, request, investigated, learned, completed, next_steps, files_read, files_modified, notes)
 VALUES (
     '$session_id',
     '$project',
@@ -90,7 +91,17 @@ VALUES (
     '$files_read',
     '$files_modified',
     '$notes'
-);
+)
+ON CONFLICT(session_id) DO UPDATE SET
+    project        = excluded.project,
+    request        = COALESCE(NULLIF(excluded.request, ''), summaries.request),
+    investigated   = COALESCE(NULLIF(excluded.investigated, ''), summaries.investigated),
+    learned        = COALESCE(NULLIF(excluded.learned, ''), summaries.learned),
+    completed      = COALESCE(NULLIF(excluded.completed, ''), summaries.completed),
+    next_steps     = COALESCE(NULLIF(excluded.next_steps, ''), summaries.next_steps),
+    files_read     = COALESCE(NULLIF(excluded.files_read, '[]'), summaries.files_read),
+    files_modified = COALESCE(NULLIF(excluded.files_modified, '[]'), summaries.files_modified),
+    notes          = COALESCE(NULLIF(excluded.notes, ''), summaries.notes);
 SQL
 }
 
@@ -107,7 +118,8 @@ eagle_get_recent_summaries() {
 }
 
 eagle_search_summaries() {
-    local query; query=$(eagle_sql_escape "$1")
+    local query; query=$(eagle_fts_sanitize "$1")
+    query=$(eagle_sql_escape "$query")
     local project="${2:-}"
     local limit; limit=$(eagle_sql_int "${3:-10}")
 
@@ -126,25 +138,6 @@ eagle_search_summaries() {
               LIMIT $limit;"
 }
 
-eagle_get_pending_tasks() {
-    local project; project=$(eagle_sql_escape "$1")
-
-    eagle_db "SELECT id, title, instructions, status, ordinal
-              FROM tasks
-              WHERE project = '$project' AND status IN ('pending', 'active')
-              ORDER BY ordinal ASC, id ASC;"
-}
-
-eagle_get_next_task() {
-    local project; project=$(eagle_sql_escape "$1")
-
-    eagle_db "SELECT id, title, instructions, context_snapshot
-              FROM tasks
-              WHERE project = '$project' AND status = 'pending'
-              ORDER BY ordinal ASC, id ASC
-              LIMIT 1;"
-}
-
 eagle_observation_exists() {
     local session_id; session_id=$(eagle_sql_escape "$1")
     local tool_name; tool_name=$(eagle_sql_escape "$2")
@@ -174,33 +167,9 @@ 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 query; query=$(eagle_fts_sanitize "$1")
+    query=$(eagle_sql_escape "$query")
     local project; project=$(eagle_sql_escape "$2")
     local limit; limit=$(eagle_sql_int "${3:-5}")
 

package/package.json

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

package/scripts/help.sh

@@ -8,7 +8,7 @@ PACKAGE_DIR="$(cd "$SCRIPTS_DIR/.." && pwd)"
 
 . "$SCRIPTS_DIR/style.sh"
 
-version=$(node -e "console.log(require('$PACKAGE_DIR/package.json').version)" 2>/dev/null || echo "unknown")
+version=$(jq -r .version "$PACKAGE_DIR/package.json" 2>/dev/null || echo "unknown")
 
 eagle_banner
 
@@ -20,7 +20,7 @@ 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}tasks${RESET}       View mirrored Claude Code tasks"
 echo -e "    ${CYAN}overview${RESET}    View or set project overview"
 echo -e "    ${CYAN}memories${RESET}    Browse and search Claude Code memories, plans, and tasks"
 echo -e "    ${CYAN}scan${RESET}        Analyze a project and generate an overview"
@@ -35,8 +35,8 @@ echo ""
 echo -e "  ${BOLD}Examples:${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 tasks              ${DIM}# View pending tasks${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem tasks search \"X\"   ${DIM}# Search task history${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}"
@@ -53,11 +53,11 @@ echo -e "    ${DOT} Injects relevant memory at session start"
 echo -e "    ${DOT} Searches past sessions when you ask related questions"
 echo -e "    ${DOT} Tracks file operations across sessions"
 echo -e "    ${DOT} Mirrors Claude Code memories, plans, and tasks into FTS5-searchable storage"
-echo -e "    ${DOT} Provides task management for complex multi-step work"
+echo -e "    ${DOT} Uses Claude Code's native task system (TaskCreate/TaskUpdate) for multi-step work"
 echo ""
 echo -e "  ${BOLD}Skills${RESET} ${DIM}(available inside Claude Code):${RESET}"
 echo -e "    ${CYAN}/eagle-mem-search${RESET}      Search past sessions and observations"
-echo -e "    ${CYAN}/eagle-mem-tasks${RESET}       Break work into tracked subtasks"
+echo -e "    ${CYAN}/eagle-mem-tasks${RESET}       Break work into Claude Code tasks with dependencies"
 echo -e "    ${CYAN}/eagle-mem-overview${RESET}    Generate a persistent project summary"
 echo -e "    ${CYAN}/eagle-mem-index${RESET}       Index source files for code search"
 echo -e "    ${CYAN}/eagle-mem-scan${RESET}        Scan and analyze a project"

package/scripts/index.sh

@@ -104,7 +104,6 @@ fi
 project_sql=$(eagle_sql_escape "$PROJECT")
 NEEDS_INDEX="$TMPDIR_IDX/needs_index"
 
-indexed_count=0
 skipped_count=0
 
 while IFS= read -r file; do

package/scripts/prune.sh

@@ -15,6 +15,33 @@ LIB_DIR="$SCRIPTS_DIR/../lib"
 
 eagle_ensure_db
 
+# ─── Help ────────────────────────────────────────────────
+
+show_help() {
+    echo -e "  ${BOLD}eagle-mem prune${RESET} — Clean up old data"
+    echo ""
+    echo -e "  ${BOLD}Usage:${RESET}"
+    echo -e "    eagle-mem prune                     ${DIM}# prune observations > 90 days${RESET}"
+    echo -e "    eagle-mem prune ${CYAN}--days 30${RESET}           ${DIM}# prune observations > 30 days${RESET}"
+    echo -e "    eagle-mem prune ${CYAN}--dry-run${RESET}           ${DIM}# show what would be pruned${RESET}"
+    echo ""
+    echo -e "  ${BOLD}What gets pruned:${RESET}"
+    echo -e "    ${DOT} Observations older than --days (default: 90)"
+    echo -e "    ${DOT} Code chunks for files that no longer exist"
+    echo ""
+    echo -e "  ${BOLD}What is preserved:${RESET}"
+    echo -e "    ${DOT} All sessions and summaries (your session history)"
+    echo -e "    ${DOT} All tasks"
+    echo -e "    ${DOT} Project overviews"
+    echo ""
+    echo -e "  ${BOLD}Options:${RESET}"
+    echo -e "    ${CYAN}-d, --days${RESET} <N>        Age threshold (default: 90)"
+    echo -e "    ${CYAN}-p, --project${RESET} <name>  Only prune for this project"
+    echo -e "    ${CYAN}-n, --dry-run${RESET}         Show counts without deleting"
+    echo ""
+    exit 0
+}
+
 # ─── Parse arguments ──────────────────────────────────────
 
 days=90
@@ -26,30 +53,7 @@ while [ $# -gt 0 ]; do
         --days|-d)      days="$2"; shift 2 ;;
         --project|-p)   project="$2"; shift 2 ;;
         --dry-run|-n)   dry_run=true; shift ;;
-        --help|-h)
-            echo -e "  ${BOLD}eagle-mem prune${RESET} — Clean up old data"
-            echo ""
-            echo -e "  ${BOLD}Usage:${RESET}"
-            echo -e "    eagle-mem prune                     ${DIM}# prune observations > 90 days${RESET}"
-            echo -e "    eagle-mem prune ${CYAN}--days 30${RESET}           ${DIM}# prune observations > 30 days${RESET}"
-            echo -e "    eagle-mem prune ${CYAN}--dry-run${RESET}           ${DIM}# show what would be pruned${RESET}"
-            echo ""
-            echo -e "  ${BOLD}What gets pruned:${RESET}"
-            echo -e "    ${DOT} Observations older than --days (default: 90)"
-            echo -e "    ${DOT} Code chunks for files that no longer exist"
-            echo ""
-            echo -e "  ${BOLD}What is preserved:${RESET}"
-            echo -e "    ${DOT} All sessions and summaries (your session history)"
-            echo -e "    ${DOT} All tasks"
-            echo -e "    ${DOT} Project overviews"
-            echo ""
-            echo -e "  ${BOLD}Options:${RESET}"
-            echo -e "    ${CYAN}-d, --days${RESET} <N>        Age threshold (default: 90)"
-            echo -e "    ${CYAN}-p, --project${RESET} <name>  Only prune for this project"
-            echo -e "    ${CYAN}-n, --dry-run${RESET}         Show counts without deleting"
-            echo ""
-            exit 0
-            ;;
+        --help|-h)  show_help ;;
         *)
             eagle_err "Unknown option: $1"
             exit 1
@@ -109,7 +113,6 @@ if [ -n "$projects" ]; then
 
         if [ -n "$proj_cwd" ] && [ -d "$proj_cwd" ]; then
             if [ "$dry_run" = true ]; then
-                orphan_count=$(eagle_db "SELECT COUNT(DISTINCT file_path) FROM code_chunks WHERE project = '$(eagle_sql_escape "$proj")';")
                 # Count files that no longer exist
                 orphans=0
                 paths=$(eagle_db "SELECT DISTINCT file_path FROM code_chunks WHERE project = '$(eagle_sql_escape "$proj")';")

package/scripts/search.sh

@@ -14,6 +14,27 @@ LIB_DIR="$SCRIPTS_DIR/../lib"
 
 eagle_ensure_db
 
+# ─── Help ────────────────────────────────────────────────
+
+show_help() {
+    echo -e "  ${BOLD}eagle-mem search${RESET} — Search persistent memory"
+    echo ""
+    echo -e "  ${BOLD}Usage:${RESET}"
+    echo -e "    eagle-mem search ${CYAN}<query>${RESET}                   ${DIM}# keyword search${RESET}"
+    echo -e "    eagle-mem search ${CYAN}--timeline${RESET}               ${DIM}# recent sessions${RESET}"
+    echo -e "    eagle-mem search ${CYAN}--session <id>${RESET}            ${DIM}# session details${RESET}"
+    echo -e "    eagle-mem search ${CYAN}--files${RESET}                  ${DIM}# frequently modified files${RESET}"
+    echo -e "    eagle-mem search ${CYAN}--stats${RESET}                  ${DIM}# project statistics${RESET}"
+    echo ""
+    echo -e "  ${BOLD}Options:${RESET}"
+    echo -e "    ${CYAN}-p, --project${RESET} <name>    Project name (default: current dir)"
+    echo -e "    ${CYAN}-n, --limit${RESET} <N>         Max results (default: 10)"
+    echo -e "    ${CYAN}-a, --all${RESET}               Search across all projects"
+    echo -e "    ${CYAN}-j, --json${RESET}              Output as JSON"
+    echo ""
+    exit 0
+}
+
 # ─── Parse arguments ──────────────────────────────────────
 
 mode="keyword"
@@ -34,24 +55,7 @@ while [ $# -gt 0 ]; do
         --limit|-n)          limit="$2"; shift 2 ;;
         --all|-a)            cross_project=true; shift ;;
         --json|-j)           json_output=true; shift ;;
-        --help|-h)
-            echo -e "  ${BOLD}eagle-mem search${RESET} — Search persistent memory"
-            echo ""
-            echo -e "  ${BOLD}Usage:${RESET}"
-            echo -e "    eagle-mem search ${CYAN}<query>${RESET}                   ${DIM}# keyword search${RESET}"
-            echo -e "    eagle-mem search ${CYAN}--timeline${RESET}               ${DIM}# recent sessions${RESET}"
-            echo -e "    eagle-mem search ${CYAN}--session <id>${RESET}            ${DIM}# session details${RESET}"
-            echo -e "    eagle-mem search ${CYAN}--files${RESET}                  ${DIM}# frequently modified files${RESET}"
-            echo -e "    eagle-mem search ${CYAN}--stats${RESET}                  ${DIM}# project statistics${RESET}"
-            echo ""
-            echo -e "  ${BOLD}Options:${RESET}"
-            echo -e "    ${CYAN}-p, --project${RESET} <name>    Project name (default: current dir)"
-            echo -e "    ${CYAN}-n, --limit${RESET} <N>         Max results (default: 10)"
-            echo -e "    ${CYAN}-a, --all${RESET}               Search across all projects"
-            echo -e "    ${CYAN}-j, --json${RESET}              Output as JSON"
-            echo ""
-            exit 0
-            ;;
+        --help|-h)  show_help ;;
         -*)
             eagle_err "Unknown option: $1"
             exit 1
@@ -249,7 +253,7 @@ search_stats() {
     sessions=$(eagle_db "SELECT COUNT(*) FROM sessions WHERE project = '$p';")
     summaries=$(eagle_db "SELECT COUNT(*) FROM summaries WHERE project = '$p';")
     observations=$(eagle_db "SELECT COUNT(*) FROM observations o JOIN sessions s ON s.id = o.session_id WHERE s.project = '$p';")
-    tasks=$(eagle_db "SELECT COUNT(*) FROM tasks WHERE project = '$p';")
+    tasks=$(eagle_db "SELECT COUNT(*) FROM claude_tasks WHERE project = '$p';")
     local chunks
     chunks=$(eagle_db "SELECT COUNT(*) FROM code_chunks WHERE project = '$p';")
 

package/scripts/tasks.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 # ═══════════════════════════════════════════════════════════
-# Eagle Mem — Tasks
-# CLI wrapper for task management (replaces raw SQL in skills)
+# Eagle Mem — Tasks (read-only viewer of Claude Code tasks)
+# Claude Code manages task state via TaskCreate/TaskUpdate;
+# Eagle Mem mirrors it and displays it here.
 # ═══════════════════════════════════════════════════════════
 set -euo pipefail
 
@@ -22,28 +23,26 @@ shift 2>/dev/null || true
 project=""
 json_output=false
 
-# Extract global options from remaining args
-args=()
-
 show_help() {
-    echo -e "  ${BOLD}eagle-mem tasks${RESET} — Manage tracked tasks"
+    echo -e "  ${BOLD}eagle-mem tasks${RESET} — View mirrored Claude Code tasks"
     echo ""
     echo -e "  ${BOLD}Usage:${RESET}"
-    echo -e "    eagle-mem tasks                           ${DIM}# list pending tasks${RESET}"
-    echo -e "    eagle-mem tasks ${CYAN}list${RESET}                      ${DIM}# list all tasks${RESET}"
-    echo -e "    eagle-mem tasks ${CYAN}add${RESET} <title> [instructions] ${DIM}# add a task${RESET}"
-    echo -e "    eagle-mem tasks ${CYAN}done${RESET} <id>                 ${DIM}# mark task complete${RESET}"
-    echo -e "    eagle-mem tasks ${CYAN}block${RESET} <id>                ${DIM}# mark task blocked${RESET}"
-    echo -e "    eagle-mem tasks ${CYAN}context${RESET} <id> <snapshot>    ${DIM}# set task context${RESET}"
-    echo -e "    eagle-mem tasks ${CYAN}clear${RESET}                     ${DIM}# remove all done tasks${RESET}"
+    echo -e "    eagle-mem tasks                  ${DIM}# list pending/in-progress tasks${RESET}"
+    echo -e "    eagle-mem tasks ${CYAN}list${RESET}             ${DIM}# list all tasks${RESET}"
+    echo -e "    eagle-mem tasks ${CYAN}completed${RESET}        ${DIM}# list completed tasks${RESET}"
+    echo -e "    eagle-mem tasks ${CYAN}search${RESET} <query>   ${DIM}# search tasks by keyword${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 "  ${DIM}Tasks are managed by Claude Code (TaskCreate/TaskUpdate).${RESET}"
+    echo -e "  ${DIM}Eagle Mem automatically mirrors them for cross-session recall.${RESET}"
+    echo ""
     exit 0
 }
 
+args=()
 while [ $# -gt 0 ]; do
     case "$1" in
         --project|-p)   project="$2"; shift 2 ;;
@@ -63,24 +62,28 @@ tasks_list() {
 
     local where_status=""
     case "$filter" in
-        pending) where_status="AND status IN ('pending', 'active')" ;;
-        done)    where_status="AND status = 'done'" ;;
-        all)     where_status="" ;;
+        pending) where_status="AND status IN ('pending', 'in_progress')" ;;
+        completed) where_status="AND status = 'completed'" ;;
+        all) where_status="" ;;
     esac
 
     if [ "$json_output" = true ]; then
-        eagle_db_json "SELECT id, title, instructions, status, ordinal, context_snapshot, completed_at, created_at
-                       FROM tasks
+        eagle_db_json "SELECT source_task_id, subject, description, status, blocks, blocked_by, updated_at
+                       FROM claude_tasks
                        WHERE project = '$project_sql' $where_status
-                       ORDER BY ordinal ASC, id ASC;"
+                       ORDER BY updated_at DESC
+                       LIMIT 20;"
         return
     fi
 
     local results
-    results=$(eagle_db "SELECT id, title, status, ordinal, instructions
-                        FROM tasks
+    results=$(eagle_db "SELECT source_task_id, subject, status, blocked_by, description
+                        FROM claude_tasks
                         WHERE project = '$project_sql' $where_status
-                        ORDER BY ordinal ASC, id ASC;")
+                        ORDER BY
+                            CASE status WHEN 'in_progress' THEN 0 WHEN 'pending' THEN 1 ELSE 2 END,
+                            updated_at DESC
+                        LIMIT 20;")
 
     if [ -z "$results" ]; then
         eagle_dim "No tasks for project '$project'"
@@ -92,170 +95,74 @@ tasks_list() {
     echo -e "  ${DIM}─────────────────────────────────────${RESET}"
     echo ""
 
-    while IFS='|' read -r tid title status ordinal instructions; do
+    while IFS='|' read -r tid subject status blocked_by desc; do
         [ -z "$tid" ] && continue
         local icon marker
         case "$status" in
-            active)  icon="${CYAN}▶${RESET}"; marker=" ${CYAN}[ACTIVE]${RESET}" ;;
-            pending) icon="${DIM}○${RESET}"; marker="" ;;
-            done)    icon="${GREEN}✓${RESET}"; marker=" ${DIM}[DONE]${RESET}" ;;
-            blocked) icon="${RED}✗${RESET}"; marker=" ${RED}[BLOCKED]${RESET}" ;;
-            *)       icon="$DOT"; marker="" ;;
+            in_progress) icon="${CYAN}>${RESET}"; marker=" ${CYAN}[in_progress]${RESET}" ;;
+            pending)     icon="${DIM}o${RESET}"; marker="" ;;
+            completed)   icon="${GREEN}+${RESET}"; marker=" ${DIM}[completed]${RESET}" ;;
+            deleted)     icon="${RED}x${RESET}"; marker=" ${RED}[deleted]${RESET}" ;;
+            *)           icon="$DOT"; marker="" ;;
         esac
-        echo -e "  ${icon}  ${BOLD}#$tid${RESET} $title$marker"
-        [ -n "$instructions" ] && echo -e "     ${DIM}$instructions${RESET}"
+        if [ "$blocked_by" != "[]" ] && [ -n "$blocked_by" ]; then
+            marker+=" ${DIM}(blocked)${RESET}"
+        fi
+        echo -e "  ${icon}  ${BOLD}$tid${RESET} $subject$marker"
+        [ -n "$desc" ] && echo -e "     ${DIM}$(echo "$desc" | cut -c1-80)${RESET}"
     done <<< "$results"
     echo ""
 }
 
-# ─── Add task ─────────────────────────────────────────────
-
-tasks_add() {
-    local title="${args[0]:-}"
-    local instructions="${args[1]:-}"
-
-    if [ -z "$title" ]; then
-        eagle_err "Usage: eagle-mem tasks add <title> [instructions]"
-        exit 1
-    fi
-
-    local title_sql; title_sql=$(eagle_sql_escape "$title")
-    local instr_sql; instr_sql=$(eagle_sql_escape "$instructions")
-
-    local max_ord
-    max_ord=$(eagle_db "SELECT COALESCE(MAX(ordinal), 0) FROM tasks WHERE project = '$project_sql';")
-    local next_ord=$((max_ord + 1))
-
-    local new_id
-    new_id=$(eagle_db "INSERT INTO tasks (project, title, instructions, ordinal)
-              VALUES ('$project_sql', '$title_sql', '$instr_sql', $next_ord);
-              SELECT last_insert_rowid();")
-
-    if [ "$json_output" = true ]; then
-        jq -nc --arg id "$new_id" --arg title "$title" --argjson ord "$next_ord" \
-            '{id: ($id | tonumber), title: $title, ordinal: $ord}'
-        return
-    fi
-
-    eagle_ok "Task #$new_id added: $title"
-}
-
-# ─── Done ─────────────────────────────────────────────────
-
-tasks_done() {
-    local task_id="${args[0]:-}"
+# ─── Search tasks ─────────────────────────────────────────
 
-    if [ -z "$task_id" ]; then
-        eagle_err "Usage: eagle-mem tasks done <id>"
+tasks_search() {
+    local query="${args[0]:-}"
+    if [ -z "$query" ]; then
+        eagle_err "Usage: eagle-mem tasks search <query>"
         exit 1
     fi
 
-    if ! [[ "$task_id" =~ ^[0-9]+$ ]]; then
-        eagle_err "Task ID must be a number, got: $task_id"
-        exit 1
-    fi
-
-    local changed
-    changed=$(eagle_db "UPDATE tasks SET status = 'done', completed_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
-              WHERE id = $task_id AND project = '$project_sql';
-              SELECT changes();")
-
-    if [ "${changed:-0}" -eq 0 ]; then
-        eagle_err "Task #$task_id not found in project '$project'"
-        exit 1
-    fi
-
-    local title
-    title=$(eagle_db "SELECT title FROM tasks WHERE id = $task_id AND project = '$project_sql';")
-
     if [ "$json_output" = true ]; then
-        jq -nc --arg id "$task_id" '{id: ($id | tonumber), status: "done"}'
+        local query_sql; query_sql=$(eagle_fts_sanitize "$query")
+        query_sql=$(eagle_sql_escape "$query_sql")
+        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
+                       WHERE claude_tasks_fts MATCH '$query_sql'
+                       AND t.project = '$project_sql'
+                       ORDER BY rank
+                       LIMIT 10;"
         return
     fi
 
-    eagle_ok "Task #$task_id done: $title"
-}
-
-# ─── Block ────────────────────────────────────────────────
-
-tasks_block() {
-    local task_id="${args[0]:-}"
-
-    if [ -z "$task_id" ]; then
-        eagle_err "Usage: eagle-mem tasks block <id>"
-        exit 1
-    fi
-
-    if ! [[ "$task_id" =~ ^[0-9]+$ ]]; then
-        eagle_err "Task ID must be a number, got: $task_id"
-        exit 1
-    fi
-
-    local changed
-    changed=$(eagle_db "UPDATE tasks SET status = 'blocked' WHERE id = $task_id AND project = '$project_sql';
-              SELECT changes();")
-
-    if [ "${changed:-0}" -eq 0 ]; then
-        eagle_err "Task #$task_id not found in project '$project'"
-        exit 1
-    fi
-
-    if [ "$json_output" = true ]; then
-        jq -nc --arg id "$task_id" '{id: ($id | tonumber), status: "blocked"}'
-        return
-    fi
-
-    eagle_ok "Task #$task_id blocked"
-}
-
-# ─── Context snapshot ─────────────────────────────────────
-
-tasks_context() {
-    local task_id="${args[0]:-}"
-    local snapshot="${args[1]:-}"
-
-    if [ -z "$task_id" ] || [ -z "$snapshot" ]; then
-        eagle_err "Usage: eagle-mem tasks context <id> <snapshot>"
-        exit 1
-    fi
-
-    if ! [[ "$task_id" =~ ^[0-9]+$ ]]; then
-        eagle_err "Task ID must be a number, got: $task_id"
-        exit 1
-    fi
-
-    local snap_sql; snap_sql=$(eagle_sql_escape "$snapshot")
-    local changed
-    changed=$(eagle_db "UPDATE tasks SET context_snapshot = '$snap_sql' WHERE id = $task_id AND project = '$project_sql';
-              SELECT changes();")
-
-    if [ "${changed:-0}" -eq 0 ]; then
-        eagle_err "Task #$task_id not found in project '$project'"
-        exit 1
-    fi
+    local results
+    local query_sql; query_sql=$(eagle_fts_sanitize "$query")
+    query_sql=$(eagle_sql_escape "$query_sql")
+    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
+                        WHERE claude_tasks_fts MATCH '$query_sql'
+                        AND t.project = '$project_sql'
+                        ORDER BY rank
+                        LIMIT 10;")
 
-    if [ "$json_output" = true ]; then
-        jq -nc --arg id "$task_id" '{id: ($id | tonumber), context_snapshot: true}'
+    if [ -z "$results" ]; then
+        eagle_dim "No tasks matching '$query'"
         return
     fi
 
-    eagle_ok "Context saved for task #$task_id"
-}
-
-# ─── Clear done tasks ────────────────────────────────────
-
-tasks_clear() {
-    local count
-    count=$(eagle_db "SELECT COUNT(*) FROM tasks WHERE project = '$project_sql' AND status = 'done';")
-
-    eagle_db "DELETE FROM tasks WHERE project = '$project_sql' AND status = 'done';"
-
-    if [ "$json_output" = true ]; then
-        jq -nc --argjson cleared "${count:-0}" '{cleared: $cleared}'
-        return
-    fi
+    echo ""
+    echo -e "  ${BOLD}Task search:${RESET} $query"
+    echo -e "  ${DIM}─────────────────────────────────────${RESET}"
+    echo ""
 
-    eagle_ok "Cleared ${count:-0} completed tasks"
+    while IFS='|' read -r tid subject status desc; do
+        [ -z "$tid" ] && continue
+        echo -e "  ${BOLD}$tid${RESET} [$status] $subject"
+        [ -n "$desc" ] && echo -e "     ${DIM}$(echo "$desc" | cut -c1-80)${RESET}"
+    done <<< "$results"
+    echo ""
 }
 
 # ─── Dispatch ─────────────────────────────────────────────
@@ -263,12 +170,9 @@ tasks_clear() {
 case "$action" in
     list)       tasks_list "all" ;;
     pending)    tasks_list "pending" ;;
-    add)        tasks_add ;;
-    done)       tasks_done ;;
-    block)      tasks_block ;;
-    context)    tasks_context ;;
-    clear)      tasks_clear ;;
-    --help|-h) show_help ;;
+    completed)  tasks_list "completed" ;;
+    search)     tasks_search ;;
+    --help|-h)  show_help ;;
     *)
         eagle_err "Unknown action: $action"
         eagle_dim "  Run 'eagle-mem tasks --help' for options"

package/scripts/update.sh

@@ -117,5 +117,5 @@ fi
 
 # ─── Summary ───────────────────────────────────────────────
 
-version=$(node -e "console.log(require('$PACKAGE_DIR/package.json').version)" 2>/dev/null || echo "unknown")
+version=$(jq -r .version "$PACKAGE_DIR/package.json" 2>/dev/null || echo "unknown")
 eagle_footer "Eagle Mem updated to v${version}."

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

@@ -1,100 +1,92 @@
 ---
 name: eagle-mem-tasks
 description: >
-  TaskAware Compact Loop — break complex work into database-tracked subtasks with compaction
-  between each. Use when: 'eagle tasks', 'break this into tasks', 'create task plan',
-  'task loop', 'compact loop', 'eagle mem tasks'. Uses the eagle-mem CLI — never run raw sqlite3 queries.
+  TaskAware Compact Loop — break complex work into Claude Code tasks with dependencies,
+  compact between each. Use when: 'eagle tasks', 'break this into tasks', 'create task plan',
+  'task loop', 'compact loop', 'eagle mem tasks'. Uses Claude Code's native TaskCreate/TaskUpdate.
 ---
 
 # Eagle Mem — TaskAware Compact Loop
 
-Break complex work into subtasks stored in Eagle Mem's database. Execute one task at a time, compact between each, and let Eagle Mem re-inject context for the next task.
+Break complex work into subtasks using Claude Code's native task system. Execute one task at a time, compact between each, and let Eagle Mem re-inject task state for the next task.
 
 ## How it works
 
 1. **Plan**: Break the user's request into ordered subtasks
-2. **Store**: Add each subtask via the CLI
-3. **Execute**: Work on the current task (marked `[ACTIVE]`)
-4. **Compact**: When done, tell the user to run `/compact`
-5. **Resume**: After compact, SessionStart re-injects memory + loads the next task
-6. **Repeat**: Until all tasks are done
+2. **Create**: Add each subtask via `TaskCreate` with dependencies via `addBlockedBy`
+3. **Execute**: Work on the current task (mark `in_progress` with `TaskUpdate`)
+4. **Complete**: Mark done with `TaskUpdate(completed)`, emit `<eagle-summary>`
+5. **Compact**: Tell the user to run `/compact`
+6. **Resume**: After compact, SessionStart re-injects memory + loads task state from Eagle Mem's mirror
+7. **Repeat**: Until all tasks are done
 
-## Commands
+## Creating tasks
 
-### List tasks
+Use Claude Code's `TaskCreate` tool. Each task gets `pending` status automatically.
 
-```bash
-eagle-mem tasks
-eagle-mem tasks list
-```
-
-### Add tasks
-
-When the user invokes `/eagle-mem-tasks` or asks to break work into tasks:
-
-1. Analyze the request and break it into 3-8 focused subtasks
-2. Each task should be completable in one context window
-3. Add tasks using the CLI:
+For tasks that depend on earlier work, use `addBlockedBy` in `TaskUpdate`:
 
-```bash
-eagle-mem tasks add "Set up project structure" "Install deps, create folders, init config"
-eagle-mem tasks add "Implement auth middleware" "JWT validation, role checks, error responses"
-eagle-mem tasks add "Build CRUD endpoints" "Users and posts REST API with validation"
 ```
+TaskCreate({ subject: "Set up project structure", description: "Install deps, create folders, init config" })
+TaskCreate({ subject: "Implement auth middleware", description: "JWT validation, role checks, error responses" })
+TaskCreate({ subject: "Build CRUD endpoints", description: "Users and posts REST API with validation" })
 
-4. Show the task plan to the user for confirmation
-5. After confirmation, start working on task #1
-
-### Complete a task
-
-```bash
-eagle-mem tasks done <id>
+// Then set dependencies:
+TaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })
 ```
 
-After marking done:
-1. Emit your `<eagle-summary>` block
-2. Tell the user: **"Task #N complete. Run `/compact` to save progress and load the next task."**
+## Working on a task
 
-### Block a task
+1. Call `TaskUpdate({ taskId: "N", status: "in_progress" })` before starting work
+2. Do the work
+3. Call `TaskUpdate({ taskId: "N", status: "completed" })` when done
+4. Emit your `<eagle-summary>` block
+5. Tell the user: **"Task complete. Run `/compact` to save progress and load the next task."**
 
-```bash
-eagle-mem tasks block <id>
-```
-
-### Set context snapshot
+## Viewing tasks
 
-For tasks that depend on decisions from earlier tasks:
+Use `TaskList` to see all tasks, or the CLI for cross-session history:
 
 ```bash
-eagle-mem tasks context <id> "Using JWT with RS256, sessions stored in Redis"
+eagle-mem tasks              # pending/in-progress (from mirror)
+eagle-mem tasks list         # all tasks
+eagle-mem tasks search <q>   # FTS5 search across task history
 ```
 
-### Clear completed tasks
+## Cross-session context
 
-```bash
-eagle-mem tasks clear
-```
+When a task depends on decisions made in earlier tasks, put that context in the task's `description` field — it persists across compactions via Eagle Mem's mirror.
 
-## Options
+For example, if task 1 decides to use JWT with RS256:
 
-| Flag | Description |
-|------|-------------|
-| `-p, --project <name>` | Target a specific project (default: current directory) |
-| `-j, --json` | Output as JSON |
+```
+TaskUpdate({ taskId: "2", description: "Implement auth middleware. Decision from task 1: using JWT with RS256, sessions stored in Redis." })
+```
 
 ## Task design guidelines
 
-- Each task should be **self-contained** — completable without mid-execution context from a previous task
-- Include instructions with enough detail that a fresh context window can pick it up
-- Use context snapshots for tasks that depend on decisions from earlier tasks
-- Order tasks so that foundational work comes first (schema before API, API before UI)
+- Each task should be **self-contained** — completable in one context window
+- Include enough detail in `description` that a fresh context window can pick it up
+- Use `addBlockedBy` for tasks that depend on earlier tasks
+- Order tasks so foundational work comes first (schema before API, API before UI)
+- Keep tasks focused: 3-8 tasks per plan
 
 ## The compact cycle
 
 ```
-User request → Plan tasks → Execute task 1 → /compact
-→ Eagle Mem saves summary → Context cleared → Memory re-injected
-→ Task 2 loaded as [ACTIVE] → Execute task 2 → /compact
-→ ... repeat until all tasks done ...
-→ Final summary: "All N tasks complete."
+User request -> Plan tasks (TaskCreate) -> Execute task 1 (TaskUpdate: in_progress)
+-> Complete task 1 (TaskUpdate: completed) -> /compact
+-> Eagle Mem saves summary -> Context cleared -> Task state re-injected
+-> Execute task 2 -> /compact
+-> ... repeat until all tasks done ...
+-> Final summary: "All N tasks complete."
 ```
+
+## Status reference
+
+| Status | Meaning |
+|---|---|
+| `pending` | Not started yet |
+| `in_progress` | Currently being worked on |
+| `completed` | Done |
+| `deleted` | Removed |