--- read_when: - می‌خواهید ارائه‌دهندگان جست‌وجوی حافظه یا مدل‌های تعبیه‌سازی را پیکربندی کنید - می‌خواهید بک‌اند QMD را راه‌اندازی کنید - می‌خواهید جست‌وجوی ترکیبی، MMR یا زوال زمانی را تنظیم کنید - می‌خواهید نمایه‌سازی حافظهٔ چندوجهی را فعال کنید sidebarTitle: Memory config summary: همه گزینه‌های پیکربندی برای جست‌وجوی حافظه، ارائه‌دهندگان تعبیه‌سازی، QMD، جست‌وجوی ترکیبی و نمایه‌سازی چندوجهی title: مرجع پیکربندی حافظه x-i18n: generated_at: "2026-07-16T17:19:57Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 1947d6d654de85059ef777a3a6387f6db5b76c8d688fbb539a063162d323c1f6 source_path: reference/memory-config.md workflow: 16 --- این صفحه همه گزینه‌های پیکربندی جست‌وجوی حافظه OpenClaw را فهرست می‌کند. برای مرورهای مفهومی، بنگرید به: نحوه کار حافظه. بک‌اند پیش‌فرض SQLite. فرایند جانبی با اولویت اجرای محلی. خط لوله جست‌وجو و تنظیم آن. زیرعامل حافظه برای نشست‌های تعاملی. همه تنظیمات جست‌وجوی حافظه، مگر آنکه خلافش ذکر شده باشد، زیر `agents.defaults.memorySearch` در `openclaw.json` (یا یک بازنویسی مختص هر عامل در `agents.list[].memorySearch`) قرار دارند. اگر به‌دنبال کلید فعال‌سازی قابلیت **Active Memory** و پیکربندی زیرعامل هستید، این موارد به‌جای `memorySearch` زیر `plugins.entries.active-memory` قرار دارند. Active Memory از یک مدل دوشرطی استفاده می‌کند: 1. Plugin باید فعال باشد و شناسه عامل فعلی را هدف بگیرد 2. درخواست باید یک نشست گفت‌وگوی تعاملی، ماندگار و واجد شرایط باشد برای مدل فعال‌سازی، پیکربندی تحت مالکیت Plugin، ماندگاری رونوشت و الگوی عرضه ایمن، به [Active Memory](/fa/concepts/active-memory) مراجعه کنید. --- ## انتخاب ارائه‌دهنده | کلید | نوع | پیش‌فرض | توضیحات | | ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | `boolean` | `true` | فعال یا غیرفعال‌کردن جست‌وجوی حافظه | | `provider` | `string` | `"openai"` | شناسه آداپتور تعبیه‌سازی مانند `bedrock`، `deepinfra`، `gemini`، `github-copilot`، `local`، `mistral`، `ollama`، `openai`، `openai-compatible` یا `voyage`؛ همچنین می‌تواند یک `models.providers.` پیکربندی‌شده باشد که `api` آن به یک آداپتور تعبیه‌سازی حافظه یا API مدل سازگار با OpenAI اشاره می‌کند | | `model` | `string` | پیش‌فرض ارائه‌دهنده | نام مدل تعبیه‌سازی | | `fallback` | `string` | `"none"` | شناسه آداپتور جایگزین در صورت خرابی آداپتور اصلی | وقتی `provider` تنظیم نشده باشد، OpenClaw از تعبیه‌سازی‌های OpenAI استفاده می‌کند. برای استفاده از Bedrock، DeepInfra، Gemini، GitHub Copilot، Mistral، Ollama، Voyage، یک مدل محلی GGUF یا نقطه پایانی `/v1/embeddings` سازگار با OpenAI، مقدار `provider` را به‌صراحت تنظیم کنید. پیکربندی‌های قدیمی که همچنان `provider: "auto"` را ذکر می‌کنند، به `openai` نگاشت می‌شوند. تغییر ارائه‌دهنده یا مدل تعبیه‌سازی، تنظیمات ارائه‌دهنده، منابع، دامنه، قطعه‌بندی یا توکن‌ساز می‌تواند نمایه برداری موجود SQLite را ناسازگار کند. OpenClaw به‌جای تعبیه‌سازی مجدد خودکار همه‌چیز، جست‌وجوی برداری را متوقف می‌کند و هشدار هویت نمایه را گزارش می‌دهد. هر زمان آماده بودید، با `openclaw memory status --index --agent ` یا `openclaw memory index --force --agent ` آن را بازسازی کنید. وقتی `provider` تنظیم نشده باشد، `provider: "auto"` قدیمی وجود داشته باشد یا `provider: "none"` عمداً حالت فقط FTS را انتخاب کند، در صورت دردسترس‌نبودن تعبیه‌سازی‌ها، بازیابی حافظه همچنان می‌تواند از رتبه‌بندی واژگانی FTS استفاده کند. ارائه‌دهندگان غیرمحلی که به‌صراحت انتخاب شده‌اند، در صورت خطا بسته باقی می‌مانند. اگر `memorySearch.provider` را روی یک ارائه‌دهنده مشخص با پشتوانه راه‌دور مانند Bedrock، DeepInfra، Gemini، GitHub Copilot، LM Studio، Mistral، Ollama، OpenAI، Voyage یا یک ارائه‌دهنده سفارشی سازگار با OpenAI تنظیم کنید و آن ارائه‌دهنده هنگام اجرا دردسترس نباشد، `memory_search` به‌جای استفاده بی‌سروصدا از بازیابی فقط FTS، نتیجه عدم دسترسی را برمی‌گرداند. پیکربندی ارائه‌دهنده/احراز هویت را اصلاح کنید، به یک ارائه‌دهنده دردسترس تغییر دهید یا اگر عمداً بازیابی فقط FTS را می‌خواهید، `provider: "none"` را تنظیم کنید. ### شناسه‌های ارائه‌دهنده سفارشی `memorySearch.provider` می‌تواند برای آداپتورهای ارائه‌دهنده مختص حافظه مانند `ollama` یا APIهای مدل سازگار با OpenAI مانند `openai-responses` / `openai-completions` به یک ورودی سفارشی `models.providers.` اشاره کند. OpenClaw مالک `api` آن ارائه‌دهنده را برای آداپتور تعبیه‌سازی شناسایی می‌کند و درعین‌حال شناسه ارائه‌دهنده سفارشی را برای مدیریت نقطه پایانی، احراز هویت و پیشوند مدل حفظ می‌کند. این قابلیت به پیکربندی‌های چند-GPU یا چندمیزبانه اجازه می‌دهد تعبیه‌سازی‌های حافظه را به یک نقطه پایانی محلی مشخص اختصاص دهند: ```json5 { models: { providers: { "ollama-5080": { api: "ollama", baseUrl: "http://gpu-box.local:11435", apiKey: "ollama-local", models: [{ id: "qwen3-embedding:0.6b", name: "Qwen3 Embedding 0.6B" }], }, }, }, agents: { defaults: { memorySearch: { provider: "ollama-5080", model: "qwen3-embedding:0.6b", }, }, }, } ``` ### تشخیص کلید API تعبیه‌سازی‌های راه‌دور به کلید API نیاز دارند. Bedrock در عوض از زنجیره پیش‌فرض اعتبارنامه AWS SDK استفاده می‌کند (نقش‌های نمونه، SSO، کلیدهای دسترسی یا کلید API مربوط به Bedrock). | ارائه‌دهنده | متغیر محیطی | کلید پیکربندی | | -------------- | --------------------------------------------------- | ----------------------------------- | | Bedrock | زنجیره اعتبارنامه AWS یا `AWS_BEARER_TOKEN_BEDROCK` | نیازی به کلید API نیست | | DeepInfra | `DEEPINFRA_API_KEY` | `models.providers.deepinfra.apiKey` | | Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | | GitHub Copilot | `COPILOT_GITHUB_TOKEN`، `GH_TOKEN`، `GITHUB_TOKEN` | نمایه احراز هویت از طریق ورود دستگاه | | Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | | Ollama | `OLLAMA_API_KEY` (جای‌نگهدار) | -- | | OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | | Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | OAuth مربوط به Codex فقط گفت‌وگو/تکمیل‌ها را پوشش می‌دهد و نیازمندی‌های درخواست‌های تعبیه‌سازی را برآورده نمی‌کند. --- ## پیکربندی نقطه پایانی راه‌دور از `provider: "openai-compatible"` برای یک سرور عمومی `/v1/embeddings` سازگار با OpenAI استفاده کنید که نباید اعتبارنامه‌های سراسری گفت‌وگوی OpenAI را به ارث ببرد. نشانی پایه سفارشی API. بازنویسی کلید API. سرآیندهای HTTP اضافی (ادغام‌شده با پیش‌فرض‌های ارائه‌دهنده). ```json5 { agents: { defaults: { memorySearch: { provider: "openai-compatible", model: "text-embedding-3-small", remote: { baseUrl: "https://api.example.com/v1/", apiKey: "YOUR_KEY", }, }, }, }, } ``` --- ## پیکربندی مختص ارائه‌دهنده | کلید | نوع | پیش‌فرض | توضیحات | | ---------------------- | -------- | ---------------------- | ------------------------------------------- | | `model` | `string` | `gemini-embedding-001` | از `gemini-embedding-2-preview` نیز پشتیبانی می‌کند | | `outputDimensionality` | `number` | `3072` | برای Embedding 2: 768، 1536 یا 3072 | تغییر مدل یا `outputDimensionality` هویت نمایه را تغییر می‌دهد. OpenClaw جست‌وجوی برداری را تا زمانی که نمایه حافظه را به‌صراحت بازسازی کنید، متوقف می‌کند. نقاط پایانی تعبیه‌سازی سازگار با OpenAI می‌توانند فیلدهای درخواست `input_type` مختص ارائه‌دهنده را فعال کنند. این قابلیت برای مدل‌های تعبیه‌سازی نامتقارنی مفید است که برای تعبیه‌سازی‌های پرس‌وجو و سند به برچسب‌های متفاوت نیاز دارند. | کلید | نوع | پیش‌فرض | توضیحات | | ------------------- | -------- | ------- | -------------------------------------------------------- | | `inputType` | `string` | تنظیم‌نشده | `input_type` مشترک برای تعبیه‌سازی‌های پرس‌وجو و سند | | `queryInputType` | `string` | تنظیم‌نشده | `input_type` هنگام پرس‌وجو؛ `inputType` را بازنویسی می‌کند | | `documentInputType` | `string` | تنظیم‌نشده | `input_type` نمایه/سند؛ `inputType` را بازنویسی می‌کند | ```json5 { agents: { defaults: { memorySearch: { provider: "openai-compatible", remote: { baseUrl: "https://embeddings.example/v1", apiKey: "${EMBEDDINGS_API_KEY}", }, model: "asymmetric-embedder", queryInputType: "query", documentInputType: "passage", }, }, }, } ``` تغییر این مقادیر بر هویت حافظه نهان تعبیه‌سازی برای نمایه‌سازی دسته‌ای ارائه‌دهنده اثر می‌گذارد و هنگامی که مدل بالادستی با برچسب‌ها رفتار متفاوتی دارد، باید پس از آن نمایه‌سازی مجدد حافظه انجام شود. ### پیکربندی تعبیه‌سازی Bedrock Bedrock از زنجیره پیش‌فرض اعتبارنامه AWS SDK به‌علاوه یک توکن حامل بررسی‌شده توسط OpenClaw استفاده می‌کند؛ بنابراین هیچ کلید API در پیکربندی ذخیره نمی‌شود. اگر OpenClaw روی EC2 با نقش نمونه‌ای که Bedrock برای آن فعال است اجرا می‌شود، فقط ارائه‌دهنده و مدل را تنظیم کنید: ```json5 { agents: { defaults: { memorySearch: { provider: "bedrock", model: "amazon.titan-embed-text-v2:0", }, }, }, } ``` | کلید | نوع | پیش‌فرض | توضیحات | | ---------------------- | -------- | ------------------------------- | -------------------------------- | | `model` | `string` | `amazon.titan-embed-text-v2:0` | هر شناسه مدل تعبیه‌سازی Bedrock | | `outputDimensionality` | `number` | پیش‌فرض مدل | برای Titan V2: 256، 512 یا 1024 | **مدل‌های پشتیبانی‌شده** (با تشخیص خانواده و پیش‌فرض‌های ابعاد): | شناسه مدل | ارائه‌دهنده | ابعاد پیش‌فرض | ابعاد قابل پیکربندی | | ------------------------------------------- | ---------- | ------------- | -------------------------- | | `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | | `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | | `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | | `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | | `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 | | `cohere.embed-english-v3` | Cohere | 1024 | -- | | `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | | `cohere.embed-v4:0` | Cohere | 1536 | 256, 384, 512, 768, 1024, 1536 | | `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | | `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | گونه‌های دارای پسوند توان عملیاتی (برای مثال، `amazon.titan-embed-text-v1:2:8k`) و شناسه‌های پروفایل استنتاج دارای پیشوند منطقه (برای مثال، `us.amazon.titan-embed-text-v2:0`) پیکربندی مدل پایه را به ارث می‌برند. **منطقه:** به این ترتیب تعیین می‌شود: بازنویسی `memorySearch.remote.baseUrl`، پیکربندی `models.providers.amazon-bedrock.baseUrl`، سپس `AWS_REGION`، `AWS_DEFAULT_REGION` و در نهایت مقدار پیش‌فرض `us-east-1`. **احراز هویت:** OpenClaw ابتدا وجود `AWS_ACCESS_KEY_ID` به‌همراه `AWS_SECRET_ACCESS_KEY` یا `AWS_BEARER_TOKEN_BEDROCK` را بررسی می‌کند و سپس به زنجیره استاندارد ارائه‌دهندگان پیش‌فرض اعتبارنامه در AWS SDK می‌رود: 1. متغیرهای محیطی (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)، مگر اینکه `AWS_PROFILE` نیز تنظیم شده باشد 2. SSO (فقط وقتی فیلدهای SSO پیکربندی شده باشند) 3. اعتبارنامه‌های مشترک و فایل‌های پیکربندی (`fromIni`، شامل `AWS_PROFILE`) 4. فرایند اعتبارنامه (`credential_process` در فایل پیکربندی AWS) 5. اعتبارنامه‌های توکن هویت وب 6. اعتبارنامه‌های فراداده نمونه ECS یا EC2 **مجوزهای IAM:** نقش یا کاربر IAM به موارد زیر نیاز دارد: ```json { "Effect": "Allow", "Action": "bedrock:InvokeModel", "Resource": "*" } ``` برای کمترین سطح دسترسی، دامنه `InvokeModel` را به مدل مشخص محدود کنید: ```text arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0 ``` | کلید | نوع | پیش‌فرض | توضیحات | | --------------------- | ------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `local.modelPath` | `string` | دانلود خودکار | مسیر فایل مدل GGUF | | `local.modelCacheDir` | `string` | پیش‌فرض node-llama-cpp | پوشه کش مدل‌های دانلودشده | | `local.contextSize` | `number \| "auto"` | `4096` | اندازه پنجره زمینه برای زمینه تعبیه‌سازی. مقدار 4096 قطعه‌های معمول (128-512 توکن) را پوشش می‌دهد و در عین حال VRAM غیرمرتبط با وزن‌ها را محدود می‌کند. در میزبان‌های دارای منابع محدود، آن را به 1024-2048 کاهش دهید. `"auto"` از حداکثر آموزش‌دیده مدل استفاده می‌کند -- برای مدل‌های 8B+ توصیه نمی‌شود (Qwen3-Embedding-8B: حداکثر 40 960 توکن می‌تواند مصرف VRAM را به حدود 32 GB برساند). | ابتدا ارائه‌دهنده رسمی llama.cpp را نصب کنید: `openclaw plugins install @openclaw/llama-cpp-provider`. مدل پیش‌فرض: `embeddinggemma-300m-qat-Q8_0.gguf` (حدود 0.6 GB، با دانلود خودکار). دریافت‌های کد منبع همچنان به تأیید ساخت بومی نیاز دارند: ابتدا `pnpm approve-builds` و سپس `pnpm rebuild node-llama-cpp`. برای تأیید همان مسیر ارائه‌دهنده‌ای که Gateway استفاده می‌کند، از CLI مستقل استفاده کنید: ```bash openclaw memory status --deep --agent main openclaw memory index --force --agent main ``` مقادیر عددی `local.contextSize` همچنین جانمایی خودکار لایه‌های GPU در node-llama-cpp را هدایت می‌کنند تا وزن‌های مدل و زمینه تعبیه‌سازی درخواستی با هم جای بگیرند. پس از بارگذاری زمان اجرا، `openclaw memory status --deep` آخرین اطلاعات شناخته‌شده از بک‌اند llama.cpp، دستگاه، برون‌سپاری، زمینه درخواستی و واقعیت‌های حافظه دارای برچسب زمانی را گزارش می‌کند؛ وضعیت غیرفعال هیچ مدلی را بارگذاری نمی‌کند. برای تعبیه‌سازی‌های محلی GGUF، `provider: "local"` را صریحاً تنظیم کنید. `hf:` و ارجاعات مدل HTTP(S) برای پیکربندی‌های محلی صریح پشتیبانی می‌شوند (از طریق تفکیک مدل در node-llama-cpp)، اما ارائه‌دهنده پیش‌فرض را تغییر نمی‌دهند. ### مهلت زمانی تعبیه‌سازی درون‌خطی مهلت زمانی دسته‌های تعبیه‌سازی درون‌خطی هنگام نمایه‌سازی حافظه را بازنویسی کنید. اگر تنظیم نشده باشد، از مقدار پیش‌فرض ارائه‌دهنده استفاده می‌شود: 600 ثانیه برای ارائه‌دهندگان محلی/خودمیزبان مانند `local`، `ollama` و `lmstudio`، و 120 ثانیه برای ارائه‌دهندگان میزبانی‌شده. وقتی دسته‌های تعبیه‌سازی محلی متکی به CPU سالم اما کند هستند، این مقدار را افزایش دهید. --- ## رفتار نمایه‌سازی همه موارد زیر ذیل `memorySearch.sync` هستند، مگر آنکه خلافش ذکر شود: | کلید | نوع | پیش‌فرض | توضیحات | | ------------------------------ | --------- | ------- | --------------------------------------------------------------------- | | `onSessionStart` | `boolean` | `true` | همگام‌سازی نمایه حافظه هنگام شروع نشست | | `onSearch` | `boolean` | `true` | همگام‌سازی تنبل هنگام جست‌وجو، پس از تشخیص تغییرات محتوا | | `watch` | `boolean` | `true` | پایش فایل‌های حافظه (chokidar) و زمان‌بندی نمایه‌سازی مجدد هنگام تغییرات | | `watchDebounceMs` | `number` | `1500` | پنجره تأخیر برای ادغام رویدادهای سریع پایش فایل | | `intervalMinutes` | `number` | `0` | فاصله زمانی نمایه‌سازی مجدد دوره‌ای برحسب دقیقه (`0` آن را غیرفعال می‌کند) | | `sessions.postCompactionForce` | `boolean` | `true` | اجبار به نمایه‌سازی مجدد نشست پس از به‌روزرسانی رونوشت ناشی از Compaction | اندازه قطعه برحسب توکن که هنگام تقسیم منابع حافظه پیش از تعبیه‌سازی استفاده می‌شود (پیش‌فرض: 400). هم‌پوشانی توکن میان قطعه‌های مجاور برای حفظ زمینه نزدیک مرزهای تقسیم (پیش‌فرض: 80). تغییر `chunking.tokens` یا `chunking.overlap` مرزهای قطعه‌ها را تغییر می‌دهد و هویت نمایه موجود را نامعتبر می‌کند (هشدار زیر بخش انتخاب ارائه‌دهنده را ببینید). --- ## پیکربندی جست‌وجوی ترکیبی همه موارد ذیل `memorySearch.query`: | کلید | نوع | پیش‌فرض | توضیحات | | ------------ | -------- | ------- | ----------------------------------------- | | `maxResults` | `number` | `6` | حداکثر نتایج حافظه بازگردانده‌شده پیش از تزریق | | `minScore` | `number` | `0.35` | حداقل امتیاز ارتباط برای گنجاندن یک نتیجه | و ذیل `memorySearch.query.hybrid`: | کلید | نوع | پیش‌فرض | توضیحات | | --------------------- | --------- | ------- | ---------------------------------- | | `enabled` | `boolean` | `true` | فعال‌سازی جست‌وجوی ترکیبی BM25 + برداری | | `vectorWeight` | `number` | `0.7` | وزن امتیازهای برداری (0-1) | | `textWeight` | `number` | `0.3` | وزن امتیازهای BM25 (0-1) | | `candidateMultiplier` | `number` | `4` | ضریب اندازه مجموعه نامزدها | | کلید | نوع | پیش‌فرض | توضیحات | | ------------- | --------- | ------- | ------------------------------------- | | `mmr.enabled` | `boolean` | `false` | فعال‌سازی رتبه‌بندی مجدد MMR | | `mmr.lambda` | `number` | `0.7` | 0 = بیشترین تنوع، 1 = بیشترین ارتباط | | کلید | نوع | پیش‌فرض | توضیحات | | ---------------------------- | --------- | ------- | -------------------------- | | `temporalDecay.enabled` | `boolean` | `false` | فعال‌سازی تقویت تازگی | | `temporalDecay.halfLifeDays` | `number` | `30` | امتیاز در هر N روز نصف می‌شود | فایل‌های همیشه‌سبز (`MEMORY.md`، فایل‌های بدون تاریخ در `memory/`) هرگز دچار افت نمی‌شوند. ### نمونه کامل ```json5 { agents: { defaults: { memorySearch: { query: { maxResults: 6, minScore: 0.35, hybrid: { vectorWeight: 0.7, textWeight: 0.3, mmr: { enabled: true, lambda: 0.7 }, temporalDecay: { enabled: true, halfLifeDays: 30 }, }, }, }, }, }, } ``` --- ## مسیرهای حافظه اضافی | کلید | نوع | توضیحات | | ------------ | ---------- | ---------------------------------------- | | `extraPaths` | `string[]` | پوشه‌ها یا فایل‌های اضافی برای نمایه‌سازی | ```json5 { agents: { defaults: { memorySearch: { extraPaths: ["../team-docs", "/srv/shared-notes"], }, }, }, } ``` مسیرها می‌توانند مطلق یا نسبی به فضای کاری باشند. پوشه‌ها به‌صورت بازگشتی برای فایل‌های `.md` پویش می‌شوند. نحوه مدیریت پیوندهای نمادین به بک‌اند فعال بستگی دارد: موتور داخلی از پیوندهای نمادین صرف‌نظر می‌کند، درحالی‌که QMD از رفتار پویشگر زیربنایی QMD پیروی می‌کند. برای جست‌وجوی رونوشت میان عامل‌ها با دامنه عامل، به‌جای `memory.qmd.paths` از `agents.list[].memorySearch.qmd.extraCollections` استفاده کنید. این مجموعه‌های اضافی از همان ساختار `{ path, name, pattern? }` پیروی می‌کنند، اما برای هر عامل ادغام می‌شوند و وقتی مسیر به خارج از فضای کاری فعلی اشاره دارد، می‌توانند نام‌های مشترک صریح را حفظ کنند. اگر مسیر تفکیک‌شده یکسانی هم در `memory.qmd.paths` و هم در `memorySearch.qmd.extraCollections` ظاهر شود، QMD ورودی نخست را نگه می‌دارد و از مورد تکراری صرف‌نظر می‌کند. --- ## حافظه چندوجهی (Gemini) تصاویر و صدا را در کنار Markdown با استفاده از Gemini Embedding 2 نمایه‌سازی کنید: | کلید | نوع | پیش‌فرض | توضیحات | | ------------------------- | ---------- | ---------- | -------------------------------------- | | `multimodal.enabled` | `boolean` | `false` | فعال‌سازی نمایه‌سازی چندوجهی | | `multimodal.modalities` | `string[]` | -- | `["image"]`، `["audio"]` یا `["all"]` | | `multimodal.maxFileBytes` | `number` | `10485760` | حداکثر اندازه فایل برای نمایه‌سازی (10 MiB) | فقط برای فایل‌های موجود در `extraPaths` اعمال می‌شود. ریشه‌های پیش‌فرض حافظه همچنان فقط از Markdown پشتیبانی می‌کنند. به `gemini-embedding-2-preview` نیاز دارد. `fallback` باید `"none"` باشد. قالب‌های پشتیبانی‌شده: `.jpg`، `.jpeg`، `.png`، `.webp`، `.gif`، `.heic`، `.heif` (تصاویر)؛ `.mp3`، `.wav`، `.ogg`، `.opus`، `.m4a`، `.aac`، `.flac` (صوت). --- ## نهانگاه تعبیه‌ها | کلید | نوع | پیش‌فرض | توضیحات | | ------------------ | --------- | ------- | -------------------------------------------- | | `cache.enabled` | `boolean` | `true` | ذخیره تعبیه‌های قطعه‌ها در نهانگاه SQLite | | `cache.maxEntries` | `number` | تنظیم‌نشده | حد بالای تقریبی تعداد تعبیه‌های ذخیره‌شده در نهانگاه | از تعبیه مجدد متن تغییریافته‌نشده هنگام نمایه‌سازی مجدد یا به‌روزرسانی رونوشت جلوگیری می‌کند. برای نهانگاه بدون محدودیت، `maxEntries` را تنظیم‌نشده بگذارید؛ اگر رشد فضای دیسک از حداکثر سرعت نمایه‌سازی مجدد مهم‌تر است، آن را تنظیم کنید. پس از تنظیم، وقتی نهانگاه از حد فراتر رود، قدیمی‌ترین ورودی‌ها (بر اساس زمان آخرین به‌روزرسانی) ابتدا حذف می‌شوند. --- ## نمایه‌سازی دسته‌ای | کلید | نوع | پیش‌فرض | توضیحات | | ----------------------------- | --------- | ------- | -------------------------- | | `remote.nonBatchConcurrency` | `number` | `4` | تعبیه‌های درون‌خطی موازی | | `remote.batch.enabled` | `boolean` | `false` | فعال‌سازی API تعبیه دسته‌ای | | `remote.batch.concurrency` | `number` | `2` | کارهای دسته‌ای موازی | | `remote.batch.wait` | `boolean` | `true` | انتظار برای تکمیل دسته | | `remote.batch.pollIntervalMs` | `number` | `2000` | فاصله زمانی نظرسنجی | | `remote.batch.timeoutMinutes` | `number` | `60` | مهلت زمانی دسته | برای `gemini`، `openai` و `voyage` در دسترس است. حالت دسته‌ای OpenAI معمولاً برای بازپُرکردن‌های بزرگ سریع‌ترین و ارزان‌ترین گزینه است. `remote.nonBatchConcurrency` فراخوانی‌های تعبیه درون‌خطی را کنترل می‌کند که ارائه‌دهندگان محلی/خودمیزبان و ارائه‌دهندگان میزبانی‌شده در زمان غیرفعال‌بودن APIهای دسته‌ای ارائه‌دهنده استفاده می‌کنند. برای جلوگیری از تحمیل بار بیش‌ازحد به میزبان‌های محلی کوچک‌تر، مقدار پیش‌فرض Ollama برای نمایه‌سازی غیردسته‌ای `1` است؛ در دستگاه‌های بزرگ‌تر مقدار بالاتری تنظیم کنید. این مورد از `sync.embeddingBatchTimeoutSeconds` جدا است؛ آن مورد مهلت زمانی فراخوانی‌های تعبیه درون‌خطی را کنترل می‌کند. --- ## جست‌وجوی حافظه نشست (آزمایشی) رونوشت‌های نشست را نمایه‌سازی کنید و آن‌ها را از طریق `memory_search` نمایش دهید: | کلید | نوع | پیش‌فرض | توضیحات | | ----------------------------- | ---------- | ------------ | --------------------------------------- | | `experimental.sessionMemory` | `boolean` | `false` | فعال‌سازی نمایه‌سازی نشست | | `sources` | `string[]` | `["memory"]` | افزودن `"sessions"` برای گنجاندن رونوشت‌ها | | `sync.sessions.deltaBytes` | `number` | `100000` | آستانه بایتی برای نمایه‌سازی مجدد | | `sync.sessions.deltaMessages` | `number` | `50` | آستانه پیام برای نمایه‌سازی مجدد | نمایه‌سازی نشست اختیاری است و به‌صورت ناهمگام اجرا می‌شود. نتایج ممکن است کمی قدیمی باشند. گزارش‌های نشست روی دیسک قرار دارند؛ بنابراین دسترسی به سامانه فایل را مرز اعتماد در نظر بگیرید. نتایج رونوشت نشست نیز از [`tools.sessions.visibility`](/fa/gateway/config-tools#toolssessions) پیروی می‌کنند. قابلیت مشاهده پیش‌فرض `tree` فقط نشست جاری و نشست‌هایی را که ایجاد کرده است نمایش می‌دهد. برای بازیابی یک نشست نامرتبطِ متعلق به همان عامل که Gateway آن را از نشستی دیگر ارسال کرده است، مانند یک پیام خصوصی، قابلیت مشاهده را عمداً به `agent` گسترش دهید (یا فقط زمانی به `all` که بازیابی میان‌عاملی نیز لازم باشد و خط‌مشی عامل‌به‌عامل آن را مجاز بداند). نمونه‌های زیر این تنظیمات را زیر `agents.defaults` قرار می‌دهند. همچنین می‌توان تنظیمات معادل `memorySearch` را در بازنویسی مخصوص هر عامل اعمال کرد، زمانی که فقط یک عامل باید رونوشت‌های نشست را نمایه‌سازی و جست‌وجو کند. برای بازیابی از Gateway به پیام خصوصی در همان عامل: ```json5 { agents: { defaults: { memorySearch: { experimental: { sessionMemory: true }, sources: ["memory", "sessions"], }, }, }, tools: { sessions: { visibility: "agent" }, }, } ``` ```json5 { agents: { defaults: { memorySearch: { experimental: { sessionMemory: true }, sources: ["memory", "sessions"], }, }, }, memory: { backend: "qmd", qmd: { sessions: { enabled: true }, }, }, tools: { sessions: { visibility: "agent" }, }, } ``` هنگام استفاده از QMD، `agents.defaults.memorySearch.experimental.sessionMemory` و `sources: ["sessions"]` به‌تنهایی رونوشت‌ها را به QMD صادر نمی‌کنند. `memory.qmd.sessions.enabled: true` را نیز تنظیم کنید. --- ## شتاب‌دهی برداری SQLite (sqlite-vec) | کلید | نوع | پیش‌فرض | توضیحات | | ---------------------------- | --------- | ------- | --------------------------------- | | `store.vector.enabled` | `boolean` | `true` | استفاده از sqlite-vec برای پرس‌وجوهای برداری | | `store.vector.extensionPath` | `string` | همراه | بازنویسی مسیر sqlite-vec | وقتی sqlite-vec در دسترس نباشد، OpenClaw به‌طور خودکار از شباهت کسینوسی درون‌فرایندی استفاده می‌کند. --- ## ذخیره‌سازی نمایه نمایه‌های حافظه داخلی در پایگاه‌داده SQLite متعلق به OpenClaw برای هر عامل، در `agents//agent/openclaw-agent.sqlite` قرار دارند. | کلید | نوع | پیش‌فرض | توضیحات | | --------------------- | -------- | ----------- | ----------------------------------------- | | `store.fts.tokenizer` | `string` | `unicode61` | توکن‌ساز FTS5 (`unicode61` یا `trigram`) | --- ## پیکربندی بک‌اند QMD برای فعال‌سازی، `memory.backend = "qmd"` را تنظیم کنید. همه تنظیمات QMD زیر `memory.qmd` قرار دارند: | کلید | نوع | پیش‌فرض | توضیحات | | ------------------------ | --------- | -------- | ------------------------------------------------------------------------------------- | | `command` | `string` | `qmd` | مسیر فایل اجرایی QMD؛ وقتی `PATH` سرویس با پوسته شما متفاوت است، مسیری مطلق تنظیم کنید | | `searchMode` | `string` | `search` | فرمان جست‌وجو: `search`، `vsearch`، `query` | | `rerank` | `boolean` | -- | با `searchMode: "query"` و QMD 2.1+ روی `false` تنظیم کنید تا رتبه‌بندی مجدد QMD نادیده گرفته شود | | `includeDefaultMemory` | `boolean` | `true` | نمایه‌سازی خودکار `MEMORY.md` + `memory/**/*.md` | | `paths[]` | `array` | -- | مسیرهای اضافی: `{ name, path, pattern? }` | | `sessions.enabled` | `boolean` | `false` | صادرکردن رونوشت‌های نشست به QMD | | `sessions.retentionDays` | `number` | -- | نگهداشت رونوشت | | `sessions.exportDir` | `string` | -- | پوشه خروجی | `searchMode: "search"` فقط واژگانی/BM25 است. OpenClaw در این حالت، از جمله هنگام `memory status --deep`، بررسی‌های آمادگی بردار معنایی یا نگهداشت تعبیه‌های QMD را اجرا نمی‌کند؛ `vsearch` و `query` همچنان به آمادگی برداری و تعبیه‌های QMD نیاز دارند. `rerank: false` فقط حالت `query` در QMD را تغییر می‌دهد و به QMD 2.1 یا جدیدتر نیاز دارد. در حالت مستقیم CLI، OpenClaw مقدار `--no-rerank` را ارسال می‌کند؛ در حالت MCP مبتنی بر mcporter، مقدار `rerank: false` را به ابزار یکپارچه پرس‌وجوی QMD می‌فرستد. برای استفاده از رفتار پیش‌فرض رتبه‌بندی مجدد پرس‌وجوی QMD، آن را تنظیم‌نشده بگذارید. OpenClaw شکل‌های فعلی مجموعه و پرس‌وجوی MCP در QMD را ترجیح می‌دهد، اما با امتحان‌کردن پرچم‌های سازگار الگوی مجموعه و نام‌های قدیمی‌تر ابزار MCP در مواقع لازم، نسخه‌های قدیمی‌تر QMD را نیز قابل‌استفاده نگه می‌دارد. وقتی QMD پشتیبانی از چند فیلتر مجموعه را اعلام می‌کند، مجموعه‌های هم‌منبع با یک فرایند QMD جست‌وجو می‌شوند؛ ساخت‌های قدیمی‌تر QMD مسیر سازگاری مجزا برای هر مجموعه را حفظ می‌کنند. هم‌منبع یعنی مجموعه‌های حافظه ماندگار (فایل‌های پیش‌فرض حافظه به‌علاوه مسیرهای سفارشی) با هم گروه‌بندی می‌شوند، درحالی‌که مجموعه‌های رونوشت نشست در گروهی جدا باقی می‌مانند تا تنوع‌بخشی منابع همچنان هر دو ورودی را داشته باشد. بازنویسی مدل‌های QMD در سمت QMD باقی می‌ماند، نه در پیکربندی OpenClaw. اگر لازم است مدل‌های QMD را به‌صورت سراسری بازنویسی کنید، متغیرهای محیطی مانند `QMD_EMBED_MODEL`، `QMD_RERANK_MODEL` و `QMD_GENERATE_MODEL` را در محیط زمان اجرای Gateway تنظیم کنید. ### یکپارچه‌سازی mcporter همه تنظیمات زیر `memory.qmd.mcporter` قرار دارند. جست‌وجوهای QMD را به‌جای ایجاد `qmd` برای هر پرس‌وجو، از طریق یک دیمن MCP با عمر طولانی `mcporter` مسیریابی می‌کند و سربار شروع سرد مدل‌های بزرگ‌تر را کاهش می‌دهد. | کلید | نوع | پیش‌فرض | توضیحات | | ------------- | --------- | ------- | ---------------------------------------------------------------------- | | `enabled` | `boolean` | `false` | مسیریابی فراخوانی‌های QMD از طریق mcporter به‌جای ایجاد `qmd` برای هر درخواست | | `serverName` | `string` | `qmd` | نام سرور mcporter که `qmd mcp` را با `lifecycle: keep-alive` اجرا می‌کند | | `startDaemon` | `boolean` | `true` | شروع خودکار دیمن mcporter وقتی `enabled` درست است | نیازمند نصب‌بودن `mcporter` و قرارداشتن آن در PATH، به‌همراه یک سرور پیکربندی‌شده mcporter است که `qmd mcp` را اجرا کند. برای راه‌اندازی‌های محلی ساده‌تر که هزینه ایجاد فرایند برای هر پرس‌وجو قابل‌قبول است، آن را غیرفعال نگه دارید. | کلید | نوع | پیش‌فرض | توضیحات | | --------------------------- | --------- | -------- | ---------------------------------------- | | `update.interval` | `string` | `5m` | فاصلهٔ بازآوری | | `update.debounceMs` | `number` | `15000` | حذف پرش تغییرات فایل | | `update.onBoot` | `boolean` | `true` | بازآوری هنگام بازشدن مدیر بلندمدت QMD؛ برای ردشدن به‌روزرسانی فوری هنگام راه‌اندازی، روی false تنظیم کنید | | `update.startup` | `string` | `off` | مقداردهی اولیهٔ اختیاری QMD هنگام شروع Gateway: `off`، `idle` یا `immediate` | | `update.startupDelayMs` | `number` | `120000` | تأخیر پیش از اجرای بازآوری `startup: "idle"` | | `update.waitForBootSync` | `boolean` | `false` | مسدودکردن بازشدن مدیر تا تکمیل بازآوری اولیهٔ آن | | `update.embedInterval` | `string` | `60m` | تناوب جداگانهٔ تعبیه | | `update.commandTimeoutMs` | `number` | `30000` | مهلت زمانی فرمان‌های نگه‌داری QMD (فهرست/افزودن مجموعه) | | `update.updateTimeoutMs` | `number` | `120000` | مهلت زمانی هر چرخهٔ `qmd update` | | `update.embedTimeoutMs` | `number` | `120000` | مهلت زمانی هر چرخهٔ `qmd embed` | | کلید | نوع | پیش‌فرض | توضیحات | | --------------------------- | -------- | ------- | ------------------------------ | | `limits.maxResults` | `number` | `4` | حداکثر نتایج جست‌وجو | | `limits.maxSnippetChars` | `number` | `450` | محدودکردن طول قطعه | | `limits.maxInjectedChars` | `number` | `2200` | محدودکردن مجموع نویسه‌های تزریق‌شده | | `limits.timeoutMs` | `number` | `4000` | مهلت زمانی فرمان QMD هنگام جست‌وجوی مبتنی بر QMD، شامل `memory_search`؛ راه‌اندازی، همگام‌سازی، بازگشت داخلی و کارهای تکمیلی، مهلت پیش‌فرض ابزار را حفظ می‌کنند | تعیین می‌کند کدام نشست‌ها می‌توانند نتایج جست‌وجوی QMD را دریافت کنند. ساختار آن با [`session.sendPolicy`](/fa/gateway/config-agents#session) یکسان است: ```json5 { memory: { qmd: { scope: { default: "deny", rules: [{ action: "allow", match: { chatType: "direct" } }], }, }, }, } ``` پیش‌فرض عرضه‌شده فقط پیام خصوصی/مستقیم را مجاز می‌کند و گروه‌ها و دیگر انواع کانال را رد می‌کند. `match.keyPrefix` با کلید عادی‌سازی‌شدهٔ نشست مطابقت دارد؛ `match.rawKeyPrefix` با کلید خام شامل `agent::` مطابقت دارد. `memory.citations` برای همهٔ بک‌اندها اعمال می‌شود: | مقدار | رفتار | | ------------------ | ------------------------------------------------------ | | `auto` (پیش‌فرض) | درج پانوشت `Source: ` در قطعه‌ها | | `on` | همیشه پانوشت را درج می‌کند | | `off` | پانوشت را حذف می‌کند (مسیر همچنان به‌صورت داخلی به عامل ارسال می‌شود) | وقتی مقداردهی اولیهٔ QMD هنگام شروع Gateway فعال باشد، OpenClaw تنها QMD مربوط به عامل‌های واجد شرایط را راه‌اندازی می‌کند. اگر `update.onBoot` برابر true باشد و هیچ نگه‌داری دوره‌ای برای به‌روزرسانی/تعبیه پیکربندی نشده باشد، هنگام راه‌اندازی از یک مدیر یک‌باره برای بازآوری آغازین استفاده می‌شود و سپس مدیر بسته می‌شود. اگر فاصلهٔ به‌روزرسانی یا تعبیه پیکربندی شده باشد، هنگام راه‌اندازی مدیر بلندمدت QMD باز می‌شود تا مالک ناظر و زمان‌سنج‌های دوره‌ای باشد؛ `update.onBoot: false` فقط بازآوری فوری آغازین را رد می‌کند. ### نمونهٔ کامل QMD ```json5 { memory: { backend: "qmd", citations: "auto", qmd: { includeDefaultMemory: true, update: { interval: "5m", debounceMs: 15000 }, limits: { maxResults: 4, timeoutMs: 4000 }, scope: { default: "deny", rules: [{ action: "allow", match: { chatType: "direct" } }], }, paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }], }, }, } ``` --- ## Dreaming Dreaming در `plugins.entries.memory-core.config.dreaming` پیکربندی می‌شود، نه در `agents.defaults.memorySearch`. Dreaming به‌صورت یک پیمایش زمان‌بندی‌شده اجرا می‌شود و از مراحل داخلی سبک/عمیق/REM به‌عنوان جزئیات پیاده‌سازی استفاده می‌کند. برای رفتار مفهومی و فرمان‌های اسلش، به [Dreaming](/fa/concepts/dreaming) مراجعه کنید. ### تنظیمات کاربر | کلید | نوع | پیش‌فرض | توضیحات | | -------------------------------------- | --------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | `boolean` | `false` | فعال یا غیرفعال‌کردن کامل Dreaming | | `frequency` | `string` | `0 3 * * *` | تناوب اختیاری Cron برای پیمایش کامل Dreaming | | `model` | `string` | مدل پیش‌فرض | بازنویسی اختیاری مدل زیرعامل Dream Diary | | `phases.deep.maxPromotedSnippetTokens` | `number` | `160` | حداکثر توکن‌های تخمینی نگه‌داری‌شده از هر قطعهٔ یادآوری کوتاه‌مدت که به `MEMORY.md` ارتقا می‌یابد؛ فرادادهٔ منشأ قابل مشاهده باقی می‌ماند | ### نمونه ```json5 { plugins: { entries: { "memory-core": { subagent: { allowModelOverride: true, allowedModels: ["anthropic/claude-sonnet-4-6"], }, config: { dreaming: { enabled: true, frequency: "0 3 * * *", model: "anthropic/claude-sonnet-4-6", }, }, }, }, }, } ``` - Dreaming وضعیت ماشینی را در `memory/.dreams/` می‌نویسد. - Dreaming خروجی روایی خوانا برای انسان را در `DREAMS.md` (یا `dreams.md` موجود) می‌نویسد. - `dreaming.model` از دروازهٔ اعتماد موجود زیرعامل Plugin استفاده می‌کند؛ پیش از فعال‌سازی آن، `plugins.entries.memory-core.subagent.allowModelOverride: true` را تنظیم کنید. - وقتی مدل پیکربندی‌شده در دسترس نباشد، Dream Diary یک‌بار دیگر با مدل پیش‌فرض نشست تلاش می‌کند. خطاهای اعتماد یا فهرست مجاز ثبت می‌شوند و بدون اطلاع دوباره امتحان نمی‌شوند. - سیاست و آستانه‌های مراحل سبک/عمیق/REM رفتاری داخلی هستند، نه پیکربندی قابل‌مشاهده برای کاربر. ## مرتبط - [مرجع پیکربندی](/fa/gateway/configuration-reference) - [نمای کلی حافظه](/fa/concepts/memory) - [جست‌وجوی حافظه](/fa/concepts/memory-search)