メモリ設定リファレンス

このページでは、OpenClaw のメモリ検索に関するすべての設定項目を一覧にしています。概念的な概要については、以下を参照してください。

特に記載がない限り、メモリ検索のすべての設定は openclaw.json（またはエージェントごとの agents.list[].memorySearch オーバーライド）内の agents.defaults.memorySearch にあります。

プロバイダーの選択

provider が設定されていない場合、OpenClaw は OpenAI の埋め込みを使用します。Bedrock、DeepInfra、Gemini、GitHub Copilot、Mistral、Ollama、Voyage、ローカル GGUF モデル、または OpenAI 互換の /v1/embeddings エンドポイントを使用するには、provider を明示的に設定してください。provider: "auto" が残っているレガシー設定は、openai として解決されます。

provider が未設定の場合、レガシーの provider: "auto" が存在する場合、または provider: "none" で意図的に FTS 専用モードを選択している場合、埋め込みが利用できなくても、メモリの想起では語彙ベースの FTS ランキングを引き続き使用できます。

明示的に指定された非ローカルプロバイダーはフェイルクローズします。memorySearch.provider に Bedrock、DeepInfra、Gemini、GitHub Copilot、LM Studio、Mistral、Ollama、OpenAI、Voyage、または OpenAI 互換のカスタムプロバイダーなど、リモートバックエンドを使用する具体的なプロバイダーを設定し、そのプロバイダーが実行時に利用できない場合、memory_search は暗黙的に FTS 専用の想起を使用せず、利用不可の結果を返します。プロバイダーまたは認証の設定を修正するか、到達可能なプロバイダーに切り替えるか、意図的に FTS 専用の想起を使用する場合は provider: "none" を設定してください。

カスタムプロバイダー ID

memorySearch.provider は、ollama などのメモリ固有プロバイダーアダプター、または openai-responses / openai-completions などの OpenAI 互換モデル API 用のカスタム models.providers.<id> エントリを指すことができます。OpenClaw は、エンドポイント、認証、モデルプレフィックスの処理用にカスタムプロバイダー ID を維持しながら、埋め込みアダプターについてそのプロバイダーの api 所有者を解決します。これにより、複数 GPU または複数ホストの構成で、メモリ埋め込み専用の特定のローカルエンドポイントを使用できます。

{  models: {    providers: {      "ollama-5080": {        api: "ollama",        baseUrl: "http://gpu-box.local:11435",        apiKey: "ollama-local",        models: [{ id: "qwen3-embedding:0.6b", name: "Qwen3 Embedding 0.6B" }],      },    },  },  agents: {    defaults: {      memorySearch: {        provider: "ollama-5080",        model: "qwen3-embedding:0.6b",      },    },  },}

API キーの解決

リモート埋め込みには API キーが必要です。ただし、Bedrock は代わりに AWS SDK のデフォルト認証情報チェーン（インスタンスロール、SSO、アクセスキー、または Bedrock API キー）を使用します。

リモートエンドポイント設定

グローバルな OpenAI チャット認証情報を継承しない、汎用の OpenAI 互換 /v1/embeddings サーバーには provider: "openai-compatible" を使用します。

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        model: "text-embedding-3-small",        remote: {          baseUrl: "https://api.example.com/v1/",          apiKey: "YOUR_KEY",        },      },    },  },}

プロバイダー固有の設定

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        remote: {          baseUrl: "https://embeddings.example/v1",          apiKey: "${EMBEDDINGS_API_KEY}",        },        model: "asymmetric-embedder",        queryInputType: "query",        documentInputType: "passage",      },    },  },}

{  agents: {    defaults: {      memorySearch: {        provider: "bedrock",        model: "amazon.titan-embed-text-v2:0",      },    },  },}

{  "Effect": "Allow",  "Action": "bedrock:InvokeModel",  "Resource": "*"}

arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

openclaw memory status --deep --agent mainopenclaw memory index --force --agent main

インライン埋め込みのタイムアウト

インデックス作成の動作

特記がない限り、すべて memorySearch.sync 配下です。

ハイブリッド検索の設定

すべて memorySearch.query 配下です。

