4. メモリ・知識システム

長期記憶、セマンティック検索、Embedding、ハイブリッド検索

概要

OpenClawのメモリシステムは、エージェントに永続的な記憶を与える RAG（Retrieval-Augmented Generation）パイプラインです。 SQLiteデータベースにベクトル拡張（sqlite-vec）とFTS5（全文検索）を組み合わせた ハイブリッド検索を実現し、「覚えている」AIアシスタントを可能にしています。

アーキテクチャ概要

メモリシステム 3層アーキテクチャ: ┌─────────────────────────────────────────────┐ │ 検索レイヤー │ │ ハイブリッド検索 = ベクトル類似度 + BM25キーワード │ │ + MMR多様性再ランキング + 時間的減衰 │ ├─────────────────────────────────────────────┤ │ インデックスレイヤー │ │ ファイル監視 + セッション監視 + チャンキング │ │ + Embedding生成 + 同期オーケストレーション │ ├─────────────────────────────────────────────┤ │ ストレージレイヤー │ │ SQLite + sqlite-vec (ベクトル検索) │ │ + FTS5 (全文検索) │ └─────────────────────────────────────────────┘

メモリソース

src/memory/types.ts

ソース内容デフォルト
memory MEMORY.md, memory.md, memory/ディレクトリのMarkdownファイル 有効
sessions 過去の会話トランスクリプト（JSONLファイル） 無効（experimental.sessionMemory: true で有効化）

ストレージアーキテクチャ

src/memory/sqlite.ts

Node.jsの実験的組み込みモジュール node:sqlite を使用。 DBは ~/.openclaw/state/memory/{agentId}.sqlite に保存されます。

テーブル用途
filesインデックス対象ファイルのメタデータ
chunksテキストチャンク（ID、パス、開始/終了行、ハッシュ、モデル、テキスト、Embedding）
chunks_vecベクトル検索用仮想テーブル（vec0）
chunks_fts全文検索用テーブル（FTS5）
embedding_cacheEmbeddingのキャッシュ（コンテンツハッシュ→ベクトル）
metaメタデータ（モデル、プロバイダ、チャンク設定）

Embeddingプロバイダ

src/memory/embeddings.ts

プロバイダモデル優先度（autoモード）
ローカルembeddinggemma-300m-qat-Q8_0.gguf1（最優先）
OpenAItext-embedding-3-small2
Geminigemini-embedding-0013
Voyagevoyage-4-large4
優雅な劣化：すべてのプロバイダが利用不可の場合、システムはFTS-onlyモード （キーワード検索のみ）に自動フォールバックします。 sqlite-vecが利用不可の場合はブルートフォースコサイン類似度計算にフォールバック。 メモリ検索は常に何らかのレベルで機能します。

すべてのEmbeddingは sanitizeAndNormalizeEmbedding() でL2正規化（単位ベクトル化）されます。

チャンキングシステム

src/memory/internal.ts:167-248

Markdownチャンキング

セッションファイル処理

src/memory/session-files.ts:74-131

ハイブリッド検索パイプライン

src/memory/manager.ts:203-289

検索クエリ │ ├─ [Embeddingあり] ──────────────────────────┐ │ │ │ │ ▼ ベクトル検索 ▼ キーワード検索 │ embed(query) → cosine距離 tokenize → FTS5 BM25 │ score = 1 - cosine_distance score = 1/(1+rank) │ │ │ │ └─────────┬───────────────────────────────┘ │ ▼ │ ハイブリッドマージ │ score = 0.7 × vectorScore + 0.3 × textScore │ │ │ ▼ 時間的減衰適用（有効時） │ ▼ MMR多様性再ランキング（有効時） │ ▼ minScore=0.35 フィルタ │ ▼ maxResults=6 制限 │ │ │ ▼ 結果返却 │ ├─ [Embeddingなし（FTS-onlyモード）] ─────────┐ │ │ │ │ ▼ extractKeywords() │ │ 各キーワードで独立検索 │ │ 結果をマージ・重複排除 │ │ │ │ │ └──────────────────────────► 結果返却

ベクトル検索

src/memory/manager-search.ts:20-94

キーワード検索

src/memory/manager-search.ts:136-191、src/memory/hybrid.ts:33-44

ハイブリッドマージ

src/memory/hybrid.ts:51-149

時間的減衰（Temporal Decay）

src/memory/temporal-decay.ts

人間的な記憶を模倣：「最近の記憶ほど鮮明」という特性を数学的に実装しています。

スマートタイムスタンプ抽出

ファイルタイプタイムスタンプ減衰
日付付きファイル（memory/YYYY-MM-DD.md）パスから日付を解析あり
エバーグリーンファイル（MEMORY.md等）なし（null返却）なし
その他のファイルファイルシステムのmtimeあり

核心設計：コアナレッジ（MEMORY.md）は永久に減衰しませんが、 日々のノートは時間とともに関連性が低下します。

MMR多様性再ランキング

src/memory/mmr.ts

Maximal Marginal Relevance（Carbonell & Goldstein, 1998）アルゴリズムにより、 検索結果の多様性を確保します。

クエリ拡張

src/memory/query-expansion.ts

FTS-onlyモード用のクエリ前処理：

同期・インデックスパイプライン

src/memory/manager-sync-ops.ts

同期トリガー

トリガータイミング
セッション開始新しい会話が始まるとき
検索時ダーティなら検索前に同期
ファイルウォッチャーChokidarによる監視、1.5秒デバウンス
セッションリスナートランスクリプト更新（100KB or 50メッセージの差分閾値）
インターバルタイマー設定された周期での定期同期

同期プロセス

  1. ベクトル拡張の読み込み（必要時）
  2. メタデータチェック（モデル変更、プロバイダ変更、チャンク設定変更→フルリインデックス）
  3. メモリファイル: .mdファイルを列挙、変更されたファイルをインデックス（ハッシュ比較）
  4. セッションファイル: JSONLトランスクリプトを列挙、ダーティファイルをインデックス
  5. 古いインデックスパスを削除（存在しないファイル）
  6. 安全なリインデックス: 一時DBで新インデックスを構築 → ファイルリネームでアトミックに交換

Embeddingキャッシング

src/memory/manager-embedding-ops.ts:77-175

バッチEmbedding

src/memory/manager-embedding-ops.ts:246-494

パーソナルアシスタントとしてのメモリの意義

  1. 永続的知識ベース — MEMORY.mdとmemory/ディレクトリがセッション横断で蓄積される
  2. セッション想起 — 過去の会話を検索可能にし「あのAPIについて話したとき」の想起を実現
  3. エバーグリーン vs 時限的知識 — コア知識は永遠に保持、日付付きノートは徐々に忘却
  4. ワークスペーススコープ — エージェント+ワークスペースごとに独立したインデックス
  5. 自動同期 — ファイルウォッチャーとセッションリスナーで常に最新
  6. プライバシー配慮 — セッションコンテンツは編集済み、toolResult.detailsは要約から除去
← エージェントランタイム 自律的行動システム →