🦞 OpenClaw + QMD：让 agent 精准回忆、大幅压缩 token 成本

什么是QMD？

QMD 不仅仅是一个搜索工具——它是一个本地混合智能引擎。它结合了三种不同的搜索技术，完全在您的服务器上离线运行。

混合搜索三重奏

BM25 (关键词) + 向量 (语义) + LLM重排序          
全部通过node-llama-cpp离线运行                   

语义相似性的工作原理（"魔法"）

系统将您的文本转换为数字（向量）来"理解"它们。

文本 ───► 嵌入模型 ───► 向量（数字列表）
                                    │
                                    ▼
                              比较向量
                              （余弦相似度）
                                    │
                                    ▼
                        查找"最接近"的含义匹配

💡 类比：

• 关键词搜索： 查找词匹配（"苹果"找到"苹果"）。
• 语义搜索： 查找概念匹配（"苹果"找到"水果"、"派"、"苹果酒"）。

系统架构

内存层图

此图说明了您的日常日志和永久文件如何馈送到QMD大脑，然后再到达聊天界面。

┌─────────────────────────────────────────────────────────┐
│                    QMD层                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │  日常日志    │  │ MEMORY.md    │  │  偏好设置   │      │
│  │ (memory/*.md)│ │ (精选)       │  │  (JSON/用户)│      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
│                        │                                │
│                        ▼                                │
│              QMD混合搜索                                 │
│         (关键词 + 语义 + 重排序)                         │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
                   OpenClaw聊天

本地模型（"大脑"）

这些模型位于 ~/.cache/qmd/models 中。这就是您不需要OpenAI API密钥来进行内存操作的原因。

总磁盘影响： ~2.1 GB

安装与设置

先决条件

# 1. 安装Bun（JavaScript运行时）
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc

# 2. 安装文档工具（Pandoc）
sudo apt-get install -y pandoc poppler-utils

步骤1：安装QMD

# 直接从源代码安装
bun install -g github:tobi/qmd

步骤2：连接大脑

我们告诉QMD监视OpenClaw工作区。

# 添加集合
qmd collection add ~/.openclaw/workspace --name brain --mask "**/*.md"

步骤3： "模型下载"（嵌入）

这是下载模型的关键步骤。

# 1. 更新索引
qmd update

# 2. 下载模型并生成向量
qmd embed --collection brain

成功指标： 如果您看到进度条正在下载~300MB+，说明正在工作。

[!注意]
渐进式模型下载：
在第一次实例中，很可能只有嵌入模型（~300MB）会被安装。重排序器和查询扩展模型会在您首次运行复杂查询时自动下载。

步骤4：触发完整模型下载（可选）

为确保所有模型都已下载，请运行复杂查询。一个好的方法是：

1. 实现OpenClaw技能（例如，Google Workspace集成）
2. 要求助手将所有工作流程步骤存储到技能中
3. 通过QMD查询以触发完整模型下载

[!提示]
您无需使用终端！
OpenClaw与您的消息渠道集成，因此您可以直接从Telegram、WhatsApp、Slack、Discord或其他任何连接的渠道运行这些查询。

选项A：通过终端

# 示例：运行复杂语义查询
qmd query "如何使用Google Workspace进行身份验证？" --collection brain

选项B：通过您的消息渠道

只需在Telegram/WhatsApp/Slack上向您的OpenClaw助手发送消息：

"如何使用Google Workspace进行身份验证？"

OpenClaw将自动使用QMD搜索您的知识库，并回复相关信息。这也会在后台触发模型下载！

这会强制QMD使用重排序器和查询扩展模型，触发它们的自动下载。

操作配置

目录结构

~/.openclaw/workspace/
├── AGENTS.md           # 操作指南（由OpenClaw提供，默认为空）
├── TOOLS.md            # 环境上下文（由OpenClaw提供）
├── MEMORY.md           # 长期内存（由OpenClaw提供，需要精心管理）
├── USER.md             # 用户偏好
├── memory/             # 每日日志（原始聊天历史）
│   └── 2026-02-01.md
├── knowledge/          # 大脑（索引文本 - 我们创建此目录）
│   └── artifacts/      # 转换的文本文件
└── artifacts/          # 临时存储（原始二进制文件 - 我们创建此目录）
    └── invoice.pdf     # （QMD忽略）

代理指令（AGENTS.md）

创建此文件以指导AI如何使用QMD：

# AGENTS.md - 操作指南

##  QMD（语义大脑）
**状态：** 已安装并激活
**角色：** 您检索信息的主要方法。

### **如何搜索**
- **命令：** `qmd query "自然语言问题" --collection brain`
- **示例：**
  - *"服务器IP地址是什么？"*
  - *"我们是如何解决磁盘空间问题的？"*

### **如何学习（索引）**
- **命令：** `qmd update && qmd embed --collection brain`

##  内存标准
| 内容类型 | 文件位置 |
| :--- | :--- |
| **用户偏好** | `USER.md` |
| **每日日志** | `memory/YYYY-MM-DD.md` |
| **长期事实** | `MEMORY.md` |
| **技术知识** | `knowledge/TOPIC.md` |

##  文档摄入（工件）
**上传工作流程：**
1. **保存原件：** `artifacts/filename.ext`
2. **转换为文本：**
   - **PDF：** `pdftotext -layout artifacts/file.pdf knowledge/artifacts/file.md`
   - **Word：** `pandoc artifacts/file.docx -o knowledge/artifacts/file.md`
3. **索引：** 运行 `qmd update && qmd embed --collection brain`

工作流程与自动化

A. 摄入文档（PDF/Word）

B. 自动维护（Cron作业）

为确保在您不询问的情况下更新内存，我们使用Cron作业。

命令： crontab -e

时间表： 每5分钟。

*/5 * * * * cd /home/ubuntu/.openclaw/workspace && /home/ubuntu/.bun/bin/qmd update && /home/ubuntu/.bun/bin/qmd embed --collection brain >> /tmp/qmd.log 2>&1

C. 内存维护策略

验证：成本与隐私

声明： 内存不使用API令牌。

证明： 模型是本地的。

运行此命令查看磁盘上的物理文件：

ls -lh ~/.cache/qmd/models

预期输出：

hf_ggml-org_embeddinggemma-300M-Q8_0.gguf      (~300MB)
hf_ggml-org_qwen3-reranker-0.6b-q8_0.gguf      (~640MB)
hf_tobil_qmd-query-expansion-1.7B-q4_k_m.gguf  (~1.1GB)

优势总结