OpenClaw Active Memory設定ガイド：会話の文脈を自動で最適化

AIと会話しているとき、「さっき言ったことを思い出して」と指示しなければならないのは少し面倒ですよね。多くのメモリーシステムは受動的で、ユーザーが指示した後にようやく動き出します。しかし、その時点ではすでに会話の自然な流れが途切れてしまっていることが多いものです。Active Memoryは、メインの返答が生成される前に、関連する記憶を自ら探しに行く仕組みを提供します。

エージェントに貼り付ける

Active Memoryを、安全なデフォルト設定ですぐに使い始めたい場合は、以下の設定をエージェントに貼り付けてください。

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          enabled: true,
          agents: ["main"],
          allowedChatTypes: ["direct"],
          modelFallbackPolicy: "default-remote",
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          persistTranscripts: false,
          logging: true,
        },
      },
    },
  },
}

この設定では、main エージェントでプラグインが有効になり、デフォルトでダイレクトメッセージ形式のセッションに限定されます。また、現在のセッションのモデルを優先的に継承し、モデルが指定されていない場合は組み込みのリモートフォールバックを使用します。

設定後、Gateway を再起動してください。

openclaw gateway

会話中にリアルタイムで動作を確認するには、以下のコマンドを使用します。

/verbose on

Active Memoryを有効にする

最も安全なセットアップ手順は以下の通りです。

1. プラグインを有効にする
2. 特定の会話エージェントを対象にする
3. 調整中のみロギングを有効にする

まず、openclaw.json に以下の内容を記述します。

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          allowedChatTypes: ["direct"],
          modelFallbackPolicy: "default-remote",
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          persistTranscripts: false,
          logging: true,
        },
      },
    },
  },
}

その後、Gateway を再起動します。

openclaw gateway

設定項目の意味は以下の通りです。

• plugins.entries.active-memory.enabled: true: プラグインを有効にします。
• config.agents: ["main"]: main エージェントのみを Active Memory の対象にします。
• config.allowedChatTypes: ["direct"]: デフォルトでダイレクトメッセージ形式のセッションのみで動作させます。
• config.model が未設定の場合、Active Memory は現在のセッションのモデルを継承します。
• config.modelFallbackPolicy: "default-remote": 明示的なモデルや継承されたモデルがない場合、組み込みのリモートフォールバックをデフォルトとして使用します。
• config.promptStyle: "balanced": recent モードに適した、汎用的なデフォルトのプロンプトスタイルを使用します。
• Active Memory は、対象となるインタラクティブな永続チャットセッションでのみ実行されます。

動作を確認する方法

Active Memory は、モデルに対して隠されたシステムコンテキストを注入します。クライアント側には、生の <active_memory_plugin>...</active_memory_plugin> タグが表示されることはありません。

セッションごとの切り替え

設定ファイルを編集せずに、現在のチャットセッションで Active Memory を一時停止したり再開したりするには、プラグインコマンドを使用します。

/active-memory status
/active-memory off
/active-memory on

これはセッション単位の設定です。plugins.entries.active-memory.enabled やエージェントの対象設定、その他のグローバル設定は変更されません。

コマンドによって設定を書き換え、すべてのセッションで Active Memory を一時停止または再開したい場合は、明示的にグローバルフォームを使用してください。

/active-memory status --global
/active-memory off --global
/active-memory on --global

グローバルフォームは plugins.entries.active-memory.config.enabled を書き換えます。後でコマンドから再度有効にできるように、plugins.entries.active-memory.enabled は true のまま維持されます。

実行中のセッションで Active Memory が何をしているか確認したい場合は、そのセッションで verbose モードを有効にします。

/verbose on

verbose モードを有効にすると、OpenClaw は以下の情報を表示します。

• Active Memory のステータスライン（例: Active Memory: ok 842ms recent 34 chars）
• 人間が読めるデバッグサマリー（例: Active Memory Debug: Lemon pepper wings with blue cheese.）

これらの行は、隠されたシステムコンテキストに送られるものと同じ Active Memory の処理から生成されますが、生のプロンプトマークアップではなく人間向けにフォーマットされています。

