KK Blog

Menu

Administrator
Published on 2026-09-29 / 15 Visits
0
0

Claude Code Session Retention in 2026: What 30 Days Really Means

#claude-mem#Funes#Full Text Search#Agent Memory#Conversation History#Session Retention#Backup#Claude Code

Claude Code session retention is 30 days by default for ordinary local CLI transcripts, but that sentence is no longer the whole rule. Since version 2.1.248, sessions started or most recently continued in Claude Desktop or Cowork are kept without an age limit by default, unless a user or organization sets another policy. More importantly, retention is only the first layer. A useful session-history system must separately define archive, index, and restore.

Increasing cleanupPeriodDays can keep future files longer. It cannot recover a deleted transcript, make old sessions searchable, or prove that a backup can resume. The durable design is a four-layer contract:

retention → archive → index → restore drill

The current retention rule

Anthropic's session documentation says Claude Code stores transcripts by default at:

~/.claude/projects/<project>/<session-id>.jsonl

The project directory normally encodes the working-directory path. CLAUDE_CONFIG_DIR can move the entire configuration tree, and CLAUDE_CODE_PROJECT_DIR_NAME can choose the project-directory name in supported versions.

Each JSONL line contains a message, tool use, or metadata entry. Anthropic calls the entry format internal and warns that it can change between releases. Scripts that need a stable interface should prefer /export, a hook's transcript_path, or an official script interface over assuming a fixed JSON schema.

For ordinary CLI sessions, cleanupPeriodDays has these documented properties:

  • default: 30 days;
  • minimum: 1 day;
  • 0 is invalid;
  • the age-based sweep runs after session startup when Claude Code can safely determine the effective policy;
  • managed settings can enforce an organization-wide value.

A personal setting can be explicit:

{
  "cleanupPeriodDays": 180
}

Use a deliberate number. A large value is a retention choice, not a backup strategy.

Desktop and Cowork are different after 2.1.248

The most important current exception appears in Anthropic's .claude directory reference. Claude Code 2.1.248 and later keep a transcript at any age when the session was started or most recently continued in Claude Desktop or Cowork.

Three policy cases matter:

Session and policy Current behavior
Normal CLI transcript Deleted after cleanupPeriodDays, 30 days by default
Desktop or Cowork, no explicit cap No age limit by default
Desktop or Cowork with desktopSessionCleanupPeriodDays Deleted only after the Desktop cap and the ordinary cleanup floor are both exceeded
Organization manages cleanupPeriodDays Managed period also applies to Desktop and Cowork; the Desktop-specific key is ignored

The value 0 has opposite meanings across the two settings. cleanupPeriodDays: 0 fails validation. The default desktopSessionCleanupPeriodDays: 0 means no age limit for the Desktop exemption.

GitHub issue #81100 documents what happened in version 2.1.219: the sweep deleted the only transcript under ~/.claude/projects/ while Desktop metadata remained, leaving a visible session that could not open. That issue is useful historical evidence. The 2.1.248 changelog records the later retention fix, so the issue should not be treated as the current default behavior.

One boundary remains documented less precisely. The changelog says the exception applies while sessions are in the app, while the current directory reference describes sessions started or most recently continued there. If removing a session from the Desktop list affects the exemption, the public docs do not currently make that lifecycle explicit. Treat that case as unconfirmed and keep an independent archive.

The sweep covers more than one JSONL file

The directory reference lists a broad set of age-managed state. Depending on the version and feature, it includes main transcripts, orphaned or superseded transcript state, subagent transcripts, tool results, file-history snapshots, plans, debug data, paste and image caches, uploads, tasks, shell snapshots, backups, usage reports, and feedback bundles.

Other state follows different rules:

  • history.jsonl, used for prompt recall, is kept until the user deletes it;
  • auto-memory files are not removed simply because a session becomes old;
  • running-session files are lifecycle state, not part of the age-based transcript sweep;
  • scratchpad files also depend on the operating system's temporary-directory cleanup.

Backing up one path without a state inventory can preserve a transcript while losing attachments, tool results, or the project context needed to understand it. This is why the broader AI coding agent restore contract treats the complete recoverable state as the backup unit.

Local 30 days and server-side 30 days are separate

Anthropic's data-usage page describes both server-side policy and local caching. Some consumer configurations and standard commercial use use 30-day server-side retention. Local Claude Code also defaults ordinary transcripts to 30 days.

The matching number does not make them one control:

  • server-side retention depends on account type, privacy settings, provider, and eligible zero-data-retention arrangements;
  • local retention is enforced by the Claude Code client and its settings;
  • Remote Control can add server-side synchronization while execution remains local;
  • cloud sessions have their own managed storage lifecycle.

Audit each path separately. Changing a local JSON setting does not change Anthropic's service-side policy.

Longer retention expands the plaintext exposure window

Claude Code's official directory reference says transcripts and prompt history are not encrypted at rest. Operating-system file permissions are the default protection. If a tool reads a secret or a command prints one, that value may be written into the session JSONL.

