OpenClaw メモリ設定ガイド：検索最適化とQMDバックエンド設定

メモリ設定リファレンス

このページでは、OpenClaw のメモリ検索に関するすべての設定項目を紹介します。概念的な概要については、以下のドキュメントを確認してください。

• Memory Overview — メモリの仕組み
• Builtin Engine — デフォルトの SQLite バックエンド
• QMD Engine — ローカルファーストのサイドカー
• Memory Search — 検索パイプラインとチューニング

特に指定がない限り、すべてのメモリ検索設定は openclaw.json の agents.defaults.memorySearch 配下に記述します。

---

プロバイダーの選択

キー	型	デフォルト	説明
provider	string	自動検出	Embedding アダプター ID: openai, gemini, voyage, mistral, ollama, local
model	string	プロバイダーのデフォルト	Embedding モデル名
fallback	string	"none"	プライマリが失敗した際のフォールバック用アダプター ID
enabled	boolean	true	メモリ検索の有効化・無効化

自動検出の順序

provider が設定されていない場合、OpenClaw は利用可能なものを以下の順序で自動的に選択します。

1. local — memorySearch.local.modelPath が設定されており、ファイルが存在する場合。
2. openai — OpenAI のキーが解決できる場合。
3. gemini — Gemini のキーが解決できる場合。
4. voyage — Voyage のキーが解決できる場合。
5. mistral — Mistral のキーが解決できる場合。

ollama もサポートされていますが、自動検出はされません。利用する場合は明示的に設定してください。

API key の解決

リモートの Embedding を利用するには API key が必要です。OpenClaw は、auth profiles、models.providers.*.apiKey、環境変数などから解決します。

プロバイダー	環境変数	設定キー
OpenAI	OPENAI_API_KEY	models.providers.openai.apiKey
Gemini	GEMINI_API_KEY	models.providers.google.apiKey
Voyage	VOYAGE_API_KEY	models.providers.voyage.apiKey
Mistral	MISTRAL_API_KEY	models.providers.mistral.apiKey
Ollama	OLLAMA_API_KEY (プレースホルダー)	—

Codex OAuth は chat/completions のみをカバーしています。Embedding のリクエストには対応していないので注意

ハイブリッド検索の設定

設定はすべて memorySearch.query.hybrid の下で行います。

キー	型	デフォルト	説明
enabled	boolean	true	BM25 とベクトル検索を組み合わせたハイブリッド検索を有効にします
vectorWeight	number	0.7	ベクトルスコアの重み (0-1)
textWeight	number	0.3	BM25 スコアの重み (0-1)
candidateMultiplier	number	4	候補プールのサイズの倍率

MMR（多様性）

キー	型	デフォルト	説明
mmr.enabled	boolean	false	MMR によるリランキングを有効にします
mmr.lambda	number	0.7	0 = 多様性を最大化、1 = 関連性を最大化

時間的減衰（最新性）

キー	型	デフォルト	説明
temporalDecay.enabled	boolean	false	最新性のブーストを有効にします
temporalDecay.halfLifeDays	number	30	スコアが半分になる日数

Evergreen ファイル（MEMORY.md や memory/ 内の日付のないファイル）は、時間の経過によってスコアが減衰することはありません。

設定例

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

---

メモリパスの追加

キー	型	説明
extraPaths	string[]	インデックスを作成する追加のディレクトリまたはファイル