デフォルトでは、このメモリサブエージェントの実行ログは一時的なもので、実行完了後に削除されます。

実行例：

/verbose on
what wings should i order?

期待される返答の形式：

...normal assistant reply...

🧩 Active Memory: ok 842ms recent 34 chars
🔎 Active Memory Debug: Lemon pepper wings with blue cheese.

AI Setup Assistant

次のステップ

• Memory Systems の詳細
• Advanced Configuration

実行のタイミング

Active memoryが動作するには、2つのゲートを通過する必要があります。

1. Configでのオプトイン プラグインが有効化されており、かつ現在のagent idがplugins.entries.active-memory.config.agentsに含まれている必要があります。
2. 厳格なランタイム適格性 有効化され、対象に指定されている場合でも、Active memoryは適格なインタラクティブで永続的なチャットセッションでのみ実行されます。

実際のルールは以下の通りです：

plugin enabled
+
agent id targeted
+
allowed chat type
+
eligible interactive persistent chat session
=
active memory runs

これらの条件のいずれかが満たされない場合、Active memoryは実行されません。

セッションの種類

config.allowedChatTypesは、どの種類の会話でActive memoryを実行するかを制御します。

デフォルト設定は以下の通りです：

allowedChatTypes: ["direct"]

これは、Active memoryがデフォルトではダイレクトメッセージ形式のセッションで実行されることを意味します。グループやチャンネルのセッションで実行したい場合は、明示的に設定を追加してください。

設定例：

allowedChatTypes: ["direct"]

allowedChatTypes: ["direct", "group"]

allowedChatTypes: ["direct", "group", "channel"]

実行される場所

Active memoryは会話を豊かにするための機能であり、プラットフォーム全体の推論機能ではありません。

Surface	Runs active memory?
Control UI / web chat persistent sessions	Yes, if the plugin is enabled and the agent is targeted
Other interactive channel sessions on the same persistent chat path	Yes, if the plugin is enabled and the agent is targeted
Headless one-shot runs	No
Heartbeat/background runs	No
Generic internal agent-command paths	No
Sub-agent/internal helper execution	No

使用する理由

以下のような場合にActive memoryを使用するのがおすすめです。

• セッションが永続的でユーザーと対面しており、エージェントが検索可能な意味のある長期メモリを持っている場合
• 生のプロンプトの決定論よりも、継続性やパーソナライズが重要である場合

この機能は、特に以下のケースで効果を発揮します。

• 安定した好みや繰り返される習慣の把握
• 自然に表面化させるべき長期的なユーザーコンテキストの維持

一方で、以下のようなケースには適していません。

• 自動化
• 内部ワーカー
• ワンショットのAPIタスク
• 隠れたパーソナライズがユーザーを驚かせてしまうような場所

動作の仕組み

Active Memoryがどのように動作するのか、その流れを見ていきましょう。ランタイムの構成は以下のようになっています。

flowchart LR
  U["User Message"] --> Q["Build Memory Query"]
  Q --> R["Active Memory Blocking Memory Sub-Agent"]
  R -->|NONE or empty| M["Main Reply"]
  R -->|relevant summary| I["Append Hidden active_memory_plugin System Context"]
  I --> M["Main Reply"]

このメモリ用サブエージェント（blocking memory sub-agent）が使用できるのは、以下のツールのみです。

• memory_search
• memory_get

もし接続が不安定な場合は、NONE を返すようになっています。

クエリモード

config.queryMode を使用することで、メモリ用サブエージェントが会話のどの程度の範囲を参照できるかをコントロールできます。

プロンプトのスタイル

config.promptStyle は、メモリを呼び出す際の判断基準を「積極的」にするか、あるいは「厳格」にするかを設定するものです。

利用可能なスタイルは以下の通りです。

• balanced: recent モードでの汎用的なデフォルト設定です。
• strict: 最も厳格な設定です。周辺のコンテキストからの影響を最小限に抑えたい場合に適しています。
• contextual: コンテキストを重視する設定です。会話の履歴をより反映させたい場合に最適です。
• recall-heavy: 多少曖昧な一致であっても、積極的にメモリを表示させます。
• precision-heavy: 一致が明らかな場合を除き、厳しく NONE を返すようにします。
• preference-only: お気に入り、習慣、ルーチン、好み、繰り返し現れる個人の事実などに特化して最適化されています。

