محرك ذاكرة 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.

التفعيل

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

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

يحافظ 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 هذه البادئة ويقرأ من جذر المجموعة الصحيح.

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

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

{  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 قابلة للاسترجاع من جلسة DM منفصلة، فاضبط tools.sessions.visibility: "agent" عن قصد.

نطاق البحث

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

الإعدادات

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

ذات صلة

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