Bộ nhớ QMD

​

Những gì nó bổ sung so với công cụ tích hợp sẵn

• Reranking và mở rộng truy vấn để cải thiện khả năng truy hồi.
• Lập chỉ mục các thư mục bổ sung — tài liệu dự án, ghi chú nhóm, bất cứ thứ gì trên đĩa.
• Lập chỉ mục bản ghi phiên — truy hồi các cuộc trò chuyện trước đó.
• Hoàn toàn cục bộ — chạy với Plugin provider llama.cpp chính thức và tự động tải xuống các mô hình GGUF.
• Tự động dự phòng — nếu QMD không khả dụng, OpenClaw tự động quay về công cụ tích hợp sẵn một cách liền mạch.

​

Bắt đầu

​

Điều kiện tiên quyết

• Cài đặt QMD: npm install -g @tobilu/qmd hoặc bun install -g @tobilu/qmd
• Bản dựng SQLite cho phép extension (brew install sqlite trên macOS).
• QMD phải nằm trong PATH của gateway.
• macOS và Linux hoạt động ngay mặc định. Windows được hỗ trợ tốt nhất qua WSL2.

​

Bật

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

​

Cách sidecar hoạt động

• OpenClaw tạo collection từ các tệp bộ nhớ workspace của bạn và mọi memory.qmd.paths đã cấu hình, sau đó chạy qmd update khi trình quản lý QMD được mở và định kỳ sau đó (mặc định mỗi 5 phút). Các lượt làm mới này chạy qua subprocess QMD, không phải một lượt quét hệ thống tệp trong tiến trình. Các chế độ ngữ nghĩa cũng chạy qmd embed.
• Collection workspace mặc định theo dõi MEMORY.md cùng cây memory/. memory.md viết thường không được lập chỉ mục như một tệp bộ nhớ gốc.
• Trình quét riêng của QMD bỏ qua các đường dẫn ẩn và những thư mục dependency/build phổ biến như .git, .cache, node_modules, vendor, dist và build. Khởi động Gateway không khởi tạo QMD theo mặc định, vì vậy cold boot tránh import runtime bộ nhớ hoặc tạo watcher dài hạn trước khi bộ nhớ được dùng lần đầu.
• Nếu bạn vẫn muốn QMD được khởi tạo khi gateway khởi động, hãy đặt memory.qmd.update.startup thành idle hoặc immediate. Với memory.qmd.update.onBoot: true, khởi động sẽ chạy lượt làm mới ban đầu. Với onBoot: false, khởi động bỏ qua lượt làm mới tức thời đó nhưng vẫn mở trình quản lý dài hạn khi các khoảng update hoặc embed được cấu hình, để QMD có thể sở hữu watcher và timer định kỳ của nó.
• Tìm kiếm sử dụng searchMode đã cấu hình (mặc định: search; cũng hỗ trợ vsearch và query). search chỉ dùng BM25, nên OpenClaw bỏ qua các probe sẵn sàng vector ngữ nghĩa và bảo trì embedding ở chế độ đó. Nếu một chế độ thất bại, OpenClaw thử lại bằng qmd query.
• Khi searchMode là query, đặt memory.qmd.rerank thành false để dùng đường dẫn truy vấn hybrid của QMD mà không có reranker. OpenClaw truyền --no-rerank vào đường dẫn CLI QMD trực tiếp và rerank: false vào công cụ truy vấn MCP của QMD. Tùy chọn này yêu cầu QMD 2.1 trở lên.
• Với các bản phát hành QMD quảng bá bộ lọc đa collection, OpenClaw nhóm các collection cùng nguồn vào một lượt gọi tìm kiếm QMD. Các bản phát hành QMD cũ hơn giữ đường dẫn dự phòng tương thích theo từng collection.
• Nếu QMD thất bại hoàn toàn, OpenClaw quay về công cụ SQLite tích hợp sẵn. Các lần thử lặp lại trong lượt chat sẽ tạm lùi sau lỗi mở để một binary bị thiếu hoặc dependency sidecar bị hỏng không tạo ra bão retry; openclaw memory status và các probe CLI một lần vẫn kiểm tra lại QMD trực tiếp.

​

Hiệu năng tìm kiếm và khả năng tương thích

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

qmd --help | grep -i collection

​

Ghi đè mô hình

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"

​

Lập chỉ mục đường dẫn bổ sung

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

​

Lập chỉ mục bản ghi phiên

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

​

Phạm vi tìm kiếm

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

​

Trích dẫn

​

Khi nào nên dùng

• Reranking để có kết quả chất lượng cao hơn.
• Tìm kiếm tài liệu dự án hoặc ghi chú ngoài workspace.
• Truy hồi các cuộc trò chuyện phiên trước đây.
• Tìm kiếm hoàn toàn cục bộ, không cần khóa API.

​

Khắc phục sự cố

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

​

Cấu hình

​

Liên quan

• Tổng quan Memory
• Công cụ bộ nhớ tích hợp sẵn
• Bộ nhớ Honcho