Mesin memori QMD

QMD adalah sidecar pencarian yang mengutamakan lokal dan berjalan bersama OpenClaw. QMD menggabungkan BM25, pencarian vektor, dan pemeringkatan ulang dalam satu binary, serta dapat mengindeks konten di luar file memori workspace Anda.

# Yang ditambahkan dibanding bawaan

• Pemeringkatan ulang dan perluasan kueri untuk recall yang lebih baik.
• Indeks direktori tambahan -- dokumentasi proyek, catatan tim, apa pun di disk.
• Indeks transkrip sesi -- ingat kembali percakapan sebelumnya.
• Sepenuhnya lokal -- berjalan dengan paket runtime node-llama-cpp opsional dan mengunduh otomatis model GGUF.
• Fallback otomatis -- jika QMD tidak tersedia, OpenClaw beralih ke mesin bawaan tanpa hambatan.

# Memulai

# Prasyarat

• Instal QMD: npm install -g @tobilu/qmd atau bun install -g @tobilu/qmd
• Build SQLite yang mengizinkan ekstensi (brew install sqlite di macOS).
• QMD harus ada di PATH milik Gateway.
• macOS dan Linux langsung berfungsi. Windows paling baik didukung melalui WSL2.

# Aktifkan

{
  memory: {
    backend: "qmd",
  },
}

OpenClaw membuat home QMD mandiri di bawah ~/.openclaw/agents/<agentId>/qmd/ dan mengelola siklus hidup sidecar secara otomatis -- koleksi, pembaruan, dan proses embedding ditangani untuk Anda. OpenClaw mengutamakan koleksi QMD dan bentuk kueri MCP saat ini, tetapi tetap fallback ke flag pola koleksi alternatif dan nama alat MCP lama saat diperlukan. Rekonsiliasi saat boot juga membuat ulang koleksi terkelola yang usang kembali ke pola kanonisnya ketika koleksi QMD lama dengan nama yang sama masih ada.

# Cara kerja sidecar

• OpenClaw membuat koleksi dari file memori workspace Anda dan memory.qmd.paths apa pun yang dikonfigurasi, lalu menjalankan qmd update ketika manajer QMD dibuka dan secara berkala setelahnya (default setiap 5 menit). Penyegaran ini berjalan melalui subprocess QMD, bukan crawl filesystem dalam proses. Mode semantik juga menjalankan qmd embed.
• Koleksi workspace default melacak MEMORY.md ditambah tree memory/. memory.md huruf kecil tidak diindeks sebagai file memori root.
• Pemindai milik QMD mengabaikan path tersembunyi dan direktori dependensi/build umum seperti .git, .cache, node_modules, vendor, dist, dan build. Startup Gateway tidak menginisialisasi QMD secara default, sehingga boot dingin menghindari impor runtime memori atau pembuatan watcher berumur panjang sebelum memori pertama kali digunakan.
• Jika Anda tetap menginginkan penyegaran saat Gateway dimulai, set memory.qmd.update.startup ke idle atau immediate. Penyegaran startup opt-in menggunakan path subprocess QMD satu kali alih-alih membuat watcher dalam proses penuh yang berumur panjang.
• Pencarian menggunakan searchMode yang dikonfigurasi (default: search; juga mendukung vsearch dan query). search hanya BM25, sehingga OpenClaw melewati probe kesiapan vektor semantik dan pemeliharaan embedding dalam mode tersebut. Jika suatu mode gagal, OpenClaw mencoba lagi dengan qmd query.
• Dengan rilis QMD yang mengiklankan filter multi-koleksi, OpenClaw mengelompokkan koleksi dari sumber yang sama ke satu invocation pencarian QMD. Rilis QMD lama tetap memakai fallback per koleksi yang kompatibel.
• Jika QMD gagal sepenuhnya, OpenClaw fallback ke mesin SQLite bawaan. Upaya berulang pada giliran chat mundur sebentar setelah kegagalan membuka agar binary yang hilang atau dependensi sidecar yang rusak tidak membuat badai retry; openclaw memory status dan probe CLI satu kali tetap memeriksa ulang QMD secara langsung.

# Performa pencarian dan kompatibilitas

OpenClaw menjaga path pencarian QMD tetap kompatibel dengan instalasi QMD saat ini maupun yang lebih lama.

Saat startup, OpenClaw memeriksa teks bantuan QMD yang terinstal sekali per manajer. Jika binary mengiklankan dukungan untuk beberapa filter koleksi, OpenClaw mencari semua koleksi dari sumber yang sama dengan satu perintah:

qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main

Ini menghindari memulai satu subprocess QMD untuk setiap koleksi memori tahan lama. Koleksi transkrip sesi tetap berada dalam grup sumbernya sendiri, sehingga pencarian campuran memory + sessions tetap memberi input pendiversifikasi hasil dari kedua sumber.

Build QMD lama hanya menerima satu filter koleksi. Ketika OpenClaw mendeteksi salah satu build tersebut, OpenClaw mempertahankan path kompatibilitas dan mencari setiap koleksi secara terpisah sebelum menggabungkan dan menghapus duplikasi hasil.

Untuk memeriksa kontrak yang terinstal secara manual, jalankan:

qmd --help | grep -i collection

Bantuan QMD saat ini mengatakan filter koleksi dapat menargetkan satu atau beberapa koleksi. Bantuan lama biasanya menjelaskan satu koleksi.

