مرجع پیکربندی حافظه

این صفحه همه گزینه‌های پیکربندی جست‌وجوی حافظه OpenClaw را فهرست می‌کند. برای مرورهای مفهومی، بنگرید به:

همه تنظیمات جست‌وجوی حافظه، مگر آنکه خلافش ذکر شده باشد، زیر agents.defaults.memorySearch در openclaw.json (یا یک بازنویسی مختص هر عامل در agents.list[].memorySearch) قرار دارند.

انتخاب ارائه‌دهنده

وقتی provider تنظیم نشده باشد، OpenClaw از تعبیه‌سازی‌های OpenAI استفاده می‌کند. برای استفاده از Bedrock، DeepInfra، Gemini، GitHub Copilot، Mistral، Ollama، Voyage، یک مدل محلی GGUF یا نقطه پایانی /v1/embeddings سازگار با OpenAI، مقدار provider را به‌صراحت تنظیم کنید. پیکربندی‌های قدیمی که همچنان provider: "auto" را ذکر می‌کنند، به openai نگاشت می‌شوند.

وقتی 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.<id> اشاره کند. OpenClaw مالک api آن ارائه‌دهنده را برای آداپتور تعبیه‌سازی شناسایی می‌کند و درعین‌حال شناسه ارائه‌دهنده سفارشی را برای مدیریت نقطه پایانی، احراز هویت و پیشوند مدل حفظ می‌کند. این قابلیت به پیکربندی‌های چند-GPU یا چندمیزبانه اجازه می‌دهد تعبیه‌سازی‌های حافظه را به یک نقطه پایانی محلی مشخص اختصاص دهند:

{  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).

پیکربندی نقطه پایانی راه‌دور

از provider: "openai-compatible" برای یک سرور عمومی /v1/embeddings سازگار با OpenAI استفاده کنید که نباید اعتبارنامه‌های سراسری گفت‌وگوی OpenAI را به ارث ببرد.

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        model: "text-embedding-3-small",        remote: {          baseUrl: "https://api.example.com/v1/",          apiKey: "YOUR_KEY",        },      },    },  },}

پیکربندی مختص ارائه‌دهنده

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        remote: {          baseUrl: "https://embeddings.example/v1",          apiKey: "${EMBEDDINGS_API_KEY}",        },        model: "asymmetric-embedder",        queryInputType: "query",        documentInputType: "passage",      },    },  },}

{  agents: {    defaults: {      memorySearch: {        provider: "bedrock",        model: "amazon.titan-embed-text-v2:0",      },    },  },}

{  "Effect": "Allow",  "Action": "bedrock:InvokeModel",  "Resource": "*"}

arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

openclaw memory status --deep --agent mainopenclaw memory index --force --agent main

مهلت زمانی تعبیه‌سازی درون‌خطی

رفتار نمایه‌سازی

همه موارد زیر ذیل memorySearch.sync هستند، مگر آنکه خلافش ذکر شود:

پیکربندی جست‌وجوی ترکیبی

همه موارد ذیل memorySearch.query:

و ذیل memorySearch.query.hybrid:

نمونه کامل

{  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 },          },        },      },    },  },}

مسیرهای حافظه اضافی

{  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 نمایه‌سازی کنید:

قالب‌های پشتیبانی‌شده: .jpg، .jpeg، .png، .webp، .gif، .heic، .heif (تصاویر)؛ .mp3، .wav، .ogg، .opus، .m4a، .aac، .flac (صوت).

نهانگاه تعبیه‌ها

از تعبیه مجدد متن تغییریافته‌نشده هنگام نمایه‌سازی مجدد یا به‌روزرسانی رونوشت جلوگیری می‌کند. برای نهانگاه بدون محدودیت، maxEntries را تنظیم‌نشده بگذارید؛ اگر رشد فضای دیسک از حداکثر سرعت نمایه‌سازی مجدد مهم‌تر است، آن را تنظیم کنید. پس از تنظیم، وقتی نهانگاه از حد فراتر رود، قدیمی‌ترین ورودی‌ها (بر اساس زمان آخرین به‌روزرسانی) ابتدا حذف می‌شوند.

نمایه‌سازی دسته‌ای

برای gemini، openai و voyage در دسترس است. حالت دسته‌ای OpenAI معمولاً برای بازپُرکردن‌های بزرگ سریع‌ترین و ارزان‌ترین گزینه است.

remote.nonBatchConcurrency فراخوانی‌های تعبیه درون‌خطی را کنترل می‌کند که ارائه‌دهندگان محلی/خودمیزبان و ارائه‌دهندگان میزبانی‌شده در زمان غیرفعال‌بودن APIهای دسته‌ای ارائه‌دهنده استفاده می‌کنند. برای جلوگیری از تحمیل بار بیش‌ازحد به میزبان‌های محلی کوچک‌تر، مقدار پیش‌فرض Ollama برای نمایه‌سازی غیردسته‌ای 1 است؛ در دستگاه‌های بزرگ‌تر مقدار بالاتری تنظیم کنید.

این مورد از sync.embeddingBatchTimeoutSeconds جدا است؛ آن مورد مهلت زمانی فراخوانی‌های تعبیه درون‌خطی را کنترل می‌کند.

جست‌وجوی حافظه نشست (آزمایشی)

رونوشت‌های نشست را نمایه‌سازی کنید و آن‌ها را از طریق memory_search نمایش دهید:

نتایج رونوشت نشست نیز از tools.sessions.visibility پیروی می‌کنند. قابلیت مشاهده پیش‌فرض tree فقط نشست جاری و نشست‌هایی را که ایجاد کرده است نمایش می‌دهد. برای بازیابی یک نشست نامرتبطِ متعلق به همان عامل که Gateway آن را از نشستی دیگر ارسال کرده است، مانند یک پیام خصوصی، قابلیت مشاهده را عمداً به agent گسترش دهید (یا فقط زمانی به all که بازیابی میان‌عاملی نیز لازم باشد و خط‌مشی عامل‌به‌عامل آن را مجاز بداند).

نمونه‌های زیر این تنظیمات را زیر agents.defaults قرار می‌دهند. همچنین می‌توان تنظیمات معادل memorySearch را در بازنویسی مخصوص هر عامل اعمال کرد، زمانی که فقط یک عامل باید رونوشت‌های نشست را نمایه‌سازی و جست‌وجو کند.

برای بازیابی از Gateway به پیام خصوصی در همان عامل:

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  tools: {    sessions: { visibility: "agent" },  },}

{  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)

وقتی sqlite-vec در دسترس نباشد، OpenClaw به‌طور خودکار از شباهت کسینوسی درون‌فرایندی استفاده می‌کند.

ذخیره‌سازی نمایه

نمایه‌های حافظه داخلی در پایگاه‌داده SQLite متعلق به OpenClaw برای هر عامل، در agents/<agentId>/agent/openclaw-agent.sqlite قرار دارند.

پیکربندی بک‌اند QMD

برای فعال‌سازی، memory.backend = "qmd" را تنظیم کنید. همه تنظیمات QMD زیر memory.qmd قرار دارند:

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 مسیر سازگاری مجزا برای هر مجموعه را حفظ می‌کنند. هم‌منبع یعنی مجموعه‌های حافظه ماندگار (فایل‌های پیش‌فرض حافظه به‌علاوه مسیرهای سفارشی) با هم گروه‌بندی می‌شوند، درحالی‌که مجموعه‌های رونوشت نشست در گروهی جدا باقی می‌مانند تا تنوع‌بخشی منابع همچنان هر دو ورودی را داشته باشد.

یکپارچه‌سازی mcporter

همه تنظیمات زیر memory.qmd.mcporter قرار دارند. جست‌وجوهای QMD را به‌جای ایجاد qmd برای هر پرس‌وجو، از طریق یک دیمن MCP با عمر طولانی mcporter مسیریابی می‌کند و سربار شروع سرد مدل‌های بزرگ‌تر را کاهش می‌دهد.

نیازمند نصب‌بودن mcporter و قرارداشتن آن در PATH، به‌همراه یک سرور پیکربندی‌شده mcporter است که qmd mcp را اجرا کند. برای راه‌اندازی‌های محلی ساده‌تر که هزینه ایجاد فرایند برای هر پرس‌وجو قابل‌قبول است، آن را غیرفعال نگه دارید.

{  memory: {    qmd: {      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },    },  },}

وقتی مقداردهی اولیهٔ QMD هنگام شروع Gateway فعال باشد، OpenClaw تنها QMD مربوط به عامل‌های واجد شرایط را راه‌اندازی می‌کند. اگر update.onBoot برابر true باشد و هیچ نگه‌داری دوره‌ای برای به‌روزرسانی/تعبیه پیکربندی نشده باشد، هنگام راه‌اندازی از یک مدیر یک‌باره برای بازآوری آغازین استفاده می‌شود و سپس مدیر بسته می‌شود. اگر فاصلهٔ به‌روزرسانی یا تعبیه پیکربندی شده باشد، هنگام راه‌اندازی مدیر بلندمدت QMD باز می‌شود تا مالک ناظر و زمان‌سنج‌های دوره‌ای باشد؛ update.onBoot: false فقط بازآوری فوری آغازین را رد می‌کند.

نمونهٔ کامل QMD

{  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 مراجعه کنید.

تنظیمات کاربر

نمونه

{  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",          },        },      },    },  },}

مرتبط

• مرجع پیکربندی
• نمای کلی حافظه
• جست‌وجوی حافظه