retrace
搜索并分析 Claude Code 会话历史记录。当用户要求查找过去的对话、回忆所做的事情、搜索历史模式或分析以前的会话时使用。
📖 中文导读:搜索并分析 Claude Code 会话历史记录。当用户要求查找过去的对话、回忆所做的事情、搜索历史模式或分析以前的会话时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: Retrace description: This skill should be used when the user asks to "find past conversations", "recall what was done", "search history", "look up previous work", "how did we handle X", "what was that implementation", "find similar code", "search session", "analyze conversation history", "recover file", "restore previous version", or mentions terms like "earlier", "before", "previously", "last time", "history", "past work". version: 0.2.0
Retrace - Claude Code Session History Search
Search and analyze Claude Code conversation history using FTS5 full-text search with BM25 ranking.
When to Use This Skill
Use retrace when the user asks about:
- Past conversations, previous work, or earlier implementations
- How a specific feature or bug was handled before
- Finding similar implementations or code patterns
- Recovering code that was damaged without git record
- Extracting session chronicles or history summaries
Architecture
- Per-project databases: Each project has its own index at
~/.claude/projects/<project>/retrace-index.db - Session isolation: Sessions table with metadata and summaries
- Shared module:
retrace_common.pyfor common utilities
Core Workflow
- Ensure index exists before searching
- List sessions to find relevant session IDs
- Search with layered output (stats → list → detail → full)
- Use chronicle for single-session history extraction
- Use recover for file version restoration
Quick Reference
Ensure Index Exists
RETRACE_SCRIPTS="<plugin-path>/scripts"
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-index.py" --auto --project <project>
List Sessions
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-search.py" --list-sessions --project <project>
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-search.py" --list-sessions --project <project> --json
Search Sessions
# Basic search
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-search.py" "query" --project <project>
# With filters
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-search.py" "bug" --type tool_result --tool Edit --project <project>
# Get context around a message
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-search.py" --context <id> --before 5 --after 5
# Statistics only
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-search.py" "query" --level stats --project <project>
AI-Powered Analysis
# Search and analyze (auto-chunks if data > 100KB)
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-analyze.py" "error" --prompt "classify error types" --project <project>
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-analyze.py" "query" --prompt "summarize" --json
Session Chronicle
# Extract all events from a session (TOON format)
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-chronicle.py" --session <uuid> --project <project>
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-chronicle.py" --file <path> --json
File Recovery
# Recover file versions from session
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-recover.py" --session <uuid> --project <project> --file <path> --output ./recovery
Search Levels
| Level | Output | Token Cost |
|---|---|---|
stats |
Counts, distributions | ~50 |
list |
ID, timestamp, preview | ~500 |
detail |
Full preview, file location | ~2000 |
full |
Complete message | Variable |
Default workflow: stats → list → detail → full
Filter Options
| Filter | Example |
|---|---|
--type |
tool_result, user, assistant |
--role |
user, assistant |
--tool |
Bash, Edit, Read |
--project |
Project name (partial match) |
--session |
Session UUID |
--since |
Start date (ISO) |
--until |
End date (ISO) |
Index Management
# Build/update all project indexes
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-index.py" --auto
# Rebuild from scratch
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-index.py" --auto --no-incremental
# View statistics
$PYTHON_CMD "$RETRACE_SCRIPTS/retrace-index.py" --stats
Red Flags - Use Retrace
Stop and search retrace when thinking:
- "What did we do before?" → Search first
- "Similar implementation?" → Find existing code
- "Code was modified without git" → Use recover
- "Need to restore previous version" → Use recover
- "This seems familiar" → Search for it
Script Reference
| Script | Purpose |
|---|---|
retrace-index.py |
Build/update FTS5 index |
retrace-search.py |
Search with layered output |
retrace-analyze.py |
AI-powered analysis |
retrace-chronicle.py |
Session history extraction |
retrace-recover.py |
File version recovery |
Additional Resources
Reference Files
references/architecture.md- Detailed architecture and data storagereferences/chronicle-format.md- TOON format specification for chronicle outputreferences/recover-guide.md- File recovery guide and data source trust levels
Example Files
examples/search-examples.sh- Common search patternsexamples/chronicle-examples.sh- Chronicle usage examplesexamples/recover-examples.sh- Recovery workflow examples
Scripts
scripts/validate-skill.sh- Validate skill structure and configuration