total-recall

Total Recall — 自律型エージェントメモリ

自ら監視する唯一のメモリスキルです。

データベースも、ベクトルも、手動での保存も不要です。会話を優先度付きのメモに圧縮し、メモが増えると統合し、見落とした内容を復元する LLM オブザーバーだけで実現します。5 層の冗長性を備え、メンテナンスは不要です。月額約 $0.00（無料枠のモデルを使用）。

ほかのメモリスキルが「覚えておくことを忘れないように」と求めるのに対し、このスキルはただ注意を払います。

アーキテクチャ

Layer 1: Observer (cron, every 15-30 min)
    ↓ compresses recent messages → observations.md
Layer 2: Reflector (auto-triggered when observations > 8000 words)
    ↓ consolidates, removes superseded info → 40-60% reduction
Layer 3: Session Recovery (runs on every /new or /reset)
    ↓ catches any session the Observer missed
Layer 4: Reactive Watcher (inotify daemon, Linux only)
    ↓ triggers Observer after 40+ new JSONL writes, 5-min cooldown
Layer 5: Pre-compaction hook (memoryFlush)
    ↓ emergency capture before OpenClaw compacts context

機能

• オブザーバーは最近のセッションのトランスクリプト（JSONL）を読み込み、LLM に送信して、優先度（高、中、低）を付けた圧縮済みの観察結果を observations.md に追記します
• リフレクターは観察結果が多くなりすぎると起動し、関連項目を統合して、古くて優先度の低い項目を削除します
• セッション復元はセッション開始時に実行され、前回のセッションが記録されているか確認します。記録されていない場合は、緊急の観察を行います
• リアクティブウォッチャーは inotify でセッションディレクトリを監視し、アクティビティが活発な時間帯には cron の実行間隔より早く記録します
• 圧縮前フックは OpenClaw がコンテキストを圧縮しようとすると実行され、何も失われないようにします

クイックスタート

1. スキルをインストールする

clawdhub install total-recall

2. API キーを設定する

.env または OpenClaw の設定に追加します。

OPENROUTER_API_KEY=sk-or-v1-xxxxx

3. セットアップスクリプトを実行する

bash skills/total-recall/scripts/setup.sh

これにより、次の処理が行われます。

• メモリディレクトリの構造（memory/、logs/、バックアップ）を作成します
• inotify と systemd がある Linux では、リアクティブウォッチャーサービスをインストールします
• 手動で追加する cron ジョブとエージェント設定の手順を表示します

4. エージェントが観察結果を読み込むように設定する

エージェントのワークスペースコンテキスト（例：MEMORY.md またはシステムプロンプト）に追加します。

At session startup, read `memory/observations.md` for cross-session context.

または、OpenClaw の memoryFlush.systemPrompt を使って、起動時の指示を挿入します。

プラットフォームのサポート

プラットフォーム	オブザーバー + リフレクター + 復元	リアクティブウォッチャー
Linux（Debian/Ubuntu など）	完全対応	inotify-tools が必要
macOS	完全対応	利用不可（cron のみ）

すべてのコアスクリプトで、移植性の高い bash を使用しています。stat、date、md5 コマンドは、_compat.sh によってクロスプラットフォームで処理されます。

設定

すべてのスクリプトは、適切なデフォルト値を設定した環境変数を読み込みます。

