مرجع إعدادات الذاكرة

تسرد هذه الصفحة جميع خيارات التكوين الخاصة ببحث ذاكرة OpenClaw. للاطلاع على نظرات عامة مفاهيمية، راجع:

توجد جميع إعدادات بحث الذاكرة ضمن agents.defaults.memorySearch في openclaw.json (أو في تجاوز خاص بكل وكيل ضمن agents.list[].memorySearch) ما لم يُذكر خلاف ذلك.

اختيار المزوّد

عندما لا تُضبط قيمة provider، يستخدم OpenClaw تضمينات OpenAI. اضبط provider صراحةً لاستخدام Bedrock أو DeepInfra أو Gemini أو GitHub Copilot أو Mistral أو Ollama أو Voyage أو نموذج GGUF محلي أو نقطة نهاية /v1/embeddings متوافقة مع OpenAI. تُحوَّل التكوينات القديمة التي لا تزال تحتوي على 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 فقط بصمت. أصلح تكوين المزوّد/المصادقة، أو انتقل إلى مزوّد يمكن الوصول إليه، أو اضبط provider: "none" إذا كنت تريد استرجاعًا مقصودًا باستخدام FTS فقط.

معرّفات المزوّدين المخصصة

يمكن أن يشير memorySearch.provider إلى إدخال مخصص في models.providers.<id> لمحوّلات المزوّد الخاصة بالذاكرة، مثل ollama، أو لواجهات API لنماذج متوافقة مع OpenAI، مثل openai-responses / openai-completions. يحل OpenClaw مالك api لذلك المزوّد لاستخدامه كمحوّل تضمين، مع الاحتفاظ بمعرّف المزوّد المخصص لمعالجة نقطة النهاية والمصادقة وبادئة النموذج. يتيح ذلك للإعدادات متعددة وحدات معالجة الرسومات أو متعددة المضيفين تخصيص تضمينات الذاكرة لنقطة نهاية محلية محددة:

{  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 سلوك الماسح الأساسي الخاص به.

للبحث في نصوص المحادثات بين الوكلاء ضمن نطاق وكيل، استخدم agents.list[].memorySearch.qmd.extraCollections بدلًا من memory.qmd.paths. تتبع هذه المجموعات الإضافية البنية نفسها { 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 تلقائيًا إلى استخدام تشابه جيب التمام داخل العملية.

تخزين الفهرس

توجد فهارس الذاكرة المضمنة في قاعدة بيانات OpenClaw SQLite الخاصة بكل وكيل في agents/<agentId>/agent/openclaw-agent.sqlite.

إعداد الواجهة الخلفية لـ QMD

عيّن memory.backend = "qmd" للتمكين. توجد جميع إعدادات QMD ضمن memory.qmd:

يقتصر searchMode: "search" على البحث المعجمي/BM25. لا يشغّل OpenClaw اختبارات جاهزية المتجهات الدلالية أو صيانة تضمينات QMD لهذا الوضع، بما في ذلك أثناء memory status --deep؛ ويظل vsearch وquery يتطلبان جاهزية متجهات QMD والتضمينات.

يغيّر rerank: false وضع query في QMD فقط، ويتطلب QMD 2.1 أو إصدارًا أحدث. في وضع CLI المباشر، يمرر OpenClaw الخيار --no-rerank؛ وفي وضع MCP المدعوم بواسطة mcporter، يمرر rerank: false إلى أداة الاستعلام الموحدة في QMD. اتركه دون تعيين لاستخدام سلوك إعادة ترتيب الاستعلامات الافتراضي في QMD.

يفضّل OpenClaw أشكال المجموعات واستعلامات MCP الحالية في QMD، لكنه يحافظ على عمل إصدارات QMD الأقدم عبر تجربة خيارات أنماط المجموعات المتوافقة وأسماء أدوات MCP الأقدم عند الحاجة. عندما يعلن QMD دعمه لمرشحات مجموعات متعددة، يُبحث في المجموعات ذات المصدر نفسه باستخدام عملية QMD واحدة؛ بينما تحتفظ إصدارات QMD الأقدم بمسار التوافق لكل مجموعة. ويعني المصدر نفسه تجميع مجموعات الذاكرة الدائمة (ملفات الذاكرة الافتراضية بالإضافة إلى المسارات المخصصة) معًا، بينما تظل مجموعات نصوص الجلسات في مجموعة منفصلة، بحيث يظل تنويع المصادر مستفيدًا من كلا المدخلين.

تكامل mcporter

توجد جميع الإعدادات ضمن memory.qmd.mcporter. يوجّه هذا عمليات بحث QMD عبر عفريت MCP طويل العمر تابع لـ mcporter بدلًا من إنشاء عملية qmd لكل استعلام، مما يقلل عبء البدء البارد للنماذج الأكبر.

يتطلب تثبيت 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",          },        },      },    },  },}

ذو صلة

• مرجع الإعدادات
• نظرة عامة على الذاكرة
• البحث في الذاكرة