واجهة ذاكرة Lucid.so

تربط واجهة Lucid بين PRX وLucid.so، وهي خدمة ذاكرة مدعومة بالذكاء الاصطناعي توفّر تخزينًا مُدارًا وبحثًا دلاليًا وتنظيمًا تلقائيًا للذاكرة. تمثل بديلًا لواجهات SQLite وPostgreSQL المحلية للفرق التي تفضّل حلًا مستضافًا.

نظرة عامة

Lucid.so منصة ذاكرة سحابية مستضافة ومصممة لوكلاء الذكاء الاصطناعي. وهي تتعامل مع:

• تخزين ذاكرة دائم مع إزالة التكرار تلقائيًا
• بحث دلالي مدعوم بنماذج تضمين مستضافة
• تجميع تلقائي للموضوعات وتنظيم الذاكرة
• مشاركة الذاكرة عبر الجلسات بين عدة مثيلات للوكلاء
• إدارة دورة حياة الذاكرة مع سياسات احتفاظ قابلة للتهيئة

على عكس الواجهات المحلية (SQLite وPostgreSQL)، لا يتطلب Lucid إدارة قاعدة بيانات. تُخزَّن الذكريات في بنية Lucid التحتية ويُوصل إليها عبر REST API الخاصة بهم.

متى تستخدم Lucid

Scenario	Recommended Backend
وكيل محلي لمستخدم واحد	SQLite
نشر داخلي متعدد المستخدمين	PostgreSQL
فريق يعتمد السحابة أولًا مع حد أدنى من عبء التشغيل	Lucid
مشاركة الذاكرة عبر الأجهزة	Lucid
بيئات معزولة أو دون اتصال	SQLite or PostgreSQL
تحكم كامل في مكان إقامة البيانات	SQLite or PostgreSQL

المتطلبات المسبقة

• حساب Lucid.so (سجّل عبر lucid.so)
• مفتاح API من لوحة تحكم Lucid
• معرّف مساحة عمل (يُنشأ تلقائيًا عند أول استخدام، أو يمكنك تحديد واحد موجود)

إعداد سريع

1. الحصول على بيانات اعتماد API

1. سجّل الدخول إلى Lucid Dashboard
2. انتقل إلى "Settings" ثم "API Keys"
3. أنشئ مفتاح API جديدًا بصلاحيات "Memory Read/Write"
4. انسخ مفتاح API ومعرّف مساحة العمل

2. الإعداد

[memory]
backend = "lucid"

[memory.lucid]
api_key = "luc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
workspace_id = "ws_abc123"

3. التحقق

prx doctor memory

يختبر هذا الاتصال بـ Lucid API ويتحقق من أن مفتاح API يملك الصلاحيات المطلوبة.

مرجع الإعدادات

Field	Type	Default	Description
api_key	String	required	مفتاح Lucid.so API بصلاحيات قراءة/كتابة الذاكرة
workspace_id	String	auto-created	معرّف مساحة العمل لعزل الذاكرة. اتركه فارغًا للإنشاء التلقائي عند أول استخدام
base_url	String	"https://api.lucid.so/v1"	عنوان Lucid API الأساسي. يمكن تجاوزه للنشر الذاتي أو نقاط نهاية إقليمية
timeout_secs	u64	30	مهلة طلب HTTP بالثواني
max_retries	u32	3	الحد الأقصى لمحاولات إعادة المحاولة في حالات الفشل العابر
retry_backoff_ms	u64	500	تأخير backoff الابتدائي بين المحاولات (أُسّي)
batch_size	usize	50	عدد الذكريات المرسلة في كل طلب كتابة دُفعي
top_k	usize	10	العدد الافتراضي للنتائج المعادة في استعلامات الاسترجاع
similarity_threshold	f64	0.5	الحد الأدنى لدرجة التشابه (0.0--1.0) لنتائج الاسترجاع
auto_topics	bool	true	تفعيل تجميع الموضوعات التلقائي في Lucid
retention_days	u64	0	حذف تلقائي للذكريات الأقدم من N يومًا. القيمة 0 = الاحتفاظ للأبد

كيف تعمل

تخزين الذاكرة

عندما يخزن الوكيل ذاكرة، يرسلها PRX إلى Lucid API:

1. يُرسل نص الذاكرة وبياناتها الوصفية كطلب POST إلى /memories
2. يقوم Lucid بتضمين النص باستخدام نموذج التضمين المستضاف لديه
3. تُفهرس الذاكرة لكل من البحث بالكلمات المفتاحية والبحث الدلالي
4. إذا كان auto_topics مفعّلًا، يعيّن Lucid وسوم الموضوعات تلقائيًا

استرجاع الذاكرة

عندما يحتاج الوكيل إلى سياق، يستعلم PRX من Lucid:

1. يُرسل سياق المحادثة الحالي كاستعلام استرجاع
2. ينفذ Lucid بحثًا هجينًا (تشابه دلالي + مطابقة كلمات مفتاحية)
3. تُرتب النتائج حسب الصلة وتُفلتر بواسطة similarity_threshold
4. تُعاد أعلى K نتائج مع النص والبيانات الوصفية ودرجات الصلة

