メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

メモリの概要

メモリの仕組み。

組み込みエンジン

デフォルトの SQLite バックエンド。

QMD エンジン

ローカルファーストのサイドカー。

メモリ検索

検索パイプラインとチューニング。

Active memory

対話型セッション用のメモリサブエージェント。
特に明記されていない限り、すべてのメモリ検索設定は openclaw.json の agents.defaults.memorySearch 配下にあります。
active memory 機能の切り替えとサブエージェント設定を探している場合、それは memorySearch ではなく plugins.entries.active-memory 配下にあります。Active memory は 2 つのゲートモデルを使用します。
  1. Plugin が有効化され、現在のエージェント ID を対象にしている必要がある
  2. リクエストが対象となる対話型の永続チャットセッションである必要がある
有効化モデル、Plugin が所有する設定、トランスクリプトの永続化、安全なロールアウトパターンについては、Active Memory を参照してください。

​
プロバイダーの選択

キー型デフォルト説明
providerstring自動検出bedrock、deepinfra、gemini、github-copilot、local、mistral、ollama、openai、voyage などの埋め込みアダプター ID。api がそれらのアダプターのいずれかを指す設定済みの models.providers.<id> も指定できます
modelstringプロバイダーのデフォルト埋め込みモデル名
fallbackstring"none"プライマリが失敗したときのフォールバックアダプター ID
enabledbooleantrueメモリ検索を有効または無効にする

​
自動検出の順序

provider が設定されていない場合、OpenClaw は最初に利用可能なものを選択します。
1

local

memorySearch.local.modelPath が設定され、ファイルが存在する場合に選択されます。
2

github-copilot

GitHub Copilot トークンを解決できる場合に選択されます（環境変数または認証プロファイル）。
3

openai

OpenAI キーを解決できる場合に選択されます。
4

gemini

Gemini キーを解決できる場合に選択されます。
5

voyage

Voyage キーを解決できる場合に選択されます。
6

mistral

Mistral キーを解決できる場合に選択されます。
7

deepinfra

DeepInfra キーを解決できる場合に選択されます。
8

bedrock

AWS SDK の認証情報チェーンを解決できる場合に選択されます（インスタンスロール、アクセスキー、プロファイル、SSO、Web ID、共有設定）。
ollama はサポートされていますが、自動検出されません（明示的に設定してください）。

​
カスタムプロバイダー ID

memorySearch.provider はカスタム models.providers.<id> エントリを指すことができます。OpenClaw は埋め込みアダプター用にそのプロバイダーの api 所有者を解決しつつ、エンドポイント、認証、モデルプレフィックス処理にはカスタムプロバイダー ID を保持します。これにより、マルチ GPU またはマルチホスト構成で、特定のローカルエンドポイントにメモリ埋め込みを専用化できます。 
{
  models: {
    providers: {
      "ollama-5080": {
        api: "ollama",
        baseUrl: "http://gpu-box.local:11435",
        apiKey: "ollama-local",
        models: [{ id: "qwen3-embedding:0.6b" }],
      },
    },
  },
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama-5080",
        model: "qwen3-embedding:0.6b",
      },
    },
  },
}

​
API キーの解決

リモート埋め込みには API キーが必要です。Bedrock は代わりに AWS SDK のデフォルト認証情報チェーンを使用します（インスタンスロール、SSO、アクセスキー）。
プロバイダー環境変数設定キー
BedrockAWS 認証情報チェーンAPI キーは不要
DeepInfraDEEPINFRA_API_KEYmodels.providers.deepinfra.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKENデバイスログインによる認証プロファイル
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY（プレースホルダー）—
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
Codex OAuth はチャット/補完のみを対象としており、埋め込みリクエストには使用できません。

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

カスタム OpenAI 互換エンドポイント、またはプロバイダーのデフォルトを上書きする場合:
​
remote.baseUrl
string
カスタム API ベース URL。
​
remote.apiKey
string
API キーを上書きします。
​
remote.headers
object
追加の HTTP ヘッダー（プロバイダーのデフォルトとマージされます）。
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

​
プロバイダー固有の設定