{
  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 と並行して画像や音声をインデックスに含めることができます。

Key	Type	Default	Description
multimodal.enabled	boolean	false	マルチモーダルインデックスを有効にする
multimodal.modalities	string[]	—	["image"], ["audio"], または ["all"]
multimodal.maxFileBytes	number	10000000	インデックス対象の最大ファイルサイズ

この設定は extraPaths 内のファイルにのみ適用されます。デフォルトのメモリールートは Markdown のみのまま維持されます。 利用には gemini-embedding-2-preview が必要です。また、fallback は "none" に設定してください。

サポートされている形式： .jpg, .jpeg, .png, .webp, .gif, .heic, .heif（画像）、 .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac（音声）。

---

エンベディングキャッシュ

Key	Type	Default	Description
cache.enabled	boolean	false	チャンクのエンベディングを SQLite にキャッシュする
cache.maxEntries	number	50000	キャッシュされるエンベディングの最大数

再インデックスや文字起こしの更新を行う際、内容に変更のないテキストの再エンベディング処理をスキップできます。

バッチインデックス作成

大量のデータを一度に処理したいときは、Batch indexing（バッチインデックス作成）が便利です。API の制限を気にせず、効率的にデータを同期できます。

Key	Type	Default	Description
remote.batch.enabled	boolean	false	バッチ埋め込み API を有効化
remote.batch.concurrency	number	2	並列バッチジョブ数
remote.batch.wait	boolean	true	バッチ完了まで待機
remote.batch.pollIntervalMs	number	—	ポーリング間隔
remote.batch.timeoutMinutes	number	—	バッチのタイムアウト時間

この機能は openai、gemini、voyage で利用可能です。特に大規模なデータのバックフィル（過去データの再登録）を行うなら、OpenAI の Batch API が最も高速でコストも抑えられるのでおすすめです。

---

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

過去のやり取りを最大限に活用するための機能です。セッションのログをインデックス化して、memory_search 経由で呼び出せるようになります。

Key	Type	Default	Description
experimental.sessionMemory	boolean	false	セッションのインデックス作成を有効化
sources	string[]	["memory"]	"sessions" を追加してログを含める
sync.sessions.deltaBytes	number	100000	再インデックスを行うバイト数の閾値
sync.sessions.deltaMessages	number	50	再インデックスを行うメッセージ数の閾値

セッションのインデックス作成はオプトイン方式で、バックグラウンド（非同期）で実行されます。そのため、検索結果に最新の会話が反映されるまで少し時間がかかる場合があります。また、セッションログはディスク上に保存されるため、ファイルシステムへのアクセス権限を信頼境界として適切に管理してください。

SQLite ベクトルアクセラレーション (sqlite-vec)

キー	型	デフォルト値	説明
store.vector.enabled	boolean	true	ベクトルクエリに sqlite-vec を使用する
store.vector.extensionPath	string	bundled	sqlite-vec のパスを上書きする

sqlite-vec が利用できない場合、OpenClaw は自動的にプロセス内での cosine similarity 計算に切り替わります。

---

インデックスの保存

キー	型	デフォルト値	説明
store.path	string	~/.openclaw/memory/{agentId}.sqlite	インデックスの保存場所（{agentId} トークンをサポート）
store.fts.tokenizer	string	unicode61	FTS5 tokenizer (unicode61 または trigram)

---

QMD バックエンド設定

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

キー	型	デフォルト値	説明
command	string	qmd	QMD 実行ファイルのパス
searchMode	string	search	検索コマンド: search, vsearch, query
includeDefaultMemory	boolean	true	MEMORY.md と memory/**/*.md を自動インデックスする
paths[]	array	—	追加パス: { name, path, pattern? }
sessions.enabled	boolean	false	セッションの書き起こしをインデックスする
sessions.retentionDays	number	—	書き起こしの保持期間
sessions.exportDir	string	—	エクスポート先ディレクトリ

アップデートスケジュール

キー	型	デフォルト値	説明
update.interval	string	5m	リフレッシュの間隔
update.debounceMs	number	15000	ファイル変更のデバウンス時間
update.onBoot	boolean	true	起動時にリフレッシュする
update.waitForBootSync	boolean	false	リフレッシュが完了するまで起動をブロックする
update.embedInterval	string	—	個別の埋め込み（embed）サイクル
update.commandTimeoutMs	number	—	QMD コマンドのタイムアウト時間

制限事項

キー	型	デフォルト値	説明
limits.maxResults	number	6	検索結果の最大数
limits.maxSnippetChars	number	—	スニペットの長さを制限する
limits.maxInjectedChars	number	—	注入される総文字数を制限する
limits.timeoutMs	number	4000	検索のタイムアウト時間

スコープ

どのセッションが QMD の検索結果を受け取れるかを制御します。設定方法は session.sendPolicy と同じスキーマを使用します。

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

デフォルトは DM（ダイレクトメッセージ）のみです。match.keyPrefix は正規化されたセッションキーに一致し、match.rawKeyPrefix は agent:<id>: を含む生のキーに一致します。

引用

memory.citations はすべてのバックエンドに適用されます。

値	挙動
auto (デフォルト)	スニペットのフッターに Source: <path#line> を含める
on	常にフッターを含める
off	フッターを省略する（パス情報は内部的にエージェントへ渡されます）

QMD の設定例

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

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