また、memorySearch.query.hybrid 配下には次の設定があります。

完全な例

{  agents: {    defaults: {      memorySearch: {        query: {          maxResults: 6,          minScore: 0.35,          hybrid: {            vectorWeight: 0.7,            textWeight: 0.3,            mmr: { enabled: true, lambda: 0.7 },            temporalDecay: { enabled: true, halfLifeDays: 30 },          },        },      },    },  },}

追加のメモリパス

{  agents: {    defaults: {      memorySearch: {        extraPaths: ["../team-docs", "/srv/shared-notes"],      },    },  },}

パスは絶対パスまたはワークスペース相対パスにできます。ディレクトリは .md ファイルを対象に再帰的にスキャンされます。シンボリックリンクの処理はアクティブなバックエンドによって異なります。組み込みエンジンはシンボリックリンクをスキップしますが、QMD は基盤となる QMD スキャナーの動作に従います。

エージェント単位のエージェント横断トランスクリプト検索には、memory.qmd.paths ではなく agents.list[].memorySearch.qmd.extraCollections を使用します。これらの追加コレクションは同じ { path, name, pattern? } 形式に従いますが、エージェントごとにマージされ、パスが現在のワークスペース外を指す場合は明示的な共有名を保持できます。同じ解決済みパスが memory.qmd.paths と memorySearch.qmd.extraCollections の両方に存在する場合、QMD は最初のエントリを保持し、重複をスキップします。

マルチモーダルメモリ（Gemini）

Gemini Embedding 2 を使用して、Markdown とともに画像と音声をインデックス化します。

対応形式：.jpg、.jpeg、.png、.webp、.gif、.heic、.heif（画像）、.mp3、.wav、.ogg、.opus、.m4a、.aac、.flac（音声）。

埋め込みキャッシュ

再インデックスやトランスクリプト更新時に、変更されていないテキストが再度埋め込み処理されるのを防ぎます。キャッシュを無制限にする場合は maxEntries を未設定のままにし、再インデックスの最高速度よりディスク使用量の増加が重要な場合は設定します。設定すると、キャッシュが上限を超えた時点で、最終更新日時が古いエントリから順に削除されます。

バッチインデックス

gemini、openai、voyage で利用できます。大量のバックフィルでは、通常 OpenAI のバッチが最も高速かつ低コストです。

remote.nonBatchConcurrency は、ローカル／セルフホスト型プロバイダー、およびプロバイダーのバッチ API が有効でない場合のホスト型プロバイダーで使用されるインライン埋め込み呼び出しを制御します。小規模なローカルホストへの過負荷を避けるため、Ollama の非バッチインデックスではデフォルト値が 1 です。より大規模なマシンでは、より大きい値を設定してください。

これは、インライン埋め込み呼び出しのタイムアウトを制御する sync.embeddingBatchTimeoutSeconds とは別の設定です。

セッションメモリ検索（実験的）

セッションのトランスクリプトをインデックス化し、memory_search を通じて提示します。

セッショントランスクリプトのヒットにも tools.sessions.visibility が適用されます。デフォルトの tree 可視性では、現在のセッションと、そのセッションから生成されたセッションのみが公開されます。DM など、別のセッションから、同じエージェントに Gateway 経由でディスパッチされた無関係なセッションを 呼び出すには、可視性を意図的に agent まで拡大してください（エージェント間の呼び出しも必要で、エージェント間ポリシーで許可されている場合のみ all）。

以下の例では、これらの設定を agents.defaults の下に配置しています。セッショントランスクリプトのインデックス化と検索を 1 つの エージェントだけに行わせる場合は、エージェント単位のオーバーライドに同等の memorySearch 設定を 適用することもできます。

同一エージェントで Gateway から DM を呼び出す場合：

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  tools: {    sessions: { visibility: "agent" },  },}

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  memory: {    backend: "qmd",    qmd: {      sessions: { enabled: true },    },  },  tools: {    sessions: { visibility: "agent" },  },}

QMD を使用する場合、agents.defaults.memorySearch.experimental.sessionMemory と sources: ["sessions"] だけでは、トランスクリプトは QMD にエクスポートされません。 memory.qmd.sessions.enabled: true も設定してください。

