---
read_when:
    - می‌خواهید سازوکار پیش‌فرض حافظه را درک کنید
    - می‌خواهید ارائه‌دهندگان تعبیه‌سازی یا جست‌وجوی ترکیبی را پیکربندی کنید
summary: بک‌اند پیش‌فرض حافظه مبتنی بر SQLite با جست‌وجوی کلیدواژه‌ای، برداری و ترکیبی
title: موتور حافظه داخلی
x-i18n:
    generated_at: "2026-07-12T09:54:49Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: e8cbe2bae73b1d393ac158edb67fc442e76d1e5ff93e5201dbb7e7216801aa85
    source_path: concepts/memory-builtin.md
    workflow: 16
---

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

## امکانات

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

## شروع به کار

موتور داخلی به‌طور پیش‌فرض از تعبیه‌سازی‌های OpenAI استفاده می‌کند. اگر `OPENAI_API_KEY` یا
`models.providers.openai.apiKey` از قبل پیکربندی شده باشد، جست‌وجوی برداری
بدون نیاز به پیکربندی اضافی حافظه کار می‌کند.

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

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

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

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

```bash
openclaw plugins install @openclaw/llama-cpp-provider
```

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

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

| ارائه‌دهنده       | شناسه               | توضیحات                                      |
| ----------------- | ------------------- | -------------------------------------------- |
| Bedrock           | `bedrock`           | از زنجیرهٔ اعتبارنامهٔ AWS استفاده می‌کند    |
| DeepInfra         | `deepinfra`         | پیش‌فرض: `BAAI/bge-m3`                       |
| Gemini            | `gemini`            | از چندرسانه‌ای (تصویر + صدا) پشتیبانی می‌کند |
| GitHub Copilot    | `github-copilot`    | از اشتراک Copilot شما استفاده می‌کند         |
| LM Studio         | `lmstudio`          | محلی/خودمیزبان                               |
| محلی              | `local`             | `@openclaw/llama-cpp-provider`                |
| Mistral           | `mistral`           |                                              |
| Ollama            | `ollama`            | محلی/خودمیزبان                               |
| OpenAI            | `openai`            | پیش‌فرض: `text-embedding-3-small`             |
| سازگار با OpenAI  | `openai-compatible` | نقطهٔ پایانی عمومی `/v1/embeddings`           |
| Voyage            | `voyage`            |                                              |

برای تغییر ارائه‌دهنده از OpenAI، مقدار `memorySearch.provider` را تنظیم کنید.

## نحوهٔ کار نمایه‌سازی

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

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

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

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

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

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

اگر به رتبه‌بندی مجدد، گسترش پرس‌وجو یا نمایه‌سازی پوشه‌های خارج از فضای کاری نیاز دارید،
استفاده از [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` یکسانی استفاده می‌کنند.
هنگامی که تعبیه‌سازی محلی می‌خواهید، `memorySearch.provider: "local"` را تنظیم کنید.

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

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

## پیکربندی

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

## مرتبط

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