記憶 (Memory)

​

記憶ファイル (Markdown)

• memory/YYYY-MM-DD.md
  • 日ごとのログ (追記専用)。
  • セッション開始時に「今日」と「昨日」のファイルが読み込まれます。
• MEMORY.md (オプション)
  • 整理された長期記憶。
  • プライベートなメインセッションでのみロードされます（グループチャットなどの共有コンテキストではロードされません）。

​

記憶ツール

• memory_search: インデックス化されたスニペットに対するセマンティック検索（意味ベースの検索）。
• memory_get: 特定の Markdown ファイルの指定した行範囲を直接読み取り。

​

いつ記憶に書き込むべきか

• 決定事項、好み、不変の事実などは MEMORY.md へ。
• 日々のメモや進行中の文脈などは memory/YYYY-MM-DD.md へ。
• ユーザーが「これを覚えておいて」と言った内容は、RAM（メモリ上の一時記憶）に留めず、即座にファイルに書き留めてください。
• この分野はまだ進化の途上です。モデルに対して「記憶に保存して」と促すことで、モデルは適切に書き込み先を判断します。
• 重要な情報を確実に定着させたい場合は、ボットに記憶へ書き込むよう明示的に依頼 してください。

​

自動メモリフラッシュ (圧縮前の確認)

{
  agents: {
    defaults: {
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          systemPrompt: "セッションが圧縮（コンパクション）に近づいています。永続化すべき記憶を今すぐ保存してください。",
          prompt: "重要なメモを memory/YYYY-MM-DD.md に書き込んでください。保存すべき内容がなければ NO_REPLY と返してください。",
        },
      },
    },
  },
}

• Soft threshold: セッションの推定トークン数が contextWindow - reserveTokensFloor - softThresholdTokens を超えたときにフラッシュが発動します。
• サイレント動作: デフォルトのプロンプトに NO_REPLY に関する指示が含まれているため、ユーザーにメッセージは届きません。
• 2 つのプロンプト: ユーザープロンプトとシステムプロンプトの両方でリマインダーが追加されます。
• 1 圧縮サイクルにつき 1 回: このフラッシュ処理は sessions.json で追跡されます。
• 書き込み権限が必要: セッションがサンドボックス内で動作し、workspaceAccess が "ro" (読み取り専用) または "none" の場合、フラッシュ処理はスキップされます。

​

ベクトル記憶検索

• デフォルトで有効。
• 記憶ファイルの変更を監視（デバウンス処理あり）。
• agents.defaults.memorySearch で設定します（トップレベルの memorySearch ではありません）。
• デフォルトでリモートの埋め込み（Embeddings）を使用します。memorySearch.provider が未設定の場合、OpenClaw は以下の順序で自動選択します:
  1. local: memorySearch.local.modelPath が設定され、ファイルが存在する場合。
  2. openai: OpenAI のキーが解決できる場合。
  3. gemini: Gemini のキーが解決できる場合。
  4. voyage: Voyage のキーが解決できる場合。
  5. mistral: Mistral のキーが解決できる場合。
  6. それ以外の場合は、設定が行われるまで記憶検索は無効化されます。
• ローカルモードは node-llama-cpp を使用し、環境によっては pnpm approve-builds が必要です。
• sqlite-vec (利用可能な場合) を使用して、SQLite 内でのベクトル検索を高速化します。
• memorySearch.provider = "ollama" による自前ホストの Ollama 埋め込み (/api/embeddings) もサポートしていますが、自動選択の対象外です。

​

QMD バックエンド (実験的)

• デフォルトでは無効。構成で memory.backend = "qmd" を指定して有効化します。
• QMD CLI を別途インストールし（bun install -g https://github.com/tobi/qmd など）、qmd バイナリにゲートウェイの PATH が通っている必要があります。
• QMD には、拡張機能を許可した SQLite ビルド（macOS なら brew install sqlite）が必要です。
• QMD は Bun と node-llama-cpp を介して完全にローカルで動作し、初回使用時に HuggingFace から GGUF モデルを自動ダウンロードします（別途 Ollama デーモンを起動する必要はありません）。
• ゲートウェイは、XDG_CONFIG_HOME と XDG_CACHE_HOME を設定することで、~/.openclaw/agents/<agentId>/qmd/ 配下の独立した XDG ホーム環境で QMD を実行します。
• OS 対応: macOS と Linux では Bun と SQLite があればそのまま動作します。Windows は WSL2 経由での利用を推奨します。

