Claw Compactor — OpenClawスキルリファレンス

概要

Claw Compactorは、6つの圧縮層を使用してOpenClawワークスペース全体のトークン使用量を削減します：

層	名前	コスト	説明
1	Rule Engine	無料	重複排除、フィラー削除、セクション統合
2	Dictionary Encoding	無料	自動コードブック、$XX置換
3	Observation Compression	無料	セッションJSONL→構造化サマリー
4	RLE Patterns	無料	パス/IP/列挙型短縮記法
5	Compressed Context Protocol	無料	フォーマット省略
6	Engram	LLM API	リアルタイム観察メモリ

スキル場所: skills/claw-compactor/
エントリーポイント: scripts/mem_compress.py
Engram CLI: scripts/engram_cli.py

---

オートモード（推奨 — セッション開始時に実行）

python3 skills/claw-compactor/scripts/mem_compress.py <workspace> auto

ワークスペースのすべてのファイルを自動的に圧縮し、実行間のトークン数を追跡して、削減額を報告します。セッション開始時に毎回実行してください。

---

コアコマンド

フルパイプライン（すべての層）

python3 scripts/mem_compress.py <workspace> full

最適な順序で5つの決定論的層すべてを実行します。通常：50%以上の複合削減。

ベンチマーク（非破壊的）

python3 scripts/mem_compress.py <workspace> benchmark
# JSON出力：
python3 scripts/mem_compress.py <workspace> benchmark --json

ファイルを書き込まずに潜在的な削減額を示すドライラン報告。

個別の層

# 層1：ルールベース圧縮
python3 scripts/mem_compress.py <workspace> compress

# 層2：辞書エンコーディング
python3 scripts/mem_compress.py <workspace> dict

# 層3：観察圧縮（セッションJSONL→サマリー）
python3 scripts/mem_compress.py <workspace> observe

# 層4：RLEパターンエンコーディング（`compress`内で実行）
# 層5：トークナイザー最適化
python3 scripts/mem_compress.py <workspace> optimize

# 階層別サマリー（L0/L1/L2）
python3 scripts/mem_compress.py <workspace> tiers

# クロスファイル重複排除
python3 scripts/mem_compress.py <workspace> dedup

# トークンカウント報告
python3 scripts/mem_compress.py <workspace> estimate

# ワークスペースヘルスチェック
python3 scripts/mem_compress.py <workspace> audit

グローバルオプション

--json          マシン可読JSON出力
--dry-run       ファイル書き込みなしでプレビュー
--since DATE    日付でセッションをフィルタリング（YYYY-MM-DD）
--auto-merge    重複を自動マージ（dedupコマンド）

---

Engram — 層6：リアルタイム観察メモリ

Engramはフラグシップ層です。会話と並行してライブエンジンとして動作し、メッセージを自動的に構造化された優先度付きナレッジに圧縮します。

前提条件

engram.yaml（推奨）または環境変数経由で設定します：

# engram.yaml — claw-compactorルートに配置
llm:
  provider: openai-compatible
  base_url: http://localhost:8403
  model: claude-code/sonnet
  max_tokens: 4096

threads:
  default:
    observer_threshold: 30000    # Observerが発動するまでの保留中トークン
    reflector_threshold: 40000   # Reflectorが発動するまでの観察トークン

concurrency:
  max_workers: 4                 # 並列スレッドワーカー

# 代替：環境変数
export ANTHROPIC_API_KEY=sk-ant-...   # 推奨
# または
export OPENAI_API_KEY=sk-...          # OpenAI互換フォールバック
export OPENAI_BASE_URL=https://...    # オプション：カスタムエンドポイント（ローカルLLM等）

Engram オートモード（本番環境向け推奨）

すべてのアクティブなスレッドを自動検出し、並行して処理します（4ワーカー）：

# 単一実行 — すべてのスレッドを自動検出
python3 scripts/engram_auto.py --workspace ~/.openclaw/workspace

# シェルラッパー経由
bash scripts/engram-auto.sh

# CLI経由
python3 scripts/engram_cli.py <workspace> auto --config engram.yaml
python3 scripts/engram_cli.py <workspace> status --thread openclaw-main
python3 scripts/engram_cli.py <workspace> observe --thread openclaw-main
python3 scripts/engram_cli.py <workspace> reflect --thread openclaw-main

リトライ： LLM呼び出しは429/5xxで指数バックオフでリトライします（2s→4s→8s、最大3試行）。 400/401/403ではリトライしません（設定エラーで即座に失敗）。

統合エントリーポイント経由のEngram

# すべてのスレッドステータスをチェック
python3 scripts/mem_compress.py <workspace> engram status

# スレッドに対してObserverを強制実行
python3 scripts/mem_compress.py <workspace> engram observe --thread <thread-id>

# スレッドに対してReflectorを強制実行
python3 scripts/mem_compress.py <workspace> engram reflect --thread <thread-id>