SQLite ベクトル高速化（sqlite-vec）

sqlite-vec が利用できない場合、OpenClaw は自動的にプロセス内のコサイン類似度へフォールバックします。

インデックスストレージ

組み込みのメモリインデックスは、各エージェントの OpenClaw SQLite データベース内の agents/<agentId>/agent/openclaw-agent.sqlite に保存されます。

QMD バックエンド設定

有効にするには memory.backend = "qmd" を設定します。すべての QMD 設定は memory.qmd の下に配置されます。

searchMode: "search" は字句／BM25 のみです。OpenClaw はこのモードに対して、memory status --deep の実行中も含め、セマンティックベクトルの準備状況プローブや QMD 埋め込みの保守を実行しません。vsearch と query では、引き続き QMD ベクトルの準備完了と埋め込みが必要です。

rerank: false は QMD の query モードのみを変更し、QMD 2.1 以降が必要です。直接 CLI モードでは OpenClaw は --no-rerank を渡し、mcporter 経由の MCP モードでは QMD の統合クエリツールに rerank: false を渡します。QMD のデフォルトのクエリ再ランキング動作を使用する場合は、未設定のままにしてください。

OpenClaw は現在の QMD コレクションと MCP クエリ形式を優先しますが、必要に応じて互換性のあるコレクションパターンフラグや旧 MCP ツール名を試すことで、古い QMD リリースも引き続き動作させます。QMD が複数のコレクションフィルターへの対応を通知する場合、同一ソースのコレクションは 1 つの QMD プロセスで検索されます。古い QMD ビルドでは、コレクションごとの互換性パスが維持されます。同一ソースとは、永続メモリコレクション（デフォルトのメモリファイルとカスタムパス）がまとめてグループ化されることを意味します。一方、セッショントランスクリプトのコレクションは別のグループとして維持されるため、ソースの多様化では引き続き両方の入力が使用されます。

mcporter 連携

すべて memory.qmd.mcporter の下に配置されます。クエリごとに qmd を起動する代わりに、長時間稼働する mcporter MCP デーモンを介して QMD 検索をルーティングし、大規模モデルのコールドスタートのオーバーヘッドを削減します。

mcporter がインストールされ PATH 上にあり、かつ qmd mcp を実行する mcporter サーバーが設定されている必要があります。クエリごとのプロセス起動コストを許容できる、より単純なローカル構成では無効のままにしてください。

{  memory: {    qmd: {      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },    },  },}

Gateway 起動時の QMD 初期化が有効な場合、OpenClaw は対象となるエージェントに対してのみ QMD を起動します。update.onBoot が true で、更新間隔または埋め込みメンテナンスが設定されていない場合、起動時にはブート更新用の単発マネージャーを使用し、完了後に閉じます。更新間隔または埋め込み間隔が設定されている場合、起動時に長期間稼働する QMD マネージャーを開き、ウォッチャーと間隔タイマーを管理できるようにします。update.onBoot: false がスキップするのは、起動直後の更新のみです。

QMD の完全な例

{  memory: {    backend: "qmd",    citations: "auto",    qmd: {      includeDefaultMemory: true,      update: { interval: "5m", debounceMs: 15000 },      limits: { maxResults: 4, timeoutMs: 4000 },      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],    },  },}

Dreaming

Dreaming は agents.defaults.memorySearch ではなく、plugins.entries.memory-core.config.dreaming で設定します。

Dreaming は単一のスケジュールされたスイープとして実行され、内部の light／deep／REM フェーズは実装の詳細として使用されます。

概念的な動作とスラッシュコマンドについては、Dreamingを参照してください。

ユーザー設定

例

{  plugins: {    entries: {      "memory-core": {        subagent: {          allowModelOverride: true,          allowedModels: ["anthropic/claude-sonnet-4-6"],        },        config: {          dreaming: {            enabled: true,            frequency: "0 3 * * *",            model: "anthropic/claude-sonnet-4-6",          },        },      },    },  },}

関連項目

• 設定リファレンス
• メモリの概要
• メモリ検索