موتور حافظه 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/ ایجاد می‌کند و چرخه عمر ابزار جانبی را به‌طور خودکار مدیریت می‌کند - مجموعه‌ها، به‌روزرسانی‌ها و اجرای تعبیه‌سازی برای شما مدیریت می‌شوند. این سامانه شکل‌های فعلی مجموعه و پرس‌وجوی MCP در QMD را ترجیح می‌دهد، اما در صورت نیاز به پرچم‌های جایگزین الگوی مجموعه و نام‌های قدیمی‌تر ابزار MCP بازمی‌گردد. همگام‌سازی هنگام راه‌اندازی همچنین مجموعه‌های مدیریت‌شده قدیمی را دوباره با الگوهای معیارشان ایجاد می‌کند، اگر مجموعه قدیمی‌تری از QMD با همان نام همچنان وجود داشته باشد.

نحوه کار ابزار جانبی

• OpenClaw از فایل‌های حافظه فضای کاری و memory.qmd.paths پیکربندی‌شده مجموعه می‌سازد. آداپتور QMD مالک منطق‌های اکتشافی به‌روزرسانی، تعبیه‌سازی، رفع پرش و مهلت زمانی است؛ این موارد قابل پیکربندی توسط کاربر نیستند.
• QMD همچنان مالک index.sqlite، پیکربندی YAML مجموعه و دانلودهای مدل در خانه QMD مختص هر عامل است؛ این‌ها مصنوعات ابزار خارجی‌اند، نه جدول‌های وضعیت OpenClaw. هماهنگی تحت مالکیت OpenClaw فقط در SQLite قرار دارد: یک اجاره مشترک، کار تعبیه‌سازی میان عامل‌ها را محدود می‌کند، درحالی‌که یک اجاره در پایگاه داده هر عامل، نوشتن‌های مجموعه، به‌روزرسانی و تعبیه‌سازی آن عامل را به‌صورت متوالی اجرا می‌کند. زمان اجرا دیگر ابزارهای جانبی قفل فایل QMD را ایجاد نمی‌کند. openclaw doctor --fix ابزارهای جانبی بازنشسته را فقط پس از اثبات منقضی‌بودن مالک پردازش قدیمی آن‌ها حذف می‌کند. ارتقاها یک گذار کامل و یک‌باره هستند: پیش از استفاده از نسخه جدید، همه فرایندهای OpenClaw را که پوشه وضعیت را به‌اشتراک می‌گذارند متوقف و دوباره راه‌اندازی کنید. نویسنده‌های ترکیبی قدیمی/جدید QMD پشتیبانی نمی‌شوند؛ زمان اجرا عمداً ابزارهای جانبی بازنشسته را به‌طور هم‌زمان قفل نمی‌کند.
• مجموعه پیش‌فرض فضای کاری، MEMORY.md و درخت memory/ را ردیابی می‌کند. memory.md با حروف کوچک به‌عنوان فایل حافظه ریشه نمایه‌سازی نمی‌شود.
• اسکنر خود QMD مسیرهای مخفی و پوشه‌های رایج وابستگی/ساخت مانند .git، .cache، node_modules، vendor، dist و build را نادیده می‌گیرد. راه‌اندازی Gateway، 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 همه مجموعه‌های دارای منبع یکسان را با یک فرمان جست‌وجو می‌کند:

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 عبور می‌کنند، بنابراین می‌توانید بدون افزودن پیکربندی جدید OpenClaw، QMD را به‌صورت سراسری تنظیم کنید:

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 هم به منبع عمومی نشست memory.search و هم به صادرکننده رونوشت QMD نیاز دارد:

{  memory: {    backend: "qmd",    search: {      experimental: { sessionMemory: true },      sources: ["memory", "sessions"],    },    qmd: {      sessions: { enabled: true },    },  },}

رونوشت‌ها به‌صورت نوبت‌های پاک‌سازی‌شده کاربر/دستیار به یک مجموعه اختصاصی QMD در ~/.openclaw/agents/<id>/qmd/sessions/ صادر می‌شوند. تنظیم صرف sources: ["sessions"] رونوشت‌ها را به QMD صادر نمی‌کند؛ rememberAcrossConversations یا صادرات صریح نشست QMD را نیز فعال کنید.

نتایج نشست همچنان با tools.sessions.visibility فیلتر می‌شوند. قابلیت مشاهده پیش‌فرض tree شامل نشست فعلی، نشست‌های ایجادشده توسط آن و نشست‌های گروهی همان عامل است که از طریق آگاهی محیطی گروه پایش می‌شوند. با session.dmScope: "main"، کاربران در یک راه‌اندازی پیام مستقیم چندکاربره، نشست اصلی را به‌اشتراک می‌گذارند و می‌توانند محتوای گروه‌های پایش‌شده آن را بازیابی کنند. برای جداسازی پیام مستقیم از dmScope مختص هر همتا استفاده کنید، یا قابلیت مشاهده را روی "self" تنظیم کنید تا از خواندن محیطی نشست‌های پایش‌شده انصراف دهید. سایر نشست‌های نامرتبط همان عامل همچنان به قابلیت مشاهده "agent" نیاز دارند.

دامنه جست‌وجو

به‌طور پیش‌فرض، نتایج جست‌وجوی QMD فقط در نشست‌های مستقیم نمایش داده می‌شوند (نه گفت‌وگوهای گروهی یا کانالی). برای تغییر این رفتار، memory.qmd.scope را پیکربندی کنید:

{  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 متفاوتی دارد. فایل اجرایی را صریحاً مشخص کنید:

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

در محیطی که QMD نصب شده است از command -v 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 پیش‌فرض که فقط نشست‌های مستقیم را مجاز می‌کند، مورد انتظار است. اگر نتایج QMD را در آنجا می‌خواهید، یک قانون allow برای انواع گفت‌وگوی group یا channel اضافه کنید.

جست‌وجوی حافظه ریشه ناگهان بیش از حد گسترده شده است؟ Gateway را دوباره راه‌اندازی کنید یا تا همگام‌سازی راه‌اندازی بعدی صبر کنید. OpenClaw هنگام تشخیص تداخل نام یکسان، مجموعه‌های مدیریت‌شده قدیمی را دوباره با الگوهای معیار MEMORY.md و memory/ ایجاد می‌کند.

مخزن‌های موقت قابل‌مشاهده در فضای کاری باعث ENAMETOOLONG یا خرابی نمایه‌سازی می‌شوند؟ پیمایش QMD به‌جای قوانین پیوند نمادین موتور داخلی OpenClaw، از اسکنر زیربنایی QMD پیروی می‌کند. تا زمانی که QMD پیمایش ایمن در برابر چرخه یا کنترل‌های صریح استثناکردن را ارائه کند، نسخه‌های کاری موقت تک‌مخزنی را در پوشه‌های مخفی مانند .tmp/ یا خارج از ریشه‌های نمایه‌شده QMD نگه دارید.

پیکربندی

برای سطح کامل پیکربندی (memory.qmd.*)، حالت‌های جست‌وجو، فاصله‌های به‌روزرسانی، قوانین دامنه و همه گزینه‌های دیگر، به مرجع پیکربندی حافظه مراجعه کنید.

مرتبط

• نمای کلی حافظه
• موتور حافظه داخلی
• حافظه Honcho