# Override model

Variabel lingkungan model QMD diteruskan tanpa perubahan dari proses Gateway, sehingga Anda dapat menyetel QMD secara global tanpa menambahkan konfigurasi OpenClaw baru:

export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf"
export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"

Setelah mengubah model embedding, jalankan ulang embedding agar indeks cocok dengan ruang vektor baru.

# Mengindeks path tambahan

Arahkan QMD ke direktori tambahan agar dapat dicari:

{
  memory: {
    backend: "qmd",
    qmd: {
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

Cuplikan dari path tambahan muncul sebagai qmd/<collection>/<relative-path> dalam hasil pencarian. memory_get memahami prefix ini dan membaca dari root koleksi yang benar.

# Mengindeks transkrip sesi

Aktifkan pengindeksan sesi untuk mengingat kembali percakapan sebelumnya:

{
  memory: {
    backend: "qmd",
    qmd: {
      sessions: { enabled: true },
    },
  },
}

Transkrip diekspor sebagai giliran User/Assistant yang disanitasi ke koleksi QMD khusus di bawah ~/.openclaw/agents/<id>/qmd/sessions/.

# Cakupan pencarian

Secara default, hasil pencarian QMD ditampilkan dalam sesi langsung dan channel (bukan grup). Konfigurasikan memory.qmd.scope untuk mengubah ini:

{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}

Ketika cakupan menolak pencarian, OpenClaw mencatat peringatan dengan channel turunan dan jenis chat agar hasil kosong lebih mudah di-debug.

# Sitasi

Ketika memory.citations adalah auto atau on, cuplikan pencarian menyertakan footer Source: <path#line>. Set memory.citations = "off" untuk menghilangkan footer sambil tetap meneruskan path ke agen secara internal.

# Kapan digunakan

Pilih QMD ketika Anda membutuhkan:

• Pemeringkatan ulang untuk hasil berkualitas lebih tinggi.
• Pencarian dokumentasi proyek atau catatan di luar workspace.
• Mengingat kembali percakapan sesi terdahulu.
• Pencarian sepenuhnya lokal tanpa kunci API.

Untuk setup yang lebih sederhana, mesin bawaan berfungsi baik tanpa dependensi tambahan.

# Pemecahan masalah

QMD tidak ditemukan? Pastikan binary ada di PATH milik Gateway. Jika OpenClaw berjalan sebagai layanan, buat symlink: sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd.

Jika qmd --version berfungsi di shell Anda tetapi OpenClaw masih melaporkan spawn qmd ENOENT, proses Gateway kemungkinan memiliki PATH yang berbeda dari shell interaktif Anda. Pin binary secara eksplisit:

{
  memory: {
    backend: "qmd",
    qmd: {
      command: "/absolute/path/to/qmd",
    },
  },
}

Gunakan command -v qmd di lingkungan tempat QMD diinstal, lalu periksa ulang dengan openclaw memory status --deep.

Pencarian pertama sangat lambat? QMD mengunduh model GGUF saat pertama kali digunakan. Lakukan pre-warm dengan qmd query "test" menggunakan direktori XDG yang sama dengan yang digunakan OpenClaw.

Banyak subprocess QMD selama pencarian? Perbarui QMD jika memungkinkan. OpenClaw menggunakan satu proses untuk pencarian multi-koleksi dari sumber yang sama hanya ketika QMD yang terinstal mengiklankan dukungan untuk beberapa filter -c; jika tidak, OpenClaw mempertahankan fallback per koleksi lama demi kebenaran.

QMD hanya BM25 masih mencoba membangun llama.cpp? Set memory.qmd.searchMode = "search". OpenClaw memperlakukan mode tersebut sebagai hanya leksikal, tidak menjalankan probe status vektor QMD atau pemeliharaan embedding, dan menyerahkan pemeriksaan kesiapan semantik ke setup vsearch atau query.

Pencarian timeout? Tingkatkan memory.qmd.limits.timeoutMs (default: 4000ms). Set ke 120000 untuk perangkat keras yang lebih lambat.

Hasil kosong di chat grup? Periksa memory.qmd.scope -- default hanya mengizinkan sesi langsung dan channel.

Pencarian memori root tiba-tiba menjadi terlalu luas? Mulai ulang Gateway atau tunggu rekonsiliasi startup berikutnya. OpenClaw membuat ulang koleksi terkelola yang usang kembali ke pola kanonis MEMORY.md dan memory/ ketika mendeteksi konflik nama yang sama.

Repo sementara yang terlihat workspace menyebabkan ENAMETOOLONG atau pengindeksan rusak? Traversal QMD saat ini mengikuti perilaku pemindai QMD yang mendasari, bukan aturan symlink bawaan OpenClaw. Simpan checkout monorepo sementara di bawah direktori tersembunyi seperti .tmp/ atau di luar root QMD yang diindeks sampai QMD mengekspos traversal aman siklus atau kontrol pengecualian eksplisit.

# Konfigurasi

Untuk permukaan konfigurasi lengkap (memory.qmd.*), mode pencarian, interval pembaruan, aturan cakupan, dan semua knob lainnya, lihat referensi konfigurasi Memori.

# Terkait

• Ringkasan memori
• Mesin memori bawaan
• Memori Honcho