config.promptStyle が未設定の場合、デフォルトでは以下のようにマッピングされます。

message -> strict
recent -> balanced
full -> contextual

明示的に config.promptStyle を設定した場合は、その設定が優先されます。

例：

promptStyle: "preference-only"

モデルのフォールバックポリシー

config.model が設定されていない場合、Active Memoryは以下の順序でモデルの解決を試みます。

explicit plugin model
-> current session model
-> agent primary model
-> optional built-in remote fallback

この最後のステップを制御するのが config.modelFallbackPolicy です。

デフォルトの設定：

modelFallbackPolicy: "default-remote"

その他のオプション：

modelFallbackPolicy: "resolved-only"

明示的なモデルや継承されたモデルが利用できない場合に、組み込みのリモートデフォルトにフォールバックするのではなく、メモリの呼び出し自体をスキップしたいときは resolved-only を使用してください。

高度なエスケープハッチ

これらのオプションは、意図的に推奨設定には含まれていません。

config.thinking を使用すると、ブロッキングが発生する memory sub-agent の思考レベルを上書きできます。

thinking: "medium"

デフォルト設定：

thinking: "off"

これをデフォルトで有効にしないでください。Active Memory はリプライの経路で動作するため、思考時間を増やすとユーザーが感じるレイテンシに直接影響します。

config.promptAppend は、デフォルトの Active Memory プロンプトの後、かつ会話コンテキストの前に、追加のオペレーター指示を挿入します。

promptAppend: "Prefer stable long-term preferences over one-off events."

config.promptOverride は、デフォルトの Active Memory プロンプトを完全に置き換えます。OpenClaw は、その後に会話コンテキストを付加します。

promptOverride: "You are a memory search agent. Return NONE or one compact user fact."

プロンプトのカスタマイズは、異なるリコール契約を意図的にテストする場合を除き、推奨されません。デフォルトのプロンプトは、メインモデルに対して NONE またはコンパクトなユーザーの事実（user-fact）を返すように調整されています。

message

最新のユーザーメッセージのみが送信されます。

Latest user message only

次のような場合に使用してください：

• 最速の動作を求める場合
• 安定した好みのリコール（recall）を優先したい場合
• 後続のターンで会話のコンテキストを必要としない場合

推奨されるタイムアウト：

• 3000 から 5000 ms 程度から始めてください

recent

最新のユーザーメッセージに加えて、直近の短い会話履歴が送信されます。

Recent conversation tail:
user: ...
assistant: ...
user: ...

Latest user message:
...

次のような場合に使用してください：

• 速度と会話の整合性のバランスをとりたい場合
• 後続の質問が直近の数ターンに依存することが多い場合

推奨されるタイムアウト：

• 15000 ms 程度から始めてください

full

会話の全内容が、ブロッキングが発生する memory sub-agent に送信されます。

Full conversation context:
user: ...
assistant: ...
user: ...
...

次のような場合に使用してください：

• レイテンシよりも、リコールの品質を最優先する場合
• スレッドのかなり前の段階に重要な設定が含まれている場合

推奨されるタイムアウト：

• message や recent よりも大幅に長く設定してください
• スレッドのサイズに応じて、15000 ms 以上から始めてください

一般的に、タイムアウト設定はコンテキストのサイズに合わせて大きくする必要があります。

message < recent < full

トランスクリプトの永続化

Active Memory の memory sub-agent が実行されると、その呼び出し中に実際の session.jsonl トランスクリプトが作成されます。

デフォルトでは、このトランスクリプトは一時的なものです。

• 一時ディレクトリに書き込まれます
• memory sub-agent の実行にのみ使用されます
• 実行終了後、すぐに削除されます

デバッグや確認のために、これらのトランスクリプトをディスクに保存しておきたい場合は、明示的に永続化を有効にしてください。

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          persistTranscripts: true,
          transcriptDir: "active-memory",
        },
      },
    },
  },
}

