1776 字
9 分鐘
OpenClaw 記憶系統進化:升級至 qmd 專家模式

在上一篇文章中,我們完成了 OpenClaw 從雲端 Embeddings 向本地化的過渡,啟用了內建的 local 模式。經過一段時間的實測,雖然運作穩定,但為了追求更極致的檢索精準度與擴展性,我們決定進行第二次架構升級——引入 qmd。這是一套專為 Agent 設計的高效能本地搜尋引擎,能進一步解決本地檢索在處理複雜上下文時的盲點。

這就是 qmd 登場的時刻。

本文記錄了將 OpenClaw 記憶後端直接升級至 qmd 專家模式的完整過程,以及如何克服在 macOS 環境下遇到的技術瓶頸,最終實現毫秒級的精準檢索體驗。

1. 什麼是 qmd?:為 Agent 而生的本地搜尋引擎#

qmd (Query Markup Documents) 是由 Shopify 創辦人 Tobi Lütke 所開發的開源專案。它並非一般的資料庫,而是一個專為 AI Agent 設計的本地搜尋與索引引擎。

與傳統方案相比,qmd 的血統決定了它的卓越:

  • TypeScript/Bun 構建:基於 Bun 運行時,擁有優異的啟動速度與執行效能。
  • Agent 原生:設計初衷就是為了讓 Agent 能像人類一樣快速翻閱並理解大量文件。
  • 極簡與強大:在保持輕量化的同時,提供了超越企業級搜尋引擎的檢索精細度。

在 OpenClaw 中啟用 qmd,等同於開啟了記憶系統的「專家模式」。

2. 核心優勢:為何它是專家首選?#

升級至 qmd 後,OpenClaw 的記憶能力會發生質的飛躍:

不再僅依賴向量 (Vector) 的語意相似度。qmd 結合了 BM25 關鍵字搜尋Vector 語意搜尋。這意味著無論你是在尋找一個特定的變數名稱,還是一個抽象的邏輯概念,它都能精準命中。

B. LLM Reranking:精準度大幅提升#

這是 qmd 的殺手鐧。在初步檢索出候選片段後,它會利用本地 LLM 進行重排序 (Reranking)。這能有效過濾掉雜訊,確保遞交給 Agent 的 Context 是最相關、最有價值的。實測在複雜技術文件中的召回準確率有顯著提升。

C. 100% 本地化與隱私#

透過 node-llama-cpp 與 GGUF 模型,所有的向量計算與重排序都在本地完成。無需 API Key,無需擔心資料外洩,且完全不產生額外費用。

💡 如果你需要使用外部雲端模型(例如透過 NVIDIA API 接入 Kimi K2.5),建議搭配隔離代理機制來保護敏感資料。詳細的隔離設定方式可參考在 OpenClaw 打造 Kimi K2.5 隔離顧問代理

3. 升級實戰:克服 macOS 的 SQLite 難題#

在 macOS (特別是 Apple Silicon 平台) 上啟用 qmd 時,我們遇到了最棘手的問題:SQLite 動態載入錯誤

由於 macOS 內建的 SQLite 版本較舊且鎖定了某些動態函式庫載入權限,導致 qmd 依賴的向量擴充模組無法正常運行。

解決方案:引入 Homebrew 環境#

我們不能依賴系統內建的 SQLite,必須手動提供一個現代化、未受限的運行環境:

  1. 安裝 Homebrew 版 SQLite
    Terminal window
    brew install sqlite
  2. 配置環境變數:確保編譯與運行時優先使用 Homebrew 安裝的版本。
  3. 重新編譯擴充模組:確保 qmd 的核心組件能正確連結到新版的 libsqlite3

這一步雖然瑣碎,卻是開啟專家模式的必要代價。

4. OpenClaw 設定與啟動#

當環境準備就緒後,在 openclaw.json 中切換後端僅需一行變更:

{
"agents": {
"defaults": {
"memorySearch": {
"provider": "local",
"options": {
"backend": "qmd", // 核心設定:啟用 qmd 後端
"model": "Xenova/all-MiniLM-L6-v2",
"rerank": true // 開啟 LLM 重排序
}
}
}
}
}

修改完成後,搭配我們先前解鎖的 commands.restart 權限,Agent 即可自主重啟並完成索引遷移。

5. 最終成效:毫秒級的知識喚醒#

升級後的體感差異非常明顯:

  • 跨專案檢索:當我在 Lumina 專案中提問關於 Memory 模組的實作細節時,Agent 能在 500ms 內從數千行程式碼中精準定位到相關的 Markdown 說明文件。
  • 零干擾 Context:得益於 Reranking 機制,注入到 Prompt 中的知識片段變得非常乾淨,極大減少了 Agent 因無關資訊而產生的「胡言亂語」。
  • 穩定性:即便在處理大型 Git 儲存庫的索引時,qmd 後端的穩定性也遠超之前的內建實作。

6. 記憶管理工具:一鍵備份與恢復 (Memory Management Tool)#

隨著記憶系統的進化,確保這些累積的知識與索引能被安全備份與隨時復原變得至關重要。為了簡化管理流程,我們將原本獨立的備份與恢復功能整合進了一個單一的互動式腳本中。