キー型デフォルト説明
modelstringgemini-embedding-001gemini-embedding-2-preview もサポートします
outputDimensionalitynumber3072Embedding 2 の場合: 768、1536、または 3072
モデルまたは outputDimensionality を変更すると、自動的に完全な再インデックスが実行されます。
OpenAI 互換の埋め込みエンドポイントでは、プロバイダー固有の input_type リクエストフィールドを使用できます。これは、クエリ埋め込みとドキュメント埋め込みに異なるラベルを必要とする非対称埋め込みモデルで便利です。
キー型デフォルト説明
inputTypestring未設定クエリ埋め込みとドキュメント埋め込みで共有する input_type
queryInputTypestring未設定クエリ時の input_type。inputType を上書きします
documentInputTypestring未設定インデックス/ドキュメントの input_type。inputType を上書きします
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}
これらの値を変更すると、プロバイダーのバッチインデックス作成における埋め込みキャッシュの同一性に影響します。上流モデルがラベルを異なるものとして扱う場合は、メモリの再インデックスを行う必要があります。

​
Bedrock 埋め込み設定

Bedrock は AWS SDK のデフォルト認証情報チェーンを使用します。API キーは不要です。OpenClaw が Bedrock 対応のインスタンスロールを持つ EC2 上で動作している場合は、プロバイダーとモデルを設定するだけです。
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
キー型デフォルト説明
modelstringamazon.titan-embed-text-v2:0任意の Bedrock 埋め込みモデル ID
outputDimensionalitynumberモデルのデフォルトTitan V2 の場合: 256、512、または 1024
サポートされるモデル（ファミリー検出と次元数のデフォルトを含む）:
モデル IDプロバイダーデフォルト次元設定可能な次元
amazon.titan-embed-text-v2:0Amazon1024256、512、1024
amazon.titan-embed-text-v1Amazon1536—
amazon.titan-embed-g1-text-02Amazon1536—
amazon.titan-embed-image-v1Amazon1024—
amazon.nova-2-multimodal-embeddings-v1:0Amazon1024256、384、1024、3072
cohere.embed-english-v3Cohere1024—
cohere.embed-multilingual-v3Cohere1024—
cohere.embed-v4:0Cohere1536256-1536
twelvelabs.marengo-embed-3-0-v1:0TwelveLabs512—
twelvelabs.marengo-embed-2-7-v1:0TwelveLabs1024—
スループットサフィックス付きのバリアント（例: amazon.titan-embed-text-v1:2:8k）は、ベースモデルの設定を継承します。認証: Bedrock 認証は標準の AWS SDK 認証情報解決順序を使用します。
  1. 環境変数（AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY）
  2. SSO トークンキャッシュ
  3. Web ID トークン認証情報
  4. 共有認証情報ファイルと設定ファイル
  5. ECS または EC2 メタデータ認証情報
リージョンは AWS_REGION、AWS_DEFAULT_REGION、amazon-bedrock プロバイダーの baseUrl から解決されるか、デフォルトで us-east-1 になります。IAM 権限: IAM ロールまたはユーザーには次が必要です。
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
最小権限にするには、InvokeModel のスコープを特定のモデルに限定します。
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
キー型デフォルト説明
local.modelPathstring自動ダウンロードGGUF モデルファイルへのパス
local.modelCacheDirstringnode-llama-cpp のデフォルトダウンロードされたモデルのキャッシュディレクトリ
local.contextSizenumber | "auto"4096埋め込みコンテキストのコンテキストウィンドウサイズ。4096 は非重み VRAM を抑えつつ、一般的なチャンク (128–512 トークン) をカバーします。制約のあるホストでは 1024–2048 まで下げてください。"auto" はモデルの訓練時の最大値を使用します。8B+ モデルでは推奨されません (Qwen3-Embedding-8B: 40 960 トークン → 4096 で約 8.8 GB に対し、約 32 GB VRAM)。
デフォルトモデル: embeddinggemma-300m-qat-Q8_0.gguf (約 0.6 GB、自動ダウンロード)。ソースチェックアウトでは、引き続きネイティブビルドの承認が必要です: pnpm approve-builds の後に pnpm rebuild node-llama-cpp。Gateway が使用するものと同じプロバイダーパスを検証するには、スタンドアロン CLI を使用します。
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
provider が auto の場合、local.modelPath が既存のローカルファイルを指しているときにのみ local が選択されます。hf: および HTTP(S) モデル参照は provider: "local" で明示的に使用できますが、モデルがディスク上で利用可能になる前に auto がローカルを選択することはありません。

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

​
sync.embeddingBatchTimeoutSeconds
number
メモリのインデックス作成中に、インライン埋め込みバッチのタイムアウトを上書きします。未設定の場合はプロバイダーのデフォルトが使用されます。local、ollama、lmstudio などのローカル/セルフホストプロバイダーでは 600 秒、ホスト型プロバイダーでは 120 秒です。ローカルの CPU バウンドな埋め込みバッチが正常だが遅い場合は、この値を増やしてください。

