Chuyển đến nội dung chính
QMD là một sidecar tìm kiếm ưu tiên cục bộ chạy cùng với OpenClaw. Công cụ này kết hợp BM25, tìm kiếm vectơ và xếp hạng lại trong một tệp nhị phân duy nhất, đồng thời có thể lập chỉ mục nội dung ngoài các tệp bộ nhớ trong không gian làm việc của bạn.

​
Những tính năng bổ sung so với công cụ tích hợp sẵn

  • Xếp hạng lại và mở rộng truy vấn để cải thiện khả năng tìm thấy kết quả.
  • Lập chỉ mục các thư mục bổ sung - tài liệu dự án, ghi chú của nhóm, mọi nội dung trên ổ đĩa.
  • Lập chỉ mục bản chép lời phiên - tìm lại các cuộc trò chuyện trước đó.
  • Hoàn toàn cục bộ - chạy với plugin nhà cung cấp 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 chuyển sang 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 phần mở rộng (brew install sqlite trên macOS).
  • QMD phải nằm trong PATH của Gateway.
  • macOS và Linux hoạt động ngay khi cài đặt. Windows được hỗ trợ tốt nhất qua WSL2.

​
Bật

OpenClaw tạo một thư mục chính QMD độc lập tại ~/.openclaw/agents/<agentId>/qmd/ và tự động quản lý vòng đời của sidecar - các bộ sưu tập, bản cập nhật và lượt chạy nhúng đều được xử lý cho bạn. OpenClaw ưu tiên các dạng truy vấn bộ sưu tập QMD và MCP hiện tại, nhưng chuyển sang các cờ mẫu bộ sưu tập thay thế và tên công cụ MCP cũ hơn khi cần. Quá trình đối soát khi khởi động cũng tạo lại các bộ sưu tập được quản lý đã lỗi thời về mẫu chuẩn khi vẫn còn một bộ sưu tập QMD cũ có cùng tên.

​
Cách sidecar hoạt động

  • OpenClaw tạo các bộ sưu tập từ những tệp bộ nhớ trong không gian làm việc và mọi memory.qmd.paths đã cấu hình, sau đó chạy qmd update khi trình quản lý QMD mở và chạy lại định kỳ sau đó (memory.qmd.update.interval, mặc định 5m). Các lần làm mới chạy qua tiến trình con QMD, không phải quy trình quét hệ thống tệp trong tiến trình. Các chế độ tìm kiếm ngữ nghĩa cũng chạy qmd embed (memory.qmd.update.embedInterval, mặc định 60m).
  • QMD tiếp tục sở hữu index.sqlite, cấu hình bộ sưu tập YAML và các mô hình đã tải xuống trong thư mục chính QMD riêng của từng tác tử; đây là các tạo tác của công cụ bên ngoài, không phải bảng trạng thái của OpenClaw. Hoạt động điều phối thuộc sở hữu của OpenClaw chỉ nằm trong SQLite: một hợp đồng thuê dùng chung giới hạn công việc nhúng giữa các tác tử, còn một hợp đồng thuê trong mỗi cơ sở dữ liệu tác tử tuần tự hóa các thao tác ghi bộ sưu tập, cập nhật và nhúng của tác tử đó. Runtime không còn tạo các sidecar tệp khóa QMD. openclaw doctor --fix chỉ xóa các sidecar đã ngừng sử dụng sau khi chứng minh chủ sở hữu tiến trình cũ của chúng đã lỗi thời. Việc nâng cấp là một lần chuyển đổi dứt điểm: dừng và khởi động lại mọi tiến trình OpenClaw dùng chung thư mục trạng thái trước khi sử dụng phiên bản mới. Không hỗ trợ các trình ghi QMD cũ/mới chạy lẫn nhau; runtime chủ ý không khóa kép các sidecar đã ngừng sử dụng.
  • Bộ sưu tập không gian làm việc 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 dưới dạng 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 phụ thuộc/bản dựng phổ biến như .git, .cache, node_modules, vendor, dist và build. Theo mặc định, quá trình khởi động Gateway không khởi tạo QMD (memory.qmd.update.startup mặc định là off), vì vậy quá trình khởi động nguội tránh nhập runtime bộ nhớ hoặc tạo trình theo dõi tồn tại lâu dài trước khi bộ nhớ được sử dụng lần đầu.
  • Đặt memory.qmd.update.startup thành idle hoặc immediate để vẫn khởi tạo QMD khi Gateway khởi động. memory.qmd.update.onBoot mặc định là true và chạy lần làm mới ban đầu khi khởi động; đặt thành false để bỏ qua lần làm mới tức thì đó (trình quản lý tồn tại lâu dài vẫn mở khi đã cấu hình khoảng thời gian cập nhật hoặc nhúng, vì vậy QMD tiếp tục sở hữu trình theo dõi/bộ hẹn giờ định kỳ của mình).
  • Các lượt 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, vì vậy OpenClaw bỏ qua các bước kiểm tra mức độ sẵn sàng của vectơ ngữ nghĩa và bảo trì dữ liệu nhúng trong chế độ đó. Nếu một chế độ thất bại, OpenClaw thử lại bằng qmd query.
  • Khi searchMode là query, hãy đặt memory.qmd.rerank thành false để sử dụng đường dẫn truy vấn kết hợp của QMD mà không dùng trình xếp hạng lại (yêu cầu QMD 2.1 trở lên). OpenClaw truyền --no-rerank đến đường dẫn CLI trực tiếp của QMD và rerank: false đến công cụ truy vấn MCP của QMD.
  • Với các bản phát hành QMD công bố hỗ trợ bộ lọc nhiều bộ sưu tập, OpenClaw nhóm các bộ sưu tập cùng nguồn vào một lần gọi tìm kiếm QMD. Các bản phát hành QMD cũ hơn vẫn dùng phương án dự phòng tương thích theo từng bộ sưu tập.
  • Nếu QMD thất bại hoàn toàn, OpenClaw chuyển sang công cụ SQLite tích hợp sẵn. Các lần thử lặp lại trong lượt trò chuyện sẽ tạm lùi lại sau khi mở thất bại để tệp nhị phân bị thiếu hoặc phụ thuộc sidecar bị hỏng không tạo ra một cơn bão thử lại; openclaw memory status và các bước kiểm tra CLI một lần vẫn kiểm tra lại QMD trực tiếp.
Lần tìm kiếm đầu tiên có thể chậm - QMD tự động tải xuống các mô hình GGUF (~2 GB) để xếp hạng lại và mở rộng truy vấn trong lần chạy qmd query đầu tiên.

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

OpenClaw duy trì đường dẫn tìm kiếm QMD tương thích với cả các bản cài đặt QMD hiện tại và cũ hơn. Khi khởi động, OpenClaw kiểm tra văn bản trợ giúp của QMD đã cài đặt một lần cho mỗi trình quản lý. Nếu tệp nhị phân công bố hỗ trợ nhiều bộ lọc bộ sưu tập, OpenClaw tìm kiếm tất cả bộ sưu tập cùng nguồn bằng một lệnh:
Cách này tránh khởi chạy một tiến trình con QMD cho mỗi bộ sưu tập bộ nhớ bền vững. Các bộ sưu tập bản chép lời phiên vẫn nằm trong nhóm nguồn riêng, vì vậy các lượt tìm kiếm kết hợp memory + sessions vẫn cung cấp dữ liệu đầu vào từ cả hai nguồn cho bộ đa dạng hóa kết quả. Các bản dựng QMD cũ hơn chỉ chấp nhận một bộ lọc bộ sưu tập. Khi OpenClaw phát hiện một trong những bản dựng đó, OpenClaw giữ lại đường dẫn tương thích và tìm kiếm riêng từng bộ sưu tập trước khi hợp nhất và loại bỏ kết quả trùng lặp. Để kiểm tra thủ công hợp đồng đã cài đặt, hãy chạy:
Trợ giúp QMD hiện tại đề cập đến việc nhắm đến một hoặc nhiều bộ sưu tập. Trợ giúp cũ hơn thường mô tả một bộ sưu tập duy nhất.

​
Ghi đè mô hình

Các biến môi trường mô hình QMD được truyền nguyên trạng từ tiến trình Gateway, vì vậy bạn có thể điều chỉnh QMD trên toàn cục mà không cần thêm cấu hình OpenClaw mới:
Sau khi thay đổi mô hình nhúng, hãy chạy lại quá trình nhúng để chỉ mục khớp với không gian vectơ mới.

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

Trỏ QMD đến các thư mục bổ sung để có thể tìm kiếm chúng:
Các đoạn trích từ đường dẫn bổ sung xuất hiện dưới dạng qmd/<collection>/<relative-path> trong kết quả tìm kiếm. memory_get hiểu tiền tố này và đọc từ thư mục gốc chính xác của bộ sưu tập.

​
Lập chỉ mục bản chép lời phiên

Bật tính năng lập chỉ mục phiên để nhớ lại các cuộc trò chuyện trước đó. QMD cần cả nguồn phiên memorySearch chung và trình xuất bản chép lời QMD:
Các bản chép lời được xuất dưới dạng các lượt Người dùng/Trợ lý đã được làm sạch vào một bộ sưu tập QMD chuyên biệt trong ~/.openclaw/agents/<id>/qmd/sessions/. Chỉ đặt memorySearch.experimental.sessionMemory sẽ không xuất bản chép lời vào QMD. Các kết quả khớp từ phiên vẫn được lọc bởi tools.sessions.visibility. Khả năng hiển thị tree mặc định bao gồm phiên hiện tại, các phiên do phiên đó tạo ra và các phiên nhóm của cùng agent được theo dõi thông qua nhận biết nhóm xung quanh. Với session.dmScope: "main", người dùng trong thiết lập DM nhiều người dùng chia sẻ phiên chính và có thể nhớ lại nội dung từ các nhóm mà phiên đó theo dõi. Sử dụng dmScope riêng cho từng peer để cô lập DM, hoặc đặt khả năng hiển thị thành "self" để không đọc các phiên được theo dõi xung quanh. Các phiên cùng agent không liên quan khác vẫn yêu cầu khả năng hiển thị "agent".

​
Phạm vi tìm kiếm

Theo mặc định, kết quả tìm kiếm QMD chỉ hiển thị trong các phiên trực tiếp (không hiển thị trong cuộc trò chuyện nhóm hoặc kênh). Cấu hình memory.qmd.scope để thay đổi điều này:
Đoạn mã trên chính là quy tắc mặc định thực tế. Khi phạm vi từ chối một tìm kiếm, OpenClaw ghi nhật ký cảnh báo kèm kênh và loại trò chuyện đã suy ra để dễ gỡ lỗi kết quả trống hơn.

​
Trích dẫn

Khi memory.citations là auto hoặc on, các đoạn trích tìm kiếm được nối thêm phần chân trang Source: <path>#L<line> (hoặc #L<start>-L<end>). Trong chế độ auto, phần chân trang chỉ được thêm cho các phiên trò chuyện trực tiếp. Đặt memory.citations = "off" để bỏ phần chân trang trong khi vẫn truyền đường dẫn nội bộ cho agent.

​
Khi nào nên dùng

Chọn QMD khi bạn cần:
  • Xếp hạng lại để 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ú bên ngoài workspace.
  • Nhớ lại các cuộc trò chuyện trong phiên trước đây.
  • Tìm kiếm hoàn toàn cục bộ mà không cần khóa API.
Đối với các thiết lập đơn giản hơn, công cụ tích hợp sẵn hoạt động tốt mà không cần phần phụ thuộc bổ sung.

​
Khắc phục sự cố

Không tìm thấy QMD? Đảm bảo tệp nhị phân nằm trong PATH của Gateway. Nếu OpenClaw chạy dưới dạng dịch vụ, hãy tạo liên kết tượng trưng: sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd. Nếu qmd --version hoạt động trong shell của bạn nhưng OpenClaw vẫn báo spawn qmd ENOENT, tiến trình Gateway có thể có PATH khác với shell tương tác của bạn. Chỉ định rõ tệp nhị phân:
Sử dụng command -v qmd trong môi trường đã cài đặt QMD, sau đó kiểm tra lại bằng openclaw memory status --deep. Lần tìm kiếm đầu tiên rất chậm? QMD tải xuống các mô hình GGUF trong lần sử dụng đầu tiên. Hãy làm nóng trước bằng qmd query "test", sử dụng cùng các thư mục XDG mà OpenClaw sử dụng. Có nhiều tiến trình con QMD trong khi tìm kiếm? Hãy cập nhật QMD nếu có thể. OpenClaw chỉ sử dụng một tiến trình cho các tìm kiếm nhiều bộ sưu tập có cùng nguồn khi QMD đã cài đặt công bố hỗ trợ nhiều bộ lọc -c; nếu không, hệ thống giữ cơ chế dự phòng cũ, mỗi bộ sưu tập một tiến trình, để đảm bảo tính chính xác. QMD chỉ dùng BM25 vẫn cố gắng xây dựng llama.cpp? Đặt memory.qmd.searchMode = "search". OpenClaw coi chế độ đó là chỉ dùng tìm kiếm từ vựng, bỏ qua các phép thăm dò trạng thái vector QMD và việc bảo trì embedding, đồng thời để các bước kiểm tra mức độ sẵn sàng ngữ nghĩa cho thiết lập vsearch hoặc query. Tìm kiếm hết thời gian chờ? Tăng memory.qmd.limits.timeoutMs (mặc định: 4000ms). Đặt giá trị cao hơn, ví dụ 120000, cho phần cứng chậm hơn. Giới hạn này áp dụng cho các lệnh tìm kiếm riêng của QMD trong những lần gọi memory_search của agent; công việc thiết lập, đồng bộ, dự phòng tích hợp sẵn và kho dữ liệu bổ sung vẫn giữ thời hạn ngắn hơn riêng. Kết quả trống trong cuộc trò chuyện nhóm hoặc kênh? Đây là hành vi dự kiến với memory.qmd.scope mặc định, vốn chỉ cho phép các phiên trực tiếp. Thêm quy tắc allow cho loại trò chuyện group hoặc channel nếu bạn muốn có kết quả QMD ở đó. Tìm kiếm bộ nhớ gốc đột nhiên trở nên quá rộng? Khởi động lại Gateway hoặc đợi đợt đối chiếu tiếp theo khi khởi động. OpenClaw tạo lại các bộ sưu tập được quản lý đã lỗi thời theo các mẫu MEMORY.md và memory/ chuẩn khi phát hiện xung đột trùng tên. Các kho lưu trữ tạm thời hiển thị trong không gian làm việc gây ra ENAMETOOLONG hoặc làm hỏng việc lập chỉ mục? Quá trình duyệt của QMD tuân theo trình quét QMD nền tảng thay vì các quy tắc liên kết tượng trưng tích hợp của OpenClaw. Hãy giữ các bản checkout monorepo tạm thời trong các thư mục ẩn như .tmp/ hoặc bên ngoài các thư mục gốc QMD được lập chỉ mục cho đến khi QMD cung cấp cơ chế duyệt an toàn trước chu trình hoặc các tùy chọn kiểm soát loại trừ rõ ràng.

​
Cấu hình

Để biết toàn bộ phạm vi cấu hình (memory.qmd.*), các chế độ tìm kiếm, khoảng thời gian cập nhật, quy tắc phạm vi và tất cả tùy chọn khác, hãy xem Tham chiếu cấu hình bộ nhớ.

​
Liên quan