# 挿入可能なコンテキストを出力
python3 scripts/mem_compress.py <workspace> engram context --thread <thread-id>

専用CLI経由のEngram

# ステータス：すべてのスレッド
python3 scripts/engram_cli.py <workspace> status

# ステータス：単一スレッド
python3 scripts/engram_cli.py <workspace> status --thread <thread-id>

# 観察を強制実行
python3 scripts/engram_cli.py <workspace> observe --thread <thread-id>

# 反映を強制実行
python3 scripts/engram_cli.py <workspace> reflect --thread <thread-id>

# ファイルから会話をインポート（JSONアレイまたはJSONL）
python3 scripts/engram_cli.py <workspace> ingest \
    --thread <thread-id> --input /path/to/conversation.jsonl

# 挿入可能なコンテキスト文字列を取得（システムプロンプト用）
python3 scripts/engram_cli.py <workspace> context --thread <thread-id>

# 任意のコマンドのJSON出力
python3 scripts/engram_cli.py <workspace> status --json
python3 scripts/engram_cli.py <workspace> context --thread <id> --json

Engramデーモンモード（リアルタイムストリーミング）

# デーモン起動、stdを経由してJSONLメッセージをパイプ
python3 scripts/engram_cli.py <workspace> daemon --thread <thread-id>

# メッセージをパイプ：
echo '{"role":"user","content":"Hello!","timestamp":"12:00"}' | \
    python3 scripts/engram_cli.py <workspace> daemon --thread <thread-id>

# コントロールコマンド（JSONLとして送信）：
echo '{"__cmd":"observe"}'   # 今すぐ観察を強制実行
echo '{"__cmd":"reflect"}'   # 今すぐ反映を強制実行
echo '{"__cmd":"status"}'    # スレッドステータスJSONを出力
echo '{"__cmd":"quit"}'      # デーモンを終了

# クワイエットモード（stderrのスタートアップメッセージを抑制）
python3 scripts/engram_cli.py <workspace> daemon --thread <id> --quiet

Engram Python API

from scripts.lib.engram import EngramEngine

engine = EngramEngine(
    workspace_path="/path/to/workspace",
    observer_threshold=30_000,     # 自動観察前のトークン
    reflector_threshold=40_000,    # 自動反映前のトークン
    anthropic_api_key="sk-ant-...", # または環境変数ANTHROPIC_API_KEYを設定
)

# メッセージを追加 — 閾値を超えると自動的にobserve/reflectがトリガーされます
status = engine.add_message("thread-id", role="user", content="Hello!")
# 戻り値: {"observed": bool, "reflected": bool, "pending_tokens": int, ...}

# 閾値に関わらず手動でトリガー
obs_text = engine.observe("thread-id")    # 保留中のメッセージがない場合はNoneを返す
ref_text = engine.reflect("thread-id")   # 観察がない場合はNoneを返す

# 完全なコンテキスト辞書を取得
ctx = engine.get_context("thread-id")
# 戻り値: {"thread_id", "observations", "reflection", "recent_messages", "stats", "meta"}

# 挿入可能なシステムコンテキスト文字列をビルド
ctx_str = engine.build_system_context("thread-id")
# システムプロンプトの先頭に追加する準備完了

Engram設定変数

変数	デフォルト	説明
ANTHROPIC_API_KEY	—	AnthropicのAPIキー（推奨）
OPENAI_API_KEY	—	OpenAI互換APIキー
OPENAI_BASE_URL	https://api.openai.com	ローカルLLM用のカスタムエンドポイント
OM_OBSERVER_THRESHOLD	30000	自動観察前の保留中トークン
OM_REFLECTOR_THRESHOLD	40000	自動反映前の観察トークン
OM_MODEL	claude-opus-4-5	LLMモデルオーバーライド

閾値チューニング クイックリファレンス

各Observer呼び出しは約2Kの出力トークン（Sonnet）を生成します。デフォルト30K閾値での日次ボリューム：

チャネル	日次トークン	@30K閾値	@10K閾値
#aimm	~149K	~5×/日	~15×/日
openclaw-main	~138K	~4.5×/日	~14×/日
#open-compress	~68K	~2.3×/日	~7×/日
#general	~62K	~2×/日	~6×/日
subagent	~43K	~1.4×/日	~4×/日
cron	~9K	~0.3×/日	~1×/日
合計	~470K/日	~16×/日（~32K出力トークン）	~47×/日（~94K出力トークン）

observer_threshold: 30000から開始します。より新鮮なコンテキストのためにチューンダウン、コスト削減のためにチューンアップします。

Engram ベンチマーク概要

戦略	トークン削減	ROUGE-L	IR-F1	レイテンシ	LLM呼び出し
Engram (L6)	87.5%	0.038	0.414	~35秒	2
RuleCompressor (L1–5)	9.0%	0.923	0.958	~6ms	0
RandomDrop	21.5%	0.852	0.911	~0ms	0

