past-conversations
Tools
recent_chats
Retrieve recent conversation sessions with all messages.
python3 ${CLAUDE_PLUGIN_ROOT}/skills/past-conversations/scripts/recent_chats.py --n 3
| Option | Effect |
|---|---|
--n N | Number of sessions (1-20, default 3) |
--sort-order | 'desc' (newest first, default) or 'asc' |
--before DATE | Sessions before this datetime (ISO) |
--after DATE | Sessions after this datetime (ISO) |
--project NAME | Filter by project name(s), comma-separated |
--verbose | Include files_modified and commits |
--format | 'markdown' (default) or 'json' |
--include-notifications | Include task notification messages (hidden by default) |
Usage guidance:
- •Use
--n 20to maximize information gathering - •For comprehensive review, use
--n 20 - •For quick context, use
--n 3-5 - •Use
--verbosefor lenses that need file/commit context
search_conversations
Search for sessions containing keywords using full-text search (FTS5/FTS4/LIKE cascade).
python3 ${CLAUDE_PLUGIN_ROOT}/skills/past-conversations/scripts/search_conversations.py --query "keyword"
| Option | Effect |
|---|---|
--query | Required - substantive keywords |
--max-results N | Limit results (1-10, default 5) |
--project NAME | Filter by project name(s), comma-separated |
--verbose | Include files_modified and commits |
--format | 'markdown' (default) or 'json' |
--include-notifications | Include task notification messages (hidden by default) |
Output: Default markdown format (token-efficient):
## myproject | 2026-02-01 10:00 Session: abc123 ### Conversation **User:** ... **Assistant:** ...
Use --format json when structured data is needed.
Workflow
- •
Identify the lens from user intent (see Routing table below)
- •
Gather context using lens-appropriate tools:
- •For recent context:
recent_chats.py --n N - •For keyword search:
search_conversations.py --query "keywords"Use the Parameters table to select tool and options.
- •For recent context:
- •
Apply lens questions to analyze the retrieved conversations
- •
Deepen the search if initial results are insufficient:
- •Retrieve more sessions:
--n 20 - •Search for specific terms that surfaced
- •Filter by project:
--project projectname
- •Retrieve more sessions:
Query Construction
When building search queries from user requests, extract substantive keywords. Search uses branch-level full-text search — each branch's full conversation text is indexed as one document, so multi-word queries work naturally across message boundaries. BM25 ranking is used when FTS5 is available; falls back to FTS4 or LIKE on older systems.
Include: Specific nouns, technologies, concepts, project names, domain terms, unique phrases. More terms improve ranking precision — BM25 weights rare terms higher automatically.
Exclude: Generic verbs ("discuss", "talk"), time markers ("yesterday"), vague nouns ("thing", "stuff"), meta-conversation words ("conversation", "chat").
Algorithm:
- •Extract substantive keywords from user request
- •If 0 keywords → ask for clarification ("Which project specifically?")
- •If 1+ specific terms → search with those terms; use
--projectto narrow scope
Lenses
Routing
| User Says | Lens |
|---|---|
| "where were we", "recap" | restore-context |
| "what I learned", "reflect" | extract-learnings |
| "gaps", "struggling" | find-gaps |
| "mentor", "review process" | review-process |
| "retro", "project review" | run-retro |
| "decisions", "CLAUDE.md" | extract-decisions |
| "bad habits", "antipatterns" | find-antipatterns |
Parameters
| Lens | Tool | Options | Also Gather |
|---|---|---|---|
| restore-context | recent_chats | --n 5 --verbose | git status, git log -10 |
| extract-learnings | recent_chats | --n 20 | — |
| find-gaps | search_conversations | --query "confused struggling" | — |
| review-process | recent_chats | --n 20 --verbose | recent git log |
| run-retro | recent_chats | --n 20 --project NAME --verbose | full git history |
| extract-decisions | search_conversations | --query "decided chose trade-off" | — |
| find-antipatterns | search_conversations | --query "again same mistake repeated" | — |
Use --verbose for lenses that benefit from seeing files modified and commits (restore-context, review-process, run-retro).
Core Questions
| Lens | Ask |
|---|---|
| restore-context | What's unfinished? What were the next steps? |
| extract-learnings | Where did understanding shift? What mistakes became lessons? |
| find-gaps | What topics recur? Where is guidance needed repeatedly? |
| review-process | Is there planning before coding? Is debugging systematic? |
| run-retro | How did the solution evolve? What worked? What was painful? |
| extract-decisions | What trade-offs were discussed? What was rejected and why? |
| find-antipatterns | What mistakes repeat? What confusions persist? |
Follow-ups: find-gaps → suggest learn-anything. extract-decisions → suggest /updateclaudemd.
Supplementary Search Patterns
When recent retrieval doesn't surface enough, use targeted searches:
| Lens | Query |
|---|---|
| extract-learnings | --query "learned realized understand clicked" |
| find-gaps | --query "confused struggling help don't understand" |
| extract-decisions | --query "decided chose instead trade-off because" |
| find-antipatterns | --query "again same mistake repeated forgot" |
Synthesis
Principles
- •Prioritize significance — 3-5 key findings, not exhaustive lists
- •Be specific — file paths, dates, project names
- •Make it actionable — every finding suggests a response
- •Show evidence — quotes or references
- •Keep it scannable — clear structure, no walls of text
Structure
## [Analysis Type]: [Scope] ### Summary [2-3 sentences] ### Findings [Organized by whatever fits: categories, timeline, severity] ### Patterns [Cross-cutting observations] ### Recommendations [Actionable next steps]
Length
Default: 300-500 words. Expand only when data warrants it.