Claude Code 普通本地 CLI 会话默认保留 30 天，但这句话已经无法完整描述当前规则。从 2.1.248 开始，在 Claude Desktop 或 Cowork 中启动或最近继续的会话，默认没有年龄上限，除非用户或组织另行设置策略。更重要的是，保留时长只是第一层。真正可用的历史系统还要分别定义归档、索引与恢复。
提高 cleanupPeriodDays 只能让未来文件晚一点被清理。它无法找回已经删除的 transcript，无法自动提供全文检索，也无法证明备份可以恢复。完整合同应包含四层：
留存 → 归档 → 索引 → 恢复演练
当前留存规则
Anthropic 的会话文档说明，Claude Code 默认把 transcript 保存为：
~/.claude/projects/<project>/<session-id>.jsonl
项目目录通常由工作目录路径编码而来。CLAUDE_CONFIG_DIR 可以移动整个配置树，支持版本中的 CLAUDE_CODE_PROJECT_DIR_NAME 可以自行指定项目目录名。
JSONL 的每一行可能是消息、工具使用或元数据。Anthropic 明确将其视为内部格式，版本升级时可能改变。需要稳定接口的自动化应优先使用 /export、Hook 收到的 transcript_path 或官方脚本接口，避免把当前 JSON schema 当作长期合同。
普通 CLI 会话的 cleanupPeriodDays 具有以下官方属性：
- 默认 30 天；
- 最小值 1 天；
- 设置为 0 会校验失败；
- 会话启动后，Claude Code 在能够安全确定有效策略时运行后台清理；
- Managed Settings 可以强制组织级数值。
个人设置可以显式写成：
{
"cleanupPeriodDays": 180
}
这个数字代表留存选择，不能替代备份。
2.1.248 之后，Desktop 与 Cowork 走另一条规则
当前最重要的例外位于 Anthropic 的 .claude 目录说明。Claude Code 2.1.248 及以后版本会长期保留在 Claude Desktop 或 Cowork 中启动或最近继续的会话 transcript。
| 会话与策略 | 当前行为 |
|---|---|
| 普通 CLI transcript | 超过 cleanupPeriodDays 后删除，默认 30 天 |
| Desktop 或 Cowork，没有显式上限 | 默认没有年龄上限 |
设置 desktopSessionCleanupPeriodDays |
同时超过 Desktop 上限与普通清理下限后才删除 |
组织托管 cleanupPeriodDays |
托管期限也适用于 Desktop 与 Cowork，Desktop 专用键被忽略 |
两个设置中的 0 含义相反。cleanupPeriodDays: 0 属于无效配置；desktopSessionCleanupPeriodDays 的默认值 0 代表 Desktop 例外没有年龄上限。
GitHub issue #81100记录了 2.1.219 的旧故障：清理程序删除 ~/.claude/projects/ 下唯一的正文，Desktop 元数据仍然存在，于是列表中保留一个无法打开的幽灵会话。该 issue 是有价值的历史证据。2.1.248 changelog已经记录后续修复，因此不能把 2.1.219 的行为继续描述成当前默认。
公开文档仍有一个边界没有完全说清。Changelog 使用会话仍在 App 中这一条件，当前目录文档则描述为在 Desktop 或 Cowork 中启动或最近继续。若用户从 Desktop 列表移除会话，例外是否随之失效，官方文档尚未明确。对这类边界应保留独立归档。
清理范围远大于一个 JSONL 文件
目录参考列出了多种按年龄管理的状态。根据版本和功能，它可能包括主 transcript、孤立或被替代的会话状态、subagent transcript、tool result、file-history 快照、plan、debug 数据、paste 与 image cache、upload、task、shell snapshot、backup、usage report 和 feedback bundle。
另一些状态使用不同规则：
- 用于 Prompt 回溯的
history.jsonl一直保留到用户主动删除； - auto memory 文件不会因会话变旧而直接删除；
- running session 文件属于生命周期状态，不走年龄清理；
- scratchpad 还受操作系统临时目录清理影响。
只备份一个路径，可能保住 transcript，却丢失附件、工具结果或解释会话所需的项目状态。站内的 AI Coding Agent 恢复合同因此把完整可恢复状态作为备份单元。
本地 30 天与服务端 30 天是两套策略
Anthropic 的数据使用文档同时描述服务端策略与本地缓存。部分消费者设置和标准商业账户使用 30 天服务端留存，普通本地 transcript 同样默认 30 天。
数字相同，控制面不同：
- 服务端留存取决于账户类型、隐私设置、模型提供商和符合条件的 Zero Data Retention 安排；
- 本地留存由 Claude Code 客户端及其设置执行；
- Remote Control 在本地执行之外，还可能产生服务端同步副本；
- Cloud session 使用独立的托管存储生命周期。
两条路径需要分别审计。修改本地 JSON 设置不会改变 Anthropic 服务端数据策略。
留得越久，明文暴露窗口越大
Claude Code 的官方目录文档明确指出，transcript 与 Prompt history 默认不做静态加密，主要依赖操作系统文件权限保护。如果工具读取 .env，或者命令把凭据打印到输出，这些值可能进入会话 JSONL。
延长留存会同时带来收益与成本：
- 调试、交接和审计证据更多；
- 本地源代码、Prompt、工具输出和潜在凭据积累更多；
- 更多数据进入派生索引和归档；
- 访问控制、删除传播和合规义务持续更久。
修改留存期前，应先定义谁能读取归档、怎样加密、哪些秘密必须排除或脱敏、派生索引何时过期，以及删除如何传播到每一份副本。
原生 resume 不是全文检索
Claude Code 提供了实用的会话导航。在会话中运行 /resume，或在命令行运行不带参数的 claude --resume，即可打开 picker。根据官方说明，picker 可以搜索名称、AI 生成标题、conversation summary、首个 Prompt 和 PR URL。Ctrl+A 扩展到所有本地项目，Ctrl+W 扩展到当前仓库的所有 worktree，Space 预览会话。
这个界面用于找到会话，官方没有把它定义为跨所有回复与工具结果的全文搜索。
不同问题适合不同检索层：
| 查询类型 | 优先工具 |
|---|---|
| 精确错误、文件名、命令、Issue ID | 在受保护副本上使用 rg 或 SQLite FTS5 |
| 已命名会话或首个任务 | 原生 /resume picker |
| 不同措辞表达的概念与理由 | 混合词法与语义检索 |
| 经过治理的当前知识 | 来源绑定的主张库或持续维护的项目文档 |
原始日志属于证据，旧日志中的命中项不会自动变成当前事实。历史决策可能已经被替代，可能绑定旧代码版本，也可能源于一次未完成实验。把历史提升为可执行知识时，仍需要来源绑定的记忆合同。
Funes 与 claude-mem 解决检索问题，不等于完成备份
Funes把 Claude Code、Codex、pi 与 Hermes 的现有轨迹建立为本地 Lance 数据集。官方描述的查询管线结合 BM25、向量检索、排序融合、rerank、时间权重与相邻上下文。返回结果可以定位到 Agent、session、时间与 turn。可选的 Hugging Face Hub 发布默认使用私有 Dataset，并提供秘密扫描，实际边界仍受其文档说明限制。
claude-mem通过 Hook 捕获工作过程，把内容压缩成 observation 与 session summary，再通过 SQLite FTS5 和向量存储分阶段检索。它适合把后续会话变成更紧凑的跨会话上下文。由于它主要从安装之后开始捕获，并对原始活动进行转换，无法代替既有 transcript 归档。
只安装检索工具，无法证明以下事项：
- 所有原始 transcript 都已覆盖；
- 损坏或删除后仍保留旧版本；
- 归档写权限已经与 Agent 隔离；
- 恢复的 JSONL 可以继续 resume；
- 满足指定 RPO 与 RTO。
索引提升召回，备份保留恢复选项。这两个结论必须分开。
四层会话历史合同
第一层：留存
记录已安装 Claude Code 版本、有效设置来源、普通 CLI 期限、Desktop/Cowork 规则和 Managed Override。每次升级后重新核验。
retention:
cli_days: 180
desktop_days: unlimited
managed_override_checked: true
verified_version: 2.1.248_or_later
第二层：归档
把源 transcript 与必要相邻状态复制到 active sweep tree 之外的版本化位置。对归档进行加密，隔离写权限，记录 Hash，并定义 RPO、RTO 和删除规则。需要接近实时归档时，可以使用 SessionEnd Hook 或等价的受控任务。
第三层：索引
索引应从归档构建，不能替代归档。每条命中都保留源路径、session ID、时间、项目、turn 和内容 Hash。标识符与错误优先用精确检索，概念型问题确实需要时再增加语义检索。
第四层：恢复演练
定期抽取一个旧恢复点，在隔离的 CLAUDE_CONFIG_DIR 中执行恢复，并检查：
- 文件与 Hash 是否齐全；
- 兼容版本能否读取或导出 JSONL；
- 会话能否出现在 picker 中，或通过受支持的路径 resume；
- 精确与语义测试查询能否返回预设段落和来源；
- 访问控制与删除规则是否仍然有效；
- 演练不会覆盖真实项目状态。
完成恢复演练，留存设置才会升级为可用的长期记忆能力。
常见问题
Claude Code 会在 30 天后删除所有会话吗？
不会。普通本地 CLI transcript 默认 30 天。Claude Code 2.1.248 及以后版本默认长期保留在 Desktop 或 Cowork 中启动或最近继续的会话，除非用户或托管策略设置了期限。
Claude Code 日志在哪里？
默认位于 ~/.claude/projects/<project>/<session-id>.jsonl。CLAUDE_CONFIG_DIR 可以移动整个目录树。
cleanupPeriodDays: 0 能永久保留吗？
不能。普通设置中的 0 会校验失败。独立的 Desktop 设置才把默认值 0 解释为没有年龄上限。
提高留存期能恢复已经删除的会话吗？
不能。它只影响未来清理。恢复依赖已经存在的归档、文件系统快照或其他副本。
/resume 能全文搜索所有 Claude 回复吗？
官方 picker 主要搜索会话元数据与首个任务，并支持预览。正文全文检索需要单独的词法或语义索引。
Funes 和 claude-mem 算备份吗？
它们属于检索与记忆层。备份还要证明原始数据覆盖、版本历史、权限隔离、完整性检查和恢复成功。
长期保留是否安全？
Claude Code transcript 默认以明文保存在本地，工具输出可能包含源代码或秘密。长期留存需要配合加密、最小权限、脱敏和经过测试的删除流程。
参考资料
- Anthropic：Manage Claude Code sessions
- Anthropic：Explore the
.claudedirectory - Anthropic：
cleanupPeriodDays - Anthropic：
desktopSessionCleanupPeriodDays - Anthropic：Claude Code data usage
- Claude Code issue #81100
- Claude Code changelog
- Hugging Face：Give Your Coding Agents a Memory You Own
- Funes repository
- claude-mem repository
- claude-mem database architecture
- claude-mem search architecture