محرك ذاكرة QMD

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.

# التفعيل

{
  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 مباشرة.

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

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

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

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

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

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

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

qmd --help | grep -i collection

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

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

تمر متغيرات بيئة نماذج QMD دون تغيير من عملية Gateway، لذلك يمكنك ضبط QMD عمومياً دون إضافة إعداد OpenClaw جديد:

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 إلى أدلة إضافية لجعلها قابلة للبحث:

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

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

# فهرسة نُسخ جلسات الحوار

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

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

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

# نطاق البحث

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

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

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

# الاقتباسات

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

# متى تستخدمه

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

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

للإعدادات الأبسط، يعمل المحرك المضمّن جيداً دون اعتمادات إضافية.

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

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

إذا كان qmd --version يعمل في صدفتك لكن OpenClaw لا يزال يبلغ عن spawn qmd ENOENT، فمن المحتمل أن عملية Gateway لديها PATH مختلف عن صدفتك التفاعلية. ثبّت الملف التنفيذي صراحةً:

{
  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.*)، وأوضاع البحث، وفواصل التحديث، وقواعد النطاق، وكل عناصر التحكم الأخرى، راجع مرجع إعداد الذاكرة.

# ذات صلة

• نظرة عامة على الذاكرة
• محرك الذاكرة المضمّن
• ذاكرة Honcho