Claude Code SDK #3：Session 管理全解——continue / resume / fork 三把钥匙，让 Agent 真正拥有记忆

Session 是什么？存在哪里？

~/.claude/projects/<cwd-encoded>/<session-id>.jsonl

三种模式：continue、resume、fork

continue：最简单的多轮对话

import asyncio
from claude_agent_sdk import (
    ClaudeSDKClient,
    ClaudeAgentOptions,
    AssistantMessage,
    ResultMessage,
    TextBlock,
)

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Glob", "Grep"],
    )
    async with ClaudeSDKClient(options=options) as client:
        # 第一轮：分析认证模块
        await client.query("Analyze the auth module")
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(block.text)

# 第二轮：自动续接，"it" 就指 auth module
        await client.query("Now refactor it to use JWT")
        async for message in client.receive_response():
            if isinstance(message, ResultMessage):
                print(f"Done, cost: ${message.total_cost_usd:.4f}")

asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

// 第一轮
for await (const message of query({
  prompt: "Analyze the auth module",
  options: { allowedTools: ["Read", "Glob", "Grep"] }
})) {
  if (message.type === "result") console.log(message.result);
}

// 第二轮：continue: true 让 SDK 自动找上一个 session
for await (const message of query({
  prompt: "Now refactor it to use JWT",
  options: {
    continue: true,
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep"]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

resume：精确恢复指定 session

• Python：ResultMessage.session_id——每次 query 结束都会有
• TypeScript：SystemMessage（init 类型）的 session_id 字段，在流的最早期就出现；ResultMessage 末尾也有

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def first_run():
    session_id = None
    async for message in query(
        prompt="Analyze the auth module and suggest improvements",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if isinstance(message, ResultMessage):
            session_id = message.session_id  # 从结果消息取 ID
            if message.subtype == "success":
                print(message.result)
    return session_id

session_id = asyncio.run(first_run())
print(f"Captured session: {session_id}")

async def follow_up(session_id: str):
    async for message in query(
        prompt="Now implement the refactoring you suggested",
        options=ClaudeAgentOptions(
            resume=session_id,   # 精确指向上一个 session
            allowed_tools=["Read", "Edit", "Write", "Glob", "Grep"],
        ),
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)

asyncio.run(follow_up(session_id))

• Agent 上一轮分析完了一个模块，这一轮继续在那个分析基础上修改代码，不需要重读文件
• 上一轮跑到 max_turns 限制中断，这一轮调高上限后恢复
• 服务重启，从数据库里取出上次保存的 session ID，用户继续对话

fork：保留原路，探索新路

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

# 假设 session_id 已有一轮分析 auth module 的历史

async def explore_alternatives(session_id: str):
    # 分叉：从 session_id 的历史出发，探索 OAuth2 路径
    forked_id = None
    async for message in query(
        prompt="Instead of JWT, implement OAuth2 for the auth module",
        options=ClaudeAgentOptions(
            resume=session_id,
            fork_session=True,  # 关键：创建新 session，不修改原 session
        ),
    ):
        if isinstance(message, ResultMessage):
            forked_id = message.session_id  # fork 的 ID != session_id
            if message.subtype == "success":
                print(f"OAuth2 approach: {message.result}")

print(f"Fork ID: {forked_id}")

# 原 session_id 未被修改，继续 JWT 路径
    async for message in query(
        prompt="Continue with the JWT approach",
        options=ClaudeAgentOptions(resume=session_id),
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(f"JWT approach: {message.result}")

asyncio.run(explore_alternatives(session_id))

CLI 对应关系：脚本里的 session 操作

# continue：接续当前目录最近的 session
claude -c -p "继续上次的任务"

# resume：按 ID 或名字恢复
claude -r "auth-refactor" "Finish this PR"
claude --resume "550e8400-e29b-41d4-a716-446655440000" "继续分析"

# 给 session 命名（方便 resume 时用名字而不是 UUID）
claude -n "auth-refactor" "开始认证模块重构"

# fork：resume 时加 --fork-session flag
claude --resume abc123 --fork-session

# 禁用持久化（TypeScript SDK 专属，CLI 无效）
claude -p --no-session-persistence "一次性查询，不写磁盘"

跨机器迁移：两种策略

实践建议