search-conversations
Extraction
python3 ~/.claude/skills/search-conversations/scripts/extract_conversations.py --days 3
| Option |
Effect |
--days N |
Days from last activity (not today) |
--from-today |
Days from today instead |
--all-projects |
Cross-project (implies --from-today) |
--project /path |
Filter to specific project |
--compact |
No metadata, more conversation |
--min-exchanges N |
Skip sessions with < N exchanges |
--ids abc,def |
Fetch specific conversations |
--paths /path.jsonl |
Direct file paths |
Output: Default shows files, tools, errors + conversation. --compact omits metadata.
Time modes: --days N counts from last activity (useful when returning to old projects). --all-projects or --from-today counts from today (calendar-based).
Workflow
Identify the lens from user intent (see Routing table below)
Extract recent context using the script with lens-appropriate parameters:
python3 ~/.claude/skills/search-conversations/scripts/extract_conversations.py --days N [flags]
Use the Parameters table to select --days, flags, and any supplementary data to gather.
Apply lens questions to analyze the extracted conversations
Deepen the search using what you learned from the initial extraction:
This step surfaces older context, related discussions, or cross-project patterns that complement the initial extraction.
Keep index updated: Run qmd update periodically to index new sessions.
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 |
Days |
Flags |
Also Gather |
| restore-context |
3 |
— |
git status, git log -10 |
| extract-learnings |
14 |
--all-projects --compact |
— |
| find-gaps |
30 |
--all-projects --compact |
— |
| review-process |
14 |
--all-projects --compact |
recent git log |
| run-retro |
30 |
--project /path |
full git history |
| extract-decisions |
90 |
--project /path |
— |
| find-antipatterns |
30 |
--all-projects --compact |
— |
--min-exchanges 2 or 3 filters out short sessions and reduces noise.
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 extraction doesn't surface enough, use these qmd queries to find specific sessions:
| Lens |
Query |
| extract-learnings |
qmd search "learned realized understand clicked" -c conversations -n 15 --files |
| find-gaps |
qmd search "confused struggling help with don't understand" -c conversations -n 15 --files |
| extract-decisions |
qmd search "decided chose instead of trade-off because" -c conversations -n 15 --files |
| find-antipatterns |
qmd search "again same mistake repeated forgot" -c conversations -n 15 --files |
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.
1---2name: search-conversations-23description: Search past Claude Code conversations. Use when user says "search conversations", "find that chat", "what did we discuss", "where did we talk about", "look up past session", "find conversation about X", "search history", "what did I ask about", "remember when we", "that discussion about". Also triggers on past-tense questions referencing prior work or possessives without context.4---5
6# search-conversations
7
8## Extraction
9
10```bash
11python3 ~/.claude/skills/search-conversations/scripts/extract_conversations.py --days 3
12```
13
14| Option | Effect |
15|--------|--------|
16| `--days N` | Days from last activity (not today) |
17| `--from-today` | Days from today instead |
18| `--all-projects` | Cross-project (implies --from-today) |
19| `--project /path` | Filter to specific project |
20| `--compact` | No metadata, more conversation |
21| `--min-exchanges N` | Skip sessions with < N exchanges |
22| `--ids abc,def` | Fetch specific conversations |
23| `--paths /path.jsonl` | Direct file paths |
24
25**Output**: Default shows files, tools, errors + conversation. `--compact` omits metadata.
26
27**Time modes**: `--days N` counts from last activity (useful when returning to old projects). `--all-projects` or `--from-today` counts from today (calendar-based).
28
29## Workflow
30
311. **Identify the lens** from user intent (see Routing table below)
32
332. **Extract recent context** using the script with lens-appropriate parameters:
34 ```bash
35 python3 ~/.claude/skills/search-conversations/scripts/extract_conversations.py --days N [flags]
36 ```
37 Use the Parameters table to select `--days`, flags, and any supplementary data to gather.
38
393. **Apply lens questions** to analyze the extracted conversations
40
414. **Deepen the search** using what you learned from the initial extraction:
42 - Extract additional timeframes with the script (`--days 30`, `--all-projects`)
43 - Search for specific keywords, project names, or patterns that surfaced:
44 ```bash
45 qmd search "keyword from context" -c conversations -n 15 --files
46 ```
47 - Extract those specific paths: `python3 ... --paths /found/conv.jsonl`
48
49 This step surfaces older context, related discussions, or cross-project patterns that complement the initial extraction.
50
51**Keep index updated**: Run `qmd update` periodically to index new sessions.
52
53---
54
55## Lenses
56
57### Routing
58
59| User Says | Lens |
60|-----------|------|
61| "where were we", "recap" | restore-context |
62| "what I learned", "reflect" | extract-learnings |
63| "gaps", "struggling" | find-gaps |
64| "mentor", "review process" | review-process |
65| "retro", "project review" | run-retro |
66| "decisions", "CLAUDE.md" | extract-decisions |
67| "bad habits", "antipatterns" | find-antipatterns |
68
69### Parameters
70
71| Lens | Days | Flags | Also Gather |
72|------|------|-------|-------------|
73| restore-context | 3 | — | `git status`, `git log -10` |
74| extract-learnings | 14 | `--all-projects --compact` | — |
75| find-gaps | 30 | `--all-projects --compact` | — |
76| review-process | 14 | `--all-projects --compact` | recent git log |
77| run-retro | 30 | `--project /path` | full git history |
78| extract-decisions | 90 | `--project /path` | — |
79| find-antipatterns | 30 | `--all-projects --compact` | — |
80
81`--min-exchanges 2` or `3` filters out short sessions and reduces noise.
82
83### Core Questions
84
85| Lens | Ask |
86|------|-----|
87| restore-context | What's unfinished? What were the next steps? |
88| extract-learnings | Where did understanding shift? What mistakes became lessons? |
89| find-gaps | What topics recur? Where is guidance needed repeatedly? |
90| review-process | Is there planning before coding? Is debugging systematic? |
91| run-retro | How did the solution evolve? What worked? What was painful? |
92| extract-decisions | What trade-offs were discussed? What was rejected and why? |
93| find-antipatterns | What mistakes repeat? What confusions persist? |
94
95**Follow-ups**: find-gaps → suggest `learn-anything`. extract-decisions → suggest `/updateclaudemd`.
96
97### Supplementary Search Patterns
98
99When recent extraction doesn't surface enough, use these qmd queries to find specific sessions:
100
101| Lens | Query |
102|------|-------|
103| extract-learnings | `qmd search "learned realized understand clicked" -c conversations -n 15 --files` |
104| find-gaps | `qmd search "confused struggling help with don't understand" -c conversations -n 15 --files` |
105| extract-decisions | `qmd search "decided chose instead of trade-off because" -c conversations -n 15 --files` |
106| find-antipatterns | `qmd search "again same mistake repeated forgot" -c conversations -n 15 --files` |
107
108---
109
110## Synthesis
111
112### Principles
113
1141. **Prioritize significance** — 3-5 key findings, not exhaustive lists
1152. **Be specific** — file paths, dates, project names
1163. **Make it actionable** — every finding suggests a response
1174. **Show evidence** — quotes or references
1185. **Keep it scannable** — clear structure, no walls of text
119
120### Structure
121
122```markdown
123## [Analysis Type]: [Scope]
124
125### Summary
126[2-3 sentences]
127
128### Findings
129[Organized by whatever fits: categories, timeline, severity]
130
131### Patterns
132[Cross-cutting observations]
133
134### Recommendations
135[Actionable next steps]
136```
137
138### Length
139
140Default: 300-500 words. Expand only when data warrants it.
majiayu000