eagle-mem 1.6.2 → 2.0.0

package/scripts/help.sh

@@ -13,58 +13,37 @@ version=$(jq -r .version "$PACKAGE_DIR/package.json" 2>/dev/null || echo "unknow
 eagle_banner
 
 echo -e "  ${BOLD}Eagle Mem${RESET} ${DIM}v${version}${RESET}"
-echo -e "  ${DIM}Lightweight persistent memory for Claude Code${RESET}"
-echo ""
-echo -e "  ${BOLD}Usage:${RESET}"
-echo -e "    eagle-mem ${CYAN}<command>${RESET}"
+echo -e "  ${DIM}Persistent memory for Claude Code${RESET}"
 echo ""
 echo -e "  ${BOLD}Commands:${RESET}"
-echo -e "    ${CYAN}search${RESET}      Search past sessions, files, and observations"
-echo -e "    ${CYAN}tasks${RESET}       View mirrored Claude Code tasks"
+echo -e "    ${CYAN}search${RESET}      Search past sessions, memories, and code"
 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"
-echo -e "    ${CYAN}index${RESET}       Index source files for code-level search"
+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}install${RESET}     Set up hooks, database, and skills"
+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}update${RESET}      Re-deploy hooks and run new migrations"
-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 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}# 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}"
-echo -e "    ${DIM}\$${RESET} eagle-mem memories           ${DIM}# List mirrored memories${RESET}"
-echo -e "    ${DIM}\$${RESET} eagle-mem memories sync      ${DIM}# Backfill memories + plans + tasks${RESET}"
-echo -e "    ${DIM}\$${RESET} eagle-mem memories plans     ${DIM}# List captured plans${RESET}"
-echo -e "    ${DIM}\$${RESET} eagle-mem memories tasks     ${DIM}# List captured tasks${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"
-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} 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 Claude Code tasks with dependencies"
-echo -e "    ${CYAN}/eagle-mem-overview${RESET}    Generate a persistent project summary"
+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 ""
+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-scan${RESET}        Scan and analyze a project"
-echo -e "    ${CYAN}/eagle-mem-memories${RESET}    Browse Claude Code memories, plans, tasks"
-echo -e "    ${CYAN}/eagle-mem-prune${RESET}       Clean up old observations and chunks"
-echo ""
-echo -e "  ${DIM}Skills use these CLI commands under the hood — no raw SQL.${RESET}"
+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}https://github.com/eagleisbatman/eagle-mem${RESET}"
 echo ""

package/scripts/overview.sh

@@ -88,7 +88,7 @@ overview_set() {
         exit 1
     fi
 
-    eagle_upsert_overview "$project" "$content"
+    eagle_upsert_overview "$project" "$content" "manual"
 
     if [ "$json_output" = true ]; then
         jq -nc --arg project "$project" '{project: $project, updated: true}'

package/scripts/refresh.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Refresh
+# Full project sync: scan (if needed) + index + memories sync
+# One command to bring everything up to date
+# ═══════════════════════════════════════════════════════════
+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
+
+TARGET_DIR="${1:-.}"
+if [ ! -d "$TARGET_DIR" ]; then
+    eagle_err "Directory not found: $TARGET_DIR"
+    exit 1
+fi
+TARGET_DIR="$(cd "$TARGET_DIR" && pwd)"
+PROJECT=$(eagle_project_from_cwd "$TARGET_DIR")
+
+eagle_header "Refresh"
+eagle_info "Syncing ${BOLD}$PROJECT${RESET} at $TARGET_DIR"
+echo ""
+
+failed=0
+STEP_LOG=$(mktemp)
+trap 'rm -f "$STEP_LOG"' EXIT
+
+run_step() {
+    local label="$1"; shift
+    if "$@" > "$STEP_LOG" 2>&1; then
+        tail -5 "$STEP_LOG"
+        eagle_ok "$label complete"
+    else
+        cat "$STEP_LOG"
+        eagle_warn "$label had issues (non-fatal)"
+        failed=$((failed + 1))
+    fi
+}
+
+# ─── 1. Structural scan (scan.sh guards against overwriting manual overviews) ──
+eagle_info "Step 1/4: Scanning codebase structure..."
+run_step "Scan" bash "$SCRIPTS_DIR/scan.sh" "$TARGET_DIR"
+echo ""
+
+# ─── 2. Code indexing ────────────────────────────────────
+eagle_info "Step 2/4: Indexing source files..."
+run_step "Index" bash "$SCRIPTS_DIR/index.sh" "$TARGET_DIR"
+echo ""
+
+# ─── 3. Memory sync ─────────────────────────────────────
+eagle_info "Step 3/4: Syncing Claude Code memories, plans, and tasks..."
+run_step "Memory sync" bash "$SCRIPTS_DIR/memories.sh" sync
+echo ""
+
+# ─── 4. Stats ────────────────────────────────────────────
+eagle_info "Step 4/4: Verifying..."
+
+project_sql=$(eagle_sql_escape "$PROJECT")
+sessions=$(eagle_db "SELECT COUNT(*) FROM sessions WHERE project = '$project_sql';")
+summaries=$(eagle_db "SELECT COUNT(*) FROM summaries WHERE project = '$project_sql';")
+chunks=$(eagle_db "SELECT COUNT(*) FROM code_chunks WHERE project = '$project_sql';")
+memories=$(eagle_db "SELECT COUNT(*) FROM claude_memories WHERE project = '$project_sql';")
+tasks=$(eagle_db "SELECT COUNT(*) FROM claude_tasks WHERE project = '$project_sql';")
+
+echo ""
+eagle_kv "Sessions:" "${sessions:-0}"
+eagle_kv "Summaries:" "${summaries:-0}"
+eagle_kv "Code chunks:" "${chunks:-0}"
+eagle_kv "Memories:" "${memories:-0}"
+eagle_kv "Tasks:" "${tasks:-0}"
+
+if [ "$failed" -eq 0 ]; then
+    eagle_footer "Refresh complete. Run /eagle-mem-overview inside Claude Code for a rich project briefing."
+else
+    eagle_footer "Refresh complete with $failed warning(s)."
+fi

package/scripts/scan.sh

@@ -15,7 +15,17 @@ LIB_DIR="$SCRIPTS_DIR/../lib"
 
 eagle_ensure_db
 
-TARGET_DIR="${1:-.}"
+# ─── Parse arguments ─────────────────────────────────────
+force=false
+args=()
+for arg in "$@"; do
+    case "$arg" in
+        --force|-f) force=true ;;
+        *) args+=("$arg") ;;
+    esac
+done
+
+TARGET_DIR="${args[0]:-.}"
 TARGET_DIR="$(cd "$TARGET_DIR" && pwd)"
 PROJECT=$(eagle_project_from_cwd "$TARGET_DIR")
 
