I investigated the storage location and retention period of Claude Code conversation history
This page has been translated by machine translation. View original
Hello, this is tsukuboshi (tsukuboshi0755)!
The other day, when I tried to dig up past Claude Code conversation history, I noticed that history older than 1 month was nowhere to be found.
After looking into it, I learned for the first time that Claude Code's conversation history is automatically deleted after 30 days by default.
So in this article, I'll introduce where and in what format Claude Code's conversation history is stored, and the cleanupPeriodDays setting that controls the retention period!
Where Conversation History is Stored
Claude Code's conversation history is saved as per-session JSONL files at the following path.
~/.claude/projects/<working directory encoded name>/<session ID>.jsonl
The official documentation shows a structure of projects/<project>/<session>.jsonl, and when I checked in my own environment, the directory name was the absolute path of the working directory where Claude Code was launched, converted to a hyphen-separated name.
For example, the history of a session launched in /Users/username/myapp would be saved in a directory like this.
~/.claude/projects/-Users-username-myapp/
├── 0a8f2f2b-xxxx-xxxx-xxxx-xxxxxxxxxxxx.jsonl
├── 10023f4b-xxxx-xxxx-xxxx-xxxxxxxxxxxx.jsonl
└── ...
In other words, conversation history is stored separately per project (working directory), so if you're working across multiple repositories, multiple directories will be created.
What is Recorded in the JSONL File
According to the official documentation, this JSONL file records a complete conversation transcript including all messages, tool calls, and tool execution results.
One important thing to note is that the transcript is saved as unencrypted plain text.
The official documentation explicitly states that if a tool reads a .env file or if command output contains credentials, those values will also be written as-is into the transcript.
As measures to reduce exposure of sensitive information, the official documentation suggests the following.
- Shorten
cleanupPeriodDaysto limit the retention period - Disable transcript writing entirely using the environment variable
CLAUDE_CODE_SKIP_PROMPT_HISTORY
Conversation History is Automatically Deleted After 30 Days by Default
This conversation history (session files) does not remain indefinitely.
According to the official documentation, Claude Code automatically deletes session files older than the cleanupPeriodDays setting at startup.
- Default value:
30(days) - Minimum value:
1 - Deletion timing: At Claude Code startup
In my own environment as well, the oldest remaining session file was from exactly 30 days ago.
$ ls -lt ~/.claude/projects/*/*.jsonl | tail -1
-rw------- 1 username staff 5315939 6月 5 00:13 /Users/username/.claude/projects/-Users-username-myapp/a24cd078-xxxx.jsonl
Note that since deletion occurs at startup, even if you extend the retention period later, history that has already been deleted cannot be restored.
How to Change the Retention Period
The retention period can be changed with cleanupPeriodDays in ~/.claude/settings.json.
For example, if you want to extend it to 90 days, configure it as follows.
{
"cleanupPeriodDays": 90
}
If you want to use past work history for retrospectives or brainstorming, it's a good idea to extend it early.
If You Don't Want to Keep History
Conversely, there are also ways to disable the writing of conversation history entirely.
- Set the environment variable
CLAUDE_CODE_SKIP_PROMPT_HISTORY - In non-interactive mode (
-p), use the--no-session-persistenceflag
Consider these options in cases where you don't want to leave history, such as when using a shared machine.
References
In Closing
This time, I introduced where Claude Code's conversation history is stored and the specification of the retention period that automatically deletes it after 30 days by default.
Since conversation history contains past design decisions and the background of investigations, it can be quite a shock to realize it's gone after the fact.
For those who want to make use of history for retrospectives or brainstorming, please take a look at revisiting your cleanupPeriodDays setting!
That's all from tsukuboshi (tsukuboshi0755)!