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

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

همهٔ تنظیمات جست‌وجوی حافظه، مگر اینکه خلافش ذکر شده باشد، زیر agents.defaults.memorySearch در openclaw.json قرار دارند.

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

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

وقتی provider تنظیم نشده باشد، provider: "auto" قدیمی وجود داشته باشد، یا provider: "none" عمداً حالت فقط FTS را انتخاب کند، فراخوانی حافظه همچنان می‌تواند وقتی embeddingها در دسترس نیستند از رتبه‌بندی واژگانی FTS استفاده کند.

ارائه‌دهنده‌های غیرمحلی صریح به‌صورت بسته شکست می‌خورند. اگر memorySearch.provider را روی یک ارائه‌دهندهٔ مشخص مبتنی بر راه دور مانند OpenAI، Gemini، Voyage، Mistral، Bedrock، GitHub Copilot، DeepInfra، Ollama، LM Studio، یا یک ارائه‌دهندهٔ سفارشی سازگار با OpenAI تنظیم کنید و آن ارائه‌دهنده هنگام اجرا در دسترس نباشد، memory_search به‌جای اینکه بی‌صدا از فراخوانی فقط FTS استفاده کند، نتیجهٔ در دسترس نبودن را برمی‌گرداند. پیکربندی ارائه‌دهنده/احراز هویت را اصلاح کنید، به یک ارائه‌دهندهٔ قابل دسترس تغییر دهید، یا اگر فراخوانی فقط FTS تعمدی می‌خواهید provider: "none" را تنظیم کنید.

شناسه‌های ارائه‌دهندهٔ سفارشی

memorySearch.provider می‌تواند برای آداپترهای ارائه‌دهندهٔ مخصوص حافظه مانند ollama، یا برای APIهای مدل سازگار با OpenAI مانند openai-responses / openai-completions، به یک ورودی سفارشی models.providers.<id> اشاره کند. OpenClaw مالک api آن ارائه‌دهنده را برای آداپتر embedding حل می‌کند، درحالی‌که شناسهٔ ارائه‌دهندهٔ سفارشی را برای مدیریت endpoint، احراز هویت، و پیشوند مدل حفظ می‌کند. این به راه‌اندازی‌های چند-GPU یا چندمیزبان اجازه می‌دهد embeddingهای حافظه را به یک endpoint محلی مشخص اختصاص دهند:

{  models: {    providers: {      "ollama-5080": {        api: "ollama",        baseUrl: "http://gpu-box.local:11435",        apiKey: "ollama-local",        models: [{ id: "qwen3-embedding:0.6b" }],      },    },  },  agents: {    defaults: {      memorySearch: {        provider: "ollama-5080",        model: "qwen3-embedding:0.6b",      },    },  },}

حل کلید API

embeddingهای راه دور به کلید API نیاز دارند. Bedrock در عوض از زنجیرهٔ پیش‌فرض اعتبارنامهٔ AWS SDK استفاده می‌کند (نقش‌های نمونه، SSO، کلیدهای دسترسی).

پیکربندی endpoint راه دور

برای یک سرور عمومی سازگار با 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

مهلت زمانی embedding درون‌خطی

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

همه موارد زیر memorySearch.query.hybrid قرار دارند:

مثال کامل

{  agents: {    defaults: {      memorySearch: {        query: {          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 پویش می‌شوند. نحوهٔ مدیریت پیوندهای نمادین به backend فعال بستگی دارد: موتور داخلی پیوندهای نمادین را نادیده می‌گیرد، در حالی که 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 (صدا).

کش تعبیه

از تعبیه‌سازی دوبارهٔ متن بدون تغییر هنگام نمایه‌سازی دوباره یا به‌روزرسانی رونوشت جلوگیری می‌کند.

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

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

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

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

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

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

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

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

برای یادآوری Gateway به DM در همان عامل:

{  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 قرار دارند.

پیکربندی backend در QMD

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

searchMode: "search" فقط واژگانی/BM25 است. OpenClaw برای این حالت، از جمله هنگام memory status --deep، کاوشگرهای آمادگی برداری معنایی یا نگهداری embedding در QMD را اجرا نمی‌کند؛ vsearch و query همچنان به آمادگی برداری QMD و embeddingها نیاز دارند.

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

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

وقتی مقداردهی اولیه QMD هنگام شروع Gateway فعال باشد، OpenClaw فقط برای عامل‌های واجد شرایط QMD را شروع می‌کند. اگر update.onBoot برابر true باشد و نگه‌داری interval/embed پیکربندی نشده باشد، startup از یک مدیر یک‌باره برای بازخوانی هنگام راه‌اندازی استفاده می‌کند و سپس آن را می‌بندد. اگر یک بازه به‌روزرسانی یا embed پیکربندی شده باشد، startup مدیر QMD بلندمدت را باز می‌کند تا مالک watcher و تایمرهای interval باشد؛ update.onBoot: false فقط بازخوانی فوری هنگام راه‌اندازی را رد می‌کند.

نمونه کامل QMD

{  memory: {    backend: "qmd",    citations: "auto",    qmd: {      includeDefaultMemory: true,      update: { interval: "5m", debounceMs: 15000 },      limits: { maxResults: 6, 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 به‌صورت یک sweep زمان‌بندی‌شده اجرا می‌شود و از فازهای داخلی سبک/عمیق/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",          },        },      },    },  },}

مرتبط

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