---
read_when:
    - تريد إعداد QMD كواجهة خلفية للذاكرة
    - تريد ميزات ذاكرة متقدمة مثل إعادة الترتيب أو مسارات مفهرسة إضافية
summary: خدمة جانبية للبحث المحلي أولاً باستخدام BM25 والمتجهات وإعادة الترتيب وتوسيع الاستعلامات
title: محرك ذاكرة QMD
x-i18n:
    generated_at: "2026-04-30T07:52:34Z"
    model: gpt-5.5
    provider: openai
    source_hash: 71980e3701f9a5ddcfbbfa41497ef51d2aae2993b2326591124cc0a87f9a849f
    source_path: concepts/memory-qmd.md
    workflow: 16
---

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

## ما الذي يضيفه فوق المضمّن

- **إعادة الترتيب وتوسيع الاستعلام** لتحسين الاسترجاع.
- **فهرسة أدلة إضافية** -- وثائق المشروع، وملاحظات الفريق، وأي شيء على القرص.
- **فهرسة نُسخ جلسات الحوار** -- استرجاع المحادثات السابقة.
- **محلي بالكامل** -- يعمل مع حزمة وقت التشغيل الاختيارية 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 الحالية، لكنه لا يزال يرجع إلى
أعلام أنماط المجموعات البديلة وأسماء أدوات MCP الأقدم عند الحاجة.
كما تعيد تسوية وقت الإقلاع إنشاء المجموعات المُدارة القديمة إلى أنماطها
المعيارية عندما تظل مجموعة QMD أقدم بالاسم نفسه موجودة.

## كيفية عمل الملحق الجانبي

- ينشئ OpenClaw مجموعات من ملفات ذاكرة مساحة عملك وأي
  `memory.qmd.paths` مهيأة، ثم يشغّل `qmd update` عند فتح مدير QMD
  وبشكل دوري بعد ذلك (الافتراضي كل 5 دقائق). تعمل عمليات التحديث هذه
  عبر عمليات QMD فرعية، لا عبر زحف نظام ملفات داخل العملية. كما تشغّل
  الأوضاع الدلالية `qmd embed`.
- تتعقب مجموعة مساحة العمل الافتراضية `MEMORY.md` إضافة إلى شجرة
  `memory/`. لا تتم فهرسة `memory.md` بالأحرف الصغيرة كملف ذاكرة جذري.
- يتجاهل ماسح QMD نفسه المسارات المخفية وأدلة الاعتمادات/البناء الشائعة
  مثل `.git` و`.cache` و`node_modules` و`vendor` و`dist` و
  `build`. لا يهيئ بدء Gateway تشغيل QMD افتراضياً، لذلك يتجنب الإقلاع
  البارد استيراد وقت تشغيل الذاكرة أو إنشاء المراقب طويل العمر قبل
  استخدام الذاكرة لأول مرة.
- إذا كنت تريد تحديثاً عند بدء Gateway رغم ذلك، فاضبط
  `memory.qmd.update.startup` على `idle` أو `immediate`. يستخدم تحديث
  بدء التشغيل الاختياري مسار عملية QMD فرعية لمرة واحدة بدلاً من إنشاء
  المراقب الكامل طويل العمر داخل العملية.
- تستخدم عمليات البحث `searchMode` المهيأ (الافتراضي: `search`؛ ويدعم
  أيضاً `vsearch` و`query`). يكون `search` معتمداً على BM25 فقط، لذلك
  يتجاوز OpenClaw فحوصات جاهزية المتجهات الدلالية وصيانة التضمينات في
  هذا الوضع. إذا فشل وضع ما، يعيد OpenClaw المحاولة باستخدام `qmd query`.
- مع إصدارات QMD التي تعلن عن مرشحات متعددة المجموعات، يجمع OpenClaw
  المجموعات ذات المصدر نفسه في استدعاء بحث QMD واحد. تحتفظ إصدارات QMD
  الأقدم بالرجوع الاحتياطي المتوافق لكل مجموعة.
