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

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

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

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

وقتی provider تنظیم نشده باشد، OpenClaw از تعبیه‌سازی‌های OpenAI استفاده می‌کند. برای استفاده از Bedrock، DeepInfra، Gemini، GitHub Copilot، Mistral، Ollama، Voyage، یک مدل محلی GGUF یا نقطهٔ پایانی سازگار با OpenAI در /v1/embeddings، مقدار 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).

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

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

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

مرتبط

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