تنظيم الذاكرة

يوفّر Lucid إدارة ذاكرة على جانب الخادم:

• Deduplication -- تُدمج الذكريات شبه المكررة تلقائيًا
• Topic clustering -- تُجمع الذكريات ضمن موضوعات دون تصنيف يدوي
• Compaction -- يمكن تلخيص الذكريات القديمة أو منخفضة الصلة ودمجها
• Retention -- تُزال الذكريات المنتهية الصلاحية وفق retention_days

مقارنة مع الواجهات المحلية

Feature	SQLite	PostgreSQL	Lucid
تعقيد الإعداد	None	Moderate	Minimal (API key)
مكان إقامة البيانات	Local	Self-hosted	Cloud (Lucid servers)
البحث الدلالي	Via embeddings add-on	Via pgvector add-on	Built-in
إزالة التكرار التلقائية	No	No	Yes
تجميع الموضوعات التلقائي	No	No	Yes
المشاركة عبر الأجهزة	No	Yes (network)	Yes (cloud)
العمل دون اتصال	Yes	Yes	No
التكلفة	Free	Free (self-hosted)	Free tier + paid plans
قابلية التوسع	~100K memories	Millions	Millions (managed)

متغيرات البيئة

لبيئات CI/CD أو النشر بالحاويات، يمكن ضبط بيانات الاعتماد عبر متغيرات البيئة:

export PRX_MEMORY_LUCID_API_KEY="luc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export PRX_MEMORY_LUCID_WORKSPACE_ID="ws_abc123"

تأخذ متغيرات البيئة أولوية على قيم ملف الإعدادات.

معالجة الأخطاء

تتعامل واجهة Lucid مع الأخطاء العابرة بسلاسة:

• Network failures -- تُعاد المحاولة حتى max_retries مع backoff أُسّي
• Rate limiting -- استجابات 429 تُفعّل backoff تلقائيًا باستخدام ترويسة Retry-After
• Authentication errors -- تُسجل كأخطاء؛ ويواصل الوكيل العمل دون ذاكرة بدلًا من التعطل
• Timeout -- الطلبات التي تتجاوز timeout_secs تُلغى وتُعاد محاولتها

عندما لا يمكن الوصول إلى Lucid، يتدهور PRX بسلاسة: يعمل الوكيل دون استرجاع ذاكرة حتى عودة الاتصال. لا تضيع أي ذكريات -- تُصفّ الكتابات المعلقة وتُفرّغ عند استعادة الاتصال.

القيود

• يتطلب اتصالًا بالإنترنت؛ غير مناسب للبيئات المعزولة
• تُخزّن بيانات الذاكرة على بنية Lucid التحتية؛ راجع اتفاقية معالجة البيانات لديهم للامتثال
• الطبقة المجانية لها حدود تخزين واستعلام (راجع صفحة تسعير Lucid للتفاصيل الحالية)
• زمن الاستجابة أعلى من الواجهات المحلية بسبب دورات الشبكة (عادة 50--200ms لكل استعلام)
• نشر Lucid ذاتي الاستضافة يتطلب ترخيصًا منفصلًا

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

خطأ "Authentication failed"

• تحقّق من أن مفتاح API صحيح ولم يُلغَ من لوحة Lucid
• تأكد أن مفتاح API يملك صلاحيات "Memory Read/Write"
• افحص أن base_url يشير إلى نقطة نهاية Lucid الصحيحة

استرجاع الذاكرة لا يعيد نتائج

• تحقّق من تخزين الذكريات عبر لوحة Lucid
• خفّض similarity_threshold (مثلًا إلى 0.3) لمعرفة ما إذا كانت النتائج تُفلتر
• تحقق من تطابق workspace_id مع مساحة العمل التي خُزنت فيها الذكريات

ارتفاع زمن الاستجابة في استعلامات الاسترجاع

• قلّل top_k لإرجاع نتائج أقل لكل استعلام
• افحص زمن الشبكة إلى نقطة نهاية Lucid API
• فكّر في استخدام base_url إقليمي إذا كانت Lucid توفّر نقاط نهاية أقرب إلى نشرك

الذكريات لا تستمر عبر الجلسات

• أكّد ضبط backend = "lucid" في قسم [memory]
• تحقّق من أن workspace_id ثابت عبر جميع مثيلات الوكيل
• راجع سجلات PRX بحثًا عن أخطاء كتابة قد تدل على فشل الحفظ

صفحات ذات صلة

• نظرة عامة على نظام الذاكرة
• واجهة SQLite -- بديل محلي في ملف واحد
• واجهة PostgreSQL -- بديل ذاتي الاستضافة لمستخدمين متعددين
• واجهة Embeddings -- ذاكرة دلالية محلية قائمة على المتجهات
• نظافة الذاكرة -- استراتيجيات الضغط والتنظيف