• ゲートウェイは ~/.openclaw/agents/<agentId>/qmd/ 配下に QMD の設定・キャッシュ・DB を作成します。
• memory.qmd.paths（およびデフォルトのワークスペース記憶ファイル）からコレクションが作成され、起動時および設定された間隔（memory.qmd.update.interval、デフォルト 5 分）で qmd update と qmd embed が実行されます。
• ゲートウェイは起動時に QMD マネージャーを初期化するため、最初の検索が行われる前から定期更新タイマーが作動します。
• 起動時の同期処理はデフォルトでバックグラウンドで実行されるため、チャットの開始が待たされることはありません。以前のように同期完了を待ちたい場合は memory.qmd.update.waitForBootSync = true を設定してください。
• 検索は memory.qmd.searchMode（デフォルトは search。vsearch や query も指定可能）に従って実行されます。QMD が失敗したりバイナリが見つからない場合は、自動的に組み込みの SQLite マネージャーへフォールバックします。
• QMD の埋め込みバッチサイズ設定は、現在は OpenClaw からは露出されておらず、QMD 自身の制御に委ねられています。
• 初回検索は時間がかかる場合があります: QMD は最初の qmd query 実行時にローカルの GGUF モデル（リランカーなど）をダウンロードすることがあるためです。
  • モデルを事前に手動でダウンロードしておきたい場合は、エージェントの XDG ディレクトリ環境変数をエクスポートした状態で一度クエリを実行してください。
    Copy

    Ask AI

    STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
    export XDG_CONFIG_HOME="$STATE_DIR/agents/main/qmd/xdg-config"
    export XDG_CACHE_HOME="$STATE_DIR/agents/main/qmd/xdg-cache"
    qmd update
    qmd embed
    qmd query "テスト" -c memory-root --json >/dev/null 2>&1
    

• command (デフォルト qmd): バイナリのパス。
• searchMode: 検索に使用するサブコマンド。
• includeDefaultMemory: ワークスペースの標準ファイルを自動インデックスするかどうか。
• paths[]: 追加のディレクトリやファイル (path, pattern, 固有の name)。
• sessions: 会話履歴（JSONL）のインデックス化設定。
• update: 更新の頻度やタイムアウト設定。
• limits: 検索結果の件数や文字数制限。
• scope: session.sendPolicy と同じスキーマで、どのセッションで QMD 検索を許可するかを制限します。デフォルトは DM のみです。
  • match.keyPrefix: 正規化されたセッションキー（agent:<id>: を除去したもの）に前方一致。例: discord:channel:。
  • match.rawKeyPrefix: 生のセッションキー（agent:<id>: を含む）に前方一致。例: agent:main:discord:。
• 検索結果のスニペットには、memory.citations が auto または on の場合に Source: <path#line> というフッターが付与されます。

​

追加の記憶パス

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

• 絶対パスまたはワークスペース相対パスを指定可能。
• ディレクトリは .md ファイルを求めて再帰的にスキャンされます。
• Markdown ファイルのみが対象です。
• シンボリックリンクは無視されます。

​

Gemini 埋め込み (ネイティブ)

agents: {
  defaults: {
    memorySearch: {
      provider: "gemini",
      model: "gemini-embedding-001",
      remote: {
        apiKey: "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

​

記憶ツールの動作詳細

• memory_search: MEMORY.md および memory/ 以下の Markdown ファイルをチャンク化（約 400 トークン単位）して意味的に検索します。スニペット（最大約 700 文字）、ファイルパス、行範囲、スコア、使用されたプロバイダー/モデルを返します。
• memory_get: パス指定でファイルを読み取ります。MEMORY.md および memory/ 以外のパスへのアクセスは拒否されます。
• 両ツールともに、エージェントの設定で memorySearch.enabled が有効な場合にのみ利用可能です。

​

インデックスの作成と更新

• ファイル形式: Markdown のみ。
• 保存先: エージェントごとの SQLite ファイル ~/.openclaw/memory/<agentId>.sqlite。
• 鮮度管理: ファイル変更を監視し、セッション開始時や検索時に非同期で同期を実行します。
• 全再インデックスのトリガー: 埋め込みの プロバイダー/モデル、エンドポイント情報、またはチャンク化パラメータ が変更された場合、OpenClaw は自動的に既存のインデックスをリセットし、最初から作り直します。

​

ハイブリッド検索 (BM25 + ベクトル)

• ベクトル類似度: 意味的な一致。言葉の揺れを許容します。
• BM25 キーワード適合度: ID、環境変数、コードのシンボル名など、正確な文字列一致。

​

検索結果の後処理パイプライン

ベクトル + キーワード → 重み付けマージ → 時間的減衰 → ソート → MMR → 上位 K 件

​

MMR 再ランク付け (多様性)

​

時間的減衰 (新しさの重視)

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

​

埋め込みキャッシュ

agents: {
  defaults: {
    memorySearch: {
      cache: { enabled: true, maxEntries: 50000 }
    }
  }
}

​

セッション記憶の検索 (実験的)

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

• セッションの同期は、一定量のメッセージ（デフォルト 50 行）やデータ量（100KB）の増分が発生した際に、バックグラウンドで非同期に行われます。
• 履歴ファイルはディスク上に保存されているため、この機能を利用する際はホスト上のファイルアクセス権限が信頼の境界となります。