@@ -23,6 +33,17 @@ eagle_header "Scan"
 eagle_info "Scanning ${BOLD}$PROJECT${RESET} at $TARGET_DIR"
 echo ""
 
+# ─── Guard: skip if manual overview exists ───────────────
+# Scan produces a structural one-liner. If a manual (rich) overview
+# exists, skip unless --force is passed.
+existing_source=$(eagle_get_overview_source "$PROJECT")
+
+if [ "$force" = false ] && [ "$existing_source" = "manual" ]; then
+    eagle_ok "Manual overview exists — skipping scan"
+    eagle_dim "Run 'eagle-mem scan --force' to overwrite"
+    exit 0
+fi
+
 # ─── Collect files ─────────────────────────────────────────
 
 is_git=false
@@ -344,7 +365,7 @@ if [ -n "$configs" ]; then
 fi
 
 # Store in database
-eagle_upsert_overview "$PROJECT" "$overview"
+eagle_upsert_overview "$PROJECT" "$overview" "scan"
 
 eagle_ok "Overview saved for project '$PROJECT'"
 echo ""

package/scripts/update.sh

@@ -77,6 +77,16 @@ fi
 
 if [ -d "$PACKAGE_DIR/skills" ]; then
     mkdir -p "$EAGLE_SKILLS_DIR"
