OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

ابدأ

محرك الذاكرة QMD

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 وبصفة دورية بعد ذلك (memory.qmd.update.interval، والقيمة الافتراضية 5m). تُنفّذ عمليات التحديث عبر عمليات QMD الفرعية، لا عبر مسح لنظام الملفات داخل العملية. كما تشغّل أوضاع البحث الدلالي qmd embed (memory.qmd.update.embedInterval، والقيمة الافتراضية 60m).
  • تتعقب مجموعة مساحة العمل الافتراضية MEMORY.md بالإضافة إلى شجرة memory/. ولا تتم فهرسة memory.md المكتوبة بأحرف صغيرة باعتبارها ملف ذاكرة جذريًا.
  • يتجاهل الماسح الخاص بـ QMD المسارات المخفية وأدلة التبعيات/البناء الشائعة مثل .git و.cache وnode_modules وvendor وdist و build. لا يهيّئ بدء تشغيل Gateway محرك QMD افتراضيًا (القيمة الافتراضية لـ memory.qmd.update.startup هي off)؛ لذا يتجنب التشغيل البارد استيراد وقت تشغيل الذاكرة أو إنشاء المراقب طويل العمر قبل استخدام الذاكرة لأول مرة.
  • اضبط memory.qmd.update.startup على idle أو immediate لتهيئة QMD عند بدء Gateway رغم ذلك. القيمة الافتراضية لـ memory.qmd.update.onBoot هي true، ويشغّل التحديث الأولي عند بدء التشغيل؛ اضبطه على false لتخطي ذلك التحديث الفوري (يظل المدير طويل العمر مفتوحًا عند تهيئة فواصل التحديث أو التضمين، بحيث يواصل QMD امتلاك المراقب/المؤقتات الدورية الخاصة به).
  • تستخدم عمليات البحث searchMode المُهيأ (الافتراضي: search؛ ويدعم أيضًا vsearch وquery). يعتمد search على BM25 فقط؛ لذا يتخطى OpenClaw اختبارات جاهزية المتجهات الدلالية وصيانة التضمينات في ذلك الوضع. وإذا فشل أحد الأوضاع، يعيد OpenClaw المحاولة باستخدام qmd query.
  • عندما تكون قيمة searchMode هي query، اضبط memory.qmd.rerank على false لاستخدام مسار الاستعلام الهجين في QMD دون أداة إعادة الترتيب (يتطلب QMD 2.1 أو أحدث). يمرّر OpenClaw الخيار --no-rerank إلى مسار CLI المباشر لـ QMD و rerank: false إلى أداة استعلام MCP الخاصة بـ QMD.
  • مع إصدارات QMD التي تعلن دعم مرشحات المجموعات المتعددة، يجمع OpenClaw المجموعات ذات المصدر نفسه في استدعاء بحث QMD واحد. وتحتفظ إصدارات QMD الأقدم بمسار الرجوع الاحتياطي المتوافق لكل مجموعة.
  • إذا فشل QMD بالكامل، يرجع OpenClaw إلى محرك SQLite المدمج. تتباطأ محاولات أدوار المحادثة المتكررة لفترة وجيزة بعد فشل الفتح كي لا يؤدي غياب الملف التنفيذي أو تعطل إحدى تبعيات المحرك المساعد إلى عاصفة من إعادة المحاولات؛ بينما يظل openclaw memory status واختبارات CLI أحادية التنفيذ يعيدان فحص QMD مباشرةً.

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

يحافظ 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. ولا تكشف رؤية tree الافتراضية جلسات أخرى غير مرتبطة للوكيل نفسه. إذا كان ينبغي إتاحة استرجاع جلسة أرسلها Gateway من جلسة رسائل مباشرة منفصلة، فاضبط 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>#L<line> (أو #L<start>-L<end>). وفي وضع auto لا يُضاف التذييل إلا لجلسات المحادثة المباشرة. اضبط 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 مختلفًا عن صدفة الأوامر التفاعلية. ثبّت مسار الملف التنفيذي صراحةً:

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، للأجهزة الأبطأ. ينطبق هذا الحد على أوامر البحث الخاصة بـ QMD أثناء استدعاءات memory_search للوكيل؛ بينما تحتفظ عمليات الإعداد والمزامنة والرجوع إلى المحرك المدمج والعمل على المتون التكميلية بمهلها الأقصر الخاصة.

هل تظهر نتائج فارغة في محادثات المجموعات أو القنوات؟ هذا متوقع مع memory.qmd.scope الافتراضي، الذي لا يسمح إلا بالجلسات المباشرة. أضف قاعدة allow لنوعي المحادثة group أو channel إذا أردت ظهور نتائج QMD هناك.

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

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

الإعداد

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

ذو صلة

Was this useful?
On this page

On this page