الانتقال إلى المحتوى الرئيسي

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

تسرد هذه الصفحة كل خيارات الإعداد الخاصة ببحث الذاكرة في OpenClaw. للحصول على نظرات عامة مفاهيمية، راجع: توجد جميع إعدادات بحث الذاكرة ضمن agents.defaults.memorySearch في openclaw.json ما لم يُذكر خلاف ذلك. إذا كنت تبحث عن مفتاح تفعيل ميزة Active Memory وإعداد الوكيل الفرعي، فهو يوجد ضمن plugins.entries.active-memory بدلًا من memorySearch. يستخدم Active Memory نموذج بوابتين:
  1. يجب أن يكون Plugin مفعّلًا ويستهدف معرّف الوكيل الحالي
  2. يجب أن يكون الطلب جلسة دردشة تفاعلية مستمرة مؤهلة
راجع Active Memory لمعرفة نموذج التفعيل، والإعداد المملوك للـ Plugin، واستمرارية النصوص، ونمط الطرح الآمن.

اختيار الموفّر

المفتاحالنوعالافتراضيالوصف
providerstringيُكتشف تلقائيًامعرّف مهايئ التضمينات: bedrock أو gemini أو github-copilot أو local أو mistral أو ollama أو openai أو voyage
modelstringافتراضي الموفّراسم نموذج التضمينات
fallbackstring"none"معرّف المهايئ الاحتياطي عند فشل الأساسي
enabledbooleantrueتفعيل أو تعطيل بحث الذاكرة

ترتيب الاكتشاف التلقائي

عندما لا يتم تعيين provider، يختار OpenClaw أول خيار متاح:
  1. local — إذا كان memorySearch.local.modelPath مضبوطًا وكان الملف موجودًا.
  2. github-copilot — إذا أمكن حل رمز GitHub Copilot (متغير بيئة أو ملف تعريف مصادقة).
  3. openai — إذا أمكن حل مفتاح OpenAI.
  4. gemini — إذا أمكن حل مفتاح Gemini.
  5. voyage — إذا أمكن حل مفتاح Voyage.
  6. mistral — إذا أمكن حل مفتاح Mistral.
  7. bedrock — إذا نجحت سلسلة بيانات اعتماد AWS SDK (دور المثيل أو مفاتيح الوصول أو ملف التعريف أو SSO أو هوية الويب أو الإعداد المشترك).
ollama مدعوم لكنه لا يُكتشف تلقائيًا (عيّنه صراحةً).

حل مفاتيح API

تتطلب التضمينات البعيدة مفتاح API. أما Bedrock فيستخدم سلسلة بيانات الاعتماد الافتراضية لـ AWS SDK بدلًا من ذلك (أدوار المثيل وSSO ومفاتيح الوصول).
الموفّرمتغير البيئةمفتاح الإعداد
Bedrockسلسلة بيانات اعتماد AWSلا حاجة إلى مفتاح API
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKENملف تعريف المصادقة عبر تسجيل دخول الجهاز
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY (عنصر نائب)
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
يغطي Codex OAuth الدردشة/الإكمالات فقط ولا يلبّي طلبات التضمينات.

إعداد نقطة النهاية البعيدة

لنقاط نهاية OpenAI-compatible مخصّصة أو لتجاوز الإعدادات الافتراضية للموفّر:
المفتاحالنوعالوصف
remote.baseUrlstringعنوان URL أساسي مخصّص للـ API
remote.apiKeystringتجاوز مفتاح API
remote.headersobjectرؤوس HTTP إضافية (تُدمج مع افتراضيات الموفّر)
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

إعداد Gemini الخاص

المفتاحالنوعالافتراضيالوصف
modelstringgemini-embedding-001يدعم أيضًا gemini-embedding-2-preview
outputDimensionalitynumber3072بالنسبة إلى Embedding 2: 768 أو 1536 أو 3072
يؤدي تغيير النموذج أو outputDimensionality إلى إعادة فهرسة كاملة تلقائيًا.

إعداد تضمينات Bedrock

