Claw Code Session Management: Persistence, Memory, and Compaction

会话存储

Python 端的会话存储围绕 StoredSession 数据类构建，该类捕获完全恢复对话所需的最小状态。每个存储的会话包含四个字段：

class StoredSession:
    session_id: str
    messages: tuple           # immutable snapshot of message history
    input_tokens: int
    output_tokens: int
      

会话序列化为 JSON 并保存到 .port_sessions/{session_id}.json。messages 字段存储为元组（而非列表），以强制持久化快照的不可变性——实时会话继续修改自己的消息列表，但保存的状态在持久化时被冻结。

Rust 会话模型

Rust 层定义了具有更强类型保证的自有会话类型。Rust Session 包含用于模式迁移的 version 字段（u32）和保存完整对话历史的 messages 字段（Vec<ConversationMessage>）。两个方法处理持久化：save_to_path 序列化为 JSON 并写入磁盘，load_from_path 反序列化并验证模式版本。

消息角色与内容块

Claw Code 会话中的每条消息都带有一个 MessageRole 枚举标签，用于标识发言者：

System — 由框架注入的指令、上下文和配置
User — 来自人类操作者的消息
Assistant — AI 模型生成的响应
Tool — 工具执行返回的结果

消息内容表示为 ContentBlock 变体的数组。Rust 实现定义了三种变体：

enum ContentBlock {
    Text { text: String },
    ToolUse { id: String, name: String, input: Value },
    ToolResult {
        tool_use_id: String,
        tool_name: String,
        output: String,
        is_error: bool,
    },
}
      

Text 块承载纯文本内容。ToolUse 块表示代理调用工具的决策，包含用于关联的唯一 id、工具 name 和 JSON input 载荷。ToolResult 块将工具的响应传回模型，通过 tool_use_id 链接到发起的工具使用，并包含一个 is_error 标志，告诉模型工具是成功还是失败。

压缩系统

Claw Code 压缩系统防止长时间运行会话中的上下文窗口溢出。它由包含两个关键参数的 CompactionConfig 管控：

struct CompactionConfig {
    preserve_recent_messages: usize,  // default: 4
    max_estimated_tokens: usize,      // default: 10000
}
      

should_compact 函数检查两个条件：消息数量是否超过阈值，以及估计的令牌数是否超过 max_estimated_tokens。令牌估算使用约 4 字符/令牌的启发式方法——简单但有效地判断何时需要压缩。

当压缩触发时，compact_session 保留最近的 4 条消息（可通过 preserve_recent_messages 配置），并将所有更早的消息替换为单条系统消息摘要。format_compact_summary 函数通过以下方式生成此摘要：

从对话历史中剥离 <analysis> 标签
收集关键文件引用（按扩展名过滤：rs、ts、tsx、js、json、md）
从对话上下文推断 pending_work 和 current_work
将摘要截断为 160 个字符以保持紧凑

令牌估算

约 4 字符/令牌的启发式方法是刻意保守的。对于代码（更密集）会高估，对于散文会低估，但压缩触发是一个软阈值——几百个令牌的不准确性不会影响正确性。

TranscriptStore

TranscriptStore 是一个内存缓冲区，在刷新到持久存储之前累积对话条目。它提供四个操作：

append — 向缓冲区添加新条目（消息、工具结果或系统事件）
compact(keep_last=10) — 将缓冲区修剪为最近的 10 条条目
replay — 以元组形式返回完整缓冲区内容，用于会话恢复
flush — 将缓冲区写入磁盘并清空

replay 方法返回元组（而非列表），以防止意外修改回放的历史。compact 方法的 keep_last=10 提供了与主引擎 compact_after_turns 设置分离的压缩边界，确保即使引擎的压缩配置较为激进，记录存储也不会无限增长。

历史日志

除了原始记录外，Claw Code 会话系统还通过 HistoryEvent 和 HistoryLog 维护结构化历史日志。每个 HistoryEvent 有两个字段：title（简短摘要，如"编辑了 main.rs"）和 detail（关于更改内容和原因的更长上下文）。HistoryLog 类提供 add（追加事件）和 as_markdown（将日志渲染为可读的 Markdown 文档，用于包含在提示或报告中）。

上下文发现

在会话的第一个轮次之前，Claw Code 框架通过 PortContext 数据类发现工作区上下文。此上下文为系统提示提供信息，帮助代理理解它正在工作的项目：

class PortContext:
    source_root: Path
    tests_root: Path
    assets_root: Path
    archive_root: Path
    python_file_count: int
    test_file_count: int
    asset_file_count: int
    archive_available: bool
      

上下文扫描器统计 Python 文件、测试文件和资源文件的数量，让代理快速了解项目的规模和结构。archive_available 标志指示是否存在可供参考的已归档会话数据。

系统提示组装

系统提示是每个 Claw Code 会话的基础。它通过发现和合并项目层次结构中的指令文件来组装。发现过程遍历祖先目录链，寻找三个特定文件：

CLAUDE.md — 纳入版本控制的项目级指令
CLAUDE.local.md — 未纳入版本控制的本地覆盖
.claude/CLAUDE.md — .claude 配置目录中的指令

两个硬性限制防止指令文件压垮上下文窗口：

MAX_INSTRUCTION_FILE_CHARS = 4,000 — 单个指令文件不能超过 4,000 个字符
MAX_TOTAL_INSTRUCTION_CHARS = 12,000 — 所有发现文件的合并指令内容上限为 12,000 个字符

内容哈希去重步骤确保在目录层次结构的多个级别发现的相同指令内容只包含一次。这防止了冗余，例如当 monorepo 在多个子目录中软链接相同的 CLAUDE.md 时。

指令优先级

离工作目录越近的指令文件优先级越高。内容哈希去重确保这不会导致指令重复，而字符限制防止深度嵌套的 monorepo 超出上下文预算。