Longer retention therefore creates a real tradeoff:

  • more evidence for debugging, handoff, and audit;
  • a larger local collection of source code, prompts, tool output, and possible credentials;
  • more data copied into indexes and archives;
  • a longer deletion and access-control obligation.

Before extending retention, define who can read the archive, how it is encrypted, which secrets are excluded or redacted, when derived indexes expire, and how deletion propagates to every copy.

Native resume is not full-text retrieval

Claude Code provides useful session navigation. Run /resume inside a session or claude --resume without an argument to open the picker. The documented picker can search names, generated titles, conversation summaries, first prompts, and pull-request URLs. Ctrl+A widens to all local projects, Ctrl+W widens across worktrees, and Space previews a session.

That interface is designed to find a session. It is not documented as full-text search across every assistant response and tool result.

Choose retrieval by question type:

Query Suitable first tool
Exact error, filename, command, issue ID rg or SQLite FTS5 over a protected copy
Named session or first task Native /resume picker
Concept or rationale expressed with different words Hybrid lexical and semantic retrieval
Curated current knowledge Source-linked claim store or maintained project documents

Raw logs are evidence. Search results from old logs are not automatically current facts. A retrieved decision can be superseded, tied to an old code version, or based on an incomplete experiment. The source-linked memory contract remains necessary when history is promoted into actionable knowledge.

Funes and claude-mem solve retrieval, not backup

Funes builds a local Lance dataset from existing Claude Code, Codex, pi, and Hermes traces. Its documented pipeline combines BM25 and vector search, ranking fusion, reranking, recency weighting, and neighboring context. A result points back to agent, session, timestamp, and turn. Optional Hub publishing uses a private dataset by default and adds secret scanning, subject to the documented limits of that scanner.

claude-mem uses hooks to capture work, compresses observations and summaries, and provides staged retrieval over SQLite FTS5 and a vector store. It is useful when the goal is compact cross-session context. Because it mainly captures sessions after installation and transforms raw activity into memory artifacts, it does not substitute for preserving preexisting transcripts.

Neither project, by installation alone, proves:

  • that every raw transcript was captured;
  • that old versions remain available after corruption or deletion;
  • that archive permissions are isolated from the Agent;
  • that a recovered JSONL can be resumed;
  • that a particular recovery time or recovery point objective is met.

Indexing improves recall. Backup preserves recovery options. Keep those claims separate.

A four-layer session-history contract

1. Retention

Record the installed Claude Code version, effective settings source, ordinary CLI period, Desktop/Cowork policy, and any managed override. Recheck after upgrades.

Example contract:

retention:
  cli_days: 180
  desktop_days: unlimited
  managed_override_checked: true
  verified_version: 2.1.248_or_later

2. Archive

Copy source transcripts and required adjacent state to a versioned location outside the active sweep tree. Encrypt it, isolate write authority, record hashes, and define RPO, RTO, and deletion rules. Use a SessionEnd hook or an equivalent controlled job when near-real-time archival matters.

3. Index

Build indexes from the archive, not as its replacement. Preserve source path, session ID, timestamp, project, turn, and content hash for every hit. Use exact retrieval first for identifiers and errors. Add semantic retrieval for conceptual questions only when it materially improves recall.

4. Restore drill

On a schedule, select an old recovery point and restore it into an isolated CLAUDE_CONFIG_DIR. Verify:

  1. expected files and hashes are present;
  2. JSONL can be read or exported by a compatible Claude Code version;
  3. the session appears in the picker or resumes by an absolute path where supported;
  4. exact and semantic test queries return known passages with provenance;
  5. access controls and deletion rules still hold;
  6. no live project state is overwritten during the drill.

The restore drill is the point where session retention becomes operational memory rather than a setting that looked correct.

FAQ

Does Claude Code delete every session after 30 days?

No. Ordinary local CLI transcripts default to 30 days. Claude Code 2.1.248 and later keep sessions started or most recently continued in Desktop or Cowork without an age limit by default, unless a user or managed policy sets one.

Where are Claude Code transcripts stored?

By default, they are JSONL files under ~/.claude/projects/<project>/<session-id>.jsonl. CLAUDE_CONFIG_DIR can move the tree.

Does cleanupPeriodDays: 0 keep sessions forever?

No. Zero is invalid for cleanupPeriodDays. The separate Desktop setting uses zero as its default no-age-limit value.

Can a larger retention period recover sessions that are already gone?

No. It only affects future cleanup. Recovery requires an existing archive, filesystem snapshot, or other retained copy.

Can /resume search the full text of every Claude response?

The official picker searches session metadata and first-task information, and it can preview sessions. Full-text body retrieval requires a separate lexical or semantic index.

Are Funes and claude-mem backups?

They are retrieval and memory layers. A backup claim also requires raw-data coverage, version history, isolated permissions, integrity checks, and a successful restore.

Is long retention safe?

Claude Code transcripts are plaintext at rest by default and may contain source code or secrets from tool output. Long retention should be paired with encryption, least-privilege access, redaction, and tested deletion.

Sources

OpenAI Agent 借 DN...
Claude Code 会话留存合...

Comment