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

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

همه تنظیمات مشترک حافظه در سطح بالای memory در openclaw.json قرار دارند. پیش‌فرض‌های جست‌وجو از memory.search و بازنویسی‌های جست‌وجوی مختص هر عامل از agents.entries.*.memory.search استفاده می‌کنند.

به‌خاطرسپاری میان مکالمات

وقتی فقط یک عامل شخصی مورداعتماد باید از یادآوری رونوشت میان مکالمات استفاده کند، آن را برای همان عامل پیکربندی کنید:

{  agents: {    entries: {      personal: {        memory: {          search: {            rememberAcrossConversations: true,          },        },      },    },  },}

این مقدار از وراثت عادی memory.search همراه با یک بازنویسی مختص عامل پیروی می‌کند. وقتی تنظیم نشده باشد، فقط در صورتی به‌طور پیش‌فرض روشن است که session.dmScope سراسری تنظیم نشده باشد یا "main" باشد و هیچ اتصالی بازنویسی session.dmScope نداشته باشد. هرگونه جداسازی پیکربندی‌شده پیام مستقیم، آن را به‌طور پیش‌فرض خاموش می‌کند. مقدار صریح true یا false همیشه اولویت دارد. فعال‌سازی آن مستلزم نمایه‌سازی رونوشت نشست است و sessions را به منابع حافظه حل‌شده عامل اضافه می‌کند. با QMD، خروجی‌گیری نشست آن عامل را نیز فعال می‌کند؛ برای این حالت به تنظیم جداگانه memory.qmd.sessions.enabled نیازی نیست.

ارائه‌دهنده حافظه داخلی OpenClaw این مسیر محافظت‌شده را با هر دو بک‌اند داخلی و QMD پشتیبانی می‌کند. ارائه‌دهندگان جایگزین حافظه می‌توانند همچنان از قلاب‌های یادآوری و ابزارهای پیشرفته Active Memory خود استفاده کنند، اما این تنظیم نادیده گرفته می‌شود، مگر آنکه ارائه‌دهنده فعلی از یادآوری محافظت‌شده رونوشت خصوصی پشتیبانی کند. openclaw doctor ارائه‌دهنده پشتیبانی‌نشده یا فهرست صریح toolsAllow در Active Memory را که شامل memory_search نیست، گزارش می‌کند.

مرز بازیابی محدودتر از جست‌وجوی عمومی نشست است:

• فقط مکالمات خصوصی شناخته‌شده همان عامل واجد شرایط هستند
• مکالمه‌ای که به آن پاسخ داده می‌شود مستثنا است
• گروه‌ها و کانال‌ها به‌عنوان مبدأ و مقصد مستثنا هستند
• گونه‌های ناشناخته مکالمه به‌صورت بسته رد می‌شوند
• یادآوری در محیط ایزوله نمی‌تواند از مجوز ویژه میان مکالمات استفاده کند

این تنظیم tools.sessions.visibility، کلیدهای نشست، ذخیره‌سازی رونوشت، مسیریابی تحویل یا مجوزهای sessions_list، sessions_history و sessions_send را تغییر نمی‌دهد. Active Memory یک مرحله بازیابی فقط‌خواندنی و محدود انجام می‌دهد؛ در دسترس نبودن یا پایان مهلت بازیابی، پاسخ را مسدود نمی‌کند.

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

وقتی 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 استفاده کند.

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

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

memory.search.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" }],      },    },  },  memory: {    search: {      provider: "ollama-5080",      model: "qwen3-embedding:0.6b",    },  },}

حل کلید API

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

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

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

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

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

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

{  memory: {    search: {      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

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

موتورهای حافظه مسئول همگام‌سازی، دسته‌بندی، پایش و روش‌های ابتکاری نمایه‌سازی پس از Compaction هستند. OpenClaw این رفتارها را به‌جای ارائهٔ تنظیمات زمان‌بندی برای هر نصب، با پیش‌فرض‌های نگه‌داری‌شده فعال نگه می‌دارد.

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

همه در زیرمجموعهٔ memory.search.query:

بازیابی ترکیبی فعال باقی می‌ماند؛ MMR و کاهش زمانی طبق سیاست داخلی موتور غیرفعال باقی می‌مانند.

نمونهٔ کامل

{  memory: {    search: {      query: {        maxResults: 6,        minScore: 0.35,      },    },  },}

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

{  memory: {    search: {      extraPaths: ["../team-docs", "/srv/shared-notes"],    },  },}

مسیرها می‌توانند مطلق یا نسبت به فضای کاری باشند. پوشه‌ها برای یافتن فایل‌های .md به‌صورت بازگشتی پویش می‌شوند. نحوهٔ مدیریت پیوندهای نمادین به بک‌اند فعال بستگی دارد: موتور داخلی از پیوندهای نمادین عبور می‌کند، درحالی‌که QMD از رفتار پویشگر زیربنایی QMD پیروی می‌کند.

برای جست‌وجوی رونوشت میان‌عاملی با دامنهٔ عامل، به‌جای memory.qmd.paths از agents.entries.*.memory.search.qmd.extraCollections استفاده کنید. آن مجموعه‌های اضافی از همان ساختار { path, name, pattern? } پیروی می‌کنند، اما برای هر عامل ادغام می‌شوند و هنگامی که مسیر به خارج از فضای کاری فعلی اشاره دارد، می‌توانند نام‌های اشتراکی صریح را حفظ کنند. اگر مسیر تفکیک‌شدهٔ یکسانی هم در memory.qmd.paths و هم در memory.search.qmd.extraCollections ظاهر شود، QMD نخستین ورودی را نگه می‌دارد و از مورد تکراری عبور می‌کند.

حافظهٔ چندوجهی (Gemini)

تصاویر و صدا را با استفاده از Gemini Embedding 2 در کنار Markdown نمایه‌سازی کنید:

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

کش تعبیه‌سازی

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

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

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

رفتار هم‌زمانی، نظرسنجی و مهلت زمانی در اختیار ارائه‌دهنده است.

جست‌وجوی حافظهٔ نشست

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

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

rememberAcrossConversations این تنظیم را گسترده‌تر نمی‌کند. این گزینه یک مجوز جداگانه و مختص زمان اجرا فراهم می‌کند که در گذر محدود Active Memory، فقط به رونوشت‌های خصوصی همان عامل محدود است.

مثال‌های زیر این تنظیمات را زیر memory.search سطح‌بالا قرار می‌دهند. همچنین می‌توانید تنظیمات معادل را در یک بازنویسی memory.search مختص هر عامل اعمال کنید، زمانی که فقط یک عامل باید رونوشت‌های نشست را نمایه‌سازی و جست‌وجو کند.

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

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

{  memory: {    backend: "qmd",    search: {      experimental: { sessionMemory: true },      sources: ["memory", "sessions"],    },    qmd: {      sessions: { enabled: true },    },  },  tools: {    sessions: { visibility: "agent" },  },}

هنگام استفاده از QMD، sources: ["sessions"] به‌تنهایی رونوشت‌ها را به QMD صادر نمی‌کند. memory.qmd.sessions.enabled: true را نیز تنظیم کنید. تنظیم سطح‌بالاتر rememberAcrossConversations: true یک استثنا است: این تنظیم، صدور لازم نشست QMD برای آن عامل را به‌طور ضمنی فعال می‌کند. خروجی‌های ضمنی خصوصی می‌مانند: آن‌ها همیشه از محل داخلی پیش‌فرض صدور استفاده می‌کنند (یک sessions.exportDir پیکربندی‌شده فقط برای خروجی‌های صریح اعمال می‌شود)، فقط هنگام یادآوری میان‌گفت‌وگویی آن عامل جست‌وجو می‌شوند و memory_get معمولی نمی‌تواند آن‌ها را بخواند. 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 مسیر سازگاری به‌ازای هر مجموعه را حفظ می‌کنند. هم‌منبع یعنی مجموعه‌های حافظه پایدار (فایل‌های حافظه پیش‌فرض به‌اضافه مسیرهای سفارشی) با هم گروه‌بندی می‌شوند، درحالی‌که مجموعه‌های رونوشت نشست گروهی جداگانه باقی می‌مانند تا تنوع‌بخشی منبع همچنان هر دو ورودی را داشته باشد.

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

QMD هنگام نخستین استفاده از حافظه به‌صورت تنبل مقداردهی اولیه می‌شود؛ آداپتور آن زمان‌بندی‌های نوسازی و تعبیه را مدیریت می‌کند.

مثال کامل 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 پیکربندی می‌شود، نه زیر memory.search.

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

مرتبط

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