يستخدم Bedrock سلسلة بيانات الاعتماد الافتراضية لـ AWS SDK — لا حاجة إلى مفاتيح API. إذا كان OpenClaw يعمل على EC2 مع دور مثيل مفعّل لـ Bedrock، فما عليك سوى تعيين الموفّر والنموذج:
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
المفتاحالنوعالافتراضيالوصف
modelstringamazon.titan-embed-text-v2:0أي معرّف نموذج تضمينات Bedrock
outputDimensionalitynumberافتراضي النموذجبالنسبة إلى Titan V2: 256 أو 512 أو 1024

النماذج المدعومة

النماذج التالية مدعومة (مع اكتشاف العائلة والقيم الافتراضية للأبعاد):
معرّف النموذجالموفّرالأبعاد الافتراضيةالأبعاد القابلة للإعداد
amazon.titan-embed-text-v2:0Amazon1024256، 512، 1024
amazon.titan-embed-text-v1Amazon1536
amazon.titan-embed-g1-text-02Amazon1536
amazon.titan-embed-image-v1Amazon1024
amazon.nova-2-multimodal-embeddings-v1:0Amazon1024256، 384، 1024، 3072
cohere.embed-english-v3Cohere1024
cohere.embed-multilingual-v3Cohere1024
cohere.embed-v4:0Cohere1536256-1536
twelvelabs.marengo-embed-3-0-v1:0TwelveLabs512
twelvelabs.marengo-embed-2-7-v1:0TwelveLabs1024
المتغيرات ذات لاحقة الإنتاجية (مثل amazon.titan-embed-text-v1:2:8k) ترث إعدادات النموذج الأساسي.

المصادقة

تستخدم مصادقة Bedrock ترتيب حل بيانات الاعتماد القياسي في AWS SDK:
  1. متغيرات البيئة (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
  2. ذاكرة التخزين المؤقت لرمز SSO
  3. بيانات اعتماد رمز هوية الويب
  4. ملفات بيانات الاعتماد والإعدادات المشتركة
  5. بيانات اعتماد بيانات ECS أو EC2 الوصفية
تُحل المنطقة من AWS_REGION أو AWS_DEFAULT_REGION أو من baseUrl الخاص بموفّر amazon-bedrock، أو تكون افتراضيًا us-east-1.

أذونات IAM

يحتاج دور IAM أو المستخدم إلى:
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
ولأقل قدر من الامتيازات، قصّر InvokeModel على النموذج المحدد:
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

إعداد التضمينات المحلية

المفتاحالنوعالافتراضيالوصف
local.modelPathstringيُنزّل تلقائيًاالمسار إلى ملف نموذج GGUF
local.modelCacheDirstringافتراضي node-llama-cppدليل التخزين المؤقت للنماذج المنزّلة
النموذج الافتراضي: embeddinggemma-300m-qat-Q8_0.gguf (~0.6 غيغابايت، يُنزّل تلقائيًا). يتطلب بناءً أصليًا: pnpm approve-builds ثم pnpm rebuild node-llama-cpp.

إعداد البحث الهجين

كلها ضمن memorySearch.query.hybrid:
المفتاحالنوعالافتراضيالوصف
enabledbooleantrueتفعيل البحث الهجين BM25 + المتجهي
vectorWeightnumber0.7وزن الدرجات المتجهية (0-1)
textWeightnumber0.3وزن درجات BM25 (0-1)
candidateMultipliernumber4مضاعِف حجم مجموعة المرشحين

MMR (التنوع)

المفتاحالنوعالافتراضيالوصف
mmr.enabledbooleanfalseتفعيل إعادة الترتيب باستخدام MMR
mmr.lambdanumber0.70 = أقصى تنوع، 1 = أقصى صلة

التلاشي الزمني (الحداثة)

المفتاحالنوعالافتراضيالوصف
temporalDecay.enabledbooleanfalseتفعيل تعزيز الحداثة
temporalDecay.halfLifeDaysnumber30تنخفض الدرجة إلى النصف كل N يومًا
لا يُطبّق التلاشي أبدًا على الملفات الدائمة (MEMORY.md والملفات غير المؤرخة في memory/).

مثال كامل

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            vectorWeight: 0.7,
            textWeight: 0.3,
            mmr: { enabled: true, lambda: 0.7 },
            temporalDecay: { enabled: true, halfLifeDays: 30 },
          },
        },
      },
    },
  },
}

