Transcript Intelligence

Search, analyze, and extract knowledge from Claude Code session transcripts - your deep memory for past conversations, decisions, and solutions.

Quick Reference

Transcript Location

Transcripts are stored in project-specific directories:

~/.claude/projects/
├── <project-hash-1>/
│   ├── <session-id-1>.jsonl
│   ├── <session-id-2>.jsonl
│   └── ...
├── <project-hash-2>/
│   └── ...
└── ...

Finding Your Project's Transcripts

# List all Claude project directories
ls -la ~/.claude/projects/

# Find transcripts for current project (by recent modification)
ls -lt ~/.claude/projects/*/  | head -20

# Find all transcripts modified in last 7 days
find ~/.claude/projects -name "*.jsonl" -mtime -7

Transcript Line Structure

Each line is a JSON object:

interface TranscriptLine {
  type: 'user' | 'assistant' | 'file-history-snapshot' | 'system' | 'summary';
  uuid: string;
  parentUuid: string | null;
  sessionId: string;
  timestamp: string;           // ISO 8601 format
  cwd: string;                 // Working directory
  version: string;             // Claude Code version
  gitBranch?: string;          // Git branch (if in repo)
  message: {
    role: 'user' | 'assistant';
    content: ContentBlock[] | string;
    model?: string;            // e.g., "claude-sonnet-4-20250514"
    usage?: {
      input_tokens: number;
      output_tokens: number;
    };
  };
  toolUseResult?: any;         // Result from tool execution
}

Content Block Types

The message.content field can contain:

Common Search Patterns

Search for Decisions

# Find discussions about specific topics
rg -i "decided|decision|chose|choice" ~/.claude/projects/<hash>/*.jsonl

# Find architectural decisions
rg -i "architecture|design|pattern" ~/.claude/projects/<hash>/*.jsonl

# Find trade-off discussions
rg -i "tradeoff|trade-off|pros and cons|alternative" ~/.claude/projects/<hash>/*.jsonl

Search for Solutions

# Find error resolutions
rg -i "fixed|resolved|solution|workaround" ~/.claude/projects/<hash>/*.jsonl

# Find specific error discussions
rg "error|exception|failed" ~/.claude/projects/<hash>/*.jsonl | rg -i "<error-text>"

# Find implementation discussions
rg -i "implemented|implementation|approach" ~/.claude/projects/<hash>/*.jsonl

Search by Time

# Find recent transcripts (last 24 hours)
find ~/.claude/projects -name "*.jsonl" -mtime -1

# Search within date range (using jq)
cat transcript.jsonl | jq -r 'select(.timestamp >= "2025-01-01" and .timestamp < "2025-01-07")'

Search User Messages Only

# Extract only user prompts
cat transcript.jsonl | jq -r 'select(.type == "user") | .message.content'

# Search user messages for keyword
cat transcript.jsonl | jq -r 'select(.type == "user") | .message.content' | rg -i "keyword"

Search Assistant Responses Only

# Extract assistant text responses
cat transcript.jsonl | jq -r 'select(.type == "assistant") | .message.content[] | select(.type == "text") | .text'

# Search assistant responses
cat transcript.jsonl | jq -r 'select(.type == "assistant") | .message.content[] | select(.type == "text") | .text' | rg -i "keyword"

Use Cases

1. Context Restoration After Compact

When context is compacted or cleared, search transcripts to restore important information:

# Find what was discussed before compaction
rg -C 3 "important|critical|remember|note" <transcript>.jsonl

# Find file modifications
rg "Write|Edit" <transcript>.jsonl | jq '.message.content[] | select(.type == "tool_use")'

2. Finding Past Solutions

Recall how you solved similar problems:

# Search for specific error across all sessions
rg -l "TypeError" ~/.claude/projects/<hash>/*.jsonl

# Get context around the solution
rg -C 5 "TypeError" <transcript>.jsonl

3. Session Analytics

Understand usage patterns:

# Count messages per session
wc -l ~/.claude/projects/<hash>/*.jsonl

# Token usage in session
cat transcript.jsonl | jq -r 'select(.message.usage) | .message.usage | "\(.input_tokens) in, \(.output_tokens) out"'

# Total tokens
cat transcript.jsonl | jq -s '[.[].message.usage | select(.) | .input_tokens + .output_tokens] | add'

4. Finding Specific Tool Uses

# Find all file writes
cat transcript.jsonl | jq 'select(.type == "assistant") | .message.content[] | select(.type == "tool_use" and .name == "Write")'

# Find all bash commands run
cat transcript.jsonl | jq 'select(.type == "assistant") | .message.content[] | select(.type == "tool_use" and .name == "Bash") | .input.command'

# Find files that were read
cat transcript.jsonl | jq 'select(.type == "assistant") | .message.content[] | select(.type == "tool_use" and .name == "Read") | .input.file_path'

5. Reconstructing Conversation Flow

# Get chronological conversation with timestamps
cat transcript.jsonl | jq -r '[.timestamp, .type, (if .type == "user" then .message.content else (.message.content[] | select(.type == "text") | .text[:100]) end)] | @tsv'

# Get user-assistant pairs
cat transcript.jsonl | jq -r 'select(.type == "user" or .type == "assistant") | "\(.type): \(if .message.content | type == "string" then .message.content else (.message.content[] | select(.type == "text") | .text[:200]) end)"'

Integration with /recall Command

This skill works alongside the /recall command for structured memory retrieval:

# /recall uses this skill to search transcripts
/recall "what did we decide about the API design?"

When invoked via /recall:

1. Identify relevant project hash
2. Search across all session transcripts
3. Extract relevant context with surrounding lines
4. Summarize findings

Workflow: Deep Memory Search

Prerequisites

• Know the topic or keyword to search
• Have access to ~/.claude/projects/
• Know approximate timeframe (optional)

Steps

1. Identify project directory

   • List projects: ls ~/.claude/projects/
   • Find relevant project hash by examining recent files

2. Perform broad search

   • Search across all sessions: rg -i "<keyword>" ~/.claude/projects/<hash>/*.jsonl
   • Note which sessions have matches

3. Narrow to specific session

   • Focus on most relevant session
   • Get context: rg -C 5 "<keyword>" <session>.jsonl

4. Extract structured data

   • Use jq for specific fields
   • Parse tool uses if relevant

5. Summarize findings

   • Compile key decisions/solutions
   • Note related discussions

Validation

• Found relevant context
• Decisions/solutions extracted
• Context is sufficient to continue work

Performance Tips

Common jq Patterns

# Pretty print specific line types
cat transcript.jsonl | jq 'select(.type == "user")'

# Extract timestamps
cat transcript.jsonl | jq -r '.timestamp'

# Get unique models used
cat transcript.jsonl | jq -r '.message.model // empty' | sort -u

# Count by type
cat transcript.jsonl | jq -r '.type' | sort | uniq -c

# Get git branches used
cat transcript.jsonl | jq -r '.gitBranch // empty' | sort -u

Troubleshooting

Security Notes

• Transcripts may contain sensitive information
• Avoid searching for/exposing secrets, API keys, passwords
• Be cautious when sharing transcript excerpts
• Transcripts are local to your machine

Reference Files