組み込みメモリエンジン

builtin エンジンはデフォルトのメモリバックエンドです。メモリインデックスを エージェントごとの SQLite データベースに保存し、利用を開始するための 追加の依存関係は必要ありません。

提供される機能

• FTS5 全文インデックス（BM25 スコアリング）によるキーワード検索。
• サポートされている任意のプロバイダーの埋め込みによるベクトル検索。
• 最良の結果を得るために両方を組み合わせるハイブリッド検索。
• 中国語、日本語、韓国語向けのトライグラムトークン化によるCJK サポート。
• データベース内ベクトルクエリ向けの sqlite-vec アクセラレーション（オプション）。

はじめに

デフォルトでは、builtin エンジンは OpenAI の埋め込みを使用します。OPENAI_API_KEY または models.providers.openai.apiKey がすでに設定されている場合、追加のメモリ設定なしで ベクトル検索を利用できます。

プロバイダーを明示的に設定するには、次のようにします。

{  memory: {    search: {      provider: "openai",    },  },}

埋め込みプロバイダーがない場合は、キーワード検索のみ利用できます。

ローカルの GGUF 埋め込みを強制的に使用するには、公式の llama.cpp プロバイダー Plugin をインストールし、local.modelPath で GGUF ファイルを指定します。

openclaw plugins install @openclaw/llama-cpp-provider

{  memory: {    search: {      provider: "local",      fallback: "none",      local: {        modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",      },    },  },}

サポートされている埋め込みプロバイダー

OpenAI 以外に切り替えるには、memory.search.provider を設定します。

インデックス作成の仕組み

OpenClaw は MEMORY.md と memory/*.md をチャンク（デフォルトでは 400 トークン、 80 トークンのオーバーラップ）に分割してインデックス化し、エージェントごとの SQLite データベースに保存します。

• インデックスの場所: 所有エージェントのデータベース ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• ストレージのメンテナンス: SQLite WAL サイドカーは、定期チェックポイントと シャットダウン時のチェックポイントによって上限が保たれます。
• ファイル監視: メモリファイルへの変更により、デバウンスされた再インデックスが トリガーされます（デフォルトは 1.5 秒）。
• 自動再インデックス: 埋め込みプロバイダー、モデル、チャンク設定、 設定済みソース、またはスコープが変更されると、インデックスは自動的に再構築されます。
• オンデマンド再インデックス: openclaw memory index --force

使用する場合

builtin エンジンは、ほとんどのユーザーに適しています。

• 追加の依存関係なしで、そのまま利用できます。
• キーワード検索とベクトル検索の両方を適切に処理します。
• すべての埋め込みプロバイダーをサポートします。
• ハイブリッド検索により、両方の検索手法の長所を組み合わせます。

再ランキングやクエリ拡張が必要な場合、またはワークスペース外のディレクトリを インデックス化したい場合は、QMDへの切り替えを検討してください。

自動ユーザーモデリングを備えたセッション横断メモリが必要な場合は、 Honchoを検討してください。

トラブルシューティング

メモリ検索が無効になっていますか？ openclaw memory status を確認してください。プロバイダーが 検出されない場合は、明示的に設定するか、API キーを追加します。

ローカルプロバイダーが検出されませんか？ ローカルパスが存在することを確認し、次を実行します。

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

スタンドアロンの CLI コマンドと Gateway は、どちらも同じ local プロバイダー ID を使用します。 ローカル埋め込みを使用する場合は、memory.search.provider: "local" を設定します。

結果が古いですか？ 再構築するには openclaw memory index --force を実行します。まれなエッジケースでは、 ウォッチャーが変更を見逃すことがあります。

sqlite-vec が読み込まれませんか？ OpenClaw は自動的にプロセス内のコサイン 類似度へフォールバックします。openclaw memory status --deep はローカル ベクトルストアを埋め込みプロバイダーとは別に報告するため、Vector store: unavailable は sqlite-vec の読み込みを示し、Embeddings: unavailable はプロバイダー／認証またはモデルの準備状況を示します。具体的な読み込み エラーについては、ログを確認してください。

設定

埋め込みプロバイダーのセットアップ、ハイブリッド検索のチューニング（重み、MMR、時間的 減衰）、バッチインデックス作成、マルチモーダルメモリ、sqlite-vec、追加パス、および その他すべての設定項目については、 メモリ設定リファレンスを参照してください。

関連項目

• メモリの概要
• メモリ検索
• Active Memory