ذاكرة LanceDB

memory-lancedb هو Plugin ذاكرة خارجي رسمي يخزن الذاكرة طويلة الأمد في LanceDB ويستخدم التضمينات للاسترجاع. يمكنه استرجاع الذكريات ذات الصلة تلقائيا قبل دور النموذج والتقاط الحقائق المهمة بعد الرد. استخدمه عندما تريد قاعدة بيانات متجهات محلية للذاكرة، أو تحتاج إلى نقطة نهاية تضمين متوافقة مع OpenAI، أو تريد إبقاء قاعدة بيانات الذاكرة خارج مخزن الذاكرة المدمج الافتراضي.

التثبيت

ثبّت memory-lancedb قبل تعيين plugins.slots.memory = "memory-lancedb":

openclaw plugins install @openclaw/memory-lancedb

ينشر Plugin على npm ولا يكون مضمنًا في صورة وقت تشغيل OpenClaw. يكتب المثبّت إدخال Plugin ويبدّل خانة الذاكرة عندما لا يملكها أي Plugin آخر.

memory-lancedb هو Plugin Active Memory. فعّله بتحديد خانة الذاكرة باستخدام plugins.slots.memory = "memory-lancedb". يمكن تشغيل Plugins مرافقة مثل memory-wiki إلى جانبه، لكن Plugin واحدًا فقط يملك خانة Active Memory.

البدء السريع

{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "openai",
            model: "text-embedding-3-small",
          },
          autoRecall: true,
          autoCapture: false,
        },
      },
    },
  },
}

أعد تشغيل Gateway بعد تغيير إعدادات Plugin:

openclaw gateway restart

ثم تحقق من تحميل Plugin:

openclaw plugins list

التضمينات المدعومة بالمزوّدين

يمكن لـ memory-lancedb استخدام محولات مزوّد تضمينات الذاكرة نفسها التي يستخدمها memory-core. عيّن embedding.provider واحذف embedding.apiKey لاستخدام ملف تعريف المصادقة المهيأ للمزوّد، أو متغير البيئة، أو models.providers.<provider>.apiKey.

{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "openai",
            model: "text-embedding-3-small",
          },
          autoRecall: true,
        },
      },
    },
  },
}

يعمل هذا المسار مع ملفات تعريف مصادقة المزوّد التي تعرض بيانات اعتماد التضمينات. على سبيل المثال، يمكن استخدام GitHub Copilot عندما يدعم ملف تعريف/خطة Copilot التضمينات:

{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "github-copilot",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

OpenAI Codex / ChatGPT OAuth ليس بيانات اعتماد تضمينات OpenAI Platform. لتضمينات OpenAI، استخدم ملف تعريف مصادقة بمفتاح OpenAI API، أو OPENAI_API_KEY، أو models.providers.openai.apiKey. يمكن للمستخدمين المعتمدين على OAuth فقط استخدام مزوّد آخر قادر على التضمين مثل GitHub Copilot أو Ollama.

تضمينات Ollama

لتضمينات Ollama، يفضّل استخدام مزوّد تضمينات Ollama المضمن. يستخدم نقطة نهاية Ollama الأصلية /api/embed ويتبع قواعد المصادقة/عنوان URL الأساسي نفسها مثل مزوّد Ollama الموثق في Ollama.

{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "ollama",
            baseUrl: "http://127.0.0.1:11434",
            model: "mxbai-embed-large",
            dimensions: 1024,
          },
          recallMaxChars: 400,
          autoRecall: true,
          autoCapture: false,
        },
      },
    },
  },
}

عيّن dimensions لنماذج التضمين غير القياسية. يعرف OpenClaw الأبعاد الخاصة بـ text-embedding-3-small وtext-embedding-3-large؛ وتحتاج النماذج المخصصة إلى القيمة في الإعدادات كي يتمكن LanceDB من إنشاء عمود المتجهات. بالنسبة إلى نماذج التضمين المحلية الصغيرة، خفّض recallMaxChars إذا ظهرت لك أخطاء طول السياق من الخادم المحلي.

المزوّدون المتوافقون مع OpenAI

