Claude Code conversation history: where it lives and how long it lasts

Claude Code keeps your conversation history in ~/.claude/projects/, as one .jsonl file per session, grouped into one folder per project. There is no database, no central index, and no cloud copy to go looking for. That is good news: the history is plain text you already own, so you can grep it, back it up, or move it. It is also why the history can vanish without anyone telling you, which is the part most people find out too late.

The exact path, and why the folder name looks broken

Each project gets a folder named after its working directory path, with every non-alphanumeric character replaced by a dash. A project at /Users/you/code/app becomes the folder -Users-you-code-app. It looks mangled because it is a flattened path, not a name. Inside it, each session is a file named by its session id, ending in .jsonl.

That encoding is the reason history feels per project rather than global: the folder is derived from where you launched, so two projects can never collide, and the same project reached by a different path (a git worktree, a symlink, a different drive letter) gets a different folder. If your history looks like it disappeared, it usually moved because the path did.

How to actually read it

Four ways, roughly in order of how often you want them:

1. Search across everything with the tools you already have. The files are line-delimited JSON, so grep works. This is the only way to answer "which session was the one where we decided X" without opening sessions one at a time.
2. Use /export for a human copy. It renders the current transcript for people rather than for machines. Reach for this when you want to paste a conversation somewhere, not when you want to search fifty of them.
3. Let a hook tell you the path. Claude Code hands hooks a transcript_path field, so a script does not have to guess the encoded folder name. If you are automating anything against the history, take the path from the payload instead of rebuilding it.
4. Ask for structured output. claude -p --output-format json returns the session id along with the result, which is how you capture the id of a session you just created rather than hunting for it later.

The setting that deletes your history

cleanupPeriodDays in settings.json controls how long Claude Code keeps local session files. It defaults to 30 days, the minimum is 1, and the sweep runs at startup. Nothing warns you. A conversation from two months ago is not buried in the picker, it was deleted the next time you launched.

So if any of this history matters to you, raise the number now rather than the day you need it, because raising it later cannot bring back what the last startup already removed. And be honest about the tradeoff: a longer retention is a bigger pile of your own prompts sitting on the disk. Thirty days is a reasonable default. It is just not a promise anyone made you.

A transcript is a recording, not a memory

Even at its best, the history is the wrong shape for the job people want it for. You do not want to re-read a conversation. You want the two or three things that came out of it: what we are building, what we decided, why we ruled out the other option. Those exist in the transcript only in the sense that a fact exists in a recording of a meeting. Technically present, practically gone, and gone for real at day thirty.

The kit keeps that layer separately, in plain text, next to your code rather than in your home folder. Every kitstarter project has a .kitstarter/ directory: journey.json for the roadmap and the decisions, events.jsonl for an append-only feed of what the engine did, last-recap.txt for the receipts card from the last session. It is deliberately boring. No database, no daemon, five small files that a human can open, git can track, and no cleanup job deletes on day thirty.

The short version: your history is `~/.claude/projects/`, it is yours, and it expires in thirty days unless you say otherwise. Keep the parts that matter somewhere that is not a transcript, which is what kitstarter automates. Worth reading next: how to list your sessions rather than reading files by hand, and how to bring a session back a specific one once you have found it.

Common questions

Where is Claude Code conversation history stored? In ~/.claude/projects/, on your own machine. Each project gets a folder named after its working directory path with every non-alphanumeric character replaced by a dash, and each session inside it is a .jsonl file named by its session id. There is no central index file and no database.

How long does Claude Code keep conversation history? Thirty days by default. The cleanupPeriodDays setting in settings.json controls it, the minimum is 1 day, and Claude Code deletes session files older than the threshold at startup. Raise it before you need it, because a raise cannot undo a sweep that already ran.

Can I search my Claude Code conversation history? Yes. The files are line-delimited JSON, one object per line, so ordinary tools like grep work across every session in a project folder. Use /export instead when you want a readable copy of one conversation rather than a search across many.

Does /clear delete my conversation history? No. /clear empties your current context but the transcript is still saved and still resumable, so the file stays in ~/.claude/projects and the session stays in the resume picker. The only thing that deletes history is the cleanupPeriodDays sweep at startup.