Every Claude Code session starts as a blank slate, unless you really put pressure on Claude. No memory of the architectural decisions you made yesterday, the bugs you squashed last week, or the three hours you spent explaining why the authentication flow works the way it does. Every single session, you generally start over.
I've been building with Claude Code daily, across multiple codebases, some with huge contexts, and this amnesia problem is real. Context is everything, and it's usually unavailable, or fleeting. Context can be lost with big projects, conversation compaction, or just random bugs. Sometimes Claude will just nuke your entire session history...super.
Claude Sessions
Claude Code stores session transcripts as JSONL files in ~/.claude/projects/. Raw, dense, full of tool calls and system tags and thinking blocks. Thousands of lines per session. They are very expensive to read and search. Your entire history of decisions, debugging sessions, architectural explorations — bundled by default with much noise.
The Solution
I built qmd-sessions, a Claude Code skill that converts those JSONL transcripts into clean, human-readable markdown files and indexes them with Tobi's qmd, a local semantic search engine. The result is that Claude Code can search its own history at will, efficiently. Before diving into a task, Claude can now easily investigate its massive context history with you.
It sounds simple, and it is. That's the point.
What It Actually Does
The skill reads every session JSONL file across all your projects, extracting all messages. It outputs organized markdown files following the pattern {project}/{date}-{slug}-{id}.md. Subagent transcripts get converted too, with clear Task/Subagent labels so you can trace the full research tree.
Two hooks keep the index fresh automatically:
- PreCompact — converts the current session before context compaction, so nothing is lost when Claude compresses its memory mid-conversation
- SessionEnd — final conversion when a session ends, then updates the search index
Once indexed, Claude Code can search sessions via qmd's MCP server using keyword matching, semantic vector search, or deep search that auto-expands queries into variations and re-ranks results. You don't have to ask it to search. It does it proactively — at session start, before architectural decisions, after receiving corrections.
Why This Matters
I've written before about automation as the foundation of real work. The same principle applies here. Without persistent, searchable memory, every Claude Code session exists in isolation. You end up repeating yourself, explaining the same constraints, debugging the same issues.
Setup
Clone the repo into your Claude Code skills directory and run /qmd-sessions. The skill walks you through every step — output directory, conversion, Bun runtime, qmd installation, collection creation, embedding generation, MCP server config, and hook setup. Every step prompts for confirmation. Nothing runs without your approval.
Requirements are straightforward: Bun runtime, Node 22+, and qmd 1.0+. First-time embedding takes about 20 minutes to download the model and process your sessions. After that, hooks keep everything current automatically.
Full instructions and source: github.com/wbelk/claude-qmd-sessions