​
ハイブリッド検索設定

すべて memorySearch.query.hybrid の下にあります。
キー型デフォルト説明
enabledbooleantrueハイブリッド BM25 + ベクトル検索を有効化
vectorWeightnumber0.7ベクトルスコアの重み (0-1)
textWeightnumber0.3BM25 スコアの重み (0-1)
candidateMultipliernumber4候補プールサイズの乗数
キー型デフォルト説明
mmr.enabledbooleanfalseMMR 再ランキングを有効化
mmr.lambdanumber0.70 = 最大の多様性、1 = 最大の関連性

​
完全な例

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

​
追加メモリパス

キー型説明
extraPathsstring[]インデックス作成対象にする追加のディレクトリまたはファイル
{
  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 と並べて画像と音声をインデックス作成します。
キー型デフォルト説明
multimodal.enabledbooleanfalseマルチモーダルインデックス作成を有効化
multimodal.modalitiesstring[]—["image"]、["audio"]、または ["all"]
multimodal.maxFileBytesnumber10000000インデックス作成対象の最大ファイルサイズ
extraPaths 内のファイルにのみ適用されます。デフォルトのメモリルートは Markdown のみに限定されます。gemini-embedding-2-preview が必要です。fallback は "none" でなければなりません。
サポートされる形式: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (画像); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (音声)。

​
埋め込みキャッシュ

キー型デフォルト説明
cache.enabledbooleanfalseチャンク埋め込みを SQLite にキャッシュ
cache.maxEntriesnumber50000キャッシュされる埋め込みの最大数
再インデックス作成またはトランスクリプト更新時に、変更されていないテキストを再埋め込みすることを防ぎます。

​
バッチインデックス作成

キー型デフォルト説明
remote.nonBatchConcurrencynumber4並列インライン埋め込み
remote.batch.enabledbooleanfalseバッチ埋め込み API を有効化
remote.batch.concurrencynumber2並列バッチジョブ
remote.batch.waitbooleantrueバッチ完了を待機
remote.batch.pollIntervalMsnumber—ポーリング間隔
remote.batch.timeoutMinutesnumber—バッチタイムアウト
openai, gemini, voyage で利用できます。大規模なバックフィルでは、OpenAI バッチが通常最速で最も低コストです。 remote.nonBatchConcurrency は、ローカル/セルフホストのプロバイダー、およびプロバイダーのバッチ API が有効でない場合のホスト型プロバイダーで使用されるインライン埋め込み呼び出しを制御します。Ollama は、小さめのローカルホストに過負荷をかけないよう、非バッチインデックス作成ではデフォルトで 1 になります。より大きなマシンでは高い値を設定してください。 これは、インライン埋め込み呼び出しのタイムアウトを制御する sync.embeddingBatchTimeoutSeconds とは別です。

​
セッションメモリ検索 (実験的)

セッショントランスクリプトをインデックス化し、memory_search 経由で表示します。
キー型デフォルト説明
experimental.sessionMemorybooleanfalseセッションインデックス作成を有効化
sourcesstring[]["memory"]トランスクリプトを含めるには "sessions" を追加
sync.sessions.deltaBytesnumber100000再インデックス作成のバイトしきい値
sync.sessions.deltaMessagesnumber50再インデックス作成のメッセージしきい値
セッションインデックス作成はオプトインで、非同期に実行されます。結果はわずかに古い場合があります。セッションログはディスク上に存在するため、ファイルシステムアクセスを信頼境界として扱ってください。

​
SQLite ベクトル高速化 (sqlite-vec)

キー型デフォルト説明
store.vector.enabledbooleantrueベクトルクエリに sqlite-vec を使用
store.vector.extensionPathstring同梱sqlite-vec パスを上書き
sqlite-vec が利用できない場合、OpenClaw は自動的にプロセス内コサイン類似度にフォールバックします。

​
インデックスストレージ

キー型デフォルト説明
store.pathstring~/.openclaw/memory/{agentId}.sqliteインデックスの場所 ({agentId} トークンをサポート)
store.fts.tokenizerstringunicode61FTS5 トークナイザー (unicode61 または trigram)

​
QMD バックエンド設定

有効にするには memory.backend = "qmd" を設定します。すべての QMD 設定は memory.qmd の下にあります。
キー型デフォルト説明
commandstringqmdQMD 実行可能ファイルのパス。サービスの PATH がシェルと異なる場合は絶対パスを設定
searchModestringsearch検索コマンド: search, vsearch, query
includeDefaultMemorybooleantrueMEMORY.md + memory/**/*.md を自動インデックス化
paths[]array—追加パス: { name, path, pattern? }
sessions.enabledbooleanfalseセッショントランスクリプトをインデックス化
sessions.retentionDaysnumber—トランスクリプトの保持期間
sessions.exportDirstring—エクスポートディレクトリ
searchMode: "search" は字句/BM25 のみです。OpenClaw はそのモードでは、memory status --deep の実行中も含め、セマンティックベクトルの準備状況プローブや QMD 埋め込みメンテナンスを実行しません。vsearch と query は引き続き QMD ベクトルの準備状況と埋め込みを必要とします。 OpenClaw は現在の QMD コレクションと MCP クエリ形式を優先しますが、必要に応じて互換性のあるコレクションパターンフラグや古い MCP ツール名を試すことで、古い QMD リリースも動作し続けるようにしています。QMD が複数のコレクションフィルター対応を通知する場合、同一ソースのコレクションは 1 つの QMD プロセスで検索されます。古い QMD ビルドでは、コレクションごとの互換性パスが維持されます。同一ソースとは、永続メモリコレクションがまとめてグループ化される一方で、セッショントランスクリプトコレクションは別グループのままになり、ソースの多様化で両方の入力が引き続き使われることを意味します。
QMD モデルの上書きは OpenClaw 設定ではなく QMD 側に残ります。QMD のモデルをグローバルに上書きする必要がある場合は、Gateway ランタイム環境で QMD_EMBED_MODEL、QMD_RERANK_MODEL、QMD_GENERATE_MODEL などの環境変数を設定してください。
キー型デフォルト説明
update.intervalstring5m更新間隔
update.debounceMsnumber15000ファイル変更のデバウンス
update.onBootbooleantrue長期稼働の QMD マネージャーが開いたときに更新する。オプトインの起動時更新も制御
update.startupstringoff任意の Gateway 起動時更新: off、idle、または immediate
update.startupDelayMsnumber120000startup: "idle" 更新が実行されるまでの遅延
update.waitForBootSyncbooleanfalse初回更新が完了するまでマネージャーのオープンをブロック
update.embedIntervalstring—個別の埋め込み周期
update.commandTimeoutMsnumber—QMD コマンドのタイムアウト
update.updateTimeoutMsnumber—QMD 更新操作のタイムアウト
update.embedTimeoutMsnumber—QMD 埋め込み操作のタイムアウト
キー型デフォルト説明
limits.maxResultsnumber6最大検索結果数
limits.maxSnippetCharsnumber—スニペット長を制限
limits.maxInjectedCharsnumber—注入される合計文字数を制限
limits.timeoutMsnumber4000検索タイムアウト
どのセッションが 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 のブート更新は、Gateway 起動中にワンショットのサブプロセスパスを使用します。長期稼働の QMD マネージャーは、メモリ検索が対話的な使用のために開かれたとき、通常のファイルウォッチャーとインターバルタイマーを引き続き所有します。

​
完全な 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" }],
    },
  },
}

