retrace

shikihane's avatarfrom shikihane

Search and analyze Claude Code session history. Use when user asks to find past conversations, recall what was done, search for patterns in history, or analyze previous sessions.

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 8, 2026⬇️1downloads
[Memory and Context Management]

When & Why to Use This Skill

Retrace is a specialized Claude skill designed to search, analyze, and manage Claude Code session history. By implementing FTS5 full-text search with BM25 ranking, it enables users to efficiently recall past implementations, recover lost code versions, and perform AI-driven analysis on previous conversation patterns. This tool significantly enhances developer productivity by providing a robust long-term memory layer for AI-assisted coding workflows, ensuring that valuable context and technical decisions are never lost.

Use Cases

  • Recalling technical implementations: Quickly locate specific code snippets or architectural decisions made in previous sessions to maintain consistency across a project.
  • Code recovery without Git: Restore previous versions of files that were modified during an AI session but were not yet committed to a version control system.
  • AI-powered history analysis: Use the analyze script to identify recurring bugs, classify error types, or summarize progress across multiple historical sessions.
  • Contextual debugging: Search for similar error patterns or 'how we fixed this before' to accelerate the resolution of current technical issues.
  • Session chronicling: Extract detailed event logs and summaries from past work to generate project reports or handoff documentation.
nameRetrace
descriptionThis 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".
version0.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.py for common utilities

Core Workflow

  1. Ensure index exists before searching
  2. List sessions to find relevant session IDs
  3. Search with layered output (stats → list → detail → full)
  4. Use chronicle for single-session history extraction
  5. 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 storage
  • references/chronicle-format.md - TOON format specification for chronicle output
  • references/recover-guide.md - File recovery guide and data source trust levels

Example Files

  • examples/search-examples.sh - Common search patterns
  • examples/chronicle-examples.sh - Chronicle usage examples
  • examples/recover-examples.sh - Recovery workflow examples

Scripts

  • scripts/validate-skill.sh - Validate skill structure and configuration