這套 Memory Management Tool 提供了一個簡潔的選單,讓您能在「備份記憶」與「恢復記憶」之間自由切換。它會自動處理 memory/ 原始檔案、MEMORY.md 長期記憶、qmd 搜尋引擎索引以及系統核心設定檔 openclaw.json

#!/bin/bash
# OpenClaw + QMD 記憶管理工具 (整合版)
echo "------------------------------------------------"
echo "OpenClaw + QMD 記憶管理系統"
echo "------------------------------------------------"
echo "1) 🌌 備份記憶資料 (Backup)"
echo "2) 🌊 恢復記憶資料 (Restore)"
echo "3) 🚪 離開 (Exit)"
echo "------------------------------------------------"
read -p "請選擇操作項目: " choice
case $choice in
1)
# --- 備份邏輯 ---
echo "正在準備備份記憶檔案與索引資料..."
BACKUP_DATE=$(date +%Y%m%d_%H%M%S)
DEFAULT_NAME="openclaw_memory_backup_$BACKUP_DATE"
read -p "請輸入備份檔案名稱 (預設: $DEFAULT_NAME): " custom_name
BACKUP_NAME=${custom_name:-$DEFAULT_NAME}
BACKUP_DIR="$HOME/${BACKUP_NAME}_temp"
mkdir -p "$BACKUP_DIR"
echo "📦 正在打包資料夾與系統設定檔..."
cp -r "$HOME/openclaw/memory" "$BACKUP_DIR/memory" 2>/dev/null
cp "$HOME/openclaw/MEMORY.md" "$BACKUP_DIR/" 2>/dev/null
mkdir -p "$BACKUP_DIR/qmd_cache"
cp -r "$HOME/.cache/qmd" "$BACKUP_DIR/qmd_cache/" 2>/dev/null
mkdir -p "$BACKUP_DIR/openclaw_config"
cp "$HOME/.openclaw/openclaw.json" "$BACKUP_DIR/openclaw_config/" 2>/dev/null
tar -czf "$HOME/${BACKUP_NAME}.tar.gz" -C "$HOME" "${BACKUP_NAME}_temp"
rm -rf "$BACKUP_DIR"
echo "✨ 備份完成!"
echo "檔案位置:$HOME/${BACKUP_NAME}.tar.gz"
;;
2)
# --- 恢復邏輯 ---
echo "準備執行恢復程序..."
echo "⚠️ 警告:這將會覆蓋您目前的工作區記憶與系統設定!"
read -p "請輸入或拖曳備份檔案 (.tar.gz) 路徑: " BACKUP_FILE
BACKUP_FILE="${BACKUP_FILE%\"}"
BACKUP_FILE="${BACKUP_FILE#\"}"
if [ ! -f "$BACKUP_FILE" ]; then
echo "❌ 錯誤:找不到檔案 $BACKUP_FILE"
exit 1
fi
read -p "確定要執行恢復嗎?(y/n): " final_confirm
if [[ $final_confirm == "y" ]]; then
TEMP_DIR="$HOME/openclaw_restore_temp"
mkdir -p "$TEMP_DIR"
tar -xzf "$BACKUP_FILE" -C "$TEMP_DIR"
EXTRACTED_DIR=$(ls "$TEMP_DIR" | grep "_temp")
FULL_PATH="${TEMP_DIR}/${EXTRACTED_DIR:-.}"
echo "📦 正在恢復記憶資料與核心設定..."
mkdir -p "$HOME/openclaw"
cp -r "$FULL_PATH/memory" "$HOME/openclaw/" 2>/dev/null
cp "$FULL_PATH/MEMORY.md" "$HOME/openclaw/" 2>/dev/null
mkdir -p "$HOME/.cache/qmd"
if [ -d "$FULL_PATH/qmd_cache/qmd" ]; then
cp -r "$FULL_PATH/qmd_cache/qmd/"* "$HOME/.cache/qmd/" 2>/dev/null
else
cp -r "$FULL_PATH/qmd_cache/"* "$HOME/.cache/qmd/" 2>/dev/null
fi
mkdir -p "$HOME/.openclaw"
cp "$FULL_PATH/openclaw_config/openclaw.json" "$HOME/.openclaw/" 2>/dev/null
rm -rf "$TEMP_DIR"
echo "✨ 資料恢復完成!"
echo "💡 請執行 'openclaw gateway restart' 以重啟系統並套用變更。"
else
echo "已取消恢復操作。"
fi
;;
*)
echo "操作已結束。"
;;
esac

維護建議: 定期執行此工具,能確保您的 Agent 記憶資料始終安全。在執行恢復作業後,請務必重啟 OpenClaw Gateway,以確保系統能正確載入已還原的記憶與配置。

參考來源:

tobi/qmd - GitHub

OpenClaw Memory Configuration Guide

OpenClaw 記憶系統進化:升級至 qmd 專家模式
https://laplusda.com/posts/openclaw-memory-upgrade-qmd/
作者
Zero
發佈於
2026-02-06
許可協議
CC BY-NC-SA 4.0
這篇文章有幫助嗎?

回報錯字、失效連結,或告訴我你想看的延伸主題。