+    # Remove stale symlinks for deleted skills
+    for existing in "$EAGLE_SKILLS_DIR"/eagle-mem-*/; do
+        local_path="${existing%/}"
+        [ ! -L "$local_path" ] && continue
+        skill_name=$(basename "$local_path")
+        if [ ! -d "$PACKAGE_DIR/skills/$skill_name" ]; then
+            rm "$local_path"
+            eagle_ok "Removed stale skill: $skill_name"
+        fi
+    done
     for skill_dir in "$PACKAGE_DIR"/skills/*/; do
         [ ! -d "$skill_dir" ] && continue
         skill_name=$(basename "$skill_dir")

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

@@ -1,49 +1,120 @@
 ---
 name: eagle-mem-index
 description: >
-  Index source files into FTS5-searchable chunks for code-level search. Use when: 'eagle index',
-  'index this project', 'index codebase', 'eagle mem index', 'make code searchable',
-  'update code index'. Uses the eagle-mem CLI.
+  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
 
-Chunk and index source files into Eagle Mem's FTS5 search index. Enables code-level search across sessions.
+## Purpose
 
-## What it does
+**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.
 
-- Walks the project directory for source files
-- Splits each file into chunks (default 80 lines)
-- Stores chunks in the `code_chunks` table with FTS5 indexing
-- Incremental: only re-indexes files modified since the last run (via mtime)
+**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.
 
-## Commands
+## Judgment
 
-### Index current project
+**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.
 
-### Index a specific directory
+### 2. Understand chunk size
 
+Default: 80 lines per chunk. Override with:
 ```bash
-eagle-mem index /path/to/project
+EAGLE_MEM_CHUNK_SIZE=40 eagle-mem index .
 ```
 
-## When to use
+**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).
 
-- After initial project setup to make code searchable
-- After pulling significant changes
-- When `/eagle-mem-search` isn't finding code you know exists
+## What makes a good indexing practice
 
-## How it integrates
+**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.
 
-Once indexed, the UserPromptSubmit hook can surface relevant code chunks when you ask questions. The `/eagle-mem-search` skill also searches indexed code.
+**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.
 
-## Notes
+## Reference
 
-- Respects .gitignore — only indexes tracked/untracked source files
-- Skips binary files and files over 1MB
-- Chunk size is configurable via `EAGLE_MEM_CHUNK_SIZE` env var (default: 80 lines)
-- Re-running is safe — unchanged files are skipped automatically
+| 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-memories/SKILL.md

@@ -2,74 +2,145 @@
 name: eagle-mem-memories
 description: >
   View and sync Claude Code auto-memories, plans, and tasks mirrored in Eagle Mem. Use when:
-  'eagle memories', 'show memories', 'list memories', 'sync memories', 'eagle mem memories',
-  'what does claude remember', 'show plans', 'show tasks'. Uses the eagle-mem CLI.
+  'eagle memories', 'show memories', 'sync memories', 'what does claude remember',
+  'show plans', 'show tasks', 'mirror memories', 'onboard project',
+  'what did past sessions learn'. Uses the eagle-mem CLI.
 ---
 
 # Eagle Mem — Memories
 
-View, search, and sync Claude Code's auto-memories, plans, and tasks that are mirrored into Eagle Mem's SQLite + FTS5 database.
+## Purpose
 
-## Commands
+**For the user:** Claude Code remembers across sessions. Decisions, preferences, project context, and architectural plans survive session boundaries. The user never has to re-explain "we chose Postgres because..." or "don't use semicolons in this project."
 
-### List mirrored memories
+**For you (Claude Code):** Access to what past Claude sessions learned about this project. Memories tell you *why* decisions were made. Plans tell you *what's coming*. Tasks tell you *what's in flight*. Together they're the knowledge bridge that makes you effective from message one.
 
-```bash
-eagle-mem memories
-eagle-mem memories list
-```
+## Judgment
 
-### Search memories
+**Check memories when:**
+- The user references a past decision ("remember when we decided to...", "what's our convention for...")
+- You're about to make an architectural or style choice -- memories may record the user's preference
+- You need project context that isn't in CLAUDE.md or README (relationships between services, deployment quirks, naming conventions)
+- The user asks "what does Claude remember about X?"
 
-```bash
-eagle-mem memories search "auth middleware"
-```
+**Check plans when:**
+- The user asks about upcoming work or roadmap
+- You need to understand a multi-session effort that's in progress
+- The user says "continue where we left off"
+
+**Check tasks when:**
+- The user asks about in-flight work across sessions
+- You need to understand what sub-tasks are pending/completed in a larger effort
+
+**Don't check memories when:**
+- The answer is in the current code -- read the file instead
+- The question is about *what the code does now* (memories record past decisions, code records current state)
+- You already have the context from SessionStart injection
 
-### Show a specific memory
+**Decision rule:** Memories = *why we decided*. Code = *what it does now*. If the question is about rationale, conventions, or preferences, check memories first. If the question is about current behavior, read code first.
 
+## Steps
+
+### 1. Know the three data types
+
+**Memories** -- Claude Code's auto-memory files (`~/.claude/projects/*/memory/*.md`). These contain user preferences, project conventions, and feedback. Each has a name, type (user/feedback/project/reference), and description.
 ```bash
-eagle-mem memories show <name>
+eagle-mem memories list                    # all memories
+eagle-mem memories search "typescript"     # FTS5 search
+eagle-mem memories show <file_path>        # full content
 ```
 
-### List mirrored plans
+**Plans** -- Claude Code's plan files (`~/.claude/plans/*.md`). Multi-step strategies for complex work. Each has a title, optional project tag, and markdown content.
+```bash
+eagle-mem memories plans                   # all plans
+eagle-mem memories plans search "migration"
+eagle-mem memories plans show <file_path>
+```
 
+**Tasks** -- Claude Code's task JSON (`~/.claude/tasks/<session>/*.json`). Individual units of work with status tracking (pending/in_progress/completed).
 ```bash
-eagle-mem memories plans
+eagle-mem memories tasks                   # all tasks
+eagle-mem memories tasks search "refactor"
+eagle-mem memories tasks show <file_path>
 ```
 
-### List mirrored tasks
+### 2. Understand how data flows in
+
+Two paths feed the mirror:
 
+**Real-time (PostToolUse hook).** Every time Claude Code writes or edits a memory file, plan file, or creates/updates a task, the hook intercepts it and mirrors it into Eagle Mem's SQLite with FTS5 indexing. This happens automatically -- no user action needed.
+
+**Backfill (sync command).** For memories, plans, and tasks that existed before Eagle Mem was installed, or that were written outside a Claude Code session:
 ```bash
-eagle-mem memories tasks
+eagle-mem memories sync
 ```
+This scans all three directories, hashes each file, skips unchanged ones, and mirrors anything new or modified. It also backfills project names from Claude Code transcripts. Safe to run repeatedly -- content-hash dedup prevents double-insertion.
 
-### Sync all from Claude Code
+### 3. Search effectively
 
-Backfill all memories, plans, and tasks from Claude Code's filesystem into Eagle Mem:
+The search hits FTS5 indexes across all three types independently. Start with the most likely container:
 
+- User asked about a preference or convention? Search **memories** first.
+- User asked about a multi-step plan? Search **plans** first.
+- User asked about what's been done vs. what's left? Search **tasks** first.
+- Not sure? Search all three -- they're fast:
 ```bash
-eagle-mem memories sync
+eagle-mem memories search "auth"
+eagle-mem memories plans search "auth"
+eagle-mem memories tasks search "auth"
 ```
 
-## Options
+### 4. Scope by project when needed
 
-| Flag | Description |
-|------|-------------|
-| `-p, --project <name>` | Target a specific project (default: current directory) |
-| `-n, --limit <N>` | Max results (default: 20) |
-| `-j, --json` | Output as JSON |
+Unlike `eagle-mem search` (which auto-scopes to the current project), memories commands are **cross-project by default** -- list and search show everything across all projects. This makes sense because memories, plans, and preferences often apply broadly.
 
-## How it works
+To narrow to a specific project:
+```bash
+eagle-mem memories search "testing" -p eagle-mem
+eagle-mem memories plans -p my-api
+```
 
-Eagle Mem automatically mirrors Claude Code writes via the PostToolUse hook:
-- **Memories** from `~/.claude/projects/*/memory/*.md`
-- **Plans** from `~/.claude/plans/*.md`
-- **Tasks** from Claude Code's TaskCreate/TaskUpdate calls
+This asymmetry is intentional but easy to forget. If you're getting too many irrelevant results from other projects, add `-p`.
 
-The `sync` command does a full backfill for anything the hooks missed.
+### 5. Onboard an existing project
 
-## When to use
+When Eagle Mem is installed on a project that already has Claude Code history:
+```bash
+eagle-mem memories sync
+```
+This is the first thing to run. It pulls in all existing memories, plans, and tasks. The output shows counts: "12 synced, 3 unchanged" -- verify the numbers make sense given the project's history.
+
+### 6. Verify the mirror is working
 
-- To check what Claude Code has auto-saved about this project
-- To search across memories from multiple projects
-- After installing Eagle Mem on an existing project (run `sync` to backfill)
+After sync or after expecting the hook to fire:
+```bash
+eagle-mem memories list          # should show recent memories
+eagle-mem search --stats         # check counts are non-zero
+```
+If memories list is empty after sync, check that `~/.claude/projects/` contains memory files for this project. If the hook isn't capturing new writes, check that PostToolUse hook is registered in settings.json.
+
+## What makes a good memory lookup
+
+**Good:**
+> I checked Eagle Mem's memories before choosing an error handling pattern. Memory "project_error-conventions" [project type] records that you prefer Result types over try/catch in this codebase, and that error messages should include the operation name and original error. Following that convention here.
+
+**Bad:**
+> I'll use try/catch for error handling here.
+> *(Didn't check -- missed a recorded preference that would have changed the approach.)*
+
+## Reference
+
+| Command | What it does |
+|---|---|
+| `memories list` | All mirrored memories (name, type, description, date) |
+| `memories search "query"` | FTS5 search across memory content |
+| `memories show <path>` | Full content of one memory |
+| `memories plans` | All captured plans |
+| `memories plans search "query"` | FTS5 search across plan content |
+| `memories plans show <path>` | Full content of one plan |
+| `memories tasks` | All captured tasks |
+| `memories tasks search "query"` | FTS5 search across task content |
+| `memories tasks show <path>` | Full content of one task |
+| `memories sync` | Backfill all memories + plans + tasks from disk |
+| `-p <name>` / `--project` | Filter by project name |
+| `-l N` / `--limit` | Max results (default: 20) |