​
Dreaming

Dreaming は agents.defaults.memorySearch ではなく、plugins.entries.memory-core.config.dreaming の下で設定します。 Dreaming は 1 つのスケジュールされたスイープとして実行され、実装の詳細として内部の light/deep/REM フェーズを使用します。 概念的な動作とスラッシュコマンドについては、Dreaming を参照してください。

​
ユーザー設定

キー型デフォルト説明
enabledbooleanfalseDreaming 全体を有効または無効にする
frequencystring0 3 * * *完全な Dreaming スイープの任意の Cron 周期
modelstringデフォルトモデル任意の Dream Diary サブエージェントモデル上書き

​
例

{
  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",
          },
        },
      },
    },
  },
}
  • Dreaming はマシン状態を memory/.dreams/ に書き込みます。
  • Dreaming は人間が読めるナラティブ出力を DREAMS.md（または既存の dreams.md）に書き込みます。
  • dreaming.model は既存の Plugin サブエージェント信頼ゲートを使用します。有効にする前に plugins.entries.memory-core.subagent.allowModelOverride: true を設定してください。
  • Dream Diary は、設定されたモデルが利用できない場合、セッションのデフォルトモデルで 1 回再試行します。信頼または許可リストの失敗はログに記録され、黙って再試行されることはありません。
  • light/deep/REM フェーズのポリシーとしきい値は内部動作であり、ユーザー向け設定ではありません。

​
関連