Claude Code 的可恢复性机制

关于 Claude Code 的可恢复性机制，官方并未发布一份名为“续跑协议”的独立技术文档。其实现主要围绕 Checkpoint（检查点） 和 Session（会话） 两个维度展开，以下是根据官方文档和公开资料梳理的核心机制。

🛡️ 一、核心机制：Checkpoint（检查点）

Checkpoint 提供了类似“游戏存档”的功能，让你能随时回退到之前的某个状态。

· 触发与内容：每个用户提示都会自动创建一个新的 Checkpoint。它只记录 Claude 通过Write、Edit等工具所做的文件编辑，不跟踪 Bash 命令（如rm）或用户手动更改。
· 存储与生命周期：Checkpoint 在会话之间持久存在，存储在本地~/.claude/projects/目录下，默认30天后自动清理。

💾 二、落盘机制：如何存储与恢复

· SDK 控制：在 SDK 中设置 enable_file_checkpointing=True 即可启用。
· 核心标识：UUID：每个 Checkpoint 都有唯一 UUID。你需要在响应流中捕获它，恢复时调用 rewind_files(checkpoint_id)。
· 代码示例（Python）：

# 1. 启用并捕获 checkpoint_idoptions=ClaudeAgentOptions(enable_file_checkpointing=True)asyncwithClaudeSDKClient(options)asclient:awaitclient.query("重构认证模块")# 从消息中获取 checkpoint_id 和 session_id# 2. 恢复文件asyncwithClaudeSDKClient(ClaudeAgentOptions(resume=session_id))asclient:awaitclient.rewind_files(checkpoint_id)# 根据 UUID 恢复

🔄 三、续跑机制：如何恢复会话

这里的“续跑”指恢复整个对话上下文，主要靠 Session 机制。

· 手动恢复：
· /resume：在会话中输入，选择历史会话恢复。
· claude --resume ：启动时直接恢复指定会话。
· claude --continue：恢复当前目录下的最近会话。
· 外部存储：高级场景下可通过 SessionStore 将会话镜像到 S3 或数据库，实现跨主机恢复。
· 恢复选项：执行/rewind后，可选择：
· 恢复代码和对话：完全回退。
· 仅恢复对话：回退消息，保留代码。
· 仅恢复代码：回退文件，保留对话。
· 从此处/到此处总结：将对话压缩为摘要以释放空间。

⚠️ 重要提示

  1. Checkpoint 是会话级工具，不可替代 Git。
  2. 它不跟踪 Bash 命令（如rm）的更改。
  3. 第三方工具（如 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。

  1. 实现 SessionStore 接口
    你需要用 Node.js/TypeScript 实现包含以下核心方法的类：

· append(key, entries): 必需。本地写入后调用，负责将 entries（JSON对象数组）存入 PG。
· load(key): 必需。恢复会话时调用，从 PG 读取并返回数据。
· listSessions(projectKey): 可选。用于列出项目下的会话。
· delete(key): 可选。删除会话。

注意 key 包含 projectKey（工作目录编码）、sessionId（会话 UUID）和 subpath（子代理记录）。

  1. 在查询中使用
    将你的 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 密钥（用于生成向量嵌入）。