---
read_when:
    - تريد إعداد QMD كواجهة خلفية للذاكرة
    - تريد ميزات ذاكرة متقدمة مثل إعادة الترتيب أو مسارات مفهرسة إضافية
summary: خدمة جانبية للبحث المحلي أولًا مع BM25، والمتجهات، وإعادة الترتيب، وتوسيع الاستعلام
title: محرك ذاكرة QMD
x-i18n:
    generated_at: "2026-04-12T23:28:00Z"
    model: gpt-5.4
    provider: openai
    source_hash: 27afc996b959d71caed964a3cae437e0e29721728b30ebe7f014db124c88da04
    source_path: concepts/memory-qmd.md
    workflow: 15
---

# محرك ذاكرة QMD

[QMD](https://github.com/tobi/qmd) هو خدمة جانبية للبحث المحلي أولًا تعمل
إلى جانب OpenClaw. وهو يجمع بين BM25، والبحث المتجهي، وإعادة الترتيب في ملف
تنفيذي واحد، ويمكنه فهرسة محتوى يتجاوز ملفات ذاكرة مساحة العمل الخاصة بك.

## ما الذي يضيفه مقارنة بالمحرك المدمج

- **إعادة الترتيب وتوسيع الاستعلام** لتحسين الاسترجاع.
- **فهرسة أدلة إضافية** -- مثل وثائق المشاريع، وملاحظات الفريق، وأي شيء على القرص.
- **فهرسة نصوص الجلسات** -- لاسترجاع المحادثات السابقة.
- **محلي بالكامل** -- يعمل عبر Bun + node-llama-cpp، ويحمّل نماذج GGUF تلقائيًا.
- **الرجوع الاحتياطي التلقائي** -- إذا لم يكن QMD متاحًا، يعود OpenClaw إلى
  المحرك المدمج بسلاسة.

## البدء

### المتطلبات الأساسية

- ثبّت QMD: `npm install -g @tobilu/qmd` أو `bun install -g @tobilu/qmd`
- إصدار SQLite يسمح بالامتدادات (`brew install sqlite` على macOS).
- يجب أن يكون QMD موجودًا على `PATH` الخاص بـ Gateway.
- يعمل macOS وLinux مباشرة. أما Windows فأفضل دعم له يكون عبر WSL2.

### التفعيل

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

ينشئ OpenClaw دليل QMD مستقلًا تحت
`~/.openclaw/agents/<agentId>/qmd/` ويدير دورة حياة الخدمة الجانبية
تلقائيًا -- تتم إدارة المجموعات، والتحديثات، وعمليات التضمين نيابةً عنك.
وهو يفضّل أشكال مجموعات QMD الحالية وصيغ استعلام MCP الحالية، لكنه لا يزال
يرجع إلى علامات المجموعات القديمة `--mask` وأسماء أدوات MCP الأقدم عند الحاجة.

## كيف تعمل الخدمة الجانبية

- ينشئ OpenClaw مجموعات من ملفات ذاكرة مساحة العمل الخاصة بك وأي
  `memory.qmd.paths` تم إعدادها، ثم يشغّل `qmd update` و`qmd embed` عند
  الإقلاع وبشكل دوري (افتراضيًا كل 5 دقائق).
- تتعقب مجموعة مساحة العمل الافتراضية ملف `MEMORY.md` بالإضافة إلى شجرة
  `memory/`. يظل الملف `memory.md` بالأحرف الصغيرة خيارًا احتياطيًا للتهيئة
  الأولية، وليس مجموعة QMD منفصلة.
- يعمل تحديث الإقلاع في الخلفية حتى لا يتم حظر بدء الدردشة.
- تستخدم عمليات البحث `searchMode` المُعدّ (الافتراضي: `search`؛ ويدعم أيضًا
  `vsearch` و`query`). وإذا فشل وضع ما، يعيد OpenClaw المحاولة باستخدام
  `qmd query`.
- إذا فشل QMD بالكامل، يعود OpenClaw إلى محرك SQLite المدمج.

<Info>
قد يكون البحث الأول بطيئًا -- إذ يحمّل QMD نماذج GGUF (~2 GB) تلقائيًا من أجل
إعادة الترتيب وتوسيع الاستعلام عند أول تشغيل للأمر `qmd query`.
</Info>

## تجاوزات النموذج

تُمرَّر متغيرات بيئة نموذج QMD كما هي من عملية Gateway،
لذلك يمكنك ضبط QMD على مستوى عام من دون إضافة إعدادات جديدة في OpenClaw:

```bash
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"
```

بعد تغيير نموذج التضمين، أعد تشغيل عمليات التضمين حتى يتطابق الفهرس مع
الفضاء المتجهي الجديد.

## فهرسة مسارات إضافية

وجّه QMD إلى أدلة إضافية لجعلها قابلة للبحث:

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

تظهر المقاطع من المسارات الإضافية بصيغة `qmd/<collection>/<relative-path>` في
نتائج البحث. وتفهم `memory_get` هذه البادئة وتقرأ من جذر المجموعة الصحيح.

## فهرسة نصوص الجلسات

فعّل فهرسة الجلسات لاسترجاع المحادثات السابقة:

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

تُصدَّر النصوص كسلاسل من أدوار المستخدم/المساعد بعد تنقيحها إلى مجموعة QMD
مخصصة تحت `~/.openclaw/agents/<id>/qmd/sessions/`.

## نطاق البحث

بشكل افتراضي، تُعرض نتائج بحث QMD في الجلسات المباشرة وجلسات القنوات
(وليس المجموعات). غيّر ذلك عبر إعداد `memory.qmd.scope`:

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

عندما يمنع النطاق عملية بحث، يسجل OpenClaw تحذيرًا مع القناة المشتقة ونوع
الدردشة بحيث يسهل تصحيح النتائج الفارغة.

## الاستشهادات

عندما تكون قيمة `memory.citations` هي `auto` أو `on`، تتضمن مقاطع البحث
تذييلًا بصيغة `Source: <path#line>`. اضبط `memory.citations = "off"` لحذف
التذييل مع الاستمرار في تمرير المسار إلى الوكيل داخليًا.

## متى يُستخدم

اختر QMD عندما تحتاج إلى:

- إعادة الترتيب للحصول على نتائج أعلى جودة.
- البحث في وثائق المشروع أو الملاحظات خارج مساحة العمل.
- استرجاع محادثات الجلسات السابقة.
- بحث محلي بالكامل من دون مفاتيح API.

بالنسبة إلى الإعدادات الأبسط، يعمل [المحرك المدمج](/ar/concepts/memory-builtin)
بشكل جيد من دون أي تبعيات إضافية.

## استكشاف الأخطاء وإصلاحها

**لم يتم العثور على QMD؟** تأكد من أن الملف التنفيذي موجود على `PATH` الخاص بـ Gateway. إذا كان OpenClaw
يعمل كخدمة، فأنشئ رابطًا رمزيًا:
`sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`.

**البحث الأول بطيء جدًا؟** يقوم QMD بتنزيل نماذج GGUF عند أول استخدام. سخّنها مسبقًا
باستخدام `qmd query "test"` مع نفس أدلة XDG التي يستخدمها OpenClaw.

**انتهت مهلة البحث؟** زد قيمة `memory.qmd.limits.timeoutMs` (الافتراضي: 4000ms).
اضبطها على `120000` للأجهزة الأبطأ.

**نتائج فارغة في دردشات المجموعات؟** تحقق من `memory.qmd.scope` -- فالإعداد الافتراضي
يسمح فقط بالجلسات المباشرة وجلسات القنوات.

**هل تتسبب المستودعات المؤقتة الظاهرة في مساحة العمل في `ENAMETOOLONG` أو فهرسة معطلة؟**
يعتمد اجتياز QMD حاليًا على سلوك ماسح QMD الأساسي بدلًا من قواعد الروابط
الرمزية المدمجة في OpenClaw. أبقِ سحب monorepo المؤقتة تحت أدلة مخفية مثل
`.tmp/` أو خارج جذور QMD المفهرسة إلى أن يوفّر QMD اجتيازًا آمنًا من
الحلقات أو عناصر تحكم صريحة للاستبعاد.

## الإعدادات

للاطلاع على سطح الإعداد الكامل (`memory.qmd.*`)، وأوضاع البحث، وفواصل
التحديث، وقواعد النطاق، وجميع الخيارات الأخرى، راجع
[مرجع إعدادات الذاكرة](/ar/reference/memory-config).
