Recall

/recall — Context Memory Search

Search past Claude Code sessions, notes, and daily entries from the local vault.

Usage

/recall <mode> <query>

Mode routing — pick by what the user actually wants:

Modes

0. Where were we — the session-start "catch me up" (the most common use)

This is how a work session starts: catch me up on where a thread was left. Two flavors:

• On a project (the common case — parallel work tabs): /recall <project> → assemble the resume point from three sources, newest-first:
  1. The newest per-session handoff for the project — glob System/handoffs/**/*.md and pick the most recent whose project: frontmatter matches (this is the deepest current-state snapshot). Handle both handoff shapes (see below).
  2. The latest $PROJECT_DIR/Notes/<repo-name>/PROJECT_LOG.md entry (history/depth — the newest ## YYYY-MM-DD · … heading — uniform H2, per the merged vault-push convention).
  3. The project's section of System/handoffs/RESUME.md if the board exists (the L0 current-state pointer — read it first when present; it's the fastest "where's the thread now"). Lead from the board section / newest handoff (where the thread is now), then the latest PROJECT_LOG entry + open threads + recent project context (qmd query "<project> <topic>" -c projects -c handoffs -c sessions). This is the load-bearing per-project resume.
• Global / operational tab: /recall (no project) → if RESUME.md exists, read its last_touched section first (last thing touched anywhere) + a reference line per other active thread (latest PROJECT_LOG entry); otherwise fall back to the newest handoff across System/handoffs/**/*.md (or that day's _day.md rollup) + the latest PROJECT_LOG entry per recently-touched project.

Non-repo fallback — applies to BOTH flavors (load-bearing for homelab/infra/DevOps work): Every Mode 0 source above lives under $PROJECT_DIR (git rev-parse --show-toplevel). When the cwd isn't a git repo (e.g. ~/Documents/Projects itself) or the in-repo handoff sources are absent, the primary path is empty and recall must NOT degrade to the raw transcript.

Central-vault first (when $VAULT_DIR is set — the default on this machine): read $VAULT_DIR/System/handoffs/RESUME.md (the board — surface the <project> section, or last_touched for "where were we") + $VAULT_DIR/Notes/<project>/PROJECT_LOG.md. This is the primary resume surface; the daily-journal fallback below applies only when no central vault exists. Then read the vault daily journal as the structured handoff for non-repo work:

1. Glob ~/vault/daily/*.md newest-first; read the 2–3 most recent files.
2. Grep for the project/topic (the ## Session — <time> · <sid> · <topic> headings, or the projects: [<topic>] frontmatter list) to find the matching resume point.
3. Use that entry's What was worked on / Key decisions / Open threads as the resume point — it is the same structured handoff /vault-push writes for non-repo sessions. Only if the daily journal has no matching entry should recall touch ~/vault/sessions/ (the raw transcript). The SessionStart hint names the transcript file — do NOT follow it blindly; check the daily handoff first. (Optional qmd boost if available: qmd query "<topic>" -c daily — but prefer the direct glob+grep, since the daily collection name varies by machine [daily↔work-daily] and an unknown -c silently drops the source.)

Both handoff shapes — the reader must handle either:

• Legacy flat: System/handoffs/<date>.md (one file per day, older vault layout).
• Current per-session: System/handoffs/<date>/<sid>.md (one handoff per session) plus the day rollup System/handoffs/<date>/_day.md (written by /wrap-up).

Always glob System/handoffs/**/*.md so both shapes are picked up; filter by project: frontmatter, and sort by date (folder or filename) to find "newest". If a _day.md rollup exists for a day, prefer it for a day-level ask; for the deepest current state prefer the newest <sid>.md.

The warm-start hook may already auto-surface the board's / newest handoff's last-touched state at tab start; this mode is the deeper, project-scoped catch-up — and the way to swap from the last-touched thread to the project you're actually on.

Mode 0 output template (budget ≤ 15 lines — a resume point, not a history lesson):

## Where we left off: <project>
**Now:** <2-3 lines — in-flight state + immediate next step, from RESUME section / newest handoff>
**Last session:** <sid8> · <date> · <one-line outcome>
**Open threads:** <up to 3 bullets>
**Resume with:** <the concrete command / file / step the handoff names>
(sources: <handoff path> · <PROJECT_LOG path>)

1. Temporal — Search by time

/recall yesterday
/recall last week
/recall 2026-03-01

How to handle:

1. Parse the time expression into a date range
2. List files in ~/vault/sessions/ that match the date range (filenames start with YYYY-MM-DD)
3. Use ls ~/vault/sessions/ and filter by date prefix
4. Read matching files and provide a summary of each session (title, project, key topics)
5. If many sessions match, list them with one-line summaries; offer to deep-dive into specific ones

1b. Project-scoped temporal & the temporal hierarchy

/recall is the read side of the temporal hierarchy maintained by /vault-push + /wrap-up. Map the request to the right granularity:

Entity-first + aliases: for a person/metric/product/tool, the canonical People//Glossary/ note is the answer's spine — read it first, then fan out to mentions. Entity notes carry an aliases: list, so a query for "viral coefficient" should match [[K-factor]]; if qmd misses it, also grep -rl "aliases:.*<term>" People Glossary.

Project filtering: session handoffs carry project: in frontmatter — grep that, not the filename. PROJECT_LOG.md entries are headed ## YYYY-MM-DD · <sid> · <type> · <summary> (H2; tolerate legacy ### when slicing with grep -E '^##+ [0-9]{4}-') — a date-range slice of those headings answers any project+window question even with no digest.

Weekly is always computed on demand — the materialized weekly-digest tier (/week-review, handoffs/weekly/, digests/) was retired 2026-07-01.

2. Topic — Search by content

/recall topic authentication
/recall topic docker deployment
/recall topic graphs

How to handle:

1. Use qmd CLI via Bash to search:
   • qmd query "<query>" -c sessions — hybrid search (BM25 + vector), best for most queries
   • qmd search "<query>" -c sessions — BM25 keyword search, for exact term matching
   • qmd get <file> — read a full session file for deeper context
2. If qmd is not available (fallback):
   • Use grep -rl "query" ~/vault/ to find matching files
   • Read the top matches and synthesize
3. Present results as a synthesized summary with links to source sessions
4. Include relevant excerpts from the most relevant sessions

3. Graph — Visualize session connections

/recall graph
/recall graph last 7 days

How to handle:

1. Read YAML frontmatter from all session files in ~/vault/sessions/
2. Extract: date, project, title, session_id
3. Generate a self-contained HTML file with a D3.js force-directed graph:
   • Nodes = sessions (colored by project)
   • Edges = sessions that share the same project or date
   • Node size = message_count
   • Hover shows title + date
4. Save to /tmp/recall-graph.html
5. Open with open /tmp/recall-graph.html

Filtering Rules

These rules apply to ALL modes (temporal, topic, graph, lenses):

1. Trivial session filter: Always skip sessions where message_count <= 2 in the YAML frontmatter. These are incomplete or abandoned sessions with no useful context.
2. When multiple exports of the same session exist (same session_id), prefer the one with the highest message_count.

4. Analysis Lenses

Lenses provide structured analysis across multiple collections. Each lens has a specific purpose, query strategy, and output template.

/recall retro <topic>
/recall decisions <topic>
/recall gaps <topic>
/recall patterns <topic>
/recall context <topic>

retro — Retrospective

Purpose: What worked, what didn't, what to do differently next time.

Query strategy:

1. qmd query "<topic>" -c sessions — find relevant sessions
2. qmd query "<topic> error OR bug OR fix" -c sessions — find problems
3. qmd query "<topic>" -c work-daily — check daily reflections

Output template:

## Retro: <topic>

### What Worked
- ...

### What Didn't
- ...

### Do Differently
- ...

Sources: [session files]

decisions — Decision Log

Purpose: Extract architectural and design decisions with rationale.

Query strategy:

1. qmd query "<topic> decision OR chose OR architecture" -c sessions
2. qmd query "<topic>" -c plans
3. qmd query "<topic>" -c claude-plans

Output template:

## Decisions: <topic>

| Date | Decision | Rationale | Source |
|------|----------|-----------|--------|
| ... | ... | ... | ... |

gaps — Unfinished Work

Purpose: Find dropped threads, unfinished work, and outstanding TODOs.

Query strategy:

1. qmd query "<topic> TODO OR unfinished OR defer OR hack" -c sessions
2. qmd query "<topic> TODO OR incomplete" -c plans

Output template:

## Gaps: <topic>

### Open Items
- [ ] ...

### Deferred Decisions
- ...

Sources: [session files]

patterns — Recurring Patterns

Purpose: Identify recurring patterns, anti-patterns, and common fixes.

Query strategy:

1. qmd query "<topic>" -c sessions — broad context
2. qmd query "<topic> pattern OR always OR recurring" -c sessions — explicit patterns
3. qmd query "<topic>" -c notes — check permanent notes

Output template:

## Patterns: <topic>

### Recurring
- ...

### Anti-patterns
- ...

### Common Fixes
- ...

Sources: [session files]

context — Full Context Restore

Purpose: Restore full context for resuming paused work. Most comprehensive lens.

Query strategy:

1. qmd query "<topic>" -c sessions — recent sessions
2. qmd query "<topic>" -c plans — active plans
3. qmd query "<topic>" -c claude-plans — plan mode outputs
4. qmd query "<topic>" -c notes — permanent notes
5. qmd query "<topic>" -c work-daily — daily journal

Focus on the most recent results. Present chronologically.

Output template:

## Context: <topic>

### Current State
- ...

### Recent Activity
- ...

### Active Plans
- ...

### Key Decisions
- ...

Sources: [session files]

General lens rules

• Apply the trivial session filter (message_count <= 2) to all results
• Read top 3-5 results per collection queried
• Use qmd search for exact terms, qmd query for semantic matching
• Cite sources with session file paths
• Be honest when data is sparse — say "limited data" rather than fabricating

Response Format

Always start with a brief summary line, then details:

Found 5 sessions matching "authentication" (2 this week, 3 older)

### [Session Title] — 2026-03-04
- Project: ai-data-analyst-v2
- Key points: ...
- [Full session →](file path)

Notes

• Vault location: in-repo project knowledge at $PROJECT_DIR/System/handoffs/ + $PROJECT_DIR/Notes/<repo-name>/ (where $PROJECT_DIR = git rev-parse --show-toplevel and <repo-name> = its basename lowercased); runtime session archive at ~/vault/sessions/ (qmd-indexed).
• Sessions are markdown files with YAML frontmatter
• QMD collections vary by machine/vintage — run qmd collection list FIRST and use only names that exist. Do NOT guess variants: an unknown -c errors out and silently drops that source from the search (the project CLAUDE.md documents this trap — e.g. on the main work vault there is NO daily collection; the daily journal is work-daily). Known name pairs across machines: daily↔work-daily (daily journal), notes↔vault-notes (permanent notes), plans↔claude-plans (plan-mode outputs); plus sessions, projects ($PROJECT_DIR/Notes/<repo-name>/ — PROJECT_LOG/ARC/research), handoffs (System/handoffs/**), glossary, people, meta. Use -c projects for PROJECT_LOG/ARC/research, -c handoffs for handoffs, -c glossary -c people for entities.
• Session filenames follow: YYYY-MM-DD_project_slug_sessionid.md
• Always use qmd CLI via Bash — do NOT use QMD MCP tools