مسارات ذاكرة إضافية

المفتاحالنوعالوصف
extraPathsstring[]أدلة أو ملفات إضافية للفهرسة
{
  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:
المفتاحالنوعالافتراضيالوصف
multimodal.enabledbooleanfalseتفعيل الفهرسة متعددة الوسائط
multimodal.modalitiesstring[]["image"] أو ["audio"] أو ["all"]
multimodal.maxFileBytesnumber10000000الحد الأقصى لحجم الملف للفهرسة
ينطبق هذا فقط على الملفات الموجودة في extraPaths. تظل جذور الذاكرة الافتراضية مقتصرة على Markdown. يتطلب gemini-embedding-2-preview. ويجب أن تكون قيمة fallback هي "none". التنسيقات المدعومة: .jpg و.jpeg و.png و.webp و.gif و.heic و.heif (صور)؛ و.mp3 و.wav و.ogg و.opus و.m4a و.aac و.flac (صوت).

ذاكرة التخزين المؤقت للتضمينات

المفتاحالنوعالافتراضيالوصف
cache.enabledbooleanfalseتخزين تضمينات الأجزاء مؤقتًا في SQLite
cache.maxEntriesnumber50000الحد الأقصى للتضمينات المخزنة مؤقتًا
يمنع إعادة إنشاء التضمينات للنص غير المتغير أثناء إعادة الفهرسة أو تحديثات النصوص.

الفهرسة على دفعات

المفتاحالنوعالافتراضيالوصف
remote.batch.enabledbooleanfalseتفعيل API التضمينات على دفعات
remote.batch.concurrencynumber2مهام دفعات متوازية
remote.batch.waitbooleantrueانتظار اكتمال الدفعة
remote.batch.pollIntervalMsnumberفترة الاستطلاع
remote.batch.timeoutMinutesnumberمهلة الدفعة
متاح مع openai وgemini وvoyage. وعادةً ما تكون دفعات OpenAI الأسرع والأقل تكلفة لعمليات التعبئة الكبيرة.

بحث ذاكرة الجلسة (تجريبي)

افهرس نصوص الجلسات وأظهرها عبر memory_search:
المفتاحالنوعالافتراضيالوصف
experimental.sessionMemorybooleanfalseتفعيل فهرسة الجلسات
sourcesstring[]["memory"]أضف "sessions" لتضمين النصوص
sync.sessions.deltaBytesnumber100000عتبة البايتات لإعادة الفهرسة
sync.sessions.deltaMessagesnumber50عتبة الرسائل لإعادة الفهرسة
فهرسة الجلسات اختيارية وتعمل بشكل غير متزامن. وقد تكون النتائج قديمة قليلًا. توجد سجلات الجلسات على القرص، لذا تعامل مع الوصول إلى نظام الملفات بوصفه حدود الثقة.

تسريع المتجهات في SQLite ‏(sqlite-vec)

المفتاحالنوعالافتراضيالوصف
store.vector.enabledbooleantrueاستخدام sqlite-vec لاستعلامات المتجهات
store.vector.extensionPathstringbundledتجاوز مسار sqlite-vec
عندما لا يكون sqlite-vec متاحًا، يعود OpenClaw تلقائيًا إلى تشابه جيب التمام داخل العملية.

تخزين الفهرس

المفتاحالنوعالافتراضيالوصف
store.pathstring~/.openclaw/memory/{agentId}.sqliteموقع الفهرس (يدعم الرمز {agentId})
store.fts.tokenizerstringunicode61محلّل FTS5 (unicode61 أو trigram)

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

عيّن memory.backend = "qmd" للتفعيل. توجد جميع إعدادات QMD ضمن memory.qmd:
المفتاحالنوعالافتراضيالوصف
commandstringqmdمسار الملف التنفيذي لـ QMD
searchModestringsearchأمر البحث: search أو vsearch أو query
includeDefaultMemorybooleantrueفهرسة MEMORY.md وmemory/**/*.md تلقائيًا
paths[]arrayمسارات إضافية: { name, path, pattern? }
sessions.enabledbooleanfalseفهرسة نصوص الجلسات
sessions.retentionDaysnumberمدة الاحتفاظ بالنصوص
sessions.exportDirstringدليل التصدير
يفضّل OpenClaw أشكال مجموعة QMD الحالية واستعلامات MCP، لكنه يُبقي إصدارات QMD الأقدم عاملة من خلال الرجوع إلى أعلام مجموعات --mask القديمة وأسماء أدوات MCP الأقدم عند الحاجة. تبقى تجاوزات نموذج QMD ضمن جهة QMD، وليس في إعداد OpenClaw. إذا احتجت إلى تجاوز نماذج QMD على مستوى عام، فاضبط متغيرات البيئة مثل QMD_EMBED_MODEL وQMD_RERANK_MODEL وQMD_GENERATE_MODEL في بيئة تشغيل Gateway.

جدول التحديث

المفتاحالنوعالافتراضيالوصف
update.intervalstring5mفترة التحديث
update.debounceMsnumber15000تأخير إزالة الاهتزاز لتغييرات الملفات
update.onBootbooleantrueالتحديث عند بدء التشغيل
update.waitForBootSyncbooleanfalseحظر بدء التشغيل حتى يكتمل التحديث
update.embedIntervalstringوتيرة تضمين منفصلة
update.commandTimeoutMsnumberمهلة أوامر QMD
update.updateTimeoutMsnumberمهلة عمليات تحديث QMD
update.embedTimeoutMsnumberمهلة عمليات التضمين في QMD

الحدود

المفتاحالنوعالافتراضيالوصف
limits.maxResultsnumber6الحد الأقصى لنتائج البحث
limits.maxSnippetCharsnumberتقييد طول المقتطف
limits.maxInjectedCharsnumberتقييد إجمالي الأحرف المدرجة
limits.timeoutMsnumber4000مهلة البحث

النطاق

يتحكم في الجلسات التي يمكنها تلقي نتائج بحث QMD. وهو بنفس مخطط session.sendPolicy:
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
يسمح الإعداد الافتراضي المرفق بجلسات الرسائل المباشرة والقنوات، مع الاستمرار في رفض المجموعات. الافتراضي هو الرسائل المباشرة فقط. يطابق match.keyPrefix مفتاح الجلسة المطبّع؛ ويطابق match.rawKeyPrefix المفتاح الخام بما في ذلك agent:<id>:.

الاستشهادات

ينطبق memory.citations على جميع الواجهات الخلفية:
القيمةالسلوك
auto (الافتراضي)تضمين تذييل Source: <path#line> في المقتطفات
onتضمين التذييل دائمًا
offحذف التذييل (لا يزال المسار يُمرر إلى الوكيل داخليًا)

مثال 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 كعملية مسح مجدولة واحدة ويستخدم مراحل light/deep/REM الداخلية بوصفها تفصيلًا تنفيذيًا. للاطلاع على السلوك المفاهيمي وأوامر الشرطة المائلة، راجع Dreaming.

إعدادات المستخدم

المفتاحالنوعالافتراضيالوصف
enabledbooleanfalseتفعيل Dreaming أو تعطيله بالكامل
frequencystring0 3 * * *وتيرة Cron اختيارية لعملية Dreaming الكاملة

مثال

{
  plugins: {
    entries: {
      "memory-core": {
        config: {
          dreaming: {
            enabled: true,
            frequency: "0 3 * * *",
          },
        },
      },
    },
  },
}
ملاحظات:
  • يكتب Dreaming حالة الآلة إلى memory/.dreams/.
  • يكتب Dreaming مخرجات سردية مقروءة للبشر إلى DREAMS.md (أو dreams.md الموجود).
  • إن سياسة المراحل light/deep/REM والعتبات هي سلوك داخلي، وليست إعدادًا موجّهًا للمستخدم.