Claude Code 的可恢复性机制

关于 Claude Code 的可恢复性机制官方并未发布一份名为“续跑协议”的独立技术文档。其实现主要围绕 Checkpoint检查点 和 Session会话 两个维度展开以下是根据官方文档和公开资料梳理的核心机制。️ 一、核心机制Checkpoint检查点Checkpoint 提供了类似“游戏存档”的功能让你能随时回退到之前的某个状态。· 触发与内容每个用户提示都会自动创建一个新的 Checkpoint。它只记录 Claude 通过Write、Edit等工具所做的文件编辑不跟踪 Bash 命令如rm或用户手动更改。· 存储与生命周期Checkpoint 在会话之间持久存在存储在本地~/.claude/projects/目录下默认30天后自动清理。 二、落盘机制如何存储与恢复· SDK 控制在 SDK 中设置 enable_file_checkpointingTrue 即可启用。· 核心标识UUID每个 Checkpoint 都有唯一 UUID。你需要在响应流中捕获它恢复时调用 rewind_files(checkpoint_id)。· 代码示例Python# 1. 启用并捕获 checkpoint_idoptionsClaudeAgentOptions(enable_file_checkpointingTrue)asyncwithClaudeSDKClient(options)asclient:awaitclient.query(重构认证模块)# 从消息中获取 checkpoint_id 和 session_id# 2. 恢复文件asyncwithClaudeSDKClient(ClaudeAgentOptions(resumesession_id))asclient:awaitclient.rewind_files(checkpoint_id)# 根据 UUID 恢复 三、续跑机制如何恢复会话这里的“续跑”指恢复整个对话上下文主要靠 Session 机制。· 手动恢复· /resume在会话中输入选择历史会话恢复。· claude --resume 启动时直接恢复指定会话。· claude --continue恢复当前目录下的最近会话。· 外部存储高级场景下可通过 SessionStore 将会话镜像到 S3 或数据库实现跨主机恢复。· 恢复选项执行/rewind后可选择· 恢复代码和对话完全回退。· 仅恢复对话回退消息保留代码。· 仅恢复代码回退文件保留对话。· 从此处/到此处总结将对话压缩为摘要以释放空间。⚠️ 重要提示Checkpoint 是会话级工具不可替代 Git。它不跟踪 Bash 命令如rm的更改。第三方工具如 claude-vigil-mcp、Continuum提供了更丰富的增强功能可供参考。总而言之Claude Code 通过 Checkpoint 机制精确记录文件变更结合 Session 管理实现对话上下文的恢复两者共同构成了其核心的可恢复性体系。Claude Code 的会话持久化主要基于 本地文件系统辅以可选的 外部存储适配器 来实现跨主机恢复。️ 核心存储本地 JSONL 文件会话数据以 JSONL (JSON Lines) 格式存储。路径为~/.claude/projects/项目路径/会话ID.jsonl。· 项目路径从工作目录的绝对路径派生移动项目目录会导致历史记录“丢失”。· 会话 ID唯一标识符如 uuid恢复时需指定。· 文件内容每行是一个 JSON 对象记录对话轮次、元数据、子代理记录等。 写入与恢复机制· 写入Append-Only采用仅追加模式。消息通过 parentUuid 字段形成链表结构支持分支和子代理记录。为提高性能会话文件在首条消息时才真正创建。· 恢复–resume通过 parentUuid 链重建完整对话。恢复命令有· claude --continue恢复当前目录的最近会话。· claude --resume打开交互式选择器。· claude --resume 按名称恢复。· /resume在会话内切换。 跨主机持久化外部存储适配器 (SessionStore)默认存储绑定特定机器通过 SessionStore 适配器可将记录镜像到 S3、Redis 或数据库。· 存储是“镜像”而非“替换”SDK 仍先写本地磁盘再异步调用适配器 append()。· 关键接口需实现 append写和 load读。· 适用场景多主机部署、无服务器函数、CI/CD 等无持久化本地磁盘的环境。 生命周期与注意事项· 默认保留会话和 Checkpoint 默认保留 30 天后自动清理。· 临时会话可通过 --no-session-persistence 禁用持久化。· 外部工具社区有 ccs、claude-sync等工具可增强管理、加密或跨设备同步能力。要把 Claude Code 的会话持久化到 PostgreSQL主要有两种实现路径一种是原生扩展基于官方 SDK 的 SessionStore 接口适合深度定制另一种是社区工具通过 MCP 协议配置更简单开箱即用。 路径一原生扩展基于官方 SDK这是官方推荐的方式通过实现 SessionStore 接口将会话镜像到 PostgreSQL。实现 SessionStore 接口你需要用 Node.js/TypeScript 实现包含以下核心方法的类· append(key, entries): 必需。本地写入后调用负责将 entriesJSON对象数组存入 PG。· load(key): 必需。恢复会话时调用从 PG 读取并返回数据。· listSessions(projectKey): 可选。用于列出项目下的会话。· delete(key): 可选。删除会话。注意 key 包含 projectKey工作目录编码、sessionId会话 UUID和 subpath子代理记录。在查询中使用将你的 Store 实例传入 query 的 options.sessionStore。 路径二社区工具基于 MCP 协议如果不想从零开发这些现成的 MCP 服务器是不错的选择· r2mcp提供 11个MCP工具 和三层记忆偏好/项目上下文/对话。支持 pgvector 语义搜索。配置简单支持 Supabase 和自托管 PG。· Mnestra提供 9个MCP工具。支持 Postgres pgvector默认使用 Supabase提供 memory_remember、memory_recall 等工具。· Throughline直接解析 Claude Code 本地的 JSONL 会话文件。在本地 PG 中构建知识图谱实现跨工具记忆。提供 Docker 快速启动。· code-session-memory支持多种 AI 编程工具。默认 SQLite可选 PostgreSQL pgvector 作为后端。· memhub: Postgres 驱动的跨机器记忆数据完全由你掌控。⚠️ 几点提醒· 存储是“镜像”而非“替换”SDK 始终先写本地磁盘再调用 append() 同步到 PG。如果你不想要本地副本可将 CLAUDE_CONFIG_DIR 指向临时目录。· 注意网络环境使用 Supabase 等云 PG 时注意选择兼容 IPv4 的连接串如 Session Pooler避免在 IPv6-only 网络上连接失败。· 社区方案注意点多数社区方案需依赖 pgvector 扩展和 LLM API 密钥用于生成向量嵌入。