- إذا فشل QMD بالكامل، يرجع OpenClaw إلى محرك SQLite المضمّن.
  تتراجع محاولات دورات الدردشة المتكررة لفترة وجيزة بعد فشل الفتح بحيث
  لا يؤدي ملف تنفيذي مفقود أو اعتماد ملحق جانبي معطل إلى عاصفة إعادة
  محاولات؛ ولا تزال `openclaw memory status` وفحوصات CLI لمرة واحدة
  تعيد فحص QMD مباشرة.

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

## أداء البحث والتوافق

يحافظ OpenClaw على توافق مسار بحث QMD مع تثبيتات QMD الحالية والأقدم.

عند بدء التشغيل، يفحص OpenClaw نص مساعدة QMD المثبّت مرة واحدة لكل مدير. إذا
أعلن الملف التنفيذي عن دعم مرشحات مجموعات متعددة، يبحث OpenClaw في كل
المجموعات ذات المصدر نفسه بأمر واحد:

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

يتجنب هذا بدء عملية QMD فرعية واحدة لكل مجموعة ذاكرة دائمة.
تبقى مجموعات نُسخ جلسات الحوار في مجموعة مصدرها الخاصة، لذلك لا تزال عمليات
البحث المختلطة بين `memory` + `sessions` تمنح مُنوّع النتائج مدخلات من كلا
المصدرين.

تقبل إصدارات QMD الأقدم مرشح مجموعة واحداً فقط. عندما يكتشف OpenClaw أحد
تلك الإصدارات، فإنه يحتفظ بمسار التوافق ويبحث في كل مجموعة على حدة قبل دمج
النتائج وإزالة تكرارها.

لفحص العقد المثبّت يدوياً، شغّل:

```bash
qmd --help | grep -i collection
```

تقول مساعدة QMD الحالية إن مرشحات المجموعات يمكن أن تستهدف مجموعة واحدة أو
أكثر. تصف المساعدة الأقدم عادةً مجموعة واحدة.

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

تمر متغيرات بيئة نماذج 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 },
    },
  },
}
```

تُصدّر النُسخ كأدوار User/Assistant منقّحة إلى مجموعة 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 --version` يعمل في صدفتك لكن OpenClaw لا يزال يبلغ عن
`spawn qmd ENOENT`، فمن المحتمل أن عملية Gateway لديها `PATH` مختلف عن
صدفتك التفاعلية. ثبّت الملف التنفيذي صراحةً:

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

استخدم `command -v qmd` في البيئة التي ثُبّت فيها QMD، ثم أعد الفحص باستخدام
`openclaw memory status --deep`.

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

**عمليات QMD فرعية كثيرة أثناء البحث؟** حدّث QMD إن أمكن. يستخدم OpenClaw
عملية واحدة لعمليات البحث متعددة المجموعات ذات المصدر نفسه فقط عندما يعلن
QMD المثبّت دعمه لمرشحات `-c` متعددة؛ وإلا فإنه يحافظ على الرجوع الاحتياطي
الأقدم لكل مجموعة لضمان الصحة.

**QMD المعتمد على BM25 فقط لا يزال يحاول بناء llama.cpp؟** اضبط
`memory.qmd.searchMode = "search"`. يتعامل OpenClaw مع ذلك الوضع كمعجمي فقط،
ولا يشغّل فحوصات حالة متجهات QMD أو صيانة التضمينات، ويترك فحوصات الجاهزية
الدلالية لإعدادات `vsearch` أو `query`.

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

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

**أصبح بحث الذاكرة الجذرية واسعاً جداً فجأة؟** أعد تشغيل Gateway أو انتظر
تسوية بدء التشغيل التالية. يعيد OpenClaw إنشاء المجموعات المُدارة القديمة
إلى أنماط `MEMORY.md` و`memory/` المعيارية عندما يكتشف تعارضاً بالاسم نفسه.

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

## الإعداد

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

## ذات صلة

- [نظرة عامة على الذاكرة](/ar/concepts/memory)
- [محرك الذاكرة المضمّن](/ar/concepts/memory-builtin)
- [ذاكرة Honcho](/ar/concepts/memory-honcho)