有効にすると、Active Memory はトランスクリプトをメインのユーザー会話用パスではなく、対象エージェントのセッションフォルダ内にある別のディレクトリに保存します。

デフォルトのレイアウト構成は以下の通りです。

agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl

config.transcriptDir を使って、相対サブディレクトリを変更することも可能です。

ただし、使用には注意が必要です。

• セッションが多い場合、トランスクリプトがすぐに蓄積される可能性があります
• full クエリモードでは、多くの会話コンテキストが重複して保存されます
• これらのトランスクリプトには、隠されたプロンプトコンテキストやリコールされたメモリが含まれています

設定

すべての active memory の設定は、以下の配下にあります。

plugins.entries.active-memory

主な設定項目は以下の通りです。

Key	Type	Meaning
enabled	boolean	プラグイン自体を有効にします
config.agents	string[]	active memory を使用できる Agent の ID リスト
config.model	string	オプションの blocking memory sub-agent 用モデル。未設定の場合、現在のセッションモデルを使用します
config.queryMode	"message" | "recent" | "full"	blocking memory sub-agent が参照する会話の範囲を制御します
config.promptStyle	"balanced" | "strict" | "contextual" | "recall-heavy" | "precision-heavy" | "preference-only"	メモリを返すかどうかを判断する際の、blocking memory sub-agent の積極性や厳格さを制御します
config.thinking	"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "adaptive"	blocking memory sub-agent の高度な思考設定。速度優先のためデフォルトは off です
config.promptOverride	string	プロンプトの完全な置き換え（高度な設定。通常の使用では非推奨です）
config.promptAppend	string	デフォルトまたは上書きされたプロンプトに追加する指示
config.timeoutMs	number	blocking memory sub-agent のハードタイムアウト設定
config.maxSummaryChars	number	active-memory サマリーに許可される最大合計文字数
config.logging	boolean	チューニング中に active memory のログを出力します
config.persistTranscripts	boolean	一時ファイルを削除せず、blocking memory sub-agent の記録をディスクに保存します
config.transcriptDir	string	Agent セッションフォルダ内における、blocking memory sub-agent 記録用の相対ディレクトリ

チューニングに便利な項目は以下の通りです。

Key	Type	Meaning
config.maxSummaryChars	number	active-memory サマリーに許可される最大合計文字数
config.recentUserTurns	number	queryMode が recent の時に含める過去のユーザーの発言数
config.recentAssistantTurns	number	queryMode が recent の時に含める過去のアシスタントの発言数
config.recentUserChars	number	ユーザーの各発言の最大文字数
config.recentAssistantChars	number	アシスタントの各発言の最大文字数
config.cacheTtlMs	number	同一クエリが繰り返された場合のキャッシュ再利用時間

推奨設定

まずは recent モードから始めてみるのがおすすめです。

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          logging: true,
        },
      },
    },
  },
}

チューニング中に実際の動作を確認したい場合は、専用のデバッグコマンドを探す代わりに、セッション内で /verbose on を実行してみてください。

その後、必要に応じて設定を変更します。

• レイテンシを抑えたい場合は message
• 速度よりもコンテキストの量を重視する場合は full

デバッグ

Active memory が期待通りに表示されない場合は、まず以下の手順を確認してみてください。

1. plugins.entries.active-memory.enabled でプラグインが有効になっているか確認します。
2. 現在の Agent ID が config.agents にリストされているか確認してください。
3. インタラクティブな永続チャットセッションでテストを行っているか確認が必要です。
4. config.logging: true をオンにして、Gateway のログをチェックしましょう。
5. openclaw memory status --deep を実行して、Memory Search 自体が動作しているか検証してください。

もし Memory のヒット結果にノイズが多い（不要な情報が混ざる）場合は、以下の項目を調整して制限を厳しくするのがおすすめです。

• maxSummaryChars

Active memory の動作が遅いと感じる場合は、以下の設定値を下げてみてください。

• queryMode を低くする
• timeoutMs を短くする
• 直近のターン（turn）数を減らす
• 1ターンあたりの文字数制限（char caps）を小さくする

関連ページ

• Memory Search
• Memory configuration reference
• Plugin SDK setup