ClawHub

上下文缓存管理器

Other

提供fork-safe的上下文克隆、历史消息智能压缩和快速恢复，支持多Agent并发和会话高效管理。

Install

openclaw skills install context-cache-manager

Context Cache Manager

fork-safe上下文克隆 + 智能压缩 + 快速恢复 参考Claude Code fork设计和Context缓存机制

背景问题

OpenClaw原生上下文管理：

  • fork时上下文丢失 — 子Agent无法继承父进程关键状态
  • 历史消息膨胀 — 长时间对话导致token爆炸
  • session恢复慢 — 重启后丢失工作上下文
  • 内容替换状态乱序 — 多Agent同时修改导致冲突

根因：缺乏Claude Code的fork-safe三剑客克隆机制

解决方案

Fork-Safe三剑客（必须克隆）

参考Claude Code原始设计，fork时必须克隆：

// 父进程 → 子进程
{
  contentReplacementState: parent.contentReplacementState.clone(),  // 内容替换状态
  renderedSystemPrompt: parent.renderedSystemPrompt,                // 渲染后的system提示
  messages: parent.messages.clone()                                // 消息历史
}

智能压缩策略

完整消息历史 (100条+) 
    ↓ 压缩
保留：
  - 所有system消息（完整）
  - 最近20条消息（完整）
  - 更早消息 → 摘要标记
    [Compressed 80 older messages]
    ↓
压缩后 ~25条等效消息

Session生命周期

[ACTIVE] ──fork──> [FORKED] (父) + [ACTIVE] (子)
   │
   ├──compact──> [COMPACTED]
   │
   └──archive──> [ARCHIVED]
           │
           └──cleanup──> deleted (24h后)

使用方式

Python API

from context_cache_manager import ContextCacheManager, fork_context

# 方式1：面向对象
manager = ContextCacheManager("session-001")

# 捕获当前上下文
manager.capture(
    system_prompt="You are OpenClaw agent...",
    messages=[...],
    content_replacement_state={"replaced": [...]},
    rendered_system_prompt="Rendered prompt with context..."
)

# 快速恢复
restored = manager.restore()
print(f"Restored {len(restored.messages)} messages")

# Fork到子session
child = manager.fork("child-session-002")
assert child.content_replacement_state == parent.content_replacement_state

# 方式2：便捷函数
child = fork_context("parent-id", "child-id")

压缩效果

原始消息数压缩后压缩率等效token
502550%~60%
1002575%~70%
2002587.5%~75%

Skill集成

whenToUse: |
  spawn子Agent前捕获父context
  session恢复时快速重建
  长时间对话后压缩上下文
permissions:
  - file:write (缓存目录)
  - file:read (恢复缓存)
  - memory:manage
hooks:
  before_spawn: capture_context
  after_spawn_complete: fork_context

配置参数

参数默认值说明
MAX_HISTORY_LENGTH50最大保留消息数
MAX_CACHE_AGE_HOURS24缓存过期时间
CACHE_DIRtmp/context-cache/缓存目录
formatpickle+gzip高效序列化

与AgentConcurrency配合

from agent_concurrency_controller import spawn_agent_safe
from context_cache_manager import ContextCacheManager

# 1. 捕获父上下文
parent_ctx = ContextCacheManager("main-session")
parent_ctx.capture(system_prompt, messages)

# 2. 安全spawn（自动fork上下文）
result = spawn_agent_safe(
    task="子任务",
    agent_type="researcher",
    context_manager=parent_ctx  # 自动fork
)

# 3. 子Agent继承完整上下文

日志审计

缓存日志 (logs/context-cache.log)

[2026-04-03 15:40:00] CAPTURE: session-001 | 15000_chars | compressed: true
[2026-04-03 15:40:05] FORK: session-001 -> child-002 | cloned 3 fields
[2026-04-03 15:45:00] COMPACT: session-001 | 100->25 messages | saved 65%
[2026-04-03 16:00:00] RESTORE: session-001 | loaded from cache

最佳实践

  1. spawn前capture — 确保可fork
  2. 长对话后compact — 防止token爆炸
  3. 定期cleanup — 删除过期缓存
  4. immutable fork — 子进程不修改父状态

关联

  • 并发控制：skills/agent-concurrency-controller/
  • 结果控制：skills/tool-result-size-controller/
  • 安全编辑：skills/safe-file-editor/
  • 架构参考：memory/learnings/claude-code-architecture-2026-04-03.md

版本

  • v1.0.0 (2026-04-03): 初始实现，fork-safe三剑客克隆+智能压缩