conversation-memory

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:

1. 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

2. 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

3. 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:

1. 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

2. 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

3. 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

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

1. User mentions something from a past session
2. Search history by keyword and approximate date
3. Find the session ID / transcript UUID
4. Read the relevant portion (last 50-100 lines, or grep for specific terms)
5. Summarize: what was done, what was the conclusion, what’s left
6. Continue the work in the current session

Cross-Referencing Decisions

1. User asks “why did we do X?”
2. Search for the decision point in history
3. Find the conversation where X was discussed
4. Extract the reasoning and alternatives considered
5. Present the rationale without loading the full transcript

Finding a Lost Branch or PR

1. Search history for git commands: “checkout -b”, “branch”, “pr create”
2. Extract the branch name and PR number
3. 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)