tools-only 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.