• Engramの低ROUGE-L = セマンティック再構成で逐語的コピーではない — 意図は保持されます
• 即座のプロンプト圧縮にはRuleCompressorを使用。長期メモリにはEngramを使用。
• 完全な結果 → benchmark/RESULTS.md

観察フォーマット

Engramは構造化された二言語（英語/中文）優先度付きログを生成します：

Date: 2026-03-05
- 🔴 12:10 ユーザーがOpenCompress構築中、deadline一週間内 / 用户在构建 OpenCompress，deadline 一周内
  - 🔴 12:10 ModernBERT-largeを使用 / 使用 ModernBERT-large
  - 🟡 12:12 アノテーション戦略を議論 / 讨论了标注策略
- 🟡 12:30 M3 Ultraでのデプロイメントパイプラインの討論
- 🟢 12:45 ユーザーは簡潔な返信を優先

• 🔴 重大 — 目標、期限、ブロッカー、重要な決定（削除されない）
• 🟡 重要 — 技術詳細、進行中の作業、嗜好
• 🟢 有用 — 背景、言及、ソフトコンテキスト

メモリストレージレイアウト

memory/engram/{thread_id}/
├── pending.jsonl      # 未観察のメッセージバッファ（observe後に自動クリア）
├── observations.md    # Observer出力 — 追記専用構造化ログ
├── reflections.md     # Reflector出力 — 圧縮長期メモリ（上書き）
└── meta.json          # タイムスタンプとトークンカウント

---

OpenClawメモリシステムとの統合

システムプロンプト注入

各セッション開始時にEngramコンテキストを注入します：

from scripts.lib.engram import EngramEngine

engine = EngramEngine(workspace_path)
ctx_str = engine.build_system_context("my-session")
if ctx_str:
    system_prompt = ctx_str + "\n\n" + base_system_prompt

build_system_context()の出力構造：

## Long-Term Memory (Reflections)
<Reflector出力 — 長期圧縮コンテキスト>

## Recent Observations
<Observer出力の直近200行>

<!-- engram_tokens: 1234 -->

Engramと決定論的層を組み合わせる

Engramセッション後、決定論的パイプラインを出力ファイルに対して実行します：

# Engramはobservations.mdとreflections.mdを生成
# 次にそれらにさらに圧縮を適用：
python3 scripts/mem_compress.py <workspace> full

長時間実行エージェントセッション用の推奨ワークフロー

1. セッション開始： build_system_context()をシステムプロンプトに注入
2. 各メッセージ： engine.add_message()を呼び出し — observe/reflectが自動的にトリガー
3. セッション終了 / 週次cron： ワークスペースに対してfullパイプラインを実行
4. マルチセッション継続性： コンテキストはmemory/engram/{thread}/に永続化

---

OpenClawスキルのインストール

OpenClawスキルとしてインストールするには、スキルディレクトリが以下の場所で利用可能であることを確認してください：

~/.openclaw/workspace/skills/claw-compactor/

またはOpenClawスキルレジストリでパスを設定してください。

SKILL.mdはOpenClawエージェントディスパッチャーによって読み込まれます。上記のdescriptionと triggersフィールドは、このスキルが自動的にアクティベートされるタイミングを制御します。

---

ハートビート / Cron自動化

## メモリメンテナンス（週次）
- python3 skills/claw-compactor/scripts/mem_compress.py <workspace> benchmark
- 削減額 > 5%の場合：フルパイプラインを実行
- Engram保留中メッセージがある場合：engram observe --thread <id>を実行

Cron（日曜日 午前3時）：

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

---

出力成果物リファレンス

成果物	場所	説明
辞書コードブック	memory/.codebook.json	メモリファイルと一緒に保存する必須
観察セッションログ	memory/.observed-sessions.json	処理されたトランスクリプトを追跡
層3サマリー	memory/observations/	観察圧縮出力
Engram観察	memory/engram/{thread}/observations.md	ライブObserverログ
Engram反映	memory/engram/{thread}/reflections.md	抽出された長期メモリ
レベル0サマリー	memory/MEMORY-L0.md	~200トークン超圧縮サマリー
レベル1サマリー	memory/MEMORY-L1.md	~500トークン圧縮サマリー

---

トラブルシューティング

問題	解決方法
ワークスペースでFileNotFoundError	パスをmemory/を含むワークスペースルートを指す
辞書の解凍に失敗	memory/.codebook.jsonが有効なJSONであることを確認
ベンチマークで削減率がゼロ	ワークスペースは既に最適化済み
observeがトランスクリプトを見つけない	sessions/の.jsonlファイルを確認
Engram："APIキーが設定されていない"	ANTHROPIC_API_KEYまたはOPENAI_API_KEYを設定
Engram ObserverがNoneを返す	そのスレッドに保留中メッセージがない
トークンカウントが不正確に見える	tiktokenをインストール：pip3 install tiktoken