Active Memory は、対象となる会話セッションでメイン応答の前に実行される、Plugin 所有の任意のブロッキングメモリサブエージェントです。 これは、ほとんどのメモリシステムが高機能ではあるもののリアクティブだからです。メインエージェントがメモリを検索するタイミングを判断するか、ユーザーが「これを覚えて」や「メモリを検索して」のように言うことに依存しています。その時点では、メモリが応答を自然に感じさせるはずだった瞬間はすでに過ぎています。 Active Memory は、メイン応答が生成される前に関連するメモリを表面化するための、境界付けられた 1 回の機会をシステムに与えます。Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
クイックスタート
安全なデフォルト設定として、これをopenclaw.json に貼り付けます。Plugin を有効にし、main エージェントにスコープし、ダイレクトメッセージセッションのみに限定し、利用可能な場合はセッションモデルを継承します。
plugins.entries.active-memory.enabled: trueは Plugin を有効にしますconfig.agents: ["main"]はmainエージェントのみを Active Memory にオプトインしますconfig.allowedChatTypes: ["direct"]はダイレクトメッセージセッションにスコープします（グループ/チャンネルは明示的にオプトインします）config.model（任意）は専用のリコールモデルを固定します。未設定の場合は現在のセッションモデルを継承しますconfig.modelFallbackは、明示的なモデルも継承されたモデルも解決されない場合にのみ使われますconfig.promptStyle: "balanced"はrecentモードのデフォルトです- Active Memory は、対象となるインタラクティブな永続チャットセッションでのみ実行されます
速度に関する推奨事項
最も単純な設定は、config.model を未設定のままにし、Active Memory に通常の応答ですでに使っているものと同じモデルを使わせることです。これは既存のプロバイダー、認証、モデル設定に従うため、最も安全なデフォルトです。
Active Memory をより高速に感じさせたい場合は、メインチャットモデルを借用するのではなく、専用の推論モデルを使います。リコール品質は重要ですが、メイン回答経路よりもレイテンシが重要であり、Active Memory のツール面は狭いです（利用可能なメモリリコールツールのみを呼び出します）。
高速モデルのよい選択肢:
- 専用の低レイテンシリコールモデルとして
cerebras/gpt-oss-120b - プライマリチャットモデルを変更せずに使う低レイテンシフォールバックとして
google/gemini-3-flash config.modelを未設定にすることで使う通常のセッションモデル
Cerebras のセットアップ
Cerebras プロバイダーを追加し、Active Memory をそれに向けます。chat/completions アクセスを持っていることを確認してください。/v1/models で見えるだけでは保証されません。
表示を確認する方法
Active Memory は、モデルに非表示の信頼されていないプロンプト接頭辞を注入します。通常のクライアント可視の応答には、生の<active_memory_plugin>...</active_memory_plugin> タグを公開しません。
セッション切り替え
設定を編集せずに、現在のチャットセッションで Active Memory を一時停止または再開したい場合は、Plugin コマンドを使います。plugins.entries.active-memory.enabled、エージェントターゲティング、その他のグローバル設定は変更しません。
コマンドで設定を書き込み、すべてのセッションで Active Memory を一時停止または再開したい場合は、明示的なグローバル形式を使います。
plugins.entries.active-memory.config.enabled を書き込みます。plugins.entries.active-memory.enabled はオンのままにするため、後で Active Memory を再びオンにするコマンドは引き続き利用できます。
ライブセッションで Active Memory が何をしているかを確認したい場合は、必要な出力に対応するセッション切り替えをオンにします。
/verbose onのとき、Active Memory: status=ok elapsed=842ms query=recent summary=34 charsのような Active Memory ステータス行/trace onのとき、Active Memory Debug: Lemon pepper wings with blue cheese.のような読みやすいデバッグ要約
/trace raw も有効にすると、トレースされた Model Input (User Role) ブロックには、非表示の Active Memory 接頭辞が次のように表示されます。
実行されるタイミング
Active Memory は 2 つのゲートを使います。- 設定によるオプトイン
Plugin が有効であり、現在のエージェント ID が
plugins.entries.active-memory.config.agentsに含まれている必要があります。 - 厳密な実行時適格性 有効化され、ターゲットになっている場合でも、Active Memory は対象となるインタラクティブな永続チャットセッションでのみ実行されます。
セッションタイプ
config.allowedChatTypes は、どの種類の会話で Active Memory を実行できるかを制御します。
デフォルトは次のとおりです。
config.allowedChatIds と config.deniedChatIds を使います。
allowedChatIds は、解決済み会話 ID の明示的な許可リストです。空でない場合、Active Memory はセッションの会話 ID がそのリストに含まれる場合にのみ実行されます。これは、ダイレクトメッセージを含むすべての許可済みチャットタイプを一度に狭めます。すべてのダイレクトメッセージに加えて特定のグループだけを許可したい場合は、ダイレクトピア ID を allowedChatIds に含めるか、テスト中のグループ/チャンネルロールアウトに allowedChatTypes を集中させます。
deniedChatIds は明示的な拒否リストです。これは常に allowedChatTypes と allowedChatIds より優先されるため、一致する会話は、そのセッションタイプが他の点では許可されていてもスキップされます。
ID は永続チャンネルセッションキーに由来します。たとえば Feishu の chat_id / open_id、Telegram のチャット ID、Slack のチャンネル ID です。マッチングでは大文字と小文字は区別されません。allowedChatIds が空でなく、OpenClaw がセッションの会話 ID を解決できない場合、Active Memory は推測せずにそのターンをスキップします。
例:
実行される場所
Active Memory は、会話を補強する機能であり、プラットフォーム全体の推論機能ではありません。| サーフェス | Active Memory を実行するか？ |
|---|---|
| Control UI / Web チャット永続セッション | はい。Plugin が有効で、エージェントがターゲットになっている場合 |
| 同じ永続チャットパス上のその他のインタラクティブチャンネルセッション | はい。Plugin が有効で、エージェントがターゲットになっている場合 |
| ヘッドレスのワンショット実行 | いいえ |
| Heartbeat/バックグラウンド実行 | いいえ |
汎用内部 agent-command パス | いいえ |
| サブエージェント/内部ヘルパー実行 | いいえ |
使う理由
Active Memory は次の場合に使います。- セッションが永続的でユーザー向けである
- エージェントに検索する価値のある長期メモリがある
- 素のプロンプト決定性よりも、継続性とパーソナライズが重要である
- 安定した好み
- 繰り返し発生する習慣
- 自然に表面化すべき長期的なユーザーコンテキスト
- 自動化
- 内部ワーカー
- ワンショット API タスク
- 非表示のパーソナライズが意外に感じられる場所
仕組み
実行時の形は次のとおりです。 ブロッキングメモリサブエージェントは、設定されたメモリリコールツールのみを使用できます。デフォルトでは次のとおりです。memory_searchmemory_get
plugins.slots.memory が memory-lancedb の場合、代わりにデフォルトは memory_recall です。別のメモリプロバイダーが異なるリコールツール契約を公開している場合は、config.toolsAllow を設定します。
関連性が弱い場合は、NONE を返すべきです。
クエリモード
config.queryMode は、ブロッキングメモリサブエージェントがどれだけの会話を見るかを制御します。フォローアップ質問に十分答えられる範囲で最小のモードを選びます。タイムアウト予算はコンテキストサイズに応じて増やすべきです（message < recent < full）。
- message
- recent
- full
最新のユーザーメッセージのみが送信されます。次の場合に使います。
- 最速の動作が必要
- 安定した好みのリコールに対する最も強いバイアスが必要
- フォローアップターンに会話コンテキストが不要
config.timeoutMs は 3000 から 5000 ms 付近から始めます。プロンプトスタイル
config.promptStyle は、メモリーを返すかどうかを判断するときに、ブロッキングメモリーサブエージェントがどれだけ積極的または厳格に振る舞うかを制御します。
利用可能なスタイル:
balanced:recentモード向けの汎用デフォルトstrict: 最も積極的でない。近接コンテキストからの混入を非常に少なくしたい場合に最適contextual: 継続性を最も重視する。会話履歴をより重視すべき場合に最適recall-heavy: やや弱いが妥当性のある一致でも、より積極的にメモリーを提示するprecision-heavy: 一致が明白でない限り、積極的にNONEを優先するpreference-only: お気に入り、習慣、ルーティン、好み、繰り返し現れる個人的な事実向けに最適化
config.promptStyle が未設定の場合のデフォルトマッピング:
config.promptStyle を明示的に設定した場合は、その上書きが優先されます。
例:
モデルフォールバックポリシー
config.model が未設定の場合、Active Memory は次の順序でモデルの解決を試みます。
config.modelFallback は、設定済みフォールバックのステップを制御します。
任意のカスタムフォールバック:
config.modelFallbackPolicy は、古い設定向けの非推奨の互換性フィールドとしてのみ保持されています。これはもう実行時の挙動を変更しません。
メモリーツール
デフォルトでは、Active Memory はブロッキングリコールサブエージェントがmemory_search と memory_get を呼び出せるようにします。これは組み込みの memory-core 契約と一致します。plugins.slots.memory が memory-lancedb を選択し、config.toolsAllow が未設定の場合、Active Memory は既存の LanceDB の挙動を維持し、代わりに memory_recall を使用します。
別のメモリー Plugin を使用する場合は、その Plugin が登録する正確なツール名を config.toolsAllow に設定してください。Active Memory はそれらのツールをリコールプロンプトに列挙し、同じリストを埋め込みサブエージェントに渡します。設定されたツールがどれも利用できない場合、またはメモリーサブエージェントが失敗した場合、Active Memory はそのターンのリコールをスキップし、メイン返信はメモリーコンテキストなしで続行されます。toolsAllow が受け付けるのは具体的なメモリーツール名のみです。ワイルドカード、group:* エントリー、および read、exec、message、web_search などのコアエージェントツールは、隠しメモリーサブエージェントが開始する前に無視されます。
デフォルト挙動に関する注記: Active Memory は、memory-core のデフォルト許可リストに memory_recall を含めなくなりました。既存の memory-lancedb セットアップは、plugins.slots.memory が memory-lancedb に設定されていれば引き続き動作します。明示的な toolsAllow は常に自動デフォルトを上書きします。
組み込みの memory-core
デフォルトセットアップでは、明示的なtoolsAllow は不要です。
LanceDB メモリー
バンドルされたmemory-lancedb Plugin は memory_recall を公開します。メモリースロットを選択するだけで、Active Memory はそのリコールツールを使用できます。
Lossless Claw
Lossless Claw は、独自のリコールツールを持つコンテキストエンジン Plugin です。まずコンテキストエンジンとしてインストールして設定してください。詳しくは コンテキストエンジン を参照してください。その後、Active Memory に Lossless Claw のリコールツールを使用させます。toolsAllow には lcm_expand を含めないでください。Lossless Claw はこれを、より低レベルの委任された展開ツールとして使用します。
高度な回避手段
これらのオプションは、意図的に推奨セットアップの一部にはしていません。config.thinking は、ブロッキングメモリーサブエージェントの思考レベルを上書きできます。
config.promptAppend は、デフォルトの Active Memory プロンプトの後、会話コンテキストの前に、追加のオペレーター指示を追加します。
toolsAllow とともに promptAppend を使用してください。
config.promptOverride は、デフォルトの Active Memory プロンプトを置き換えます。OpenClaw はその後に会話コンテキストを引き続き追加します。
NONE またはコンパクトなユーザー事実コンテキストのいずれかを返すよう調整されています。
トランスクリプトの永続化
Active Memory のブロッキングメモリーサブエージェント実行は、ブロッキングメモリーサブエージェント呼び出し中に実際のsession.jsonl トランスクリプトを作成します。
デフォルトでは、そのトランスクリプトは一時的です。
- 一時ディレクトリに書き込まれる
- ブロッキングメモリーサブエージェント実行にのみ使用される
- 実行完了直後に削除される
config.transcriptDir で変更できます。
これは慎重に使用してください。
- ブロッキングメモリーサブエージェントのトランスクリプトは、忙しいセッションでは急速に蓄積する可能性がある
fullクエリモードでは、多くの会話コンテキストが重複する可能性がある- これらのトランスクリプトには、隠しプロンプトコンテキストとリコールされたメモリーが含まれる
設定
すべての Active Memory 設定は次の場所にあります。| キー | 型 | 意味 |
|---|---|---|
enabled | boolean | Plugin 自体を有効化します |
config.agents | string[] | active memory を使用できるエージェント ID |
config.model | string | 任意のブロッキング memory サブエージェントのモデル参照。未設定の場合、active memory は現在のセッションモデルを使用します |
config.allowedChatTypes | ("direct" | "group" | "channel")[] | Active Memory を実行できるセッションタイプ。デフォルトはダイレクトメッセージ形式のセッションです |
config.allowedChatIds | string[] | allowedChatTypes の後に適用される、任意の会話単位の許可リスト。空でないリストはフェイルクローズします |
config.deniedChatIds | string[] | 許可されたセッションタイプと許可された ID を上書きする、任意の会話単位の拒否リスト |
config.queryMode | "message" | "recent" | "full" | ブロッキング memory サブエージェントが参照する会話量を制御します |
config.promptStyle | "balanced" | "strict" | "contextual" | "recall-heavy" | "precision-heavy" | "preference-only" | memory を返すかどうかを判断するときに、ブロッキング memory サブエージェントがどの程度積極的または厳格に振る舞うかを制御します |
config.toolsAllow | string[] | ブロッキング memory サブエージェントが呼び出せる具体的な memory ツール名。デフォルトは ["memory_search", "memory_get"]、または plugins.slots.memory が memory-lancedb の場合は ["memory_recall"] です。ワイルドカード、group:* エントリ、コアエージェントツールは無視されます |
config.thinking | "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "adaptive" | "max" | ブロッキング memory サブエージェント向けの高度な thinking 上書き。速度のため、デフォルトは off です |
config.promptOverride | string | 高度な完全プロンプト置換。通常の使用では推奨されません |
config.promptAppend | string | デフォルトまたは上書きされたプロンプトに追加される高度な追加指示 |
config.timeoutMs | number | ブロッキング memory サブエージェントのハードタイムアウト。上限は 120000 ms です |
config.setupGraceTimeoutMs | number | recall タイムアウトが切れる前の高度な追加セットアップ予算。デフォルトは 0 で、上限は 30000 ms です。v2026.4.x のアップグレードガイダンスについては コールドスタート猶予 を参照してください |
config.maxSummaryChars | number | active-memory 要約で許可される最大合計文字数 |
config.logging | boolean | チューニング中に active memory ログを出力します |
config.persistTranscripts | boolean | 一時ファイルを削除せず、ブロッキング memory サブエージェントのトランスクリプトをディスク上に保持します |
config.transcriptDir | string | エージェントセッションフォルダー配下の、相対ブロッキング memory サブエージェントトランスクリプトディレクトリ |
| キー | 型 | 意味 |
|---|---|---|
config.maxSummaryChars | number | active-memory 要約で許可される最大合計文字数 |
config.recentUserTurns | number | queryMode が recent の場合に含める以前のユーザーターン |
config.recentAssistantTurns | number | queryMode が recent の場合に含める以前のアシスタントターン |
config.recentUserChars | number | 最近のユーザーターンごとの最大文字数 |
config.recentAssistantChars | number | 最近のアシスタントターンごとの最大文字数 |
config.cacheTtlMs | number | 繰り返される同一クエリに対するキャッシュ再利用 (範囲: 1000-120000 ms、デフォルト: 15000) |
config.circuitBreakerMaxTimeouts | number | 同じエージェント/モデルでこの回数だけ連続タイムアウトした後、recall をスキップします。recall が成功したとき、またはクールダウンが切れた後にリセットされます (範囲: 1-20、デフォルト: 3)。 |
config.circuitBreakerCooldownMs | number | サーキットブレーカーが作動した後に recall をスキップする時間 (ms) (範囲: 5000-600000、デフォルト: 60000)。 |
推奨セットアップ
recent から始めます。
/verbose on、active-memory デバッグ要約には /trace on を使用します。チャットチャンネルでは、これらの診断行はメインのアシスタント返信の前ではなく後に送信されます。
その後、次に移行します:
- 低レイテンシーを求める場合は
message - 追加コンテキストが遅いブロッキング memory サブエージェントに見合うと判断した場合は
full
コールドスタート猶予
v2026.5.2 より前は、Plugin がコールドスタート中に設定済みのtimeoutMs を暗黙的に追加の 30000 ms だけ延長していたため、モデルのウォームアップ、埋め込みインデックスのロード、最初の recall が 1 つの大きな予算を共有できました。v2026.5.2 では、その猶予が明示的な setupGraceTimeoutMs 設定の背後に移動されました。オプトインしない限り、設定済みの timeoutMs がデフォルトの予算になります。
v2026.4.x からアップグレードし、古い暗黙的な猶予がある世界向けにチューニングされた値に timeoutMs を設定していた場合 (推奨スターターの timeoutMs: 15000 がその一例です)、setupGraceTimeoutMs: 30000 を設定して、プロンプトビルドフックと外側のウォッチドッグ予算を v5.2 以前の実効値まで戻してください:
setupGraceTimeoutMs 設定の背後に移動したため、Plugin はメインレーンで 15000 ms の設定を 45000 ms に暗黙的に延長しなくなりました。」
埋め込み recall ランナーは同じ実効タイムアウト予算を使用するため、setupGraceTimeoutMs は外側のプロンプト構築ウォッチドッグと内側のブロッキング recall 実行の両方を対象にします。
コールドスタートのレイテンシが既知のトレードオフである、リソースに余裕のない Gateway では、より低い値 (5000–15000 ms) も機能します。そのトレードオフは、Gateway の再起動後の最初の recall が、ウォームアップ完了前に空を返す可能性が高くなることです。
デバッグ
Active Memory が期待した場所に表示されない場合:- Plugin が
plugins.entries.active-memory.enabledで有効になっていることを確認します。 - 現在の agent id が
config.agentsに列挙されていることを確認します。 - 対話的な永続チャットセッションを通じてテストしていることを確認します。
config.logging: trueをオンにして Gateway ログを監視します。openclaw memory status --deepで memory search 自体が動作することを確認します。
maxSummaryChars
queryModeを下げるtimeoutMsを下げる- recent turn 数を減らす
- turn ごとの文字数上限を減らす
よくある問題
Active Memory は設定済み memory Plugin の recall パイプラインに乗るため、recall に関する予期しない挙動のほとんどは embedding provider の問題であり、Active Memory のバグではありません。デフォルトのmemory-core パスは memory_search と memory_get を使用し、memory-lancedb スロットは memory_recall を使用します。別の memory Plugin を使用する場合は、config.toolsAllow がその Plugin が実際に登録するツール名を指定していることを確認します。
Embedding provider switched or stopped working
Embedding provider switched or stopped working
memorySearch.provider が未設定の場合、OpenClaw は最初に利用可能な embedding provider を自動検出します。新しい API キー、クォータ枯渇、またはレート制限されたホスト型 provider により、実行間で解決される provider が変わることがあります。provider が解決されない場合、memory_search は lexical-only retrieval に劣化することがあります。provider がすでに選択された後のランタイム失敗では、自動的にフォールバックしません。選択を決定的にするには、provider (および任意の fallback) を明示的に固定します。provider の完全な一覧と固定の例については、Memory Search を参照してください。Recall feels slow, empty, or inconsistent
Recall feels slow, empty, or inconsistent
- セッション内で Plugin 所有の Active Memory デバッグ概要を表示するには、
/trace onをオンにします。 - 各返信後に
🧩 Active Memory: ...ステータス行も表示するには、/verbose onをオンにします。 active-memory: ... start|done、memory sync failed (search-bootstrap)、または provider embedding エラーについて Gateway ログを監視します。- memory-search バックエンドとインデックスの健全性を調べるには、
openclaw memory status --deepを実行します。 ollamaを使用している場合は、embedding モデルがインストールされていることを確認します (ollama list)。
First recall after gateway restart returns `status=timeout`
First recall after gateway restart returns `status=timeout`
v2026.5.2 以降では、最初の recall が発火する時点までにコールドスタート設定 (モデルのウォームアップ + embedding インデックスの読み込み) が完了していない場合、実行が設定済みの
timeoutMs 予算に達し、空の出力で status=timeout を返すことがあります。Gateway ログには、再起動後の最初の対象返信付近で active-memory timeout after Nms が表示されます。推奨される setupGraceTimeoutMs の値については、推奨設定の コールドスタート猶予 を参照してください。