🦞 Claw Compactor

“削减 token 消耗，保留全部事实。”

将 AI agent 的 token 消耗降低 50%。 仅需一条命令，即可对整个 workspace（含记忆文件、会话记录、子 agent 上下文等）执行压缩，采用 5 层级串联压缩技术。确定性执行，基本无损，无需调用 LLM。

特性

• 5 层压缩机制：按序协同工作，实现最大压缩收益
• 零 LLM 成本：全部压缩逻辑基于规则，完全确定性
• 字典编码、RLE 及规则压缩支持无损往返
• 通过观测提取，会话记录压缩率达 ~97%
• 分级摘要（L0/L1/L2）：支持渐进式上下文加载
• 支持 CJK：完整兼容中文/日文/韩文
• 单命令启动（full）：自动按最优顺序执行全部步骤

5 层压缩机制

*有损技术仅移除冗长格式，所有事实与决策均完整保留。

快速上手

git clone https://github.com/aeromomo/claw-compactor.git
cd claw-compactor

# 预估可节省量（非破坏性）
python3 scripts/mem_compress.py /path/to/workspace benchmark

# 全量压缩
python3 scripts/mem_compress.py /path/to/workspace full

依赖要求：Python 3.9+。可选：安装 pip install tiktoken 以获取精确 token 计数（未安装时回退至启发式估算）。

架构

┌─────────────────────────────────────────────────────────────┐
│                      mem_compress.py                        │
│                   (统一入口脚本)                             │
└──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬────┘
       │      │      │      │      │      │      │      │
       ▼      ▼      ▼      ▼      ▼      ▼      ▼      ▼
  estimate compress  dict  dedup observe tiers  audit optimize
       └──────┴──────┴──┬───┴──────┴──────┴──────┴──────┘
                        ▼
                  ┌────────────────┐
                  │     lib/       │
                  │ tokens.py      │ ← tiktoken 或启发式估算
                  │ markdown.py    │ ← Markdown 段落解析
                  │ dedup.py       │ ← 分片哈希（shingle hashing）
                  │ dictionary.py  │ ← 词典压缩逻辑
                  │ rle.py         │ ← 路径/IP/枚举编码
                  │ tokenizer_     │
                  │   optimizer.py │ ← 格式级优化
                  │ config.py      │ ← JSON 配置加载
                  │ exceptions.py  │ ← 自定义异常类型
                  └────────────────┘

命令列表

所有命令格式：python3 scripts/mem_compress.py [options]

全局选项

• --json — 输出机器可读的 JSON 格式结果
• --dry-run — 预览变更，不实际写入文件
• --since YYYY-MM-DD — 按日期筛选会话记录
• --auto-merge — 自动合并重复项（仅用于 dedup）

真实场景压缩效果

cacheRetention — 补充优化机制

在执行压缩前，请启用 prompt 缓存，可为缓存命中 token 降低 90% 成本：

{
  "models": {
    "model-name": {
      "cacheRetention": "long"
    }
  }
}

压缩减少 token 总数，缓存降低单 token 成本。二者结合：50% 压缩 + 90% 缓存折扣 = 95% 实际成本降幅。

心跳自动化

建议每周或按 heartbeat 触发执行：

## 记忆维护（每周）
- python3 skills/claw-compactor/scripts/mem_compress.py  benchmark
- 若预估收益 > 5%，则执行完整流水线
- 若存在待处理会话记录，则单独运行 observe

Cron 示例：

0 3 * * 0 cd /path/to/skills/claw-compactor && python3 scripts/mem_compress.py /path/to/workspace full

配置

可选：在 workspace 根目录放置 claw-compactor-config.json：

{
  "chars_per_token": 4,
  "level0_max_tokens": 200,
  "level1_max_tokens": 500,
  "dedup_similarity_threshold": 0.6,
  "dedup_shingle_size": 3
}

所有字段均为可选；缺失时将自动使用合理默认值。

产物文件

常见问题（FAQ）

Q：压缩会导致数据丢失吗？
A：规则引擎、字典编码、RLE 和 tokenizer 优化均为完全无损。观测压缩（observe）与压缩上下文协议（CCP）虽属有损，但确保所有事实与决策完整保留。

Q：字典解压如何工作？
A：decompress_text(text, codebook) 将所有 $XX 编码还原为原始文本。解压时必须提供有效的 .codebook.json 文件。

Q：能否单独运行某一步骤？
A：可以。所有命令彼此独立：compress、dict、observe、tiers、dedup、optimize 均可单独调用。

Q：若未安装 tiktoken 会怎样？
A：自动回退至 CJK 感知的启发式估算（字符数 ÷ 4），准确率约 90%。

Q：是否支持中文/日文/Unicode？
A：是。全面支持 CJK，包括字符感知的 token 估算及中文标点规范化。

故障排查

• workspace 路径报 FileNotFoundError：请确认路径指向 workspace 根目录（应包含 memory/ 或 MEMORY.md）
• 字典解压失败：请检查 memory/.codebook.json 是否存在且为合法 JSON
• benchmark 显示零收益：workspace 已高度优化，无可压缩内容
• observe 未发现会话记录：请检查 sessions 目录下是否存在 .jsonl 文件
• token 计数疑似错误：请安装 tiktoken：pip3 install tiktoken

致谢

• 灵感源自 thedotmack 的 claude-mem
• 由 Bot777 🤖 为 OpenClaw 构建

许可证

MIT