When to use

Use this skill when you need to recall something from a previous conversation session. This includes finding past debugging sessions, remembering architectural decisions, locating code changes from earlier work, or continuing a task you started days ago. Works with both Claude Code (/.claude/history.jsonl ) and Cursor (/.cursor/projects/*/agent-transcripts/ ).

How Conversation History is Stored

Claude Code

Claude Code saves every conversation in two locations:

Global index — ~/.claude/history.jsonl

• One JSON object per line, each representing a single user prompt

• Fields: prompt text, timestamp, project path, session ID

• Grows indefinitely, never auto-deleted

• Use this for searching across all projects by keyword

Full session transcripts — ~/.claude/projects/<project-path>/

• Project directory names use dashes replacing path slashes (e.g., -Users-me-Code-myproject/ )

• Each session is a .jsonl file named by session ID

• Contains the complete conversation: user messages, assistant responses, tool calls, results

• sessions-index.json has metadata: summaries, message counts, git branches, timestamps

• memory/MEMORY.md holds auto-memory

Session lookup flow:

• Search ~/.claude/history.jsonl by keyword/date to find the session ID

• Read the full session from ~/.claude/projects/<project>/<session-id>.jsonl

• Or read sessions-index.json for summaries without loading full transcripts

Cursor

Cursor stores full conversation transcripts per workspace:

Agent transcripts — ~/.cursor/projects/<workspace-path>/agent-transcripts/

• Workspace path uses dashes replacing slashes (e.g., Users-me-Code-myproject/ )

• Each conversation is a directory named by UUID

• Inside: <uuid>.jsonl with full conversation data

• Messages alternate between "role":"user" and "role":"assistant"

• User prompts are inside <user_query> tags in the message content

• Tool calls appear as [Tool call] and [Tool result] blocks

Finding the right workspace:

• List ~/.cursor/projects/ to see all workspace directories

• Match by project name in the directory name

• List the agent-transcripts/ subdirectory to see all conversations

• Sort by modification time to find recent ones

Reading transcripts:

• Files can be large — search with grep/rg first, then read relevant chunks

• Don't try to read the entire file at once for large conversations

• Search for specific keywords, error messages, or file paths mentioned

Critical Rules

1. Search Before Reading

Never read an entire history file. They can be massive.

Wrong:

Read ~/.claude/history.jsonl (loads thousands of lines, blows context window)

Correct:

grep -i "authentication bug" ~/.claude/history.jsonl | tail -20

Then read only the matching session transcript.

2. Use the Right Search Strategy per Tool

Claude Code — keyword search across all projects:

grep -i "search term" ~/.claude/history.jsonl | tail -20

Claude Code — find sessions for a specific project:

ls ~/.claude/projects/-Users-me-Code-myproject/ cat ~/.claude/projects/-Users-me-Code-myproject/sessions-index.json

Cursor — find recent conversations in a workspace:

ls -lt ~/.cursor/projects/Users-me-Code-myproject/agent-transcripts/

Cursor — search across all workspaces:

rg -l "search term" ~/.cursor/projects//agent-transcripts//*.jsonl

3. Extract Context, Don't Dump Transcripts

When you find a relevant past conversation, extract only the key decisions, code changes, and conclusions. Don't paste the entire transcript into current context.

Wrong:

Here's the full previous conversation (4000 lines)...

Correct:

From session on Feb 18 (project: myapp):

• We found the auth bug was caused by expired JWT refresh tokens
• Fix: added token rotation in middleware/auth.ts
• Branch: fix/jwt-refresh (PR #47, merged)
• Open follow-up: rate limiting on the refresh endpoint

4. Match User Intent to Search Scope

User says... Search strategy

"yesterday we looked at..." Filter by date in history.jsonl or sort transcripts by mtime

"we had a bug in the auth..." Keyword search for "auth" + "bug" across history

"continue what we started on feature X" Find session by feature name, extract last state

"what branch did we create for..." Search for "branch" or "git checkout" in transcripts

"remember when we discussed..." Broad keyword search, then read matching sessions

5. Handle Multiple Matches Gracefully

When a search returns multiple sessions, present them as options:

Found 3 sessions mentioning "auth":

1. Feb 18, 15:30 — myapp — "Debug JWT refresh token expiry"
2. Feb 12, 09:15 — myapp — "Add OAuth2 Google login"
3. Jan 28, 14:00 — api-service — "Auth middleware refactor"

Which one are you referring to?

6. Respect Privacy Boundaries

• Only search history for the current user's home directory

• Don't expose full session contents unprompted — summarize first

• If a session contains sensitive data (API keys, passwords visible in logs), note that without repeating the values

Patterns

Resuming a Previous Task

• User mentions something from a past session

• Search history by keyword and approximate date

• Find the session ID / transcript UUID

• Read the relevant portion (last 50-100 lines, or grep for specific terms)

• Summarize: what was done, what was the conclusion, what's left

• Continue the work in the current session

Cross-Referencing Decisions

• User asks "why did we do X?"

• Search for the decision point in history

• Find the conversation where X was discussed

• Extract the reasoning and alternatives considered

• Present the rationale without loading the full transcript

Finding a Lost Branch or PR

• Search history for git commands: "checkout -b", "branch", "pr create"

• Extract the branch name and PR number

• Verify it still exists with git/gh commands in the current session

Anti-Patterns

• Reading entire history files into context (context window explosion)

• Searching without date/keyword constraints (too many results)

• Dumping raw JSONL into the conversation (unreadable)

• Assuming conversation history exists for all tools (only Claude Code and Cursor store it)

• Searching other users' history directories

• Treating history as authoritative (code may have changed since the conversation)