eagle-mem 1.6.3 → 2.0.0

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

@@ -1,83 +1,97 @@
 ---
 name: eagle-mem-overview
 description: >
-  Generate or update a project overview for Eagle Mem. Use when: 'eagle overview',
-  'project overview', 'summarize this project', 'eagle mem overview', 'what is this project',
-  'update overview'. Uses the eagle-mem CLI — never run raw sqlite3 queries.
+  Build or update a structured project overview for Eagle Mem. Use when: 'eagle overview',
+  'project overview', 'summarize this project', 'what is this project', 'update overview',
+  or when SessionStart says no overview exists. Produces a multi-paragraph briefing.
 ---
 
 # Eagle Mem — Project Overview
 
-Generate a concise project overview that Eagle Mem injects at the start of every session. This gives fresh context windows an instant understanding of what the project is.
+## Purpose
 
-## How it works
+**For the user:** Every new Claude Code session starts cold. The overview eliminates the "explain what this project is" tax — Claude already knows what it's working on, how the project is structured, and what's been happening.
 
-1. Gather context about the project (recent sessions, file activity)
-2. Synthesize into a concise overview (2-4 sentences)
-3. Save via the CLI — one overview per project, updated in place
+**For you (Claude Code):** The overview is your orientation document. It's injected at SessionStart before the user says anything. A good overview lets you give informed answers from message one. A shallow one ("42 files, Node.js") gives you nothing — you'll spend the first 3 exchanges just figuring out what the project does.
 
-The overview is automatically injected by the SessionStart hook.
+## Judgment
 
-## Commands
+**Build an overview when:**
+- SessionStart says "No overview exists" — build on the user's first prompt
+- The current overview reads like scan metadata (file counts, directory listings) — upgrade it
+- The user asks: "update overview", "summarize this project", "what is this project"
+- The project has changed significantly since the last overview (new major feature, architecture shift)
 
-### View current overview
+**Don't rebuild when:**
+- The overview is already rich and current — just use it
+- The user needs help with a specific task — do the task first, update overview after if needed
 
-```bash
-eagle-mem overview
-```
+## Steps
 
-### Auto-generate from code analysis
+### 1. Read the project (skip files that don't exist)
 
