---
read_when:
    - تريد إعداد QMD كواجهة خلفية للذاكرة لديك
    - تريد ميزات ذاكرة متقدمة مثل إعادة الترتيب أو مسارات مفهرسة إضافية
summary: خدمة بحث جانبية محلية أولاً مع BM25، والمتجهات، وإعادة الترتيب، وتوسيع الاستعلامات
title: محرك ذاكرة QMD
x-i18n:
    generated_at: "2026-06-28T22:33:31Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 14af147882829451f026f0b9b6cc052c6e2129626a4ab0d0b1c7b77a31c1c050
    source_path: concepts/memory-qmd.md
    workflow: 16
---

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

## ما يضيفه مقارنة بالمضمّن

- **إعادة الترتيب وتوسيع الاستعلامات** لتحسين الاسترجاع.
- **فهرسة أدلة إضافية** -- وثائق المشروع، ملاحظات الفريق، أي شيء على القرص.
- **فهرسة نصوص الجلسات** -- استرجاع المحادثات السابقة.
- **محلي بالكامل** -- يعمل مع Plugin المزوّد الرسمي لـ 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 افتراضيًا، لذلك يتجنب الإقلاع
  البارد استيراد وقت تشغيل الذاكرة أو إنشاء المراقب طويل العمر قبل أول
  استخدام للذاكرة.
- إذا أردت تهيئة QMD عند بدء Gateway رغم ذلك، فعيّن
  `memory.qmd.update.startup` إلى `idle` أو `immediate`. مع
  `memory.qmd.update.onBoot: true`، يشغّل بدء التشغيل التحديث الأولي. ومع
  `onBoot: false`، يتخطى بدء التشغيل ذلك التحديث الفوري لكنه لا يزال يفتح
  المدير طويل العمر عندما تكون فواصل التحديث أو التضمين مضبوطة، كي يستطيع QMD
  امتلاك مراقبه ومؤقتاته المنتظمة.
- تستخدم عمليات البحث `searchMode` المضبوطة (الافتراضي: `search`؛ ويدعم أيضًا
  `vsearch` و`query`). يكون `search` مخصصًا لـ BM25 فقط، لذلك يتخطى OpenClaw
  فحوصات جاهزية المتجهات الدلالية وصيانة التضمينات في ذلك النمط. إذا فشل نمط،
  يعيد OpenClaw المحاولة باستخدام `qmd query`.
- عندما يكون `searchMode` هو `query`، عيّن `memory.qmd.rerank` إلى `false`
  لاستخدام مسار الاستعلام الهجين في QMD دون معيد الترتيب. يمرر OpenClaw
  `--no-rerank` إلى مسار QMD CLI المباشر و`rerank: false` إلى أداة استعلام
  MCP الخاصة بـ QMD. يتطلب هذا الخيار QMD 2.1 أو أحدث.
- مع إصدارات 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` هذه البادئة ويقرأ من جذر المجموعة الصحيح.

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

فعّل فهرسة الجلسات لاسترجاع المحادثات السابقة. يحتاج QMD إلى كلٍ من مصدر جلسات
`memorySearch` العام ومصدّر نصوص QMD:

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

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

لا تزال نتائج الجلسات تُرشّح بواسطة
[`tools.sessions.visibility`](/ar/gateway/config-tools#toolssessions). لا تكشف
رؤية `tree` الافتراضية الجلسات غير ذات الصلة للوكيل نفسه. إذا كان يجب أن تكون
جلسة مُرسلة عبر Gateway قابلة للاسترجاع من جلسة DM منفصلة، فاضبط
`tools.sessions.visibility: "agent"` عن قصد.

## نطاق البحث

افتراضيًا، تظهر نتائج بحث 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. أبقِ عمليات checkout المؤقتة للمستودعات الأحادية تحت
أدلة مخفية مثل `.tmp/` أو خارج جذور QMD المفهرسة إلى أن يوفّر QMD اجتيازًا
آمنًا من الدورات أو عناصر تحكم صريحة للاستبعاد.

## الإعدادات

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

## ذات صلة

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