ترفض بعض مزوّدات التضمين المتوافقة مع OpenAI معلمة encoding_format، بينما تتجاهلها أخرى وتعيد دائمًا متجهات number[]. لذلك يحذف memory-lancedb معلمة encoding_format في طلبات التضمين ويقبل إما استجابات مصفوفات الأعداد العشرية أو استجابات float32 المرمزة بـ base64. إذا كانت لديك نقطة نهاية تضمينات خام متوافقة مع OpenAI ولا تملك محول مزوّد مضمنًا، فاحذف embedding.provider (أو اتركه كـ openai) وعيّن embedding.apiKey مع embedding.baseUrl. يحافظ هذا على مسار العميل المباشر المتوافق مع OpenAI. عيّن embedding.dimensions للمزوّدين الذين لا تكون أبعاد نماذجهم مدمجة. على سبيل المثال، يستخدم ZhiPu embedding-3 أبعادًا بقيمة 2048:

{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            apiKey: "${ZHIPU_API_KEY}",
            baseUrl: "https://open.bigmodel.cn/api/paas/v4",
            model: "embedding-3",
            dimensions: 2048,
          },
        },
      },
    },
  },
}

حدود الاسترجاع والالتقاط

يحتوي memory-lancedb على حدين منفصلين للنص:

الإعداد	الافتراضي	النطاق	ينطبق على
`recallMaxChars`	`1000`	100-10000	النص المرسل إلى واجهة API التضمين للاسترجاع
`captureMaxChars`	`500`	100-10000	طول الرسالة المؤهلة للالتقاط التلقائي
`customTriggers`	`[]`	0-50	عبارات حرفية تجعل الالتقاط التلقائي يأخذ رسالة في الاعتبار

يتحكم recallMaxChars في الاسترجاع التلقائي، وأداة memory_recall، ومسار استعلام memory_forget، وopenclaw ltm search. يفضّل الاسترجاع التلقائي أحدث رسالة مستخدم من الدور، ويعود إلى الموجّه الكامل فقط عندما لا تكون هناك رسالة مستخدم متاحة. هذا يبقي بيانات تعريف القناة وكتل الموجّهات الكبيرة خارج طلب التضمين. يتحكم captureMaxChars فيما إذا كان الرد قصيرًا بما يكفي للنظر فيه للالتقاط التلقائي. ولا يحد من تضمينات استعلامات الاسترجاع. يتيح لك customTriggers إضافة عبارات التقاط تلقائي حرفية دون كتابة تعابير نمطية. تتضمن المشغلات المدمجة عبارات ذاكرة شائعة بالإنجليزية والتشيكية والصينية واليابانية والكورية.

الأوامر

عندما يكون memory-lancedb هو Plugin الذاكرة النشط، فإنه يسجل مساحة أسماء CLI ltm:

openclaw ltm list
openclaw ltm search "project preferences"
openclaw ltm stats

يشغّل الأمر الفرعي query استعلامًا غير متجهي على جدول LanceDB مباشرة:

openclaw ltm query --cols id,text,createdAt --limit 20
openclaw ltm query --filter "category = 'preference'" --order-by createdAt:desc

--cols <columns>: قائمة سماح بالأعمدة مفصولة بفواصل (الافتراضي هو id وtext وimportance وcategory وcreatedAt).
--filter <condition>: عبارة WHERE بأسلوب SQL؛ محدودة بـ 200 حرف ومقيدة بالأحرف الأبجدية الرقمية، وعوامل المقارنة، وعلامات الاقتباس، والأقواس، ومجموعة صغيرة من علامات الترقيم الآمنة.
--limit <n>: عدد صحيح موجب؛ الافتراضي 10.
--order-by <column>:<asc|desc>: فرز في الذاكرة يطبق بعد المرشح؛ يدرج عمود الفرز تلقائيًا في الإسقاط.

يحصل الوكلاء أيضًا على أدوات ذاكرة LanceDB من Plugin الذاكرة النشط:

memory_recall للاسترجاع المدعوم بـ LanceDB
memory_store لحفظ الحقائق والتفضيلات والقرارات والكيانات المهمة
memory_forget لإزالة الذكريات المطابقة

التخزين

افتراضيًا، تعيش بيانات LanceDB تحت ~/.openclaw/memory/lancedb. تجاوز المسار باستخدام dbPath:

{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          dbPath: "~/.openclaw/memory/lancedb",
          embedding: {
            apiKey: "${OPENAI_API_KEY}",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

يقبل storageOptions أزواج مفاتيح/قيم نصية لخلفيات تخزين LanceDB ويدعم توسيع ${ENV_VAR}:

{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          dbPath: "s3://memory-bucket/openclaw",
          storageOptions: {
            access_key: "${AWS_ACCESS_KEY_ID}",
            secret_key: "${AWS_SECRET_ACCESS_KEY}",
            endpoint: "${AWS_ENDPOINT_URL}",
          },
          embedding: {
            apiKey: "${OPENAI_API_KEY}",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

تبعيات وقت التشغيل

يعتمد memory-lancedb على الحزمة الأصلية @lancedb/lancedb. يتعامل OpenClaw المعبأ مع تلك الحزمة كجزء من حزمة Plugin. لا يصلح بدء تشغيل Gateway تبعيات Plugin؛ إذا كانت التبعية مفقودة، فأعد تثبيت حزمة Plugin أو حدّثها ثم أعد تشغيل Gateway. إذا سجّل تثبيت أقدم خطأ dist/package.json مفقودًا أو خطأ @lancedb/lancedb مفقودًا أثناء تحميل Plugin، فرَقِّ OpenClaw وأعد تشغيل Gateway. إذا سجّل Plugin أن LanceDB غير متاح على darwin-x64، فاستخدم خلفية الذاكرة الافتراضية على ذلك الجهاز، أو انقل Gateway إلى منصة مدعومة، أو عطّل memory-lancedb.

استكشاف الأخطاء وإصلاحها

يتجاوز طول الإدخال طول السياق

يعني هذا عادة أن نموذج التضمين رفض استعلام الاسترجاع:

memory-lancedb: recall failed: Error: 400 the input length exceeds the context length

عيّن قيمة أقل لـ recallMaxChars، ثم أعد تشغيل Gateway:

{
  plugins: {
    entries: {
      "memory-lancedb": {
        config: {
          recallMaxChars: 400,
        },
      },
    },
  },
}

بالنسبة إلى Ollama، تحقق أيضًا من إمكانية وصول خادم التضمين من مضيف Gateway:

curl http://127.0.0.1:11434/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model":"mxbai-embed-large","input":"hello"}'

نموذج تضمين غير مدعوم

بدون dimensions، لا تكون معروفة إلا أبعاد تضمين OpenAI المدمجة. بالنسبة إلى نماذج التضمين المحلية أو المخصصة، عيّن embedding.dimensions إلى حجم المتجه الذي يبلّغ عنه ذلك النموذج.

يتم تحميل Plugin لكن لا تظهر أي ذكريات

تحقق من أن plugins.slots.memory يشير إلى memory-lancedb، ثم شغّل:

openclaw ltm stats
openclaw ltm search "recent preference"

إذا كان autoCapture معطلًا، فسوف يسترجع Plugin الذكريات الموجودة لكنه لن يخزن ذكريات جديدة تلقائيًا. استخدم أداة memory_store أو فعّل autoCapture إذا كنت تريد الالتقاط التلقائي.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

ذاكرة LanceDB

التثبيت

البدء السريع

التضمينات المدعومة بالمزوّدين

تضمينات Ollama

المزوّدون المتوافقون مع OpenAI

حدود الاسترجاع والالتقاط

الأوامر

التخزين

تبعيات وقت التشغيل

استكشاف الأخطاء وإصلاحها

يتجاوز طول الإدخال طول السياق

نموذج تضمين غير مدعوم

يتم تحميل Plugin لكن لا تظهر أي ذكريات

ذو صلة

​التثبيت

​البدء السريع

​التضمينات المدعومة بالمزوّدين

​تضمينات Ollama

​المزوّدون المتوافقون مع OpenAI

​حدود الاسترجاع والالتقاط

​الأوامر

​التخزين

​تبعيات وقت التشغيل

​استكشاف الأخطاء وإصلاحها

​يتجاوز طول الإدخال طول السياق

​نموذج تضمين غير مدعوم

​يتم تحميل Plugin لكن لا تظهر أي ذكريات

​ذو صلة

التثبيت

البدء السريع

التضمينات المدعومة بالمزوّدين

تضمينات Ollama

المزوّدون المتوافقون مع OpenAI

حدود الاسترجاع والالتقاط

الأوامر

التخزين

تبعيات وقت التشغيل

استكشاف الأخطاء وإصلاحها

يتجاوز طول الإدخال طول السياق

نموذج تضمين غير مدعوم

يتم تحميل Plugin لكن لا تظهر أي ذكريات

ذو صلة