-```bash
-eagle-mem scan .
-```
+**Identity:** README.md, package.json / go.mod / pyproject.toml / Cargo.toml
+**Architecture:** Main entry point (bin/*, src/index.*, main.*, app.*), key config (tsconfig.json, Dockerfile, etc.)
+**Activity:** `git log --oneline -20` for recent direction
+**Structure:** `ls` the top-level directories to understand the layout
+
+Read these files yourself — don't run `eagle-mem scan`. Scan produces structural metadata (file counts, language breakdown). You need to understand intent, not count files.
+
+### 2. Synthesize a structured briefing
+
+Write 4-6 paragraphs covering these layers:
 
-This scans the project structure (files, languages, frameworks, entry points, tests) and saves an overview automatically.
+**What and why** — What does this project do? Who is it for? What problem does it solve? Lead with the purpose, not the tech stack.
 
-### Set overview manually
+**How it's built** — Architecture, key abstractions, data flow. What are the main modules/packages and how do they connect? What tech choices matter (framework, database, deployment target)?
 
-When you want to write a custom overview based on session history:
+**Where to start** — Entry points, key files a new contributor would need to read first. The files that, if you understand them, you understand the project.
+
+**Current state** — What version is it at? What's the recent direction from git log? Is it actively developed, stable, or in a transition? What was the most recent significant change?
+
+### 3. Save and verify
 
-1. First, gather recent context:
 ```bash
-eagle-mem search --timeline --limit 10
-eagle-mem search --files
+eagle-mem overview set "<your structured overview>"
 ```
 
-2. Synthesize the data into a concise overview covering:
-   - **What** the project is (one sentence)
-   - **Current state** — what's been worked on recently
-   - **Key patterns** — tech stack, architecture decisions
-
-3. Save it:
+Then verify it actually saved:
 ```bash
-eagle-mem overview set "eagle-mem: Node.js CLI tool providing persistent memory for Claude Code via SQLite + FTS5. Currently at v1.0.3 with 5 hooks, 3 skills, and CLI subcommands for search/tasks/overview."
+eagle-mem overview
 ```
 
-Keep it under 500 characters — this gets injected into every session start.
+If the output is empty or doesn't match what you wrote, the save failed. Retry once. If it fails again, tell the user.
 
-### List all project overviews
+### 4. Fallback for empty repos
 
+If no readable source files exist (fresh repo, no README), run a structural scan as a starting point:
 ```bash
-eagle-mem overview list
+eagle-mem scan .
 ```
+Then tell the user: "I've generated a structural overview from scan. Once you add a README or source code, re-run `/eagle-mem-overview` for a richer briefing."
 
-### Delete an overview
+## What makes a good overview
 
-```bash
-eagle-mem overview delete
-```
+A good overview lets a fresh Claude Code context window give useful answers without reading any files first.
 
-## Options
+**Good:**
+> eagle-mem is a persistent memory system for Claude Code that solves the context-loss problem across sessions. It hooks into Claude Code's lifecycle (SessionStart, Stop, PostToolUse, SessionEnd, UserPromptSubmit) to automatically capture session summaries, observations, and code context into a single SQLite database with FTS5 full-text search.
+>
+> The architecture is pure bash scripts and sqlite3 — no daemon, no vector DB, no MCP server. Hooks in hooks/ fire during Claude Code events and call into lib/ (common.sh, db.sh) for database operations. The db/ directory holds the schema and numbered migration files. CLI commands in scripts/ expose search, overview management, code indexing, and database maintenance.
+>
+> Key entry point is bin/eagle-mem, which dispatches to scripts/. Skills in skills/ are symlinked into ~/.claude/skills/ and teach Claude Code how to use each capability. The database lives at ~/.eagle-mem/memory.db.
+>
+> Currently at v2.0.0. Recent work focused on memory mirroring (Claude Code's auto-memories, plans, and tasks into FTS5), task-aware compact loops, and skill quality improvements.
 
-| Flag | Description |
-|------|-------------|
-| `-p, --project <name>` | Target a specific project (default: current directory) |
-| `-j, --json` | Output as JSON |
+**Bad:**
+> eagle-mem: Node.js project (42 files, ~5k lines). Structure: bin/ (1), db/ (10), hooks/ (5), lib/ (3), scripts/ (13), skills/ (7). Entry: bin/eagle-mem. No tests detected.
 
-## Guidelines
+## Reference
 
-- Update the overview when the project direction changes significantly
-- Keep it factual — what IS, not what SHOULD BE
-- Don't include task lists or TODOs — those belong in the tasks table
-- The overview supplements (doesn't replace) recent session summaries
+```bash
+eagle-mem overview              # view current overview
+eagle-mem overview set "..."    # save new overview
+eagle-mem overview list         # all projects with overviews
+eagle-mem overview delete       # remove current project's overview
+eagle-mem scan .                # structural scan (fallback only)
+```

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

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

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

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

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

@@ -1,78 +1,118 @@
 ---
 name: eagle-mem-search
 description: >
-  Search Eagle Mem's persistent memory database. Use when: 'eagle search', 'search memory',
-  'what did I do', 'eagle mem search', 'find in memory', 'past sessions', 'what happened with',
-  'search my history'. Uses the eagle-mem CLI — never run raw sqlite3 queries.
+  Search Eagle Mem's persistent memory. Use when: 'eagle search', 'search memory',
+  'what did I do', 'find in memory', 'past sessions', 'what happened with',
+  'search my history', 'what do you remember about', 'show recent sessions',
+  'what files changed', 'memory stats'. Uses the eagle-mem CLI.
 ---
 
-# Eagle Mem — Memory Search
+# Eagle Mem — Search
 
-Search the Eagle Mem database for past session summaries, observations, and task history using the `eagle-mem` CLI.
+## Purpose
 
-## Search commands
+**For the user:** Never repeat yourself. Every decision, every debug session, every architectural choice is searchable across months and projects. "What did we do with auth?" gets a real answer, not a guess.
 
-### Keyword search (default)
+**For you (Claude Code):** Access to the past. When the user references prior work, you can find it instead of fabricating it. Search gives you summaries, observations, file history, and cross-project patterns -- all FTS5-indexed.
 
-Search past sessions by keyword. Returns matching summaries ranked by relevance.
+## Judgment
 
-```bash
-eagle-mem search "auth middleware"
-```
+**Search when:**
+- The user asks about past work ("what did we do with X?", "when did we change Y?")
+- You need context before making a decision (was this pattern tried before? what broke last time?)
+- The user references something from a prior session and you have no context
+- You want to understand the trajectory of a project (timeline mode)
 
-Cross-project search:
-```bash
-eagle-mem search "deploy issue" --all
-```
+**Don't search when:**
+- The answer is in the current codebase -- read the code instead
+- The user is asking you to do something, not recall something
+- You already have the answer from SessionStart context injection
 
-### Timeline (chronological)
+**Decision rule:** If the question is about *what happened* or *why we decided*, search memory. If the question is about *what the code does now*, read the code.
 
-Show recent sessions for the current project in time order.
+## Steps
 
+### 1. Start specific, then broaden (3-layer recall)
+
+**Layer 1 -- Keyword search.** Start with the most specific terms.
 ```bash
-eagle-mem search --timeline
-eagle-mem search --timeline --limit 20
+eagle-mem search "webhook retry logic"
 ```
+This searches summaries (session request, completed, learned fields). Look at session IDs in results -- you'll need them for Layer 2.
 
-### Session details
-
-View all tool observations (files read/written, commands run) for a specific session.
-
+**Layer 2 -- Session drill-down.** When a summary looks relevant, expand it to see every tool call in that session.
 ```bash
-eagle-mem search --session <session_id>
+eagle-mem search --session <id>
 ```
+This shows the full observation trail: what files were read, written, what bash commands ran. This is where you find the actual sequence of work.
 
-### Frequently modified files
-
-Show which files are touched most often in this project.
-
+**Layer 3 -- Correlate across sessions.** If you see a pattern in one session, broaden to find related work.
 ```bash
-eagle-mem search --files
+eagle-mem search "webhook" --all        # cross-project
+eagle-mem search "retry" --limit 20     # more results
+eagle-mem search --timeline             # recent work chronology
 ```
 
-### Project stats
+### 2. Use FTS5 syntax effectively
 
-Get counts of sessions, summaries, observations, tasks, and code chunks.
+The query goes through FTS5 with light sanitization. What works:
+- `word1 word2` -- implicit AND (both must appear)
+- `word1 OR word2` -- either term matches
+- Single words -- broadest match
 
-```bash
-eagle-mem search --stats
-```
+What does NOT work (stripped by sanitizer):
+- `"exact phrase"` -- quotes are removed, words match independently
+- `prefix*` -- asterisks are stripped
+- Parenthesized groups -- stripped
 
-## Options
+**Practical tip:** If `webhook retry` returns nothing, try `webhook OR retry` to loosen the match. If results are noisy, add more specific terms to narrow.
 
-| Flag | Description |
-|------|-------------|
-| `-p, --project <name>` | Target a specific project (default: current directory) |
-| `-n, --limit <N>` | Max results (default: 10) |
-| `-a, --all` | Search across all projects |
-| `-j, --json` | Output as JSON (for programmatic use) |
+### 3. Use the right mode for the question
 
-## Three-layer pattern
+| Question type | Command | What you get |
+|---|---|---|
+| "What did we do with X?" | `search "X"` | Matching summaries with request/completed/learned |
+| "What happened recently?" | `search --timeline` | Last N sessions in date order |
+| "Show me that session" | `search --session <id>` | Every observation in the session |
+| "What are the hot files?" | `search --files` | Files ranked by modification frequency |
+| "How much is stored?" | `search --stats` | Session, summary, observation, chunk counts |
 
-Start with **keyword search** — it's fast and usually sufficient. If the user needs chronological context, use **--timeline**. If they need exact file-level detail, use **--session** with a specific session ID from a previous search result.
+### 4. Synthesize — don't dump
 
-## Usage tips
+Raw search output is not an answer. After searching:
+- **Summarize patterns.** "You worked on auth across 4 sessions over the past 2 weeks. The main change was moving from JWT to session cookies, driven by mobile client limitations."
+- **Cite session IDs.** "Session #42 is where the retry logic was added" -- lets the user drill down if they want.
+- **Flag gaps.** If the topic predates Eagle Mem's install or the results are thin, say so. Don't fill gaps with guesses.
 
-- Keyword search supports FTS5 syntax: `word1 AND word2`, `"exact phrase"`, `word1 OR word2`
-- The `--json` flag is useful when you need to parse results programmatically
-- Project name defaults to the basename of the current working directory
+### 5. Cross-project search
+
+When the user works on multiple projects, patterns may span them.
+```bash
+eagle-mem search "rate limiting" --all
+```
+This drops the project filter and searches everything. Useful for: "Have I implemented rate limiting before?", "What projects used Redis?", finding reusable patterns.
+
+## What makes a good search response
+
+**Good:**
+> Eagle Mem found 3 sessions related to webhook retry logic. The pattern evolved across sessions: #31 added basic retries with exponential backoff, #35 fixed a bug where retries weren't respecting the max-attempts config, and #38 added dead-letter queue support after retries exhaust. The key decision (session #35) was to cap retries at 5 with a 30-second max delay -- you noted this was to avoid overwhelming the target service.
+
+**Bad:**
+> Here are the search results:
+> #31 2024-03-01 Request: add webhook retries Completed: added retry logic
+> #35 2024-03-05 Request: fix retry bug Completed: fixed retry config
+> #38 2024-03-10 Request: webhook improvements Completed: added DLQ
+
+## Reference
+
+| Flag | What it does |
+|---|---|
+| `"query"` | FTS5 keyword search across summaries |
+| `--timeline` `-t` | Recent sessions in chronological order |
+| `--session <id>` `-s` | Full observations for one session |
+| `--files` `-f` | Most frequently modified files |
+| `--stats` | Database counts (sessions, summaries, observations, code chunks) |
+| `--all` `-a` | Cross-project search (drops project filter) |
+| `--limit N` `-n` | Max results (default: 10) |
+| `--project <name>` `-p` | Override project (default: current directory) |
+| `--json` `-j` | Machine-readable JSON output |