変数	デフォルト	説明
OPENROUTER_API_KEY	（必須）	LLM 呼び出しに使用する OpenRouter API キー
MEMORY_DIR	$OPENCLAW_WORKSPACE/memory	observations.md の保存場所
SESSIONS_DIR	~/.openclaw/agents/main/sessions	OpenClaw のセッションのトランスクリプト
OBSERVER_MODEL	stepfun/step-3.5-flash:free	圧縮に使うプライマリモデル（無料）
OBSERVER_FALLBACK_MODEL	nvidia/nemotron-3-nano-30b-a3b:free	プライマリモデルが失敗した場合のフォールバック（無料）
OBSERVER_LOOKBACK_MIN	15	さかのぼる時間（分）（日中）
OBSERVER_MORNING_LOOKBACK_MIN	480	さかのぼる時間（分）（午前 8 時前）
OBSERVER_LINE_THRESHOLD	40	リアクティブトリガーが発動するまでの行数（Linux）
OBSERVER_COOLDOWN_SECS	300	リアクティブトリガーの実行間隔（秒）（Linux）
REFLECTOR_WORD_THRESHOLD	8000	リフレクターが実行されるまでの語数
REFLECTOR_MODEL	nvidia/nemotron-3-super-120b-a12b:free	観察結果の統合に使うモデル（無料）
REFLECTOR_FALLBACK_MODEL	openrouter/hunter-alpha	リフレクターモデルが失敗した場合のフォールバック（無料）
OPENCLAW_WORKSPACE	~/your-workspace	ワークスペースのルート

LLM プロバイダーの設定

Total Recall は、OpenAI 互換のチャット補完 API を使用できます。環境変数を設定してプロバイダーを切り替えます。

変数	デフォルト	説明
LLM_BASE_URL	https://openrouter.ai/api/v1	API エンドポイント
LLM_API_KEY	OPENROUTER_API_KEY にフォールバック	API キー
LLM_MODEL	deepseek/deepseek-v3.2	使用するモデル

プロバイダーの例

# OpenRouter (default)
export OPENROUTER_API_KEY="your-key"

# Ollama (local)
export LLM_BASE_URL="http://localhost:11434/v1"
export LLM_API_KEY="ollama"
export LLM_MODEL="llama3.1:8b"

# Groq
export LLM_BASE_URL="https://api.groq.com/openai/v1"
export LLM_API_KEY="your-groq-key"
export LLM_MODEL="llama-3.3-70b-versatile"

作成されるファイル

memory/
  observations.md          # The main observation log (loaded at startup)
  observation-backups/     # Reflector backups (last 10 kept)
  .observer-last-run       # Timestamp of last observer run
  .observer-last-hash      # Dedup hash of last processed messages
logs/
  observer.log
  reflector.log
  session-recovery.log
  observer-watcher.log

Cron ジョブ

セットアップスクリプトは、次の OpenClaw cron ジョブを作成します。

ジョブ	スケジュール	説明
memory-observer	15 分ごと	最近の会話を圧縮します
memory-reflector	1 時間ごと	観察内容が多い場合に統合します

リアクティブウォッチャー（Linux のみ）

リアクティブウォッチャーは inotifywait を使用してセッションのアクティビティを検出し、cron だけの場合よりも速くオブザーバーを起動します。inotify-tools をインストールした Linux が必要です。

# Install inotify-tools (Debian/Ubuntu)
sudo apt install inotify-tools

# Check watcher status
systemctl --user status total-recall-watcher

# View logs
journalctl --user -u total-recall-watcher -f

コスト

OpenRouter 経由でデフォルトの無料モデルを使用する場合：

• 一般的な使用（オブザーバー＋リフレクター）では、月額約 $0.00（無料ティアのモデルを使用）
• 1 日あたり約 15～30 回の cron 実行で、それぞれ数百トークンを処理します
• デフォルトのモデルはすべて無料ティアのモデルです

モデルに関する注意

スクリプトには、API レスポンスの .content フィールドと .reasoning フィールドの両方に対応する防御的な処理が含まれています。ほとんどのモデルは標準の .content フィールドにコンテンツを返しますが、.reasoning へのフォールバックにより、異なるレスポンス形式を使用するモデルとの互換性が確保されます。

動作の仕組み（技術解説）

オブザーバー

1. 最近更新されたセッションの JSONL ファイルを検索します
2. サブエージェント／cron セッションを除外します
3. 過去の対象期間からユーザーとアシスタントのメッセージを抽出します
4. MD5 ハッシュの比較を使用して重複を排除します
5. オブザーバーのプロンプト（優先度に基づく圧縮）を添えて LLM に送信します
6. 結果を observations.md に追記します
7. 観察内容が語数のしきい値を超えると、リフレクターを起動します

リフレクター

1. 現在の観察内容をバックアップします
2. 統合の指示とともにログ全体を LLM に送信します
3. 出力が入力より短いことを検証します（妥当性チェック）
4. 観察内容を統合済みのバージョンに置き換えます
5. 古いバックアップを削除します（直近 10 件を保持）

セッションの復旧

1. /new または /reset のたびに実行します
2. 最後のセッションファイルの最近の行をハッシュ化します
3. 最後のオブザーバー実行時に保存されたハッシュと比較します
4. 不一致の場合：復旧モード（過去 4 時間を対象）でオブザーバーを実行します
5. フォールバック：オブザーバーが失敗した場合、メッセージをそのまま抽出します

リアクティブウォッチャー

1. inotifywait を使用してセッションディレクトリを監視します
2. メインセッションファイルへの JSONL 書き込みのみをカウントします
3. 40 行以上になった後、オブザーバーを起動します（5 分間のクールダウンあり）
4. cron／外部オブザーバーの実行を検出すると、カウンターをリセットします

プロンプトのカスタマイズ

オブザーバーとリフレクターのシステムプロンプトは prompts/ にあります。

• prompts/observer-system.txt — 会話の圧縮方法を制御します
• prompts/reflector-system.txt — 観察内容の統合方法を制御します

これらを編集して、エージェントの性格や優先事項に合わせてください。

---

ドリームサイクル

ドリームサイクルは、observations.md を統合するために営業時間外に実行される、オプションの夜間エージェントです。古くなった項目をアーカイブし、セマンティックフックを追加するため、有用な情報が実際に失われることはありません。コンテキストを簡潔に保ちながら、すべての情報を見つけられる状態にします。

実行内容

• すべての観察内容を影響度（critical／high／medium／low／minimal）と経過時間で分類します
• 関連性のしきい値を過ぎた項目をアーカイブします
• アーカイブした各項目にセマンティックフック（具体的なキーワード＋アーカイブ参照）を追加します
• 結果を検証し、問題が発生した場合は自動的にロールバックします

機能

複数フックによる検索 — アーカイブされた各項目に、検索語の異なる候補を4～5個用意します。元の記述とは異なる語句で検索しても、メモリが見つかります。

信頼度スコア — 各観察には、信頼度スコア（0.0～1.0）とソースの種類（explicit、implicit、inference、weak、uncertain）が付与されます。信頼度の高い項目はより長く保持され、低い項目はより早くアーカイブされます。

メモリタイプシステム — タイプごとにTTLを設定した7つのタイプがあります：event（14日）、fact（90日）、preference（180日）、goal（365日）、habit（365日）、rule（無期限）、context（30日）。observations.md内の、通常は見えないHTMLメタデータコメントとして埋め込まれます。

観察のチャンク化 — 関連する観察が3件以上あるクラスターを、単一の要約エントリーにまとめます。元の観察はアーカイブされ、チャンクフックがその内容を置き換えます。トークン数を最大75％削減できます。

重要度の減衰 — 各アーカイブ判定の前に、タイプごとの1日あたりの減衰率を重要度スコアに適用します。アーカイブしきい値を下回るまで減衰した項目は、削除待ちのキューに追加されます。減衰率：event（-0.5/日）、fact（-0.1/日）、preference（-0.02/日）、rule／habit／goal（減衰なし）。

パターンの昇格 — 最近のドリームログをスキャンし、繰り返し現れるテーマ（3日以上にわたり、3回以上出現）を検出します。人が確認できるよう、昇格の提案をmemory/dream-staging/に書き込みます。staging-review.shを使って、提案の一覧表示、内容確認、承認、却下を行えます。contextタイプが自動的に昇格されることはありません。

セットアップ

1. bash skills/total-recall/scripts/setup.shを実行します — Dream Cycleのディレクトリが自動的に作成されます。

2. 夜間のcronジョブを、エージェントの完全なターンとして追加します：

   # Dream Cycle — nightly (3am recommended; adjust to your timezone)
   # The dream cycle runs as a full agent turn — NOT as a direct bash call.
   # dream-cycle.sh is a file operations helper called BY the agent, not the entry point.
   #
   # 0 3 * * * bash -c 'source ~/.openclaw/shared/secrets/openclaw-secrets.env \
   #   && openclaw agent --agent main \
   #   --message "Run the Total Recall Dream Cycle. Follow the instructions in \
   # $WORKSPACE/skills/total-recall/prompts/dream-cycle-prompt.md exactly. \
   # Use READ_ONLY_MODE=false and DREAM_PHASE=1." \
   #   --json >> $WORKSPACE/logs/dream-cycle.log 2>&1'
   

3. prompts/dream-cycle-prompt.mdをシステムプロンプトとして使い、cronエージェントを設定します。推奨モデル：Dreamer（分析と判断）にはClaude Sonnet、Observer（低コストで高速）にはDeepSeek v3.2。

4. 最初の数夜はREAD_ONLY_MODE=trueで実行します。各実行後にmemory/dream-logs/を確認し、アーカイブ予定の内容を検証してください。

5. 問題がないことを確認したら、READ_ONLY_MODE=falseに切り替えます。

設定

変数	デフォルト	説明
DREAM_TOKEN_TARGET	8000	統合後のobservations.mdの目標トークン数
READ_ONLY_MODE	false	書き込みを行わずにドライラン分析を行うにはtrueに設定

ファイル

ファイル	説明
scripts/dream-cycle.sh	エージェントが呼び出すシェルヘルパー（単独で実行するランナーではありません）：事前チェック、アーカイブ、観察の更新、ログの書き込み、メトリクスの書き込み、検証、ロールバック
prompts/dream-cycle-prompt.md	夜間のDream Cycle実行で使うエージェントプロンプト
dream-cycle/README.md	Dream Cycleのクイックリファレンス
schemas/observation-format.md	拡張された観察メタデータ形式

作成されるディレクトリ

memory/
  archive/
    observations/        # Archived items (one .md file per night)
    chunks/              # Chunked observation groups
  dream-logs/            # Nightly run reports
  dream-staging/         # Pattern promotion proposals awaiting human review
  .dream-backups/        # Pre-run safety backups
research/
  dream-cycle-metrics/
    daily/               # JSON metrics per night

---

トラブルシューティング

Observerが実行されない場合

• エラーがないかlogs/observer.logを確認します
• OPENROUTER_API_KEYが設定され、有効であることを確認します
• cronが有効であることを確認します：crontab -l

セッション開始時に観察が読み込まれない場合

• エージェントの起動時の指示に、memory/observations.mdを読み込む処理が含まれていることを確認します
• MEMORY_DIRが正しい場所を指していることを確認します

リアクティブウォッチャーが起動しない場合（Linux）

• systemctl --user status total-recall-watcherを実行します
• inotify-toolsがインストールされていることを確認します：which inotifywait
• ウォッチャーのログを表示します：journalctl --user -u total-recall-watcher -f

Dream Cycleがアーカイブしすぎる場合

• READ_ONLY_MODE=trueを有効にし、運用を開始する前にドリームログを確認します
• DREAM_TOKEN_TARGETを上げると、1回の実行でアーカイブされる量を減らせます

Dream Cycleが十分にアーカイブしない場合

• DREAM_TOKEN_TARGETを下げると、より積極的な統合が行われます

---

着想を得た仕組み

このシステムは、睡眠中の人間の記憶の働き方から着想を得ています。海馬（観察役）が経験を記録し、睡眠中の記憶の固定化（振り返り役）によって、重要な記憶が強化され、不要な情報は取り除かれます。

詳しくはこちら：Your AI Has an Attention Problem

「火星に行くぞ。」――そう、エージェントの記憶を機能させましょう。