Công cụ bộ nhớ QMD

QMD là một tiến trình phụ tìm kiếm ưu tiên cục bộ, chạy song song 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

• Xếp hạng lại 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 hoặc bất kỳ nội dung nào trên đĩa.
• Lập chỉ mục bản chép lời 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 trì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 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 mà không cần cấu hình thêm. Windows được hỗ trợ tốt nhất qua WSL2.

Bật

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

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 tiến trình phụ — các bộ sưu tập, bản cập nhật và lượt tạo embedding đều được xử lý cho bạn. OpenClaw ưu tiên các dạng bộ sưu tập và truy vấn MCP hiện tại của QMD, nhưng sẽ 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 lúc khởi động cũng tạo lại các bộ sưu tập được quản lý đã lỗi thời theo 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 tiến trình phụ 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à định kỳ sau đó (memory.qmd.update.interval, mặc định là 5m). Việc làm mới được thực hiện qua các tiến trình con QMD, không phải bằng cách 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 là 60m).
• Bộ sưu tập không gian làm việc mặc định theo dõi MEMORY.md cùng toàn bộ cây memory/. Tệp 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 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 khởi động nguội tránh nhập môi trường thực thi 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ượt làm mới ban đầu lúc khởi động; đặt thành false để bỏ qua lượt làm mới tức thời đó (trình quản lý tồn tại lâu dài vẫn mở khi các khoảng thời gian cập nhật hoặc tạo embedding được cấu hình, vì vậy QMD vẫn quản lý 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 phép kiểm tra mức sẵn sàng của vectơ ngữ nghĩa và việc duy trì embedding trong 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 để sử dụng đường dẫn truy vấn kết hợp của QMD mà không có trình xếp hạng lại (yêu cầu QMD 2.1 trở lên). OpenClaw truyền --no-rerank cho đường dẫn CLI QMD trực tiếp và rerank: false cho 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 đường dự phòng tương thích theo từng bộ sưu tập.
• Nếu QMD hoàn toàn thất bại, OpenClaw chuyển sang công cụ SQLite tích hợp. 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ần phụ thuộc tiến trình phụ bị hỏng không tạo thành một cơn bão thử lại; openclaw memory status và các phép kiểm tra CLI dùng một lần vẫn trực tiếp kiểm tra lại QMD.

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ả 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ả các bộ sưu tập cùng nguồn bằng một lệnh:

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

Điều 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 đầu vào từ cả hai nguồn cho trình đ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 các bản dựng đó, OpenClaw giữ đườ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:

qmd --help | grep -i collection

Phần trợ giúp QMD hiện tại đề cập đến việc nhắm mục tiêu một hoặc nhiều bộ sưu tập. Phần 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 chuyển nguyên vẹn từ tiến trình Gateway, vì vậy bạn có thể tinh chỉnh QMD trên toàn cục mà không cần thêm cấu hình OpenClaw mới:

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"

Sau khi thay đổi mô hình embedding, hãy chạy lại việc tạo embedding để 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:

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

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ừ đúng thư mục gốc của bộ sưu tập.

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

Bật lập chỉ mục phiên để truy hồi các cuộc trò chuyện trước đó. QMD cần cả nguồn phiên memorySearch tổng quát và trình xuất bản chép lời QMD:

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

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ý đã làm sạch vào một bộ sưu tập QMD chuyên dụng tại ~/.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 phiên vẫn được lọc theo tools.sessions.visibility. Chế độ hiển thị tree mặc định không để lộ các phiên không liên quan của cùng tác tử. Nếu một phiên do Gateway điều phối cần có thể được truy hồi từ một phiên tin nhắn trực tiếp riêng biệt, hãy chủ đích đặt tools.sessions.visibility: "agent".

Phạm vi tìm kiếm

Theo mặc định, kết quả tìm kiếm QMD chỉ xuất hiện trong các phiên trực tiếp (không xuất hiện 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:

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

Đoạn mã trên là quy tắc mặc định thực tế. Khi phạm vi từ chối một lượt tìm kiếm, OpenClaw ghi 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 nhưng vẫn truyền đường dẫn nội bộ cho tác tử.

Khi nào nên sử 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 không gian làm việc.
• Truy hồ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 thiết lập đơn giản hơn, công cụ tích hợp 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? Hãy bảo đảm 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 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. Hãy chỉ định rõ tệp nhị phân:

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

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" với 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 lượt tìm kiếm nhiều bộ sưu tập cùng nguồn khi QMD đã cài đặt công bố hỗ trợ nhiều bộ lọc -c; nếu không, OpenClaw giữ đường dự phòng cũ hơn theo từng bộ sưu tập để bảo đảm tính chính xác.

QMD chỉ dùng BM25 vẫn cố gắng dựng llama.cpp? Đặt memory.qmd.searchMode = "search". OpenClaw coi chế độ đó là chỉ dùng từ vựng, bỏ qua các phép kiểm tra trạng thái vectơ QMD và việc duy trì embedding, đồng thời dành các phép 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.

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 kết quả QMD xuất hiện ở đó.

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 chờ lần đối soát khởi động tiếp theo. OpenClaw tạo lại các bộ sưu tập được quản lý đã lỗi thời theo mẫu chuẩn MEMORY.md và memory/ 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 quá trình 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 sao làm việc monorepo tạm thời trong 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 khả năng duyệt an toàn trước chu trình hoặc các điều khiển loại trừ tường minh.

Cấu hình

Để xem toàn bộ bề mặt 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à mọi tùy chọn khác, hãy xem tài liệu tham chiếu cấu hình bộ nhớ.

Liên quan

• Tổng quan về bộ nhớ
• Công cụ bộ nhớ tích hợp
• Bộ nhớ Honcho