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

تسرد هذه الصفحة كل إعدادات الضبط الخاصة بالبحث في ذاكرة 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، أو لـ APIs نماذج متوافقة مع OpenAI، مثل openai-responses / openai-completions. يحل 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 الأساسي.

للبحث في النصوص المنسوخة عبر الوكلاء ضمن نطاق وكيل، استخدم 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 أشكال مجموعات QMD واستعلامات MCP الحالية، لكنه يحافظ على عمل إصدارات 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",          },        },      },    },  },}

ذو صلة

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