---
read_when:
    - می‌خواهید بک‌اند حافظهٔ پیش‌فرض را درک کنید
    - می‌خواهید ارائه‌دهندگان بردارسازی یا جست‌وجوی ترکیبی را پیکربندی کنید
summary: بک‌اند حافظهٔ پیش‌فرض مبتنی بر SQLite با جست‌وجوی کلیدواژه‌ای، برداری و ترکیبی
title: موتور حافظهٔ داخلی
x-i18n:
    generated_at: "2026-05-03T21:30:50Z"
    model: gpt-5.5
    provider: openai
    source_hash: 72f5d1fee02bff0962bd012575b62846c1f11c030fd1174fdb2af1e81909f52a
    source_path: concepts/memory-builtin.md
    workflow: 16
---

موتور داخلی، بک‌اند پیش‌فرض حافظه است. این موتور نمایهٔ حافظهٔ شما را در
یک پایگاه‌دادهٔ SQLite برای هر عامل ذخیره می‌کند و برای شروع به وابستگی اضافه‌ای نیاز ندارد.

## آنچه فراهم می‌کند

- **جست‌وجوی کلیدواژه‌ای** از طریق نمایه‌سازی متن کامل FTS5 (امتیازدهی BM25).
- **جست‌وجوی برداری** از طریق بردارهای تعبیه از هر ارائه‌دهندهٔ پشتیبانی‌شده.
- **جست‌وجوی ترکیبی** که هر دو را برای بهترین نتیجه‌ها ترکیب می‌کند.
- **پشتیبانی از CJK** از طریق توکن‌سازی سه‌حرفی برای چینی، ژاپنی و کره‌ای.
- **شتاب‌دهی sqlite-vec** برای پرس‌وجوهای برداری درون پایگاه‌داده (اختیاری).

## شروع به کار

اگر برای OpenAI، Gemini، Voyage، Mistral یا DeepInfra کلید API دارید، موتور داخلی
آن را خودکار شناسایی می‌کند و جست‌وجوی برداری را فعال می‌کند. نیازی به پیکربندی نیست.

برای تنظیم صریح یک ارائه‌دهنده:

```json5
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
      },
    },
  },
}
```

بدون ارائه‌دهندهٔ بردار تعبیه، فقط جست‌وجوی کلیدواژه‌ای در دسترس است.

برای اجبار به استفاده از ارائه‌دهندهٔ محلی داخلی بردار تعبیه، بستهٔ runtime اختیاری
`node-llama-cpp` را کنار OpenClaw نصب کنید، سپس `local.modelPath`
را به یک فایل GGUF اشاره دهید:

```json5
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "local",
        fallback: "none",
        local: {
          modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",
        },
      },
    },
  },
}
```

## ارائه‌دهندگان پشتیبانی‌شدهٔ بردار تعبیه

| ارائه‌دهنده | شناسه | شناسایی خودکار | نکته‌ها |
| --------- | ----------- | ------------- | ----------------------------------- |
| OpenAI    | `openai`    | بله           | پیش‌فرض: `text-embedding-3-small`   |
| Gemini    | `gemini`    | بله           | از چندرسانه‌ای (تصویر + صوت) پشتیبانی می‌کند |
| Voyage    | `voyage`    | بله           |                                     |
| Mistral   | `mistral`   | بله           |                                     |
| DeepInfra | `deepinfra` | بله           | پیش‌فرض: `BAAI/bge-m3`              |
| Ollama    | `ollama`    | خیر           | محلی، به‌صورت صریح تنظیم شود               |
| محلی     | `local`     | بله (اول)   | runtime اختیاری `node-llama-cpp`   |

شناسایی خودکار نخستین ارائه‌دهنده‌ای را که کلید API آن قابل حل باشد، به ترتیبی که
نمایش داده شده انتخاب می‌کند. برای بازنویسی، `memorySearch.provider` را تنظیم کنید.

## نمایه‌سازی چگونه کار می‌کند

OpenClaw فایل‌های `MEMORY.md` و `memory/*.md` را به قطعه‌ها (حدود ۴۰۰ توکن با
هم‌پوشانی ۸۰ توکنی) نمایه‌سازی می‌کند و آن‌ها را در یک پایگاه‌دادهٔ SQLite برای هر عامل ذخیره می‌کند.

- **محل نمایه:** `~/.openclaw/memory/<agentId>.sqlite`
- **نگهداری ذخیره‌سازی:** فایل‌های جانبی SQLite WAL با checkpointهای دوره‌ای و
  هنگام خاموشی محدود نگه داشته می‌شوند.
- **پایش فایل:** تغییرات فایل‌های حافظه یک نمایه‌سازی دوبارهٔ debounce‌شده را فعال می‌کنند (۱.۵ ثانیه).
- **نمایه‌سازی دوبارهٔ خودکار:** وقتی ارائه‌دهندهٔ بردار تعبیه، مدل، یا پیکربندی قطعه‌بندی
  تغییر کند، کل نمایه به‌صورت خودکار از نو ساخته می‌شود.
- **نمایه‌سازی دوباره بر اساس درخواست:** `openclaw memory index --force`

<Info>
همچنین می‌توانید فایل‌های Markdown خارج از workspace را با
`memorySearch.extraPaths` نمایه‌سازی کنید. [مرجع پیکربندی](/fa/reference/memory-config#additional-memory-paths) را ببینید.
</Info>

## زمان استفاده

موتور داخلی انتخاب مناسب بیشتر کاربران است:

- بدون وابستگی اضافه، آمادهٔ استفاده است.
- جست‌وجوی کلیدواژه‌ای و برداری را به‌خوبی مدیریت می‌کند.
- از همهٔ ارائه‌دهندگان بردار تعبیه پشتیبانی می‌کند.
- جست‌وجوی ترکیبی بهترین بخش‌های هر دو رویکرد بازیابی را با هم ترکیب می‌کند.

اگر به رتبه‌بندی دوباره، گسترش پرس‌وجو، یا نمایه‌سازی پوشه‌های خارج از workspace نیاز دارید،
به [QMD](/fa/concepts/memory-qmd) مهاجرت کنید.

اگر حافظهٔ بین نشست‌ها با مدل‌سازی خودکار کاربر می‌خواهید،
[Honcho](/fa/concepts/memory-honcho) را در نظر بگیرید.

## عیب‌یابی

**جست‌وجوی حافظه غیرفعال است؟** `openclaw memory status` را بررسی کنید. اگر هیچ ارائه‌دهنده‌ای
شناسایی نشد، یکی را صریح تنظیم کنید یا یک کلید API اضافه کنید.

**ارائه‌دهندهٔ محلی شناسایی نمی‌شود؟** تأیید کنید مسیر محلی وجود دارد و اجرا کنید:

```bash
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
```

هم فرمان‌های مستقل CLI و هم Gateway از همان شناسهٔ ارائه‌دهندهٔ `local` استفاده می‌کنند.
اگر ارائه‌دهنده روی `auto` تنظیم شده باشد، بردارهای تعبیهٔ محلی فقط وقتی ابتدا در نظر گرفته می‌شوند
که `memorySearch.local.modelPath` به یک فایل محلی موجود اشاره کند.

**نتایج قدیمی هستند؟** برای بازسازی، `openclaw memory index --force` را اجرا کنید. پایشگر
ممکن است در موارد مرزی نادر برخی تغییرات را از دست بدهد.

**sqlite-vec بارگذاری نمی‌شود؟** OpenClaw به‌صورت خودکار به شباهت کسینوسی درون‌فرایندی
برمی‌گردد. `openclaw memory status --deep` ذخیره‌ساز برداری محلی را جدا از ارائه‌دهندهٔ بردار تعبیه
گزارش می‌کند؛ بنابراین `Vector store: unavailable` به بارگذاری sqlite-vec اشاره دارد، درحالی‌که
`Embeddings: unavailable` به ارائه‌دهنده/احراز هویت یا آماده‌بودن مدل اشاره می‌کند. برای خطای بارگذاری مشخص، logها را بررسی کنید.

## پیکربندی

برای راه‌اندازی ارائه‌دهندهٔ بردار تعبیه، تنظیم جست‌وجوی ترکیبی (وزن‌ها، MMR، کاهش زمانی)،
نمایه‌سازی دسته‌ای، حافظهٔ چندرسانه‌ای، sqlite-vec، مسیرهای اضافه، و همهٔ
گزینه‌های پیکربندی دیگر، [مرجع پیکربندی حافظه](/fa/reference/memory-config) را ببینید.

## مرتبط

- [نمای کلی حافظه](/fa/concepts/memory)
- [جست‌وجوی حافظه](/fa/concepts/memory-search)
- [Active Memory](/fa/concepts/active-memory)