I investigated the storage location and retention period (cleanupPeriodDays) 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 from more than a month ago was nowhere to be found.
After looking into it, I learned for the first time that Claude Code conversation history is automatically deleted after 30 days by default.
So in this article, I'll introduce where and in what format Claude Code conversation history is stored, as well as the cleanupPeriodDays setting that controls the retention period!
Where Conversation History Is Stored
Claude Code conversation history is saved as per-session JSONL files at the following path.
~/.claude/projects/<name encoding the working directory>/<session ID>.jsonl
The official documentation shows a structure of projects/<project>/<session>.jsonl, and when I checked in my local 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 for a session launched in /Users/username/myapp would be stored in a directory like the following.
~/.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 the complete conversation transcript, including all messages, tool calls, and tool execution results.
One important thing to note is that the transcript is stored as unencrypted plain text.
The official documentation explicitly states that if a tool reads a .env file or command output contains credentials, those values will be written directly into the transcript as well.
The following measures are officially recommended to reduce exposure of sensitive information.
- Shorten
cleanupPeriodDaysto limit the retention period - Disable transcript writing entirely using the environment variable
CLAUDE_CODE_SKIP_PROMPT_HISTORY
What Is cleanupPeriodDays
This conversation history (session files) does not remain indefinitely.
cleanupPeriodDays is a settings.json configuration key that controls this retention period.
When Claude Code starts up, session files older than the specified number of days are automatically deleted.
The main specifications are as follows.
| Item | Details |
|---|---|
| Configuration key | cleanupPeriodDays |
| Default value | 30 (days) |
| Accepted values | Integer of 1 or greater (number of days) |
| Configuration scope | Can be specified in user settings (~/.claude/settings.json), project settings (.claude/settings.json), or local settings (.claude/settings.local.json) |
| Deletion timing | At Claude Code startup |
The default is 30, so if nothing is configured, conversation history older than 30 days is automatically deleted at startup.
In my 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
How to Configure
The retention period can be changed via 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 this setting early.
Things to Note
Deleted History Cannot Be Restored
Since deletion is performed at startup, please note that even if you extend the retention period afterward, history that has already been deleted cannot be restored.
If you want to make use of your history, we recommend changing the setting before it gets deleted.
If You Don't Want History to Be Kept
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 history to remain, such as when using a shared machine.
References
Closing
This time, I introduced where Claude Code conversation history is stored and the specification of the retention period, which defaults to automatic deletion after 30 days.
Since conversation history contains past design decisions and research context, it can be quite a shock to realize it's gone after the fact.
If you'd like to use your history for retrospectives or brainstorming, please take a moment to review the cleanupPeriodDays setting!
That's all from tsukuboshi (tsukuboshi0755)!
