---
read_when:
    - می‌خواهید QMD را به‌عنوان بک‌اند حافظهٔ خود راه‌اندازی کنید
    - ویژگی‌های پیشرفتهٔ حافظه، مانند بازرتبه‌بندی یا مسیرهای نمایه‌شدهٔ اضافی، می‌خواهید
summary: سایدکار جست‌وجوی محلی‌محور با BM25، بردارها، بازرتبه‌بندی و گسترش پرس‌وجو
title: موتور حافظه QMD
x-i18n:
    generated_at: "2026-07-16T16:02:48Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: b13017ead7e7340624a35e603a18216a5c23405cbab09e7f53b1e15d74d59d23
    source_path: concepts/memory-qmd.md
    workflow: 16
---

[QMD](https://github.com/tobi/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/` ایجاد می‌کند و چرخه عمر ابزار جانبی را
به‌طور خودکار مدیریت می‌کند؛ مجموعه‌ها، به‌روزرسانی‌ها و اجرای تعبیه‌سازی برای شما انجام می‌شوند.
این سامانه شکل‌های کنونی مجموعه و پرس‌وجوی 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 را
  مستقیماً دوباره بررسی می‌کنند.

<Info>
نخستین جست‌وجو ممکن است کند باشد؛ QMD در نخستین اجرای `qmd query`
مدل‌های GGUF (حدود 2 GB) را برای رتبه‌بندی مجدد و گسترش پرس‌وجو به‌طور خودکار بارگیری می‌کند.
</Info>

## عملکرد و سازگاری جست‌وجو

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

```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`](/fa/gateway/config-tools#toolssessions) پالایش می‌شوند. قابلیت مشاهده پیش‌فرض
`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.

برای راه‌اندازی‌های ساده‌تر، [موتور داخلی](/fa/concepts/memory-builtin) بدون
وابستگی اضافی به‌خوبی کار می‌کند.

## عیب‌یابی

**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",
    },
  },
}
```

در محیطی که 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.*`)، حالت‌های جست‌وجو، بازه‌های به‌روزرسانی،
قواعد دامنه و همه تنظیمات دیگر، به
[مرجع پیکربندی حافظه](/fa/reference/memory-config) مراجعه کنید.

## مرتبط

- [نمای کلی حافظه](/fa/concepts/memory)
- [موتور حافظه داخلی](/fa/concepts/memory-builtin)
- [حافظه Honcho](/fa/concepts/memory-honcho)