موتور حافظه 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 و پس از آن به‌صورت دوره‌ای (memory.qmd.update.interval، پیش‌فرض 5m) دستور qmd update را اجرا می‌کند. تازه‌سازی‌ها از طریق زیرفرایندهای 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 است)، بنابراین راه‌اندازی سرد از واردکردن زمان‌اجرای حافظه یا ایجاد پایشگر بلندمدت پیش از نخستین استفاده از حافظه جلوگیری می‌کند.
• برای مقداردهی اولیه QMD هنگام شروع Gateway، مقدار memory.qmd.update.startup را روی idle یا immediate تنظیم کنید. مقدار پیش‌فرض memory.qmd.update.onBoot برابر true است و تازه‌سازی اولیه را هنگام راه‌اندازی اجرا می‌کند؛ برای ردکردن آن تازه‌سازی فوری، آن را روی false تنظیم کنید (اگر بازه‌های به‌روزرسانی یا تعبیه‌سازی پیکربندی شده باشند، مدیر بلندمدت همچنان باز می‌شود، بنابراین QMD مالکیت پایشگر/زمان‌سنج‌های عادی خود را حفظ می‌کند).
• جست‌وجوها از searchMode پیکربندی‌شده استفاده می‌کنند (پیش‌فرض: search؛ همچنین از vsearch و query پشتیبانی می‌کند). حالت search فقط از BM25 استفاده می‌کند، بنابراین OpenClaw در این حالت بررسی‌های آمادگی بردار معنایی و نگهداری تعبیه‌سازی را رد می‌کند. اگر حالتی ناموفق باشد، OpenClaw با qmd query دوباره تلاش می‌کند.
• وقتی searchMode برابر query است، برای استفاده از مسیر پرس‌وجوی ترکیبی QMD بدون رتبه‌بندی‌کننده مجدد، memory.qmd.rerank را روی false تنظیم کنید (به 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 هم به منبع عمومی نشست 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 باید از یک نشست پیام مستقیم جداگانه قابل یادآوری باشد، 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>#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 تنظیم کنید.

نتایج در گفت‌وگوهای گروهی یا کانال خالی هستند؟ این رفتار با memory.qmd.scope پیش‌فرض که فقط نشست‌های مستقیم را مجاز می‌کند، مورد انتظار است. اگر نتایج QMD را در آنجا می‌خواهید، یک قانون allow برای انواع گفت‌وگوی group یا channel اضافه کنید.

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

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

پیکربندی

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

مرتبط

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