# Conversation Memory > Search and recall past conversations from Claude Code history and Cursor agent transcripts. Gives your AI agent memory across sessions so you never re-explain context. - Skill: `ofershap/conversation-memory` (Agent Skill) - Install (CLI): `npx skillmds@latest add ofershap/conversation-memory` - Raw SKILL.md: https://api.skillmd.com/api/skills/ofershap/conversation-memory/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: ofershap (https://skillmd.com/u/ofershap) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ofershap/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 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//.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//agent-transcripts/` - Workspace path uses dashes replacing slashes (e.g., `Users-me-Code-myproject/`) - Each conversation is a directory named by UUID - Inside: `.jsonl` with full conversation data - Messages alternate between `"role":"user"` and `"role":"assistant"` - User prompts are inside `` 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:** ```bash grep -i "search term" ~/.claude/history.jsonl | tail -20 ``` **Claude Code — find sessions for a specific project:** ```bash ls ~/.claude/projects/-Users-me-Code-myproject/ cat ~/.claude/projects/-Users-me-Code-myproject/sessions-index.json ``` **Cursor — find recent conversations in a workspace:** ```bash ls -lt ~/.cursor/projects/Users-me-Code-myproject/agent-transcripts/ ``` **Cursor — search across all workspaces:** ```bash 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 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)