# توثيق SYNAPSE — مرجع كامل
# تم الإنشاء: 2026-07-18T06:14:39.086Z
# إجمالي المقالات: 47

يحتوي هذا المستند على التوثيق الكامل لواجهة برمجة تطبيقات Synapse.
Base URL: https://synapse.schaefer.zone
Language: ar

========================================================================

## الفئة: البدء
كل ما تحتاجه للبدء مع Synapse.

────────────────────────────────────────────────────────────
# المصادقة و Mind Keys
SUMMARY: كيف تعمل مصادقة Synapse: Mind Keys للوكلاء، JWTs للبشر، ?key= للأدوات التي تفتح عناوين URL فقط.

KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.

المصادقة و Mind Keys
يستخدم Synapse طريقتين للمصادقة، كلٌّ مُحسّنة لحالة استخدام مختلفة.
فهم الفرق أساسي لبناء تكاملات موثوقة.
طريقتان للمصادقة
| الطريقة | حالة الاستخدام | حد المعدل | الانتهاء |
|--------|----------|------------|--------|
| Mind Key | وكلاء LLM، الأدوات المؤتمتة | لا شيء (ترويسة) / 60 دقيقة (استعلام) | أبدًا |
| JWT | واجهة الإنسان، عمليات الحساب | لا شيء | 7 أيام |
Mind Key (للوكلاء)
Mind Key رمز API محدود بمستأجر. يُصادق بيانات عقل واحد
(الذكريات، المهام، الدردشة، السكربتات، إلخ). استخدمه لـ:
- وكلاء LLM الذين يستدعون الـ API
- سكربتات الأتمتة الخلفية
- إعداد خادم MCP
- أي تكامل طويل الأمد
مصادقة الترويسة (موصى بها)
[CODE BLOCK]
معامل الاستعلام (للأدوات التي تفتح عناوين URL فقط)
[CODE BLOCK]
> [!WARNING]
> معامل الاستعلام  محدود بـ 60 طلبًا في الدقيقة.
> ترويسة Bearer بلا حد معدل. استخدم الترويسة كلما دعم عميلك
> الترويسات المخصصة.
إنشاء Mind Key
[CODE BLOCK]
تتضمن الاستجابة  — احفظه فورًا، يُعرض مرة واحدة فقط.
سرد عقلك
[CODE BLOCK]
حذف عقل (لا يمكن التراجع!)
[CODE BLOCK]
JWT (للبشر)
تُصادق JWTs حساب المستخدم، لا عقلًا محددًا. استخدمها لـ:
- تسجيل الحساب والدخول
- إنشاء / سرد / حذف العقول
- مشاركة العقول مع مستخدمين آخرين
- إدارة اشتراك Web Push
تسجيل
[CODE BLOCK]
يُرجع: 
تسجيل الدخول
[CODE BLOCK]
يُرجع: 
انتهاء JWT
تنتهي JWTs بعد 7 أيام. عند انتهاء JWT، استدعِ  مرة أخرى للحصول
على واحد جديد. لا تنتهي Mind Key أبدًا، لذا تستمر تكاملات الوكلاء
بالعمل.
أفضل ممارسات الأمان
> [!CRITICAL]
> - لا تلتزم Mind Keys في git أبدًا. استخدم متغيرات البيئة.
> - لا تسجّل Mind Keys أبدًا. قنّعها في السجلات ().
> - دوّر المفاتيح إذا اشتبهت في تسريب (احذف العقل، أنشئ واحدًا جديدًا).
> - استخدم عقلًا واحدًا لكل مشروع لتحديد دائرة الضرر إذا تسرب مفتاح.
نمط متغير البيئة
[CODE BLOCK]
[CODE BLOCK]
إعداد خادم MCP
[CODE BLOCK]
نمط العقول المتعددة
يستطيع كل مستخدم امتلاك عقول متعددة. أنماط شائعة:
| اسم العقل | الغرض |
|-----------|---------|
|  | ذكريات العمل |
|  | التفضيلات الشخصية، العائلة |
|  | سياق مشروع محدد |
|  | تقدّم التعلم |
|  | بديل للأغراض العامة |
استخدم Mind Keys مختلفة لجلسات LLM مختلفة للحفاظ على عزل السياقات.
حدود المعدل
| طريقة المصادقة | الحد | النطاق |
|-------------|-------|-------|
| Mind Key (ترويسة) | لا شيء | لكل عقل |
| Mind Key (?key=) | 60/دقيقة | لكل IP |
| JWT (ترويسة) | لا شيء | لكل مستخدم |
| نقاط النهاية العامة | لا شيء | عام |
تُتضمن ترويسات حد المعدل (، ، )
في الاستجابات عند الاقتضاء.
الخطوات التالية
- Mind Key مقابل JWT — متى تستخدم أيًّا منهما
- Memory API — ما تستطيع فعله بـ Mind Key
- User API — إدارة الحساب بـ JWTs

────────────────────────────────────────────────────────────
# Mind Key مقابل JWT — ماذا ومتى؟
SUMMARY: دليل القرار: Mind Key للوصول لبيانات الوكيل، JWT لإدارة الحساب.

KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).

Mind Key مقابل JWT — ماذا ومتى؟
يمتلك Synapse رمزي مصادقة. اختيار الخاطئ يؤدي إلى أخطاء 401.
يمنحك هذا الدليل إطار قرار واضح.
جدول القرار السريع
| تريد... | استخدم |
|----------------|-----|
| تخزين / استدعاء الذكريات | Mind Key |
| إرسال / استطلاع رسائل الدردشة | Mind Key |
| إدارة المهام | Mind Key |
| تخزين السكربتات | Mind Key |
| تسجيل الـ webhooks | Mind Key |
| التحكم بالأجهزة | Mind Key (جانب المستخدم) / Computer Token (جانب الوكيل) |
| تسجيل حساب مستخدم | لا شيء (عام) |
| تسجيل الدخول | لا شيء (عام) |
| إنشاء / سرد / حذف العقول | JWT |
| مشاركة عقل مع مستخدم آخر | JWT |
| الاشتراك في إشعارات web push | JWT |
| عرض سجل التدقيق | Mind Key |
القاعدة البسيطة
> [!TIP]
> إذا كان يلامس بيانات عقل واحد → Mind Key.
> إذا كان يدير الحساب أو بيانات العقل الوصفية → JWT.
Mind Key — رمز وصول البيانات
يمنح Mind Key الوصول إلى بيانات عقل واحد. إنه رمز طويل الأمد
لا ينتهي (حتى يُحذف العقل). مثالي لـ:
- وكلاء LLM الذين يحفظون الذكريات عبر الجلسات
- مهام cron الخلفية
- إعداد خادم MCP
- تكاملات الـ webhooks
- تطبيقات الموبايل التي تقرأ الذاكرة
ما يستطيع Mind Key فعله
-  — قراءة جميع الذكريات في هذا العقل
-  — تخزين/تحديث الذكريات
-  — قراءة رسائل الدردشة
-  — إرسال رسائل الدردشة
-  — سرد المهام
-  — إنشاء المهام
-  — تخزين السكربتات
-  — تسجيل الـ webhooks
-  — إدراج أوامر الأجهزة في الطابور
ما لا يستطيع Mind Key فعله
- إنشاء / سرد / حذف العقول (يحتاج JWT)
- مشاركة عقل مع مستخدم آخر (يحتاج JWT)
- عرض معلومات حساب المستخدم (يحتاج JWT)
- الاشتراك في web push (يحتاج JWT)
JWT — رمز إدارة الحساب
تُصادق JWT حساب المستخدم. تنتهي بعد 7 أيام وتُستخدم
لعمليات مستوى الحساب التي تمتد عبر عقول متعددة أو تتضمن مستخدمين آخرين.
ما تستطيع JWT فعله
-  — إنشاء عقل جديد (يُرجع Mind Key جديد)
-  — سرد جميع العقول لهذا المستخدم
-  — حذف عقل
-  — مشاركة عقل مع مستخدم آخر
-  — الاشتراك في إشعارات web push
-  — سرد مشاركات العقل
ما لا تستطيع JWT فعله
- قراءة / كتابة الذكريات (تحتاج Mind Key)
- إرسال رسائل الدردشة (تحتاج Mind Key)
- إدارة المهام (تحتاج Mind Key)
- تسجيل الـ webhooks (تحتاج Mind Key)
حالة خاصة: Computer Token
نقاط النهاية  (الخاصة بالوكيل، لـ screen-remote-agent)
تستخدم نوع رمز ثالث: Computer Token. يُرجع هذا الرمز بواسطة
 عند استرداد رمز تثبيت، وهو خاص بـ
جهاز مسجّل واحد.
| نقطة النهاية | المصادقة |
|----------|------|
|  | Computer Token |
|  | Computer Token |
|  | Mind Key أو JWT |
|  | Mind Key أو JWT |
الأنماط الشائعة
النمط 1: وكيل LLM واحد
1. سجّل مرة واحدة → احصل على JWT
2. أنشئ عقلًا واحدًا → احصل على Mind Key
3. يستخدم LLM Mind Key لكل شيء
النمط 2: وكيل متعدد المشاريع
1. سجّل مرة واحدة → احصل على JWT
2. أنشئ عقولًا متعددة (work، personal، project-x) → احصل على Mind Keys متعددة
3. يحمل LLM Mind Key مختلفًا حسب السياق
النمط 3: مشاركة الفريق
1. المستخدم A ينشئ عقلًا → يحصل على Mind Key A
2. المستخدم A يشارك مع المستخدم B عبر JWT ()
3. المستخدم B يستطيع الآن الوصول عبر JWT الخاص به
4. لوصول LLM، يحتاج المستخدم B لإنشاء Mind Key خاص به (أو استخدام A's)
النمط 4: خادم MCP
خوادم MCP تستخدم دائمًا Mind Key (عيينها عبر متغير البيئة ). نسخة خادم MCP
واحدة = عقل واحد. لوصول عقول متعددة، شغّل نسخ MCP متعددة
أو نفّذ تبديل العقل من جانب العميل.
ورقة غش تنسيق الرموز
| الرمز | التنسيق | مثال |
|-------|--------|---------|
| Mind Key |  + 36 حرفًا |  |
| JWT |  + base64 |  |
| Computer Token |  + 36 حرفًا |  |
الخطوات التالية
- المصادقة — دليل المصادقة الكامل
- User & Minds API — نقاط نهاية محمية بـ JWT
- Memory API — نقاط نهاية محمية بـ Mind Key

────────────────────────────────────────────────────────────
# البداية السريعة لوكلاء LLM
SUMMARY: في 3 استدعاءات API: استدعِ جميع الذكريات، خزّن واحدة جديدة، ابحث. سير عمل LLM الأساسي.

KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query)
ALWAYS call /memory/recall at the start of every session.
Wichtigste Befehle: GET /memory/recall, POST /memory, GET /memory/search?q=...
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
FTS5 search: multiple words = AND, "phrases" in quotes, prefix* for prefix search

البداية السريعة لوكلاء LLM
تفقد كل الذاكرة بين الجلسات. Synapse عقلك الخارجي. يعرض هذا الدليل
ثلاثة استدعاءات API أساسية يجب أن يعرفها كل وكيل LLM.
> [!CRITICAL]
> استدعِ  في بداية كل جلسة.
> بدون هذا الاستدعاء، ليس لديك ذاكرة بمن هو المستخدم، وما وعدت به،
> أو بما كنت تعمل عليه المرة السابقة.
الخطوة 1: استدعِ جميع الذكريات (دائمًا أولًا)
[CODE BLOCK]
يُرجع ملخصًا نصيًا عاديًا منظمًا لجميع الذكريات المخزّنة. حلل هذا لإعادة
بناء نموذجك الذهني للمستخدم، مشاريعه، وتفاعلاته السابقة.
مثال على الاستجابة:
[CODE BLOCK]
الخطوة 2: خزّن ذاكرة جديدة
عندما تتعلّم شيئًا يستحق التذكر:
[CODE BLOCK]
الفئات: ، ، ، ، ، ، ، 
الأولويات: ، ، ، 
> [!TIP]
> أرفق دائمًا حقل  — مُعرّف قصير للذاكرة. هذا يتيح لك
> تحديث نفس الذاكرة لاحقًا بإعادة POST بنفس المفتاح.
الخطوة 3: ابحث عن ذاكرة محددة
[CODE BLOCK]
> [!TIP]
> صياغة FTS5: كلمات متعددة = بحث AND. عبارات بين علامات اقتباس: .
> بحث البادئة: . منطقي: .
الأدوات المفتوحة (بلا ترويسات مصادقة)
إذا كانت أداتك تفتح عناوين URL فقط (بلا ترويسات مخصصة)، استخدم معامل :
[CODE BLOCK]
> [!WARNING]
>  محدود بـ 60 طلبًا/دقيقة. ترويسة Bearer بلا حد معدل.
> استخدم ترويسة Bearer كلما أمكن.
سير عمل الجلسة الكامل
1. بداية الجلسة:  — تحميل جميع الذكريات
2. أثناء العمل:  — إيجاد حقائق محددة
3. عند معلومات جديدة:  — تخزينها (مع category، key، tags، priority)
4. دوريًا:  — التحقق من رسائل الإنسان
5. نهاية الجلسة: تخزين أي تعلمات نهائية عبر 
الأنماط الشائعة
تحديث ذاكرة موجودة
استدعِ  بنفس  و  — تُحدَّث الذاكرة
الموجودة، لا تُكرّر.
تخزين حالة مشروع
[CODE BLOCK]
تسجيل خطأ (حتى لا تكرره)
[CODE BLOCK]
التحقق من رسائل الإنسان
[CODE BLOCK]
يُرجع الرسائل غير المقروءة من الإنسان. اردّ بـ:
[CODE BLOCK]
الخطوات التالية
- المصادقة — Mind Key مقابل JWT
- مرجع Memory API — جميع نقاط نهاية الذاكرة الـ 22
- Chat API — تواصل غير متزامن مع البشر
- كتاب طبخ LLM — أنماط عملية

────────────────────────────────────────────────────────────
# البداية السريعة (للإنسان)
SUMMARY: سجّل حسابًا، أنشئ أول عقل لك، خزّن ذاكرة — كل ذلك في 5 دقائق.

البداية السريعة (للإنسان)
يأخذك هذا الدليل خلال الحصول على حساب Synapse، أول Mind Key لك،
وتخزين أول ذاكرة. الوقت الإجمالي: 5 دقائق.
الخطوة 1: سجّل حسابًا
افتح Synapse API وأنشئ حسابًا:
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
> [!TIP]
> احفظ JWT في مكان آمن — ستحتاجه لإنشاء العقول. تنتهي JWT
> بعد 7 أيام؛ أعد تسجيل الدخول بنفس نقطة النهاية للتحديث.
الخطوة 2: أنشئ أول عقل لك
"العقل" نطاق ذاكرة معزول. يبدأ معظم المستخدمين بعقل واحد، لكن يمكنك
امتلاك عقول متعددة (مثلًا "work"، "personal"، "project-x"). لكل عقل
Mind Key فريد خاص به.
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
> [!CRITICAL]
> احفظ  فورًا. يُعرض مرة واحدة فقط ولا يمكن
> استرداده لاحقًا. إذا فقدته، ستحتاج لإنشاء عقل جديد.
الخطوة 3: خزّن أول ذاكرة
الآن استخدم Mind Key لتخزين ذاكرة:
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
الخطوة 4: استدعِ جميع الذكريات
لاسترجاع كل ما خزّنته:
[CODE BLOCK]
الاستجابة (نص عادي، مُحسّن لاستهلاك LLM):
[CODE BLOCK]
الخطوة 5: ابحث في الذكريات
أوجد ذكريات محددة بالكلمة المفتاحية:
[CODE BLOCK]
الخطوة 6: اربط LLM الخاص بك
أسهل طريقة لمنح LLM الخاص بك الوصول إلى Synapse هي عبر MCP:
- إعداد Claude Desktop — إعداد بدقيقتين
- إعداد Claude Code — تكامل الـ terminal
- إعداد Cursor — تكامل IDE
بعد الإعداد، سيستدعي LLM الخاص بك  تلقائيًا في بداية
كل جلسة ويحفظ الحقائق الجديدة عبر .
فئات الذاكرة
يدعم Synapse 8 فئات — اختر الأكثر تحديدًا:
| الفئة | حالة الاستخدام |
|----------|----------|
|  | اسم المستخدم، الدور، معلومات الاتصال |
|  | الإعجابات، عدم الإعجابات، أسلوب العمل |
|  | حقائق قابلة للتحقق (تفاصيل المشروع، التواريخ) |
|  | حالة المشروع، المعالم، المهام |
|  | ما يبرع فيه المستخدم |
|  | أخطاء سابقة — تجنب تكرارها |
|  | سياق ذو صلة بالجلسة |
|  | ملاحظات متفرقة |
مستويات الأولوية
-  — جيد معرفته
-  — افتراضي
-  — مهم
-  — يجب ألا يُنسى أبدًا (هوية المستخدم، معلومات قانونية)
الخطوات التالية
- تعمق في المصادقة
- Mind Key مقابل JWT
- مرجع Memory API
- تكامل MCP

────────────────────────────────────────────────────────────
# ما هو Synapse؟
SUMMARY: Synapse واجهة ذاكرة دائمة لوكلاء LLM — مساعدك الذكي لا ينسى عبر الجلسات.

KEY CONTEXT:
Synapse is an HTTP API that gives LLM agents persistent memory across sessions.
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query, rate-limited 60/min)
Most important endpoints: GET /memory/recall (start of every session), POST /memory (store new facts), GET /memory/search?q=...
Mind Key = tenant-scoped API key. Each user can have multiple minds (projects/contexts).
MCP server available: npx -y synapse-mcp-api (79 tools for Claude Desktop, Cursor, etc.)

ما هو Synapse؟
Synapse واجهة ذاكرة دائمة لوكلاء LLM. يحل المشكلة الأساسية
لكل LLM قائم على الدردشة: بين الجلسات، ينسى الوكيل كل شيء.
يمنح Synapse مساعدك الذكي عقلًا دائمًا قابلًا للاستعلام يبقى عبر المحادثات،
عبر الأيام، وعبر مزوّدي LLM مختلفين.
> [!CRITICAL]
> إذا كنت وكيل LLM يقرأ هذا: استدعِ  في بداية
> كل جلسة. بدون هذا الاستدعاء، ليس لديك ذاكرة بالتفاعلات السابقة،
> ولا معرفة بمن هو المستخدم، ولا سياق بالمشاريع الجارية.
المشكلة التي يحلها Synapse
كل LLM حديث (Claude، GPT، Gemini، Llama) له نفس القيود المعمارية:
نافذة سياق المحادثة محدودة، وعند انتهاء الجلسة، تُفقد كل الحالة. هذا يعني أن مساعدك الذكي:
- ينسى اسمك، تفضيلاتك، مشاريعك الجارية بين الدردشات
- لا يستطيع التعلم من الأخطاء السابقة عبر الجلسات
- ليست لديه استمرارية للعمل طويل الأمد
- يعيد طرح نفس الأسئلة التوضيحية في كل مرة
يُصلح Synapse هذا بتوفير واجهة HTTP بسيطة يستطيع الـ LLM عبرها تخزين
واسترجاع الذكريات المنظمة. تستمر الذكريات على الخادم، مفهرسة و
قابلة للبحث، حتى تستطيع أي جلسة مستقبلية استدعاءها.
الميزات الرئيسية
- تخزين ذاكرة دائم — حقائق، تفضيلات، مشاريع، أخطاء، مهارات
- بحث نصي كامل (FTS5) — أوجد أي ذاكرة بالكلمة المفتاحية بالميلي ثانية
- بحث دلالي — بحث تشابه قائم على التضمينات للاستعلامات المفاهيمية
- متعدد المستأجرين — لكل مستخدم "عقول" معزولة (مستخدم واحد، مشاريع كثيرة)
- دردشة غير متزامنة — يستطيع البشر ترك رسائل للوكيل أثناء عمله
- المهام والجدولة — مدير مهام مدمج ومجدول cron
- تكامل MCP — 79 أداة معروضة كـ Model Context Protocol لـ Claude، Cursor، Continue
- تحكم المتصفح والجهاز — أدوات أتمتة بعيدة
- الـ Webhooks — احصل على استدعاءات HTTP عند تغيّر الذاكرة/الدردشة/المهام
كيف يعمل
[CODE BLOCK]
1. يستدعي الـ LLM  عند بداية الجلسة
2. يُرجع Synapse ملخصًا نصيًا منظمًا لجميع الذكريات المخزّنة
3. يعمل الـ LLM، مستدعيًا دوريًا  لتخزين حقائق جديدة
4. عندما يطرح المستخدم سؤالًا، يستطيع الـ LLM استدعاء 
5. عند نهاية الجلسة، يُحفظ السياق الجديد المهم للجلسة التالية
لمن؟
- مطوّرو وكلاء LLM الذين يحتاجون حالة دائمة
- المستخدمون المتقدمون الذين يشغّلون نماذج LLM محلية (Ollama، LM Studio) بوكلاء مخصصين
- الفرق التي تبني مساعدين ذكيين يحتاجون ذاكرة مشتركة
- مهندسو الأتمتة الذين يربطون استدعاءات LLM عبر الجلسات
مقارنة سريعة
| الميزة | ذاكرة ChatGPT | Synapse |
|---------|---------------|---------|
| موقع التخزين | خوادم OpenAI | خادمك |
| وصول الـ API | لا (مغلق) | نعم (REST + MCP) |
| متعدد المستأجرين | لا | نعم (العقول) |
| فئات مخصصة | لا | نعم (8 فئات) |
| البحث | محدود | FTS5 + دلالي |
| قابل للاستضافة الذاتية | لا | نعم (Docker) |
الخطوات التالية
- البداية السريعة للبشر — احصل على Mind Key في 5 دقائق
- البداية السريعة لـ LLMs — أول استدعاءات API
- المصادقة — Mind Keys مقابل JWTs
- نظرة عامة على البنية — كيف بُني Synapse

## الفئة: مرجع واجهة البرمجة
مرجع كامل لجميع نقاط نهاية واجهة البرمجة.

────────────────────────────────────────────────────────────
# وكيل المتصفح
SUMMARY: خدمة أتمتة المتصفح — حاوية Docker منفصلة على المنفذ 13000 للتحكم في متصفح headless.

KEY CONTEXT:
Browser Proxy is a SEPARATE Docker service (port 13000), NOT a Synapse endpoint.
Synapse endpoints do NOT include /browser/* paths.
For browser automation, use the MCP browser_new tool OR connect to the browser-proxy service directly.
Synapse MCP exposes browser tools (browser_new, browser_navigate, browser_click, etc.)

وكيل المتصفح
وكيل المتصفح هو خدمة Docker منفصلة تُوفّر أتمتة متصفح headless عبر
Playwright. وهو ليس جزءًا من Synapse API مباشرةً — لا تتضمن نقاط نهاية
Synapse مسارات .
البنية
[CODE BLOCK]
طرق الوصول
الطريقة 1: عبر خادم Synapse MCP (موصى بها)
يُعرض وكيل المتصفح عبر خادم Synapse MCP كأدوات MCP. استخدم هذا الخيار
لأتمتة المتصفح المدفوعة بنماذج LLM:
[CODE BLOCK]
أدوات متصفح MCP المتاحة:
-  — فتح علامة تبويب متصفح جديدة
-  — الانتقال إلى عنوان URL
-  — النقر على عنصر
-  — كتابة نص في حقل
-  — التقاط لقطة شاشة
-  — إغلاق علامة التبويب
- (والمزيد — راجع تكامل MCP)
الطريقة 2: الوصول المباشر لوكيل المتصفح
للتكاملات التي لا تستخدم MCP، اتصل مباشرة بخدمة وكيل المتصفح:
[CODE BLOCK]
حالات الاستخدام الشائعة
استخراج بيانات الويب
[CODE BLOCK]
أتمتة النماذج
[CODE BLOCK]
التقاط لقطات الشاشة
[CODE BLOCK]
الخدمات ذات الصلة
| الخدمة | المنفذ | الغرض |
|---------|------|---------|
| Synapse API | 12800 | الذاكرة، الدردشة، المهام |
| Synapse MCP | 13100 | خادم MCP (79 أداة) |
| وكيل المتصفح | 13000 | أتمتة متصفح headless |
| وكيل SSH | 12900 | وصول SSH إلى الأجهزة البعيدة |
الخطوات التالية
- تكامل MCP — كيفية استخدام أدوات المتصفح عبر MCP
- Computer Control API — لأتمتة الواجهة الرسومية على الأجهزة المسجّلة

────────────────────────────────────────────────────────────
# Chat API
SUMMARY: دردشة غير متزامنة بين البشر ووكلاء LLM — الاستطلاع، الرد، السجل، عدد الرسائل غير المقروءة، رفع الملفات.

KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions

Chat API
تُمكّن Chat API المراسلة غير المتزامنة بين البشر ووكلاء LLM. على عكس الدردشة
المتزامنة (بنمط ChatGPT)، يمكن للإنسان ترك رسائل بينما يعمل الوكيل — يستطلع
الوكيل بين استدعاءات الأدوات.
كيفية العمل
[CODE BLOCK]
1. يُرسل الإنسان رسالة عبر واجهة الويب (يستخدم JWT)
2. تُخزّن الرسالة وتُعلّم كغير مقروءة
3. يستطلع الوكيل عبر  بين استدعاءات الأدوات
4. يُرجع الاستطلاع جميع الرسائل غير المقروءة ويُعلّمها كمقروءة
5. يعالج الوكيل الرسالة، ويرد اختياريًا عبر 
نقاط النهاية
GET /chat/poll
الاستطلاع للرسائل الجديدة من الإنسان. يُرجع الرسائل غير المقروءة ويُعلّمها
كمقروءة. استخدم هذا بين استدعاءات الأدوات.
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
POST /chat/reply
إرسال رسالة باعتبارك الوكيل.
[CODE BLOCK]
POST /chat/send
إرسال رسالة باعتبارك الإنسان (يتطلب JWT، وليس Mind Key).
[CODE BLOCK]
GET /chat/history
الحصول على سجل الدردشة الأخير (كلا الطرفين).
[CODE BLOCK]
GET /chat/unread
الحصول على عدد الرسائل غير المقروءة.
[CODE BLOCK]
GET /chat/status
الحصول على حالة جلسة الدردشة (طوابع زمنية لآخر رسالة، عدد الرسائل غير المقروءة).
[CODE BLOCK]
POST /chat/upload
رفع مرفق ملف لرسالة محددة (نموذج multipart).
[CODE BLOCK]
GET /chat/files/:messageid
قائمة مرفقات الملفات لرسالة.
[CODE BLOCK]
GET /chat/file/:fileid
تنزيل مرفق ملف.
[CODE BLOCK]
نمط الاستطلاع
> [!TIP]
> استطلع كل 30-60 ثانية بين استدعاءات الأدوات. لا تستطلع بشكل أكثر تكرارًا —
> فهذا يهدر حصة الـ API ولا يقدم أي فائدة.
[CODE BLOCK]
الخطوات التالية
- Tasks API
- نمط استطلاع الدردشة

────────────────────────────────────────────────────────────
# Computer Control API
SUMMARY: تحكم بعيد بالأجهزة المسجّلة — إدراج الأوامر في الطابور، التقاط لقطات الشاشة، تشغيل سكربتات على الأجهزة البعيدة.

KEY CONTEXT:
Two sides: user-facing (Mind Key/JWT) and agent-facing (Computer Token)
Register agent: POST /computers/register { install_code } → returns computer_token
List: GET /computers/list (Mind Key or JWT)
Queue command: POST /computers/:id/commands { type, payload }
Command types: screenshot, click, move, type, key, scroll, drag
Agent poll: GET /computers/me/poll?wait=5 (Computer Token)
Agent result: POST /computers/me/commands/:cid/result (Computer Token)
One-shot screenshot: GET /computers/:id/screenshot (waits 30s for result)
Pattern: register agent on remote machine → user queues commands → agent polls and executes

Computer Control API
تتيح لك Computer Control API التحكم عن بُعد بالأجهزة المسجّلة. يعمل وكيل
صغير () على الجهاز الهدف، يستطلع للأوامر، ينفّذها،
ويُعيد نشر النتائج. هذا يُمكّن أتمتة الواجهة الرسومية المدفوعة بنماذج LLM.
البنية
[CODE BLOCK]
نقاط نهاية المستخدم (Mind Key أو JWT)
GET /computers/list
قائمة بجميع الأجهزة المسجّلة.
[CODE BLOCK]
GET /computers/:id
الحصول على تفاصيل جهاز واحد.
[CODE BLOCK]
POST /computers/install-code
توليد رمز تثبيت لتسجيل جهاز جديد.
[CODE BLOCK]
الاستجابة: 
POST /computers/:id/commands
إدراج أمر في الطابور لينفّذه الوكيل البعيد.
[CODE BLOCK]
الاستجابة: 
GET /computers/:id/command (عبر الاستعلام)
إدراج أمر عبر GET (للحالات البسيطة).
[CODE BLOCK]
GET /computers/:id/commands
قائمة الأوامر الأخيرة لجهاز.
[CODE BLOCK]
GET /computers/:id/commands/:cid
الحصول على الحالة + النتيجة لأمر محدد.
[CODE BLOCK]
GET /computers/:id/screenshot
أحادي الخطوة: إدراج أمر لقطة شاشة والانتظار حتى 30 ثانية للنتيجة.
[CODE BLOCK]
POST /computers/:id/disable
تعطيل جهاز (يُبطل رمزه، ويُبقي السجل للتدقيق).
[CODE BLOCK]
DELETE /computers/:id
حذف جهاز نهائيًا.
[CODE BLOCK]
نقاط نهاية الوكيل (Computer Token)
تُستخدم هذه النقاط من قبل  الذي يعمل على الجهاز الهدف.
تستخدم Computer Token (يُرجعها )، وليس Mind Key.
POST /computers/register
استرداد رمز تثبيت والحصول على Computer Token.
[CODE BLOCK]
الاستجابة: 
> [!CRITICAL]
> احفظ  — يُعرض مرة واحدة فقط ومطلوب لجميع نقاط نهاية
> الوكيل.
GET /computers/me/poll
استطلاع طويل للأوامر الجديدة. يستدعي الوكيل هذا في حلقة.
[CODE BLOCK]
يُرجع فورًا إذا كانت هناك أوامر معلّقة، أو بعد  ثانية إن لم تكن.
POST /computers/me/commands/:cid/result
نشر نتيجة تنفيذ أمر.
[CODE BLOCK]
أنواع الأوامر
| النوع | الحمولة | الوصف |
|------|---------|-------------|
|  |  | التقاط الشاشة كـ PNG (base64) |
|  |  | النقر عند الإحداثيات |
|  |  | تحريك الماوس إلى الإحداثيات |
|  |  | كتابة نص عند المؤشر |
|  |  | ضغط مجموعة مفاتيح |
|  |  | تمرير العجلة |
|  |  | سحب وإفلات |
النمط الشائع: أتمتة الواجهة الرسومية المدفوعة بـ LLM
[CODE BLOCK]
الخطوات التالية
- وكيل المتصفح — خدمة منفصلة لأتمتة المتصفح
- دليل الوكلاء المستضافين ذاتيًا

────────────────────────────────────────────────────────────
# Cron والمجدول
SUMMARY: جدولة استدعاءات API المتكررة — مهام cron تعمل وفق جدول، مثالية للمزامنة الدورية والتذكيرات.

KEY CONTEXT:
Auth: Mind Key
Create: POST /cron { schedule, endpoint, method?, body?, headers?, enabled? }
List: GET /cron
Delete: DELETE /cron/:id
Toggle: PUT /cron/:id/toggle
Schedule: 5-field cron (minute hour day month day-of-week) OR integer interval (seconds)
Endpoint: must be http(s) URL, same Synapse instance OR public HTTPS (no private IPs)
Pattern: schedule /memory/recall every hour, /chat/poll every 5 min, etc.

Cron والمجدول
تتيح لك Cron API جدولة استدعاءات HTTP متكررة لنقاط نهاية Synapse (أو
نقاط نهاية HTTPS خارجية). مثالية للمزامنة الدورية والتذكيرات ومهام الصيانة.
نقاط النهاية
POST /cron
إنشاء مهمة مجدولة.
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
GET /cron
قائمة بجميع المهام المجدولة.
[CODE BLOCK]
DELETE /cron/:id
حذف مهمة مجدولة.
[CODE BLOCK]
PUT /cron/:id/toggle
تمكين أو تعطيل مهمة دون حذفها.
[CODE BLOCK]
صيغة الجدولة
Cron القياسي (5 حقول)
[CODE BLOCK]
أمثلة:
| الجدول | المعنى |
|----------|---------|
|  | كل ساعة |
|  | كل 15 دقيقة |
|  | أيام الأسبوع الساعة 9 صباحًا |
|  | كل أحد منتصف الليل |
|  | أول كل شهر منتصف الليل |
فترة زمنية صحيحة (ثوانٍ)
للفترات البسيطة، مرّر عددًا صحيحًا:
[CODE BLOCK]
قيود نقطة النهاية
> [!WARNING]
> يجب أن تكون نقاط النهاية عناوين URL تبدأ بـ  أو  تشير إلى:
> - نفس نسخة Synapse (مثل )
> - عناوين URL HTTPS عامة (لا عناوين IP خاصة، لا localhost، لا عناوين IP للبيانات الوصفية)
هذا يمنع هجمات SSRF حيث يمكن لعقل مخترق جدولة طلبات إلى
خدمات داخلية.
الأنماط الشائعة
استدعاء الذاكرة كل ساعة (لوكلاء LLM)
[CODE BLOCK]
نسخ احتياطي يومي
[CODE BLOCK]
استطلاع الدردشة الدوري (كل 5 دقائق)
[CODE BLOCK]
مُحفّز التقرير الأسبوعي
[CODE BLOCK]
الخطوات التالية
- Variables API
- Webhooks API

────────────────────────────────────────────────────────────
# الأخطاء ومعالجتها
SUMMARY: رموز حالة HTTP وتنسيق استجابة الخطأ وكيفية التعافي من الأخطاء الشائعة.

KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.

الأخطاء ومعالجتها
يستخدم Synapse رموز حالة HTTP القياسية مع تنسيق استجابة خطأ متسق.
تشرح هذه الصفحة كيفية تفسير الأخطاء والتعافي منها.
تنسيق استجابة الخطأ
تُرجع جميع الأخطاء JSON بهذا الهيكل:
[CODE BLOCK]
| الحقل | الوصف |
|-------|-------------|
|  | رمز حالة HTTP |
|  | اسم حالة HTTP |
|  | وصف خطأ قابل للقراءة البشرية |
|  | URL للوثائق ذات الصلة (عند الاقتضاء) |
رموز حالة HTTP
200 OK
نجاح. تمت معالجة الطلب بشكل صحيح.
201 Created
نجاح. تم إنشاء مورد جديد (مثل ).
204 No Content
نجاح. لم يُرجع نصًا (مثل ).
400 Bad Request
كان الطلب غير صالح. الأسباب الشائعة:
- حقول JSON مطلوبة مفقودة
- صياغة JSON غير صالحة
- قيمة enum غير صالحة (مثل فئة خاطئة)
[CODE BLOCK]
الإصلاح: تحقق من نص الطلب مقابل وثائق API. تأكد من وجود جميع الحقول
المطلوبة بقيم صالحة.
401 Unauthorized
فشلت المصادقة. الأسباب الشائعة:
- ترويسة  مفقودة
- Mind Key أو JWT غير صالح
- استخدام Mind Key حيث يُطلب JWT (أو العكس)
[CODE BLOCK]
الإصلاح: تحقق من رمزك. راجع المصادقة.
403 Forbidden
أنت مُصادق لكن غير مسموح لك بأداء هذا الإجراء. الأسباب الشائعة:
- محاولة حذف عقل مستخدم آخر
- محاولة التحقق من ذاكرة باستخدام Mind Key (يتطلب JWT)
- العقل معطّل
الإصلاح: تحقق مما كنت تستخدم نوع الرمز الصحيح لنقطة النهاية هذه.
404 Not Found
المسار أو المورد المطلوب غير موجود.
> [!CRITICAL]
> لا تخمّن مسارات نقاط النهاية. فقط المسارات المذكورة في 
> موجودة. إذا حصلت على 404، فقد استخدمت مسارًا خاطئًا.
[CODE BLOCK]
الإصلاح: استدعِ  لرؤية قائمة نقاط النهاية الصالحة. قارن
عنوان URL الخاص بك بالقائمة حرفًا بحرف.
409 Conflict
يتعارض الطلب مع الحالة الحالية. الأسباب الشائعة:
- محاولة التسجيل ببريد إلكتروني موجود مسبقًا
- URL مكرر لـ webhook
الإصلاح: استخدم قيمة مختلفة، أو استخدم  لتحديث المورد الموجود.
429 Too Many Requests
بلغت حد المعدل. ينطبق فقط على مصادقة معامل الاستعلام  (60/دقيقة).
[CODE BLOCK]
ترويسات الاستجابة:
[CODE BLOCK]
الإصلاح: بدّل إلى ترويسة  (بلا حد معدل)، أو انتظر
عدد ثواني .
500 Internal Server Error
خطأ في الخادم. لا ينبغي حدوث ذلك — وإذا حدث، فهو خطأ برمجي.
الإصلاح:
1. أعد المحاولة مع تراجع أُسي (1 ث، 2 ث، 4 ث، 8 ث)
2. تحقق من  لمعرفة ما إذا كان الخادم يعمل
3. إذا استمر، أبلغ عن الخطأ
503 Service Unavailable
الخادم متوقف مؤقتًا (مثل أثناء النشر أو ترحيل قاعدة البيانات).
الإصلاح: انتظر وأعد المحاولة. تحقق من .
أنماط التعافي
إعادة المحاولة مع تراجع أُسي
[CODE BLOCK]
معالجة خطأ المصادقة
[CODE BLOCK]
سيناريوهات الأخطاء الشائعة
"Mind Key fehlt oder ungültig"
- نسيت ترويسة 
- استخدمت  لكن الرمز خاطئ
- تستخدم JWT حيث يُطلب Mind Key
"Route not found"
- خمّنت مسارًا غير موجود
- استخدمت فعلًا خاطئًا (مثل  مقابل )
- تحقق من  للمسارات الصالحة
"Rate limit exceeded"
- تستخدم  وتجاوزت 60 طلبًا/دقيقة
- بدّل إلى ترويسة 
الخطوات التالية
- المصادقة
- نظرة عامة على الـ API
- حدود المعدل

────────────────────────────────────────────────────────────
# Memory API
SUMMARY: مرجع كامل لنقاط نهاية الذاكرة الـ 22: التخزين، الاستدعاء، البحث، البحث الدلالي، المزامنة، التدقيق، والمزيد.

KEY CONTEXT:
Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)
ALWAYS call GET /memory/recall at session start.
POST /memory with same category+key updates the existing memory.
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
Search: GET /memory/search?q=... (FTS5 syntax: AND, OR, "phrases", prefix*)
Semantic: GET /memory/semantic-search?q=... (slower, conceptual)
Sync: GET /memory/diff?since=TIMESTAMP (incremental sync)
Export: GET /memory/mind-export (full JSON dump)

Memory API
Memory API هي قلب Synapse. تُوفّر 22 نقطة نهاية لتخزين واسترجاع وبحث وإدارة
الذكريات المنظمة. تتطلب جميع نقاط النهاية Mind Key للمصادقة.
> [!CRITICAL]
> استدعِ دائمًا  في بداية كل جلسة. هذه هي الطريقة
> الوحيدة لإعادة بناء السياق من الجلسات السابقة.
الفئات
تُنظّم الذكريات في 8 فئات:
| الفئة | حالة الاستخدام |
|----------|----------|
|  | اسم المستخدم، الدور، معلومات الاتصال، تفضيلات حول الذات |
|  | الإعجابات، عدم الإعجابات، أسلوب العمل، تفضيلات التواصل |
|  | حقائق قابلة للتحقق (تفاصيل المشروع، التواريخ، عناوين URL) |
|  | حالة المشروع، المعالم، البنية |
|  | الأشياء التي يبرع فيها المستخدم |
|  | أخطاء سابقة — تجنب تكرارها |
|  | سياق ذو صلة بالجلسة |
|  | ملاحظات متفرقة |
الأولويات
-  — جيد معرفته
-  — افتراضي
-  — مهم
-  — يجب ألا يُنسى أبدًا (هوية المستخدم، معلومات قانونية)
نقاط النهاية الأساسية
GET /memory/recall
يُرجع جميع الذكريات كنص عادي مُحسّن لنماذج LLM. استدعِ هذا عند بداية كل جلسة.
[CODE BLOCK]
الاستجابة (text/plain):
[CODE BLOCK]
POST /memory
تخزين ذاكرة جديدة أو تحديث ذاكرة موجودة (نفس الفئة + المفتاح = تحديث).
[CODE BLOCK]
الاستجابة: 
GET /memory
قائمة الذكريات مع مرشّحات اختيارية.
[CODE BLOCK]
PUT /memory/:id
تحديث ذاكرة محددة بالمعرّف.
[CODE BLOCK]
DELETE /memory/:id
حذف ذاكرة واحدة.
[CODE BLOCK]
نقاط نهاية البحث
GET /memory/search
بحث نصي كامل باستخدام FTS5.
[CODE BLOCK]
صياغة FTS5:
- كلمات متعددة = AND: 
- عبارة: 
- بادئة: 
- منطقي: 
- استبعاد: 
GET /memory/semantic-search
بحث مفاهيمي باستخدام التضمينات (أبطأ من FTS5 لكنه يفهم المعنى).
[CODE BLOCK]
يُرجع ذكريات متشابهة دلاليًا مع الاستعلام، حتى لو لم تتطابق الكلمات
المفتاحية. مفيد لـ "إيجاد ذكريات حول X" حيث يُوصف X بشكل مختلف.
GET /memory/by-tag
قائمة الذكريات حسب الوسم.
[CODE BLOCK]
GET /memory/related/:id
إيجاد ذكريات مرتبطة بذاكرة محددة (عبر الوسوم المشتركة).
[CODE BLOCK]
المزامنة والـ Diff
GET /memory/diff
مزامنة تزايدية — تُرجع الذكريات المتغيّرة منذ طابع زمني.
[CODE BLOCK]
الاستجابة: 
POST /memory/sync
تطبيق diff من نسخة أخرى (للمزامنة المستضافة ذاتيًا).
[CODE BLOCK]
العمليات الكمية
POST /memory/bulk-delete
حذف ذكريات متعددة بالمعرّف.
[CODE BLOCK]
POST /memory/embed-batch
توليد تضمينات للذكريات التي لا تملكها بعد (للبحث الدلالي).
[CODE BLOCK]
GET /memory/embed-batch-status
التحقق من تقدّم توليد التضمينات.
[CODE BLOCK]
التحقق
للذكريات علامة . الذكريات المخزّنة بواسطة الوكيل تكون غير مُتحقّق منها
افتراضيًا ()؛ الذكريات المخزّنة بواسطة الإنسان مُتحقّق منها
().
POST /memory/verify
تعليم ذاكرة كمُتحقّق منها (يتطلب JWT، وليس Mind Key).
[CODE BLOCK]
POST /memory/unverify
تعليم ذاكرة كغير مُتحقّق منها (يتطلب JWT).
[CODE BLOCK]
GET /memory/unverified
قائمة الذكريات بانتظار التحقق البشري.
[CODE BLOCK]
الإحصائيات والتدقيق
GET /memory/stats
إحصائيات تجميعية للعقل الحالي.
[CODE BLOCK]
يُرجع: 
GET /memory/audit
سجل تدقيق لجميع العمليات التي تُغيّر الحالة.
[CODE BLOCK]
GET /memory/contradictions
اكتشاف تناقضات محتملة في الذكريات المخزّنة.
[CODE BLOCK]
GET /memory/expiring
قائمة الذكريات التي تقترب تواريخ انتهائها.
[CODE BLOCK]
الحالة والتصدير
GET /memory/health
فحص حالة سريع لنظام الذاكرة.
[CODE BLOCK]
GET /memory/mind-export
تصدير JSON كامل لجميع الذكريات (للنسخ الاحتياطي).
[CODE BLOCK]
POST /memory/compact
ضغط الذكريات المتشابهة (تلخيص تلقائي).
[CODE BLOCK]
الخطوات التالية
- البداية السريعة لـ LLMs
- أفضل ممارسات الذاكرة
- بحث FTS5
- البحث الدلالي

────────────────────────────────────────────────────────────
# نظرة عامة على الـ API وعنوان URL الأساسي
SUMMARY: جميع نقاط نهاية Synapse API وعنوان URL الأساسي وأنماط المصادقة وتنسيقات الاستجابة في لمحة سريعة.

KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
      OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.

نظرة عامة على الـ API وعنوان URL الأساسي
واجهة Synapse API هي واجهة HTTP RESTful. تُرجع جميع نقاط النهاية JSON (إلا في
الحالات المذكورة). تغطي هذه الصفحة الأساسيات التي تحتاجها قبل التعمق في نقاط
النهاية المحددة.
عنوان URL الأساسي
[CODE BLOCK]
جميع المسارات في هذا الدليل نسبية إلى عنوان URL الأساسي. بالنسبة للنسخ
المستضافة ذاتيًا، استبدل العنوان بعنوان URL الخاص بك.
المصادقة
طريقتان، كلاهما يُرسل عبر ترويسة :
[CODE BLOCK]
أو عبر معامل الاستعلام (محدود بـ 60 طلبًا/دقيقة):
[CODE BLOCK]
راجع المصادقة للتفاصيل.
مجموعات نقاط النهاية
| المجموعة | المصادقة | الوصف |
|-------|------|-------------|
| عامة | لا شيء | الصفحة الرئيسية، الحالة، OpenAPI، الوثائق |
| الذاكرة | Mind Key | إنشاء/قراءة/تحديث/حذف، بحث، مزامنة، تضمينات |
| الدردشة | Mind Key / JWT | مراسلة غير متزامنة بين الإنسان والوكيل |
| المهام | Mind Key | إدارة المهام |
| السكربتات | Mind Key / JWT | تخزين دائم للسكربتات |
| المجدول | Mind Key | مهام Cron + المتغيرات |
| الـ Webhooks | Mind Key | استدعاءات HTTP عند الأحداث |
| الأجهزة | Mind Key / JWT | تحكم بعيد في الأجهزة |
| المستخدم/العقول | JWT | الحساب + إدارة العقول |
| المشاركة | JWT | مشاركة العقل بين المستخدمين |
| الإشعارات | JWT | اشتراكات Web Push |
| الأدوات | لا شيء | الوقت، الحاسبة، عشوائي (أدوات عامة) |
تنسيقات الاستجابة
- JSON (افتراضي): 
- نص عادي: يُرجع  نصًا محسّنًا لنماذج LLM
- HTML: ، ، ، ، 
مظروف الاستجابة القياسي
تُرجع استجابات النجاح البيانات مباشرة:
[CODE BLOCK]
استجابات الخطأ تستخدم هذا التنسيق:
[CODE BLOCK]
> [!NOTE]
> يربط الحقل  بالوثائق ذات الصلة للأخطاء الشائعة.
رموز حالة HTTP
| الرمز | المعنى |
|------|---------|
| 200 | نجاح (GET، PUT) |
| 201 | تم الإنشاء (POST) |
| 204 | لا يوجد محتوى (DELETE) |
| 400 | طلب سيئ (خطأ تحقق) |
| 401 | غير مصرّح (رمز مفقود/غير صالح) |
| 403 | محظور (نوع رمز خاطئ) |
| 404 | غير موجود (المسار غير موجود) |
| 409 | تعارض (مكرر) |
| 429 | طلبات كثيرة جدًا (حد المعدل) |
| 500 | خطأ في الخادم |
نقاط نهاية الاكتشاف
| نقطة النهاية | الغرض |
|----------|---------|
|  | الصفحة الرئيسية (مُحسّنة لـ LLM) |
|  | قائمة قابلة للقراءة آليًا بجميع نقاط النهاية |
|  | قائمة نقاط النهاية كنص عادي |
|  | مواصفات OpenAPI 3.0 |
|  | وثائق API الكاملة (HTML) |
|  | وثائق API كـ JSON |
|  | نظام الوثائق (HTML) |
|  | فهرس الوثائق (JSON) |
|  | جميع الوثائق ككتلة نصية واحدة |
|  | ساحة تجريبية تفاعلية للـ API |
حدود المعدل
| طريقة المصادقة | الحد |
|-------------|-------|
| Mind Key (ترويسة) | لا يوجد |
| Mind Key (?key=) | 60/دقيقة لكل IP |
| JWT (ترويسة) | لا يوجد |
| نقاط النهاية العامة | لا يوجد |
تتضمن الاستجابات الخاضعة لحد المعدل:
[CODE BLOCK]
التصفح
نقاط نهاية القوائم تدعم  و :
[CODE BLOCK]
الحد الافتراضي: 100. الحد الأقصى: 500.
CORS
جميع نقاط النهاية تدعم CORS لعملاء المتصفح:
[CODE BLOCK]
حزم SDK والعملاء
- Node.js SDK:  (المستودع)
- خادم MCP:  (المستودع)
- عميل HTTP: أي مكتبة HTTP (curl، fetch، axios، إلخ)
الخطوات التالية
- Memory API — أهم نقاط النهاية
- Chat API — تواصل غير متزامن بين الإنسان والوكيل
- الأخطاء ومعالجتها

────────────────────────────────────────────────────────────
# حدود المعدل والحصص
SUMMARY: سياسة حدود المعدل لواجهة Synapse API — ترويسة Bearer (غير محدودة)، ?key= (60/دقيقة)، نقاط النهاية العامة.

KEY CONTEXT:
Mind Key (Authorization: Bearer header) → NO rate limit
Mind Key (?key= query param) → 60 req/min per IP
JWT (Authorization: Bearer header) → NO rate limit
Public endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
Recommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.

حدود المعدل والحصص
يملك Synapse سياسة حدود معدل بسيطة وقابلة للتنبؤ مصممة لمنع إساءة الاستخدام
دون أن تعيق الاستخدام المشروع.
سياسة حد المعدل
| طريقة المصادقة | الحد | النطاق |
|-------------|-------|-------|
| Mind Key () | لا يوجد | لكل عقل |
| Mind Key () | 60 طلبًا/دقيقة | لكل IP |
| JWT () | لا يوجد | لكل مستخدم |
| نقاط النهاية العامة | لا يوجد | عام |
> [!TIP]
> استخدم دائمًا ترويسة  عندما يكون ذلك ممكنًا. ليس
> لها حد معدل. استخدم  فقط للأدوات التي لا تستطيع تعيين ترويسات مخصصة.
ترويسات حد المعدل
عند استخدام مصادقة ، تتضمن الاستجابات ترويسات حد المعدل:
[CODE BLOCK]
عند تجاوز الحد:
[CODE BLOCK]
عند بلوغ حد المعدل
إذا حصلت على 429:
1. بدّل إلى ترويسة Authorization (موصى به):
   [CODE BLOCK]
2. أو انتظر  ثانية وأعد المحاولة.
لماذا يوجد حد 
معامل الاستعلام  مريح للأدوات التي تفتح عناوين URL فقط (المتصفحات،
أوامر )، لكن له آثارًا أمنية وأدائية:
- الأمان: تُسجّل معاملات الاستعلام في سجلات الوصول للخادم، وبيانات
  المتصفح، وترويسات Referer. تحديد الاستخدام يقلل من التعرض.
- الأداء: تتطلب مصادقة معامل الاستعلام مُحدّد معدل قائم على IP
  (بحث Redis لكل طلب)، مما يضيف زمن استجابة. مصادقة الترويسة تتجاوز هذا.
- منع الإساءة: يمكن مشاركة عنوان URL  المُسرّب وقصفه بالطلبات.
  يُحجم حد IP دائرة الضرر.
الأنماط الموصى بها
وكلاء LLM
[CODE BLOCK]
أدوات المتصفح
إذا كانت أداتك تفتح عناوين URL فقط:
[CODE BLOCK]
خادم MCP
خوادم MCP تستخدم دائمًا مصادقة الترويسة عبر متغير البيئة 
— لا ينطبق حد معدل.
الاستيراد الكمي
للعمليات الكمية (مثل استيراد 1000 ذاكرة)، استخدم دائمًا مصادقة الترويسة.
الاستيراد الكمي عبر  سيبلغ حد المعدل خلال دقيقة واحدة.
الحصص (على مستوى العقل)
لا توجد حاليًا حصص على مستوى العقل لحجم التخزين أو عدد الذكريات. جميع
الحدود على مستوى المصادقة/IP، وليس على مستوى البيانات. قد يتغير ذلك
مستقبلًا لضمان العدالة في البيئات متعددة المستأجرين.
مراقبة الاستخدام
[CODE BLOCK]
الخطوات التالية
- المصادقة
- الأخطاء ومعالجتها

────────────────────────────────────────────────────────────
# Scripts API
SUMMARY: تخزين دائم للسكربتات — احفظ سكربتات shell أو Python أو Node القابلة لإعادة الاستخدام وجلبها عبر curl | bash.

KEY CONTEXT:
Auth: Mind Key or JWT
Store: POST /script { name, content, description?, language? }
Fetch as text: GET /script/:name (returns text/plain, curl | bash ready)
Info: GET /script/:name/info (metadata without content)
List: GET /scripts (JSON array)
Delete: DELETE /script/:name
Use case: store deployment scripts, config generators, troubleshooting snippets

Scripts API
تُوفّر Scripts API تخزينًا دائمًا للسكربتات القابلة لإعادة الاستخدام. تُسمّى
السكربتات وتُنسب إصداراتها داخل عقل، ويمكن جلبها كنص عادي — مثالية لأنماط
.
نقاط النهاية
POST /script
تخزين سكربت أو تحديثه.
[CODE BLOCK]
GET /script/:name
جلب محتوى السكربت كـ . مثالي للتمرير إلى bash.
[CODE BLOCK]
GET /script/:name/info
الحصول على بيانات السكربت الوصفية دون المحتوى.
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
GET /scripts
قائمة بجميع السكربتات في العقل الحالي.
[CODE BLOCK]
DELETE /script/:name
حذف سكربت.
[CODE BLOCK]
حالات الاستخدام الشائعة
سكربتات النشر
خزّن إجراءات النشر القياسية حتى يتمكن LLM من تشغيلها دون إعادة اشتقاق
الخطوات في كل مرة:
[CODE BLOCK]
مقتطفات استكشاف الأخطاء
خزّن أوامر التشخيص للمشكلات الشائعة:
[CODE BLOCK]
مولّدات الإعدادات
خزّن سكربتات تُولّد الإعدادات:
[CODE BLOCK]
الخطوات التالية
- Variables API
- Cron والمجدول

────────────────────────────────────────────────────────────
# Tasks API
SUMMARY: إدارة المهام لوكلاء LLM — إنشاء، قائمة، تحديث، إكمال، حذف المهام بأولويات.

KEY CONTEXT:
Auth: Mind Key
List: GET /mind/tasks?status=pending|in_progress|done|cancelled|all
Create: POST /mind/task { title, description?, priority?, due_at? }
Update: PUT /mind/task/:id { title?, description?, priority?, status?, due_at? }
Complete: GET /mind/task/:id/complete
Delete: GET /mind/task/:id/delete
Priorities: low, normal, high, critical
Statuses: pending, in_progress, done, cancelled
Pattern: create tasks for multi-step work, update status as you progress

Tasks API
تُعطي Tasks API لوكلاء LLM طريقة منظمة لتتبّع العمل متعدد الخطوات.
تكون المهام محدودة بالعقل الحالي وتستمر عبر الجلسات، حتى يتمكن الوكيل من
استئناف العمل من حيث توقف.
نقاط النهاية
GET /mind/tasks
قائمة بجميع المهام للعقل الحالي.
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
POST /mind/task
إنشاء مهمة جديدة.
[CODE BLOCK]
GET /mind/task (معاملات الاستعلام)
إنشاء مهمة عبر GET (للأدوات التي تفتح عناوين URL فقط).
[CODE BLOCK]
PUT /mind/task/:id
تحديث مهمة موجودة.
[CODE BLOCK]
GET /mind/task/:id/complete
تعليم مهمة كمنجزة.
[CODE BLOCK]
GET /mind/task/:id/delete
حذف مهمة نهائيًا.
[CODE BLOCK]
الأولويات
-  — غير عاجل
-  — افتراضي
-  — مهم
-  — يجب فعله فورًا
الحالات
-  — أُنشئت، لم تبدأ
-  — يجري العمل عليها حاليًا
-  — مكتملة
-  — متروكة
النمط: سير عمل مدفوع بالمهام
[CODE BLOCK]
الخطوات التالية
- سير عمل مدفوع بالمهام
- Cron والمجدول

────────────────────────────────────────────────────────────
# الأدوات المساعدة (الوقت، الحاسبة، عشوائي)
SUMMARY: نقاط نهاية الأدوات العامة — وقت الخادم، حاسبة آمنة، مولّد قيم عشوائية. لا تتطلب مصادقة.

KEY CONTEXT:
No auth required for any /tools/* endpoint.
GET /tools/time → { time, timezone, offset }
GET /tools/calc?expr=(10+5)*3 → { result, expr } (safe, no eval, arithmetic only)
GET /tools/random?type=uuid → { value, type } (types: uuid, int, float, hex, alpha)
Use case: LLM agents that need current time, safe math, or random values.

الأدوات المساعدة
نقاط النهاية  أدوات عامة — لا تتطلب مصادقة.
مفيدة لوكلاء LLM الذين يحتاجون وقتًا من جانب الخادم، أو حسابات آمنة، أو قيمًا
عشوائية.
GET /tools/time
الحصول على وقت الخادم الحالي، والمنطقة الزمنية، وإزاحة UTC.
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
حالة الاستخدام: وكلاء LLM الذين يحتاجون معرفة "كم الساعة الآن" للجدولة،
أو الطوابع الزمنية، أو حسابات التاريخ النسبية.
GET /tools/calc
حاسبة آمنة — حسابات حسابية فقط، دون . تدعم ، ، ، ،
، ، ، والأرقام.
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
> [!TIP]
> استخدم هذا بدلاً من محاولة إجراء الحسابات ذهنيًا أو عبر تحليل السلاسل.
> إنه آمن (لا يُمكن حقن كود) ودقيق.
المعاملات المدعومة
-  جمع
-  طرح
-  ضرب
-  قسمة
-  باقي القسمة
-   أقواس
- أرقام (صحيحة وعشرية)
أمثلة
[CODE BLOCK]
GET /tools/random
توليد قيم عشوائية.
[CODE BLOCK]
معاملات النوع
| النوع | المعاملات | المخرجات |
|------|-----------|--------|
|  | لا شيء | سلسلة UUID v4 |
|  | ،  (افتراضي 0-100) | عدد صحيح |
|  | ،  (افتراضي 0-100) | عدد عشري |
|  | ،  (نطاق الطول، افتراضي 8-16) | سلسلة hex |
|  | ،  (نطاق الطول، افتراضي 8-16) | سلسلة أبجدية |
حالات الاستخدام لوكلاء LLM
توليد معرّفات فريدة
[CODE BLOCK]
حساب النسب المئوية
[CODE BLOCK]
الحصول على الطابع الزمني الحالي
[CODE BLOCK]
توليد بيانات اختبار
[CODE BLOCK]
الخطوات التالية
- نظرة عامة على الـ API — جميع مجموعات نقاط النهاية
- الأخطاء ومعالجتها

────────────────────────────────────────────────────────────
# User & Minds API
SUMMARY: إدارة الحساب — التسجيل، تسجيل الدخول، إنشاء العقول، قائمة العقول، حذف العقول. محمية بـ JWT.

KEY CONTEXT:
Auth: JWT (from /register or /login)
Register: POST /register { email, password, display_name? } → returns JWT
Login: POST /login { email, password } → returns JWT
Create mind: POST /minds { name, description? } → returns mind_key (shown once!)
List minds: GET /minds
Delete mind: DELETE /minds/:id (irreversible — deletes all memories!)
JWT expires after 7 days. Mind Key never expires.
Mind Key is shown only once at creation — save it permanently.

User & Minds API
تتولى User & Minds API إدارة الحسابات. تستخدم هذه النقاط مصادقة JWT
(وليس Mind Keys) لأنها تعمل على مستوى الحساب، لا على مستوى العقل.
نقاط نهاية المصادقة
POST /register
إنشاء حساب مستخدم جديد.
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
POST /login
تسجيل الدخول إلى حساب موجود.
[CODE BLOCK]
الاستجابة: مثل .
نقاط نهاية العقول
POST /minds
إنشاء عقل جديد. يُرجع Mind Key — احفظه فورًا، فهو يُعرض مرة واحدة فقط.
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
> [!CRITICAL]
> يُعرض  مرة واحدة فقط. إذا فقدته، لا يمكنك استرداده —
> يجب حذف العقل وإنشاء واحد جديد (مما يفقد جميع الذكريات المخزّنة).
GET /minds
قائمة بجميع العقول للمستخدم الحالي.
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
DELETE /minds/:id
حذف عقل نهائيًا.
[CODE BLOCK]
> [!WARNING]
> حذف العقل لا يمكن التراجع عنه. جميع الذكريات والمهام وسجل الدردشة
> والسكربتات في ذلك العقل تُفقد نهائيًا. صدّر أولًا عبر
>  إذا كنت بحاجة إلى نسخة احتياطية.
نمط العقول المتعددة
يستفيد معظم المستخدمين من عقول متعددة لعزل السياقات:
[CODE BLOCK]
استخدم Mind Keys مختلفة في جلسات LLM مختلفة للحفاظ على عزل السياقات.
أمان الحساب
متطلبات كلمة المرور
- 6 أحرف كحد أدنى
- لا حد أقصى (استخدم مدير كلمات مرور)
- تُخزَّن كـ bcrypt hash (أبدًا كنص صريح)
انتهاء JWT
تنتهي JWTs بعد 7 أيام. عند انتهائها، استدعِ  مرة أخرى.
أمان Mind Key
لا تنتهي Mind Keys أبدًا. إذا تعرّض Mind Key للاختراق:
1. أنشئ عقلًا جديدًا عبر 
2. حدّث إعدادات LLM بـ Mind Key الجديد
3. احذف العقل المخترق عبر 
الخطوات التالية
- المصادقة — دليل المصادقة الكامل
- Mind Key مقابل JWT — دليل القرار
- Sharing API — مشاركة العقول مع مستخدمين آخرين

────────────────────────────────────────────────────────────
# Variables API
SUMMARY: تخزين سريع للقيم الأساسية لحالة LLM — عدّادات، أعلام، طوابع زمنية لآخر مشاهدة، تقدّم جزئي.

KEY CONTEXT:
Auth: Mind Key
Set: POST /var { key, value }
Get: GET /var/:key
List: GET /var
Delete: DELETE /var/:key
Use case: store last-seen timestamps, counters, flags, partial workflow state
Faster than memory (PostgreSQL direct, no FTS5 indexing)
Not for: structured facts (use /memory), long content (use /script)

Variables API
Variables API تخزين سريع للقيم الأساسية للحالة المؤقتة. على عكس
الذكريات (المُفهرَسة والقابلة للبحث والمنظمة)، المتغيرات مُحسّنة
للوصول السريع للقراءة/الكتابة — مثالية للعدّادات والأعلام وحالة
الجلسة.
نقاط النهاية
POST /var
تعيين متغير أو تحديثه.
[CODE BLOCK]
GET /var/:key
الحصول على متغير واحد.
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
GET /var
قائمة بجميع المتغيرات.
[CODE BLOCK]
DELETE /var/:key
حذف متغير.
[CODE BLOCK]
متى تستخدم المتغيرات مقابل الذاكرة
| حالة الاستخدام | استخدم |
|----------|-----|
| اسم المستخدم، التفضيلات | الذاكرة (قابلة للبحث، منظمة) |
| طابع زمني لآخر جلسة | متغير (حالة مؤقتة) |
| عدّاد (مثل الرسائل المُرسلة) | متغير (تحديثات متكررة) |
| حالة سير العمل ("الخطوة 3 من 5 مكتملة") | متغير (عابرة) |
| ملاحظات مشروع طويلة | الذاكرة (مفهرسة بنص كامل) |
| سكربتات قابلة لإعادة الاستخدام | تخزين السكربتات (مُسمّاة، مُصدَّرة) |
الأنماط الشائعة
تتبع آخر جلسة
[CODE BLOCK]
نمط العدّاد
[CODE BLOCK]
أعلام الميزات
[CODE BLOCK]
الخطوات التالية
- Memory API — للبيانات المنظمة القابلة للبحث
- Cron والمجدول

────────────────────────────────────────────────────────────
# Webhooks API
SUMMARY: تسجيل استدعاءات HTTP لأحداث الذاكرة والدردشة والمهمة — احصل على إشعار عند تغيّر البيانات.

KEY CONTEXT:
Auth: Mind Key
Register: POST /webhooks { url, events, secret? }
List: GET /webhooks
Get: GET /webhooks/:id
Update: PUT /webhooks/:id { url?, events?, secret?, enabled? }
Delete: DELETE /webhooks/:id
Events: memory.*, memory.store, memory.update, memory.delete, chat.*, chat.message_received, task.*, task.created, task.completed
Secret: HMAC-SHA256 signed payload, sent in X-Synapse-Signature header
Pattern: register webhook → receive POST → process event → call Synapse API

Webhooks API
تتيح لك الـ Webhooks استقبال استدعاءات HTTP عند وقوع أحداث في Synapse. مثالية
لتشغيل الأتمتة الخارجية أو إرسال الإشعارات أو المزامنة مع أنظمة أخرى.
نقاط النهاية
POST /webhooks
تسجيل webhook جديد.
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
GET /webhooks
قائمة بجميع الـ webhooks للعقل الحالي.
[CODE BLOCK]
GET /webhooks/:id
الحصول على webhook واحد.
[CODE BLOCK]
PUT /webhooks/:id
تحديث webhook (URL، الأحداث، السر، أو علم التمكين).
[CODE BLOCK]
DELETE /webhooks/:id
حذف webhook.
[CODE BLOCK]
أنواع الأحداث
| النمط | يُطلق عندما |
|---------|------------|
|  | أي حدث ذاكرة |
|  | تخزين ذاكرة جديدة |
|  | تحديث ذاكرة |
|  | حذف ذاكرة |
|  | أي حدث دردشة |
|  | رسالة جديدة من الإنسان |
|  | أي حدث مهمة |
|  | إنشاء مهمة جديدة |
|  | تعليم مهمة كمنجزة |
|  | جميع الأحداث |
حمولة الـ Webhook
عند إطلاق حدث، يُرسل Synapse POST إلى عنوان URL الخاص بك:
[CODE BLOCK]
التحقق من التوقيع
إذا عيّنت ، يوقّع Synapse كل حمولة بـ HMAC-SHA256:
[CODE BLOCK]
تحقق في معالجك:
[CODE BLOCK]
النمط: المزامنة اللحظية
[CODE BLOCK]
الخطوات التالية
- Cron والمجدول
- دليل أتمتة الـ Webhooks

## الفئة: تكامل MCP
التكامل مع Claude وCursor وعملاء MCP الآخرين.

────────────────────────────────────────────────────────────
# MCP في Claude Code
SUMMARY: استخدم أدوات Synapse من وكيل Claude Code الطرفي — ذاكرة دائمة لجلسات البرمجة.

KEY CONTEXT:
Claude Code config: ~/.claude/config.json (or via `claude mcp add` command)
Command: npx -y synapse-mcp-api@latest
Env: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional)
Alternative: `claude mcp add synapse -- npx -y synapse-mcp-api@latest`
Then: set SYNAPSE_MIND_KEY env var in your shell
Test: in claude code, type "recall all my memories"

MCP في Claude Code
Claude Code وكيل برمجة طرفي من Anthropic. مع Synapse MCP،
يكتسب Claude Code ذاكرة دائمة عبر جلسات البرمجة — يتذكر
سياق مشروعك، القرارات السابقة، وأنماط قاعدة الكود.
الإعداد
الطريقة 1: أمر CLI (موصى به)
[CODE BLOCK]
الطريقة 2: حرّر ملف الإعداد
حرّر :
[CODE BLOCK]
تحقق أنه يعمل
ابدأ Claude Code:
[CODE BLOCK]
في Claude Code prompt، اكتب:
[CODE BLOCK]
يجب أن يستدعي Claude  ويرد بذكرياتك المخزّنة.
الأنماط الشائعة
استمرارية سياق المشروع
عند بدء جلسة برمجة:
[CODE BLOCK]
يستدعي Claude ، يرى قائمة مشاريعك، ويواصل العمل
من حيث توقفت.
قرارات قاعدة الكود
عند اتخاذ قرار معماري:
[CODE BLOCK]
يستدعي Claude  مع الفئة ، الأولوية .
تجنب الأخطاء السابقة
[CODE BLOCK]
يبحث Claude في الذكريات بالفئة  ويذكّرك بالأخطاء السابقة.
تتبع المهام
[CODE BLOCK]
يستدعي Claude ، وتستمر المهمة عبر الجلسات.
ملفات الأدوات
لجلسات البرمجة التي لا تحتاج جميع الأدوات الـ 119:
[CODE BLOCK]
استكشاف الأخطاء
خادم MCP لا يبدأ
[CODE BLOCK]
Mind Key غير معترف به
[CODE BLOCK]
Claude Code لا يرى الأدوات
- أعد تشغيل Claude Code بعد تغييرات الإعداد
- تحقق من  للتأكد من تسجيل Synapse
- راجع استكشاف أخطاء MCP
الخطوات التالية
- إعداد Claude Desktop
- إعداد Cursor
- دليل وكيل LLM الدائم

────────────────────────────────────────────────────────────
# MCP في Claude Desktop
SUMMARY: اربط Synapse بـ Claude Desktop في دقيقتين. يحصل Claude على 79 أداة Synapse أصليًا.

KEY CONTEXT:
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
             %APPDATA%\Claude\claude_desktop_config.json (Windows)
MCP server command: npx -y synapse-mcp-api@latest
Env vars: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional, default https://synapse.schaefer.zone)
After config: restart Claude Desktop, check for 🔌 icon with "79 tools"
Test: type "memory_recall aufrufen" in a new chat
Troubleshooting: Node.js ≥ 18, check Mind Key, see /docs/mcp/troubleshooting

MCP في Claude Desktop
Claude Desktop تطبيق سطح المكتب من Anthropic لـ macOS و Windows. مع
خادم Synapse MCP مُعدًا، يحصل Claude على وصول أصلي لجميع أدوات Synapse الـ 79 — يستطيع تخزين الذكريات، استدعاؤها، إدارة المهام، الدردشة معك،
والمزيد.
المتطلبات المسبقة
- تطبيق Claude Desktop (macOS أو Windows)
- Node.js 18+ مثبت ()
- Mind Key الخاص بـ Synapse
الخطوة 1: افتح ملف الإعداد
- macOS: 
- Windows: 
إذا لم يوجد الملف، أنشئه.
الخطوة 2: أضف خادم Synapse MCP
[CODE BLOCK]
> [!TIP]
> إذا كان لديك خوادم MCP أخرى مُعدة بالفعل، فقط أضف الكتلة 
> داخل كائن  الموجود.
الخطوة 3: أعد تشغيل Claude Desktop
1. أغلق Claude Desktop بالكامل (Cmd+Q على macOS، ليس مجرد إغلاق النافذة)
2. أعد فتح Claude Desktop
3. ابدأ دردشة جديدة
4. ابحث عن أيقونة القابس 🔌 في أسفل اليسار — يجب أن تقول "79 tools"
الخطوة 4: اختبره
في دردشة جديدة، اكتب:
[CODE BLOCK]
يجب أن يستدعي Claude أداة  ويرد بملخص لـ
ذكرياتك المخزّنة (أو "No memories yet" إذا كان عقلك فارغًا).
الأدوات المتاحة (مختارة)
| الأداة | الوصف |
|------|-------------|
|  | استدعِ جميع الذكريات |
|  | خزّن ذاكرة جديدة |
|  | ابحث في الذكريات |
|  | سرد المهام |
|  | أنشئ مهمة |
|  | تحقق من رسائل جديدة |
|  | ارد على رسالة |
|  | افتح علامة متصفح |
|  | سرد الأجهزة المسجّلة |
القائمة الكاملة: ما هو MCP؟
استكشاف الأخطاء
لا تظهر أدوات في Claude Desktop
1. تحقق من إصدار Node.js:  (يجب ≥ 18)
2. تحقق أن ملف الإعداد JSON صالح (بلا فواصل لاحقة)
3. أعد تشغيل Claude Desktop بالكامل (Cmd+Q، ليس مجرد إغلاق)
4. تحقق من سجلات Claude Desktop:  (macOS)
خطأ "Mind Key invalid"
- تحقق أن  يبدأ بـ 
- احصل على مفتاح جديد عبر  (يتطلب JWT من )
- لا علامات اقتباس حول المفتاح في JSON
npx غير موجود
- ثبّت Node.js 18+: <https://nodejs.org/>
- أعد تشغيل الـ terminal بعد التثبيت
- على macOS مع Homebrew: 
الأدوات تظهر لكن الاستدعاءات تفشل
- تحقق أن  قابل للوصول: 
- تحقق أن Mind Key يعمل: 
- راجع استكشاف أخطاء MCP
ملفات الأدوات (وفّر الرموز)
إذا كنت تستخدم LLM أصغر أو تريد حفظ رموز السياق، عيّن ملف أداة:
[CODE BLOCK]
الملفات:  (8 أدوات)،  (25)،  (119، افتراضي).
الخطوات التالية
- إعداد Claude Code
- إعداد Cursor
- استكشاف أخطاء MCP

────────────────────────────────────────────────────────────
# MCP في Continue.dev
SUMMARY: اربط Synapse بـ Continue.dev — مساعد برمجة ذكي مفتوح المصدر لـ VS Code و JetBrains.

MCP في Continue.dev
Continue.dev مساعد برمجة ذكي مفتوح المصدر لـ VS Code و JetBrains
IDEs. مع Synapse MCP، يكتسب Continue ذاكرة دائمة عبر الجلسات.
المتطلبات المسبقة
- VS Code أو JetBrains IDE
- امتداد Continue.dev مثبت
- Node.js 18+
- Mind Key الخاص بـ Synapse
الإعداد
الخطوة 1: افتح إعداد Continue
في VS Code أو JetBrains:
1. افتح الشريط الجانبي لامتداد Continue
2. انقر أيقونة الترس → "Open config.json"
أو حرّر  مباشرة.
الخطوة 2: أضف خادم Synapse MCP
[CODE BLOCK]
الخطوة 3: أعد تحميل Continue
أعد تحميل نافذة VS Code (Cmd+Shift+P → "Reload Window") أو أعد تشغيل IDE.
تحقق أنه يعمل
في دردشة Continue:
[CODE BLOCK]
يجب أن يستدعي Continue  ويرد بذكرياتك المخزّنة.
الأنماط الشائعة
سياق المشروع
[CODE BLOCK]
يستدعي Continue ، يرى ذكريات مشروعك، ويواصل
العمل من حيث توقفت.
أنماط مراجعة الكود
[CODE BLOCK]
يجد Continue أنماط مراجعة الكود المخزّنة ويطبّقها.
ذاكرة البرمجة الزوجية
[CODE BLOCK]
يخزّنها Continue كذاكرة .
استكشاف الأخطاء
خادم MCP لا يتصل
1. تحقق أن  JSON صالح
2. تحقق من Node.js: 
3. تحقق من لوحة مخرجات Continue (View → Output → Continue)
4. أعد تشغيل IDE
الأدوات لا تظهر
- تحقق أن إصدار Continue يدعم MCP (≥ 0.9.x)
- تحقق أن متغير البيئة  مُعيين في الإعداد
- ابحث عن أخطاء MCP في سجلات Continue
الخطوات التالية
- إعداد Claude Desktop
- عميل MCP مخصص

────────────────────────────────────────────────────────────
# MCP في Cursor
SUMMARY: اربط Synapse بـ Cursor IDE لذاكرة مشروع دائمة عبر جلسات البرمجة.

MCP في Cursor
Cursor IDE ذكي مدعوم بـ AI مبني على VS Code. مع Synapse MCP، يكتسب Cursor
ذاكرة دائمة عبر الجلسات — يتذكر قرارات مشروعك،
أنماط قاعدة الكود، وجلسات تصحيح الأخطاء السابقة.
المتطلبات المسبقة
- Cursor IDE مثبت (<https://cursor.com>)
- Node.js 18+
- Mind Key الخاص بـ Synapse
الإعداد
الخطوة 1: افتح إعدادات Cursor
في Cursor:
1. افتح الإعدادات (Cmd+, على macOS، Ctrl+, على Windows/Linux)
2. ابحث عن "MCP" أو انتقل إلى 
الخطوة 2: أضف خادم Synapse MCP
انقر "Add MCP Server" وأعد:
| الحقل | القيمة |
|-------|-------|
| Name |  |
| Type |  |
| Command |  |
| Env |  |
الخطوة 3: حرّر config.json مباشرة (بديل)
يخزّن Cursor إعداد MCP في :
[CODE BLOCK]
الخطوة 4: أعد تشغيل Cursor
أعد تشغيل Cursor بالكامل (Cmd+Q وأعد الفتح على macOS).
تحقق أنه يعمل
في لوحة دردشة Cursor (Cmd+L):
[CODE BLOCK]
يجب أن يستدعي Cursor  ويرد بذكرياتك المخزّنة.
الأنماط الشائعة
تهيئة المشروع
عند فتح مشروع جديد:
[CODE BLOCK]
يستدعي Cursor  ويواصل العمل من حيث توقفت.
القرارات المعمارية
[CODE BLOCK]
يخزّنها Cursor كذاكرة  بأولوية .
تاريخ التصحيح
[CODE BLOCK]
يبحث Cursor عن ذكريات  ويذكّرك بالإصلاحات السابقة.
أنماط الكود عبر الجلسات
[CODE BLOCK]
يجد Cursor ذكريات حول تطبيقات المصادقة التي فعلتها من قبل.
استكشاف الأخطاء
خادم MCP لا يتصل
1. تحقق من Node.js:  (≥ 18)
2. اختبر خادم MCP:  (يجب أن يبدأ بلا أخطاء)
3. تحقق من سجلات MCP في Cursor (View → Output → MCP)
4. أعد تشغيل Cursor بالكامل
الأدوات لا تظهر
- تحقق أن  JSON صالح
- تحقق أن متغير البيئة  مُعيين
- تحقق أن إصدار Cursor يدعم MCP (≥ 0.42)
Mind Key غير صالح
[CODE BLOCK]
الخطوات التالية
- إعداد Claude Desktop
- إعداد Continue.dev
- دليل وكيل LLM الدائم

────────────────────────────────────────────────────────────
# بناء عميل MCP مخصص
SUMMARY: اتصل بخادم Synapse MCP من تطبيقك الخاص باستخدام MCP SDK.

بناء عميل MCP مخصص
إذا كنت تبني تطبيق LLM خاصًا بك، يمكنك الاتصال بخادم Synapse
MCP مباشرة باستخدام MCP SDK الرسمي. هذا يمنح تطبيقك الوصول إلى
جميع أدوات Synapse الـ 79.
حزم SDK
| اللغة | الحزمة |
|----------|---------|
| TypeScript/JavaScript |  |
| Python |  |
مثال TypeScript
تثبيت
[CODE BLOCK]
الاتصال عبر stdio
[CODE BLOCK]
الاتصال عبر HTTP/SSE (بعيد)
[CODE BLOCK]
مثال Python
تثبيت
[CODE BLOCK]
الاتصال عبر stdio
[CODE BLOCK]
ملفات الأدوات
عند الاتصال، يمكنك طلب ملف أداة محدد عبر
ترويسة  (HTTP/SSE) أو متغير البيئة  (stdio):
[CODE BLOCK]
معالجة الأخطاء
[CODE BLOCK]
حالات الاستخدام
- مساعدون ذكيون مخصصون — ابنِ وكيلك الخاص بذاكرة دائمة
- أتمتة سير العمل — اربط أدوات Synapse في سير عمل مخصص
- خطوط بيانات — استخرج الذكريات، حوّل، حمّل في مكان آخر
- لوحات المراقبة — اعرض إحصائيات الذاكرة، سجل الدردشة، المهام
الخطوات التالية
- مواصفات MCP
- مستودع Synapse MCP
- نظرة عامة على الـ API

────────────────────────────────────────────────────────────
# استكشاف أخطاء MCP
SUMMARY: حل مشكلات تكامل MCP الشائعة — الخادم لا يبدأ، الأدوات لا تظهر، أخطاء المصادقة.

KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/

استكشاف أخطاء MCP
مشكلات وحلول شائعة عند دمج Synapse MCP مع عميل LLM الخاص بك.
قائمة تشخيص سريعة
1. ✅ Node.js 18+ مثبت؟ ()
2. ✅ Mind Key يبدأ بـ ؟ (وليس JWT )
3. ✅ Synapse API قابل للوصول؟ ()
4. ✅ Mind Key يعمل؟ ()
5. ✅ ملف الإعداد JSON صالح؟ (بلا فواصل لاحقة، بلا تعليقات)
6. ✅ العميل أُعيد تشغيله بعد تغيير الإعداد؟
7. ✅ خادم MCP يبدأ يدويًا؟ ()
المشكلة: لا تظهر أدوات في العميل
الأعراض
- Claude Desktop / Cursor / Continue يُظهر 0 أدوات
- لا أيقونة 🔌 أو إدخال "synapse" في قائمة خوادم MCP
الحلول
1. أعد تشغيل العميل بالكامل — Cmd+Q على macOS (ليس مجرد إغلاق النافذة)
2. تحقق من موقع ملف الإعداد:
   - Claude Desktop macOS: 
   - Claude Desktop Windows: 
   - Cursor: 
   - Continue: 
3. تحقق من صحة JSON — الصق الإعداد في <https://jsonlint.com>
4. تحقق من سجلات العميل لأخطاء MCP:
   - Claude Desktop:  (macOS)
   - Cursor: View → Output → MCP
5. شغّل خادم MCP يدويًا لرؤية أخطاء بدء التشغيل:
   [CODE BLOCK]
المشكلة: خطأ "Mind Key invalid"
الأعراض
- الأدوات تظهر لكن الاستدعاءات تفشل بـ "401 Unauthorized"
- الخطأ: "Mind Key fehlt oder ungültig"
الحلول
1. تحقق من تنسيق Mind Key — يبدأ بـ ، 40 حرفًا
2. اختبر مباشرة:
   [CODE BLOCK]
3. تحقق أن متغير البيئة مُعيين — لنقل stdio، يجب أن يكون متغير البيئة في
   إعداد خادم MCP، لا في shell الخاص بك
4. احصل على Mind Key جديد:
   [CODE BLOCK]
المشكلة: npx غير موجود
الأعراض
- الخطأ: "npx: command not found"
- خادم MCP يفشل في البدء
الحلول
1. ثبّت Node.js 18+:
   - macOS:  أو نزّل من <https://nodejs.org>
   - Linux: 
   - Windows: نزّل من <https://nodejs.org>
2. أعد تشغيل الـ terminal بعد التثبيت
3. تحقق: 
المشكلة: SYNAPSEURL غير قابل للوصول
الأعراض
- خادم MCP يبدأ لكن استدعاءات الأدوات تنتهي بالمهلة
- الخطأ: "fetch failed" أو "ECONNREFUSED"
الحلول
1. اختبر الاتصال:
   [CODE BLOCK]
2. تحقق من جدار حماية الشركة — قد يحظر HTTPS الصادر
3. جرّب عنوان URL بديلًا:
   - الإنتاج: 
   - خادم MCP: 
4. للاستضافة الذاتية: تأكد أن نسخة Synapse الخاصة بك تعمل وقابلة للوصول
المشكلة: خادم MCP ينهار
الأعراض
- خادم MCP يخرج فورًا بعد البدء
- سجلات العميل تُظهر "MCP server disconnected"
الحلول
1. شغّل يدويًا لرؤية الخطأ:
   [CODE BLOCK]
2. تحقق من تعارضات المنفذ — خادم MCP يستخدم المنفذ 13100 افتراضيًا
3. امسح ذاكرة npx المؤقتة:
   [CODE BLOCK]
4. حدّث إلى الأحدث:
   [CODE BLOCK]
المشكلة: استدعاءات الأدوات تُرجع 429
الأعراض
- الخطأ: "Rate limit exceeded"
الحلول
هذا لا ينبغي أن يحدث مع MCP (يستخدم مصادقة الترويسة، بلا حد معدل). إذا حدث:
1. تحقق إذا كنت تستخدم  في مكان ما — بدّل إلى مصادقة الترويسة
2. تحقق من  — تأكد أنه يشير إلى النسخة الصحيحة
3. تواصل مع الدعم إذا استمرت المشكلة
المشكلة: الأدوات تظهر لكن لا تعمل
الأعراض
- الأدوات مذكورة في العميل
- استدعاء أداة يُرجع خطأ أو بلا نتيجة
الحلول
1. تحقق من اسم الأداة — يجب أن يكون دقيقًا (مثلًا ، لا )
2. تحقق من المعاملات — تحقق من مخطط إدخال الأداة
3. اختبر عبر API مباشر:
   [CODE BLOCK]
4. تحقق من صحة Synapse:
   [CODE BLOCK]
الحصول على المساعدة
إذا لم يحل أي مما سبح مشكلتك:
1. تحقق من المشكلات الموجودة: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. افتح issue جديدًا مع:
   - إصدار خادم MCP ()
   - اسم العميل وإصداره
   - نظام التشغيل
   - مقتطفات السجلات ذات الصلة
   - خطوات إعادة الإنتاج
الخطوات التالية
- إعداد Claude Desktop
- إعداد Claude Code
- أخطاء الـ API

────────────────────────────────────────────────────────────
# ما هو MCP؟
SUMMARY: Model Context Protocol يتيح لـ LLMs استدعاء أدوات خارجية. يعرض Synapse 79 أداة عبر خادم MCP رسمي.

KEY CONTEXT:
MCP = Model Context Protocol (Anthropic, 2024). Open standard for LLM-tool integration.
Synapse has official MCP server: synapse-mcp-api (npm package, npx -y synapse-mcp-api@latest)
79 tools exposed: 22 memory, 7 chat, 8 scheduler, 4 tasks, 5 scripts, 9 computers, 4 push, 5 user, 3 utility
3 transports: stdio (local), HTTP/SSE (remote), WebSocket (mobile)
Supported clients: Claude Desktop, Claude Code, Cursor, Continue, Cline, any MCP-compatible client
Tool Profiles (v1.4.0): minimal (8 tools), standard (25), full (119) — controlled via MCP_PROFILE env or Mcp-Tool-Profile header

ما هو MCP؟
Model Context Protocol (MCP) معيار مفتوح من Anthropic (2024)
يتيح لـ LLMs استدعاء أدوات خارجية بطريقة منظمة. بدلًا من لصق وثائق API
في الـ prompt، تسجّل الأدوات مع خادم MCP، ويستدعيها الـ LLM
عند الحاجة — مثل استدعاء الدوال، لكن موحّد ومستقل عن العميل.
خادم Synapse MCP
يأتي Synapse بخادم MCP رسمي ( على npm) يعرض
79 أداة تغطي جميع ميزات Synapse:
| الفئة | الأدوات | العدد |
|----------|-------|-------|
| الذاكرة | recall, list, store, search, semantic-search, update, delete, bulk-delete, stats, unverified, contradictions, audit, related, by-tag, diff, expiring, health, sync, embed-batch, verify, unverify, mind-export | 22 |
| الدردشة | poll, reply, status, history, unread, send, upload | 7 |
| المجدول | cronlist, croncreate, crondelete, crontoggle, varlist, varget, varset, vardelete | 8 |
| المهام | tasklist, taskget, taskcreate, taskupdate | 4 |
| السكربتات | scriptlist, scriptget, scriptinfo, scriptstore, scriptdelete | 5 |
| الأجهزة | computerlist, computerget, installcode, screenshot, commandqueue, commandstatus, commandslist, disable, delete | 9 |
| الإشعارات | vapidpublickey, subscribe, unsubscribe, test | 4 |
| المستخدم/العقل | register, login, mindslist, mindcreate, minddelete | 5 |
| الأدوات | time, calc, random | 3 |
| التصور | graph, tags, compact | 3 |
| المشاركة | share, list, revoke | 3 |
| الـ Webhooks | register, list, get, update, delete | 5 |
| المتصفح | new, navigate, click, type, screenshot, close | 6 |
| الإجمالي | | 79+ |
كيف يعمل
[CODE BLOCK]
1. تُعدّ عميل LLM (Claude Desktop، Cursor، إلخ) لاستخدام خادم Synapse MCP
2. يبدأ العميل خادم MCP (عبر )
3. يتصل خادم MCP بـ Synapse API باستخدام Mind Key الخاص بك
4. يرى الـ LLM جميع الأدوات الـ 79 كدوال أصلية يستطيع استدعاءها
5. عندما يحتاج الـ LLM لتذكر شيء، يستدعي  — يترجم خادم MCP هذا إلى  على Synapse
وسائل النقل
يدعم خادم Synapse MCP ثلاث وسائل نقل:
stdio (محلي، موصى به لسطح المكتب)
[CODE BLOCK]
HTTP/SSE (بعيد، متعدد المستأجرين)
اربط عميل MCP الخاص بك بـ:
[CODE BLOCK]
WebSocket (موبايل، حجم عالي)
[CODE BLOCK]
ملفات الأدوات (v1.4.0)
لتقليل عبء الرموز لـ LLMs أصغر، خادم MCP يدعم ثلاثة
ملفات أدوات:
| الملف | الأدوات | الرموز | الأفضل لـ |
|---------|-------|--------|----------|
|  | 8 (إرسال مركب) | 500 | LLMs مستضافة ذاتيًا بسياق ≤8k |
|  | 25 (مُسمّاة) | 2,500 | LLMs متوسطة (Claude Haiku، GPT-3.5) |
|  | 119 (الكل) | 8,250 | LLMs كبيرة (Claude Sonnet/Opus، GPT-4) — افتراضي |
التحكم عبر:
- متغير البيئة: 
- الترويسة: 
العملاء المدعومون
- Claude Desktop — تطبيق سطح المكتب من Anthropic
- Claude Code — وكيل برمجة طرفي
- Cursor — IDE ذكي مدعوم بـ AI
- Continue.dev — مساعد برمجة ذكي مفتوح المصدر
- Cline — امتداد VS Code
- أي عميل متوافق مع MCP
لماذا تستخدم MCP بدلًا من API مباشر؟
| النهج | المزايا | العيوب |
|----------|------|------|
| API مباشر | بسيط، بلا طبقة إضافية | يحتاج LLM معرفة عناوين URL، الترويسات، المصادقة |
| MCP | يرى الـ LLM أدوات أصلية، بلا حفظ URL | عملية خادم MCP إضافية |
لمعظم حالات استخدام وكلاء LLM، MCP الخيار الأفضل — الـ LLM لا يحتاج
لتذكر مسارات API أو أنماط المصادقة.
الخطوات التالية
- إعداد Claude Desktop — إعداد بدقيقتين
- إعداد Claude Code — تكامل الـ terminal
- عميل MCP مخصص — ابنِ خاصتك

## الفئة: الأدلة والإرشادات
أدلة خطوة بخطوة لسيناريوهات ملموسة.

────────────────────────────────────────────────────────────
# اختبار تطبيقات iOS المؤتمت
SUMMARY: استخدم Synapse + Computer Control API لأتمتة اختبارات تطبيقات iOS عبر Simulator.

اختبار تطبيقات iOS المؤتمت
اجمع نظام ذاكرة Synapse مع Computer Control API لبناء
اختبارات تطبيقات iOS مدفوعة بـ LLM. يتذكر الـ LLM سيناريوهات الاختبار، يتعلّم من الإخفاقات
السابقة، ويتكيّف مع تغييرات الواجهة.
البنية
[CODE BLOCK]
المتطلبات المسبقة
- حساب Synapse + Mind Key
- خادم Synapse MCP مُعدّ في Claude Desktop
- iOS Simulator مع  مثبت
- جهاز مسجّل في Synapse (راجع Computer Control API)
الخطوة 1: سجّل جهاز Simulator
على الـ Mac الذي يشغّل iOS Simulator:
[CODE BLOCK]
الخطوة 2: خزّن سيناريوهات الاختبار في الذاكرة
خزّن سيناريوهات اختبار قابلة لإعادة الاستخدام كذكريات:
[CODE BLOCK]
الخطوة 3: تنفيذ الاختبار المدفوع بـ LLM
في Claude Desktop (مع Synapse MCP مُعدًا):
[CODE BLOCK]
سيفعل Claude:
1. يستدعي  لإيجاد ذاكرة 
2. يستدعي  لرؤية الحالة الحالية
3. ينفّذ كل خطوة عبر  (click، type)
4. يتحقق من النتائج عبر لقطات الشاشة
5. يخزّن أي إخفاقات كذكريات 
الخطوة 4: اختبارات ذاتية الإصلاح
عند فشل اختبار، خزّن الفشل والتعافي:
[CODE BLOCK]
في المرة التالية التي يُشغّل فيها الـ LLM الاختبار، يستدعي الفشل ويطبّق
التعافي تلقائيًا.
الخطوة 5: تتبع نتائج الاختبار
تتبع عمليات تشغيل الاختبار كمهام:
[CODE BLOCK]
الأوامر الشائعة
| الإجراء | الأمر |
|--------|---------|
| تشغيل Simulator |  |
| لقطة شاشة |  (عبر Synapse MCP) |
| النقر عند (x,y) |  |
| كتابة نص |  |
| ضغط Home |  |
أفضل الممارسات
> [!TIP]
> - خزّن إحداثيات الواجهة كذكريات — تتغير الواجهة، لكن الـ LLM يستطيع إعادة التعلم
> - استخدم تسميات الوصول (accessibility labels) — أكثر ثباتًا من الإحداثيات
> - خزّن بيانات الاختبار منفصلة — استخدم متغيرات لأسماء المستخدمين، كلمات المرور
> - شغّل الاختبارات في حالة نظيفة — أعد تعيين Simulator بين التشغيلات
> - سجّل لقطات شاشة للإخفاقات — مفيد للتصحيح
الخطوات التالية
- اختبارات ذاتية الإصلاح
- Computer Control API
- أفضل ممارسات الذاكرة

────────────────────────────────────────────────────────────
# النسخ الاحتياطي والاستعادة
SUMMARY: صدّر ذكرياتك للنسخ الاحتياطي، ارتحل بين العقول، استعد بعد فقدان البيانات.

النسخ الاحتياطي والاستعادة
يوفّر Synapse تصديرًا/استيرادًا كاملًا للنسخ الاحتياطي للذاكرة، والترحيل، والتعافي من الكوارث.
يغطي هذا الدليل العمليات الأساسية.
التصدير
تصدير العقل الكامل
صدّر جميع الذكريات في عقل كـ JSON:
[CODE BLOCK]
تنسيق الاستجابة:
[CODE BLOCK]
التصدير التزايدي (Diff)
صدّر فقط الذكريات المتغيّرة منذ طابع زمني:
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
نسخ احتياطي مؤتمت
جدول نسخًا احتياطيًا يوميًا عبر cron:
[CODE BLOCK]
> [!NOTE]
> تستقبل نقطة نهاية cron الاستجابة لكنها لا تخزّنها. للنسخ
> الحقيقي، وجّه cron إلى خادم النسخ الاحتياطي الخاص بك الذي يحفظ الاستجابة.
أفضل: سكربت نسخ احتياطي خارجي
[CODE BLOCK]
أضفه إلى crontab:
[CODE BLOCK]
الاستعادة
الاستعادة إلى نفس العقل
[CODE BLOCK]
الاستعادة إلى عقل جديد
[CODE BLOCK]
سكربت استعادة Python
[CODE BLOCK]
الترحيل بين العقول
[CODE BLOCK]
نسخ احتياطي للبيانات الأخرى
لا تنسَ نسخ:
| نوع البيانات | نقطة النهاية |
|-----------|----------|
| الذكريات |  |
| المهام |  |
| السكربتات |  |
| الـ Webhooks |  |
| مهام cron |  |
| المتغيرات |  |
| سجل الدردشة |  |
التحقق
بعد الاستعادة، تحقق:
[CODE BLOCK]
أفضل الممارسات
> [!TIP]
> - انسخ احتياطيًا يوميًا — أتمت بـ cron
> - اختبر الاستعادة — النسخة التي لا تستطيع استعادتها عديمة الفائدة
> - احتفظ بإصدارات متعددة — 30 يومًا على الأقل
> - خزّن خارج الموقع — S3، Backblaze B2، إلخ
> - شفّر النسخ الحساسة — قد تحتوي الذكريات على PII
> - وثّق عملية الاستعادة — ستنساها بحلول وقت الحاجة إليها
الخطوات التالية
- Memory API
- Cron والمجدول — للنسخ الاحتياطي المؤتمت

────────────────────────────────────────────────────────────
# أفضل ممارسات الذاكرة
SUMMARY: كيف تُنظَّم الذكريات للاستدعاء الفعال — الفئات، المفاتيح، الوسوم، الأولويات.

أفضل ممارسات الذاكرة
كيف تُنظَّم الذكريات يحدد مدى فائدتها. يغطي هذا الدليل
أنماط تصنيف ووسم وأولوية الذكريات حتى يستطيع الـ LLM
استدعاء المعلومة الصحيحة في الوقت المناسب.
الفئات: اختر الأكثر تحديدًا
| الفئة | استخدم لـ | مثال |
|----------|---------|---------|
|  | اسم المستخدم، الدور، معلومات الاتصال |  |
|  | الإعجابات، عدم الإعجابات، أسلوب العمل |  |
|  | حقائق قابلة للتحقق |  |
|  | حالة المشروع، القرارات |  |
|  | مهارات المستخدم |  |
|  | أخطاء سابقة يجب تجنبها |  |
|  | سياق ذو صلة بالجلسة |  |
|  | ملاحظات متفرقة |  |
> [!TIP]
> عند الشك، استخدم  للمعلومات القابلة للتحقق و  لكل شيء آخر.
> لا تفرط في التصنيف — أفضل أن يكون لديك  واضح من  مربك.
المفاتيح: مُعرّفات ذات معنى
الحقل  هو مُعرّف الذاكرة. استخدم مفاتيح ذات معنى وثابتة:
مفاتيح جيدة:
- 
- 
- 
- 
مفاتيح سيئة:
-  (ليس ذا معنى)
-  (ليس وصفيًا)
-  (التاريخ لا يساعد الاستدعاء)
اصطلاحات تسمية المفاتيح
-  (أحرف صغيرة مع شرطات سفلية)
- بادئة بالفئة: ، ، 
- استخدم أسماء وصفية، لا أفعالًا
- أبقِها أقل من 50 حرفًا
الوسوم: للبحث والتصفية
تُمكّن الوسوم التصفية والبحث السريع. أضف 2-5 وسوم لكل ذاكرة:
[CODE BLOCK]
أنماط الوسوم
- أسماء المشاريع: ، ، 
- المواضيع: ، ، ، 
- الحالة: ، ، 
- مؤشرات الأولوية: ، 
> [!NOTE]
> الوسوم غير حساسة لحالة الأحرف. استخدم أحرفًا صغيرة للاتساق.
الأولويات: كن واقعيًا
| الأولوية | استخدم لـ | % من الذكريات |
|----------|---------|---------------|
|  | هوية المستخدم، المعلومات القانونية، القرارات غير القابلة للتراجع | 5% |
|  | المشاريع النشطة، التفضيلات المهمة | 20% |
|  | معظم الحقائق، الملاحظات، السياق | 65% |
|  | عابرة، جيد معرفتها | 10% |
> [!WARNING]
> لا تعلّم كل شيء . إذا كان كل شيء حرجًا، فلا شيء كذلك.
> احجز  للأشياء التي تسبب ضررًا حقيقيًا إذا نُسيت.
متى تخزّن ومتى لا تخزّن
خزّن دائمًا
- هوية المستخدم (الاسم، البريد، الدور)
- التفضيلات طويلة الأمد
- قرارات المشروع والمبررات
- الأخطاء السابقة والدروس المستفادة
- الالتزامات المقطوعة للمستخدم
لا تخزّن
- الحالة العابرة (استخدم المتغيرات بدلًا من ذلك)
- سجل المحادثة الحرفي (نظام الدردشة يتولى هذا)
- البيانات الحساسة (كلمات المرور، مفاتيح API)
- الحقائق المشتقة بسهولة (التاريخ الحالي، محتويات الملفات)
- السياق العابر (استخدم فئة  بأولوية منخفضة)
تحديث الذكريات
استدعِ  بنفس  +  يُحدّث الذاكرة الموجودة:
[CODE BLOCK]
> [!TIP]
> استخدم مفاتيح ثابتة حتى تُحدّث دون إنشاء مكررات. على الـ LLM
> إعادة POST لنفس المفتاح مع تغير المعلومات، لا إنشاء ذكريات جديدة.
دورة حياة الذاكرة
[CODE BLOCK]
- Create: POST /memory بسياق كامل
- Active: استدعِ كثيرًا، حدّث حسب الحاجة
- Stale: ما زال ذا صلة لكن غير مستخدم بنشاط (أولوية أقل؟)
- Archive: عيّن الأولوية إلى ، أبقِ للمرجع التاريخي
- Delete: DELETE /memory/:id عندما لا يعود ذا صلة
تنظيف دوري
[CODE BLOCK]
نمط: وراثة الذاكرة
للسياق الهرمي (مشروع → مشروع فرعي → مهمة):
[CODE BLOCK]
يستطيع الـ LLM حينها البحث  لإيجاد جميع الذكريات ذات الصلة.
نمط: سجل القرارات
خزّن القرارات مع المبررات حتى لا يعيد الـ LLM مناقشتها:
[CODE BLOCK]
نمط: تجنب الأخطاء
خزّن الأخطاء مع تعليمات تجنب محددة:
[CODE BLOCK]
أنماط مضادة يجب تجنبها
> [!WARNING]
> - تخزين سجلات المحادثة — نظام الدردشة يتولى هذا
> - تخزين الملفات الكاملة — استخدم تخزين السكربتات أو تخزينًا خارجيًا
> - تخزين الحالة العابرة — استخدم المتغيرات
> - تخزين الأسرار — استخدم متغيرات البيئة
> - تكرار الذكريات — استخدم مفاتيح ثابتة
> - الإفراط في الوسم — 2-5 وسوم لكل ذاكرة مثالي
> - كل شيء حرج — كن واقعيًا مع الأولويات
الخطوات التالية
- Memory API
- وكيل LLM الدائم
- استراتيجية وسوم الذاكرة

────────────────────────────────────────────────────────────
# تنسيق الوكلاء المتعددين
SUMMARY: نسّق عدة وكلاء LLM باستخدام عقول Synapse المشتركة، المهام، والدردشة.

تنسيق الوكلاء المتعددين
عندما لديك عدة وكلاء LLM يعملون على مهام ذات صلة، يوفّر Synapse
طبقة التنسيق — الذاكرة المشتركة، إسناد المهام، والدردشة غير المتزامنة.
الأنماط
النمط 1: العقل المشترك (مصدر واحد للحقيقة)
جميع الوكلاء يشاركون Mind Key واحد. يقرؤون/يكتبون نفس مخزن الذاكرة.
[CODE BLOCK]
حالة الاستخدام: فريق صغير من الوكلاء يعملون على مشروع واحد.
الإعداد:
[CODE BLOCK]
التنسيق عبر المهام:
[CODE BLOCK]
النمط 2: عقول متخصصة (سياقات معزولة)
كل وكيل له عقله الخاص. يتواصلون عبر عقل "تنسيق" مشترك.
[CODE BLOCK]
حالة الاستخدام: وكلاء بتخصصات مختلفة (برمجة، مراجعة، نشر).
الإعداد:
[CODE BLOCK]
التنسيق عبر العقل المشترك:
[CODE BLOCK]
النمط 3: المحور والأقطاب (المنسّق)
وكيل منسّق مركزي يُسند المهام لوكلاء العمل.
[CODE BLOCK]
حالة الاستخدام: سير عمل معقد بعمل متوازٍ.
التنفيذ:
[CODE BLOCK]
التنسيق عبر الدردشة
يستطيع الوكلاء التواصل عبر نظام الدردشة:
[CODE BLOCK]
> [!NOTE]
> رسائل الدردشة موسومة بالدور. عيّن role=agent لرسائل الوكيل-إلى-الوكيل،
> role=human للإنسان-إلى-الوكيل.
التنسيق عبر المتغيرات
استخدم المتغيرات للتنسيق الخفيف (أقفال، أعلام):
[CODE BLOCK]
أفضل الممارسات
> [!TIP]
> - استخدم عقولًا منفصلة للاهتمامات المنفصلة — لا تخلط ذاكرة المبرمج والمراجع
> - وسم الوكلاء في الدردشة —  لعنوان واضح
> - استخدم المهام لإسناد العمل — لا الدردشة (الدردشة للنقاش)
> - نفّذ الـ idempotency — قد يعيد الوكلاء محاولة العمليات الفاشلة
> - سجّل كل شيء — خزّن القرارات في الذاكرة للقابلية للتدقيق
الخطوات التالية
- وكيل LLM الدائم
- كتاب طبخ LLM
- أتمتة الـ Webhooks

────────────────────────────────────────────────────────────
# بناء وكيل LLM دائم
SUMMARY: دليل خطوة بخطوة لبناء وكيل LLM يتذكر عبر الجلسات باستخدام Synapse.

نظرة عامة
يأخذك هذا الدليل خلال بناء وكيل LLM يحفظ السياق عبر
الجلسات باستخدام Synapse. بنهايته، سيكون وكيلك:
- يستدعي السياق السابق عند بدء الجلسة
- يخزّن التعلمات الجديدة عندما تحدث
- يتتبع المهام متعددة الخطوات عبر الجلسات
- يتواصل مع البشر عبر الدردشة غير المتزامنة
البنية
[CODE BLOCK]
الخطوة 1: إعداد Mind Key
[CODE BLOCK]
الخطوة 2: بروتوكول بدء الجلسة
في بداية كل جلسة، استدعِ جميع الذكريات:
[CODE BLOCK]
الخطوة 3: تخزين التعلمات الجديدة
كلما تعلّم الوكيل شيئًا يستحق التذكر:
[CODE BLOCK]
الخطوة 4: إدارة المهام
تتبع العمل متعدد الخطوات عبر الجلسات:
[CODE BLOCK]
الخطوة 5: دردشة غير متزامنة مع البشر
استطلع للرسائل بين استدعاءات الأدوات:
[CODE BLOCK]
الخطوة 6: بروتوكول نهاية الجلسة
عند نهاية الجلسة، خزّن السياق النهائي:
[CODE BLOCK]
النمط الكامل
[CODE BLOCK]
أفضل الممارسات
> [!TIP]
>
> - استدعِ أولًا دائمًا — لا تبدأ العمل دون تحميل السياق
> - خزّن استباقيًا — لا تنتظر حتى نهاية الجلسة
> - استخدم مفاتيح ذات معنى — ، ، لا 
> - وسم كل شيء — الوسوم تُمكّن البحث والتصفية
> - عيّن أولويات واقعية — ليس كل شيء 
الخطوات التالية
- كتاب طبخ LLM — أنماط عملية
- أفضل ممارسات الذاكرة
- تنسيق الوكلاء المتعددين

────────────────────────────────────────────────────────────
# خطوط اختبار ذاتية الإصلاح
SUMMARY: ابنِ خطوط اختبار تتعلّم من الإخفاقات وتتكيف تلقائيًا باستخدام ذاكرة Synapse.

خطوط اختبار ذاتية الإصلاح
تنكسر مجموعات الاختبار التقليدية عند تغير الواجهة. تستخدم اختبارات
الإصلاح الذاتي ذاكرة Synapse للتعلّم من الإخفاقات السابقة والتكيف — مما يقلل الاختبارات المتذبذبة
والعبء الصياني.
المفهوم
[CODE BLOCK]
1. يُشغّل الاختبار
2. إذا فشل، خزّن الفشل (ما الخطأ، لماذا، كيف الإصلاح)
3. التشغيل التالي: استدعِ الإخفاقات ذات الصلة قبل التنفيذ
4. طبّق الإصلاحات المعروفة تلقائيًا
التنفيذ
الخطوة 1: غلاف الاختبار
غلّف كل اختبار باستدعاء ذاكرة/تخزين:
[CODE BLOCK]
الخطوة 2: منطق اختبار تكيّفي
داخل الاختبار، تحقق من الإخفاقات المعروفة وطبّق الإصلاحات:
[CODE BLOCK]
الخطوة 3: استراتيجيات التعافي
خزّن استراتيجيات التعافي كذكريات:
[CODE BLOCK]
الخطوة 4: تكامل CI
[CODE BLOCK]
الخطوة 5: لوحة تحليل الإخفاقات
[CODE BLOCK]
أفضل الممارسات
> [!TIP]
> - خزّن التتبعات الخلفية (tracebacks) — تحتوي السطر الدقيق الذي فشل
> - وسم حسب اسم الاختبار — يُمكّن التصفية السريعة
> - استخدم فئة  — يفصل عن الذكريات العادية
> - عيّن أولوية  — يجب ألا تُنسى الإخفاقات أبدًا
> - تنظيف دوري — احذف الذكريات للمشكلات المُصلَحة
> - لا تخزّن بيانات حساسة — بيانات الاعتماد، PII
أنماط إخفاق شائعة للتخزين
| نوع الإخفاق | ما يجب تخزينه |
|--------------|---------------|
| عنصر غير موجود | المُحدِّد المُجرَّب، حالة الصفحة، لقطة شاشة |
| انتهاء المهلة | وقت الانتظار، ما كان يُنتظر |
| فشل التأكيد | القيمة المتوقعة مقابل الفعلية |
| خطأ شبكة | عنوان URL، رمز الحالة، نص الاستجابة |
| رفض الإذن | الإذن المطلوب، دور المستخدم الحالي |
الخطوات التالية
- اختبار iOS المؤتمت
- أفضل ممارسات الذاكرة
- كتاب طبخ التعافي من الأخطاء

────────────────────────────────────────────────────────────
# أتمتة الـ Webhooks
SUMMARY: شغّل الأنظمة الخارجية عند تغير الذكريات — مزامنة، إشعارات، أتمتة.

أتمتة الـ Webhooks
تتيح لك الـ Webhooks تشغيل الأنظمة الخارجية عند إطلاق أحداث Synapse. يغطي هذا الدليل
أنماط أتمتة شائعة.
الأنماط الشائعة
النمط 1: إشعار عند ذاكرة حرجة
أرسل رسالة Slack عند تخزين ذاكرة حرجة:
[CODE BLOCK]
سجّل الـ webhook:
[CODE BLOCK]
النمط 2: مزامنة إلى نظام خارجي
زامن الذكريات إلى Notion، Obsidian، أو أي KB خارجي:
[CODE BLOCK]
النمط 3: تشغيل CI/CD
شغّل نشرًا عند تخزين ذاكرة "release":
[CODE BLOCK]
النمط 4: إيقاظ الوكيل عند رسالة الإنسان
شغّل تشغيل وكيل LLM عندما يرسل الإنسان رسالة دردشة:
[CODE BLOCK]
النمط 5: تجميع المقاييس
تتبع نمو الذاكرة، نشاط الدردشة، إكمال المهام:
[CODE BLOCK]
التحقق من التوقيع
تحقق دائمًا من توقيعات الـ webhook لمنع الانتحال:
[CODE BLOCK]
منطق إعادة المحاولة
يعيد Synapse محاولة الـ webhooks الفاشلة مع تراجع أُسي. يجب أن يفعل معالجك:
1. يُرجع 200 بسرعة — لا تفعل عملًا ثقيلًا تزامنيًا
2. أدرج العمل في الطابور — استخدم نظام مهام خلفي
3. كن idempotent — قد يُسلَّم نفس الحدث مرتين
[CODE BLOCK]
تصحيح الـ Webhooks
تحقق من سجل التسليم
تُسجَّل تسليمات الـ webhook. تحقق من التسليمات الحديثة لـ webhook الخاص بك:
[CODE BLOCK]
اختبر الـ webhook يدويًا
[CODE BLOCK]
مشكلات شائعة
| المشكلة | الإصلاح |
|-------|-----|
| استجابات 4xx | تحقق أن معالجك يُرجع 200 |
| استجابات 5xx | خطأ خادم — تحقق من سجلات تطبيقك |
| انتهاء المهلة | أرجع 200 بسرعة، أدرج العمل غير المتزامن |
| تسليمات مكررة | اجعل المعالج idempotent |
| عدم تطابق التوقيع | تحقق أن السر صحيح |
أفضل الممارسات
> [!TIP]
> - تحقق من التوقيعات دائمًا — لا تتخطى هذا أبدًا
> - أرجع 200 بسرعة — لا تحجب Synapse
> - كن idempotent — تعامل مع التسليمات المكررة
> - استخدم أحداثًا محددة —  لا 
> - راقب إخفاقات التسليم — أعد تنبيهًا
الخطوات التالية
- Webhooks API
- Cron والمجدول
- وكيل LLM الدائم

## الفئة: المفاهيم
البنية والمفاهيم وراء Synapse.

────────────────────────────────────────────────────────────
# بنية Synapse
SUMMARY: كيف بُني Synapse — Fastify، PostgreSQL، FTS5، التضمينات، خادم MCP.

بنية Synapse
Synapse واجهة ذاكرة متعددة المستأجرين مبنية على Fastify، و PostgreSQL مع FTS5،
وخدمة تضمينات اختيارية للبحث الدلالي.
البنية عالية المستوى
[CODE BLOCK]
المكوّنات الأساسية
1. Synapse API (Fastify)
خادم HTTP الرئيسي. يتولى:
- نقاط نهاية REST (، ، ، إلخ)
- المصادقة (Mind Key للوكلاء، JWT للبشر)
- حدود المعدل (مصادقة  فقط)
- تقديم الملفات الثابتة (واجهة الويب في ، ، إلخ)
- إرسال الـ webhooks
بُني بـ Fastify 5 للأداء. يعمل على المنفذ 12800 في الإنتاج.
2. PostgreSQL مع FTS5
مخزن البيانات الأساسي. يستخدم PostgreSQL مع امتداد FTS5 للبحث
بنص كامل.
الجداول الرئيسية:
| الجدول | الغرض |
|-------|---------|
|  | حسابات المستخدمين |
|  | نطاقات العقل (لكل واحد Mind Key) |
|  | سجلات الذاكرة مع جدول FTS5 الافتراضي |
|  | إدارة المهام |
|  | سجل الدردشة |
|  | السكربتات الدائمة |
|  | تسجيلات الـ webhooks |
|  | المهام المجدولة |
|  | تخزين القيم الأساسية |
|  | مسار التدقيق |
يُمكّن FTS5 بحثًا نصيًا كاملًا أقل من مللي ثانية عبر جميع محتويات الذاكرة.
راجع بحث FTS5 للتفاصيل.
3. خدمة التضمينات (اختيارية)
للبحث الدلالي، يُولّد Synapse تضمينات متجهة لمحتوى الذاكرة.
تُخزّن بجانب الذكريات وتُستخدم للبحث عن التشابه.
- المزوّد: قابل للإعداد (OpenAI، نموذج محلي، إلخ)
- يُخزَّن كعمود  في جدول 
- يُستخدم بواسطة نقطة النهاية 
- راجع البحث الدلالي
4. خادم MCP (خدمة منفصلة)
يعمل خادم Synapse MCP كعملية منفصلة (المنفذ 13100). يقوم بـ:
- عرض 79 أداة عبر Model Context Protocol
- دعم نقل stdio و HTTP/SSE و WebSocket
- ترجمة استدعاءات أدوات MCP إلى استدعاءات Synapse API
- متعدد المستأجرين: Mind Key واحد لكل جلسة
5. وكيل المتصفح (خدمة منفصلة)
لأتمتة المتصفح، تعمل خدمة منفصلة قائمة على Playwright على المنفذ 13000.
يمكن لخادم MCP استدعاؤها لأدوات .
6. وكيل SSH (خدمة منفصلة)
لأوامر SSH البعيدة، تعمل خدمة منفصلة على المنفذ 12900.
نموذج تعدد المستأجرين
[CODE BLOCK]
كل عقل معزول تمامًا. تمنح Mind Keys الوصول إلى عقل واحد فقط.
تمنح JWTs الوصول إلى حساب المستخدم (لإدارة العقول).
راجع تعدد المستأجرين للتفاصيل.
تدفق الطلبات
طلب تخزين الذاكرة
[CODE BLOCK]
طلب بحث الذاكرة
[CODE BLOCK]
النشر
يُنشر Synapse كحاوية Docker. راجع :
[CODE BLOCK]
خصائص الأداء
| العملية | زمن الاستجابة | الإنتاجية |
|-----------|---------|------------|
| تخزين ذاكرة | 5 مللي ث | 1000+ طلب/ث |
| استدعاء ذاكرة | 20 مللي ث | 500 طلب/ث |
| بحث FTS5 | 10 مللي ث | 800 طلب/ث |
| بحث دلالي | 50 مللي ث | 200 طلب/ث |
| استطلاع الدردشة | 5 مللي ث | 2000 طلب/ث |
الخطوات التالية
- نموذج الذاكرة
- تعدد المستأجرين
- بحث FTS5

────────────────────────────────────────────────────────────
# البحث النصي الكامل FTS5
SUMMARY: كيف يستخدم Synapse SQLite FTS5 للبحث النصي الكامل في الذاكرة بزمن أقل من مللي ثانية.

البحث النصي الكامل FTS5
يستخدم Synapse امتداد FTS5 (Full-Text Search 5) للبحث السريع والمرن في الذاكرة.
تشرح هذه الصفحة كيف يعمل وكيفية استخدامه بفعالية.
ما هو FTS5؟
FTS5 امتداد SQLite (متاح أيضًا في PostgreSQL عبر امتدادات) يُوفّر قدرات
البحث النصي الكامل. يقوم بـ:
- فهرسة المحتوى النصي للبحث السريع بالكلمات المفتاحية
- دعم المعاملات المنطقية (AND، OR، NOT)
- دعم مطابقة العبارات مع علامات الاقتباس
- دعم مطابقة البادئات مع 
- ترتيب النتائج حسب الصلة
يستخدم Synapse امتداد FTS5 لفهرسة جميع محتويات الذاكرة، مما يُمكّن البحث بزمن
أقل من مللي ثانية عبر آلاف الذكريات.
كيف يستخدم Synapse FTS5
عند تنفيذ :
1. يُخزَّن محتوى الذاكرة في جدول 
2. يُدرج المحتوى أيضًا في الجدول الافتراضي FTS5
3. يقوم FTS5 تلقائيًا بتجزئة المحتوى وفهرسته
عند تنفيذ :
1. يحلل Synapse الاستعلام باستخدام صياغة FTS5
2. ينفذ  مقابل فهرس FTS5
3. يصفّي حسب  (عزل المستأجر)
4. يُرجع النتائج مرتّبة
صياغة الاستعلام
بحث بالكلمات المفتاحية البسيطة
[CODE BLOCK]
يُرجع الذكريات التي تحتوي على "docker".
كلمات مفتاحية متعددة (AND ضمني)
[CODE BLOCK]
يُرجع الذكريات التي تحتوي على "docker" AND "swarm" معًا.
مطابقة العبارات
[CODE BLOCK]
يُرجع الذكريات التي تحتوي على العبارة الدقيقة "docker swarm".
مطابقة البادئات
[CODE BLOCK]
يُرجع الذكريات التي تحتوي على كلمات تبدأ بـ "docker" (مثل "dockers"،
"dockerfile"، "dockerize").
OR المنطقية
[CODE BLOCK]
يُرجع الذكريات التي تحتوي على "docker" OR "kubernetes".
NOT المنطقية
[CODE BLOCK]
يُرجع الذكريات التي تحتوي على "docker" وليس "swarm".
التجميع
[CODE BLOCK]
يُرجع الذكريات التي تحتوي على "docker" أو "kubernetes"، لكن ليس "test".
أمثلة عملية
البحث عن ذكريات حول مشروع
[CODE BLOCK]
البحث عن عبارة دقيقة
[CODE BLOCK]
استبعاد ذكريات الاختبار
[CODE BLOCK]
البحث حسب التقنية
[CODE BLOCK]
الترتيب
يرتّب FTS5 النتائج حسب الصلة باستخدام خوارزمية BM25. العوامل:
- تكرار المصطلح (كم مرة يظهر المصطلح)
- معكوس تكرار المستند (المصطلحات النادرة تُرتّب أعلى)
- طول المستند (المستندات الأقصر التي تحتوي على المصطلح تُرتّب أعلى)
- وزن العمود (العنوان > المحتوى)
تُرجع النتائج بترتيب الصلة (الأكثر صلة أولًا).
الأداء
| العملية | زمن الاستجابة |
|-----------|---------|
| البحث في 100 ذاكرة | < 5 مللي ث |
| البحث في 1,000 ذاكرة | < 10 مللي ث |
| البحث في 10,000 ذاكرة | < 25 مللي ث |
| البحث في 100,000 ذاكرة | < 100 مللي ث |
FTS5 مُحسّن للغاية لأحمال العمل الكثيفة القراءة.
القيود
الاشتقاق
FTS5 لا يقوم بالاشتقاق افتراضيًا. "running" و "run" مصطلحان مختلفان.
الحل البديل: استخدم مطابقة البادئات: 
التسامح مع الأخطاء المطبعية
FTS5 لا يدعم المطابقة الضبابية. خطأ مطبعي سيُرجع نتائج فارغة.
الحل البديل: استخدم البحث الدلالي () للمطابقة
المفاهيمية.
كلمات الوقف
الكلمات الشائعة (the، a، an، is) مفهرسة لكن قد لا تكون مفيدة للبحث.
يتعامل FTS5 مع هذا تلقائيًا.
FTS5 مقابل البحث الدلالي
| الجانب | FTS5 | البحث الدلالي |
|--------|------|-----------------|
| السرعة | أقل من مللي ثانية | 50-100 مللي ث |
| المطابقة | كلمات مفتاحية دقيقة | مفاهيمية |
| التسامح مع الأخطاء | لا شيء | بعض |
| الاشتقاق | لا شيء | ضمني |
| يتطلب تضمينات | لا | نعم |
| الأفضل لـ | مصطلحات محددة | المفاهيم |
استخدم FTS5 عندما تعرف الكلمات المفتاحية. استخدم البحث الدلالي عندما تريد
"ذكريات حول X" حيث يُوصف X بشكل مختلف.
أفضل الممارسات
> [!TIP]
> - استخدم مصطلحات محددة — "docker swarm" أفضل من "container orchestration"
> - اضبط العبارات بين علامات اقتباس —  يضمن مطابقة العبارة
> - استخدم البادئات للاختلافات —  يلتقط "deploy" و "deployment" و "deploying"
> - استبعد الضوضاء —  يصفّي ذكريات الاختبار
> - اجمع مع الوسوم —  يضيّق النتائج
الخطوات التالية
- البحث الدلالي
- Memory API
- أفضل ممارسات الذاكرة

────────────────────────────────────────────────────────────
# نموذج الذاكرة
SUMMARY: كيف تُنظَّم الذكريات — الفئات، المفاتيح، الوسوم، الأولويات، المصادر، التحقق.

نموذج الذاكرة
نموذج ذاكرة Synapse مصمم لوكلاء LLM — منظّم بما يكفي
للاستدعاء الموثوق، ومرن بما يكفي لأي مجال.
تشريح الذاكرة
[CODE BLOCK]
الحقول
| الحقل | النوع | مطلوب | الوصف |
|-------|------|----------|-------------|
|  | string | تلقائي | معرّف فريد (memxxx) |
|  | enum | ✅ | واحدة من 8 فئات |
|  | string | ✅ | مُعرّف ثابت (يُستخدم للتحديثات) |
|  | string | ✅ | محتوى الذاكرة (أي نص) |
|  | string[] | – | للبحث والتصفية |
|  | enum | – | low، normal، high، critical (افتراضي: normal) |
|  | enum | تلقائي | user، agent (من خزّنها) |
|  | bool | تلقائي | هل تحقق منها إنسان؟ |
|  | float | – | 0.0 إلى 1.0 (افتراضي: 1.0 للمستخدم، 0.7 للوكيل) |
|  | timestamp | – | متى تُنسى هذه الذاكرة |
|  | string | تلقائي | أي عقل يملكها |
|  | timestamp | تلقائي | أول تخزين |
|  | timestamp | تلقائي | آخر تعديل |
الفئات
ثماني فئات تغطي حالات استخدام وكلاء LLM الشائعة:
| الفئة | الغرض | مثال على المحتوى |
|----------|---------|-----------------|
|  | من هو المستخدم | "User is Michael Schäfer, software engineer in Berlin" |
|  | تفضيلات المستخدم | "Prefers concise technical responses" |
|  | حقائق قابلة للتحقق | "Office is in Berlin, timezone Europe/Berlin" |
|  | حالة المشروع | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
|  | مهارات المستخدم | "Advanced Python, 10+ years" |
|  | أخطاء سابقة | "Forgot to bump npm version — CI failed" |
|  | سياق الجلسة | "Currently reviewing PR #42" |
|  | ملاحظات متفرقة | "Try Redis for caching next sprint" |
المفاتيح: مُعرّفات ثابتة
الحقل  حاسم — فهو كيف تُحدّث الذكريات دون إنشاء
مكررات.
[CODE BLOCK]
قواعد المفتاح:
- يجب أن يكون فريدًا ضمن (الفئة، العقل)
- استخدم 
- أضف بادئة الفئة للوضوح: ، 
- أبقِه ثابتًا — لا تغيّر المفاتيح بعد الإنشاء
الوسوم: للبحث
تُمكّن الوسوم التصفية والبحث السريع:
[CODE BLOCK]
أفضل ممارسات الوسوم:
- 2-5 وسوم لكل ذاكرة (لا تفرط في الوسم)
- أحرف صغيرة للاتساق
- استخدم أسماء المشاريع، المواضيع، التقنيات
- الوسوم غير حساسة لحالة الأحرف
مستويات الأولوية
| الأولوية | متى تُستخدم | سلوك الاستدعاء |
|----------|-------------|-----------------|
|  | الهوية، القانونية، غير القابلة للتراجع | دائمًا في أعلى الاستدعاء |
|  | المشاريع النشطة، التفضيلات الأساسية | بارز في الاستدعاء |
|  | معظم الذكريات (افتراضي) | ترتيب استدعاء قياسي |
|  | عابرة، جيد معرفتها | قد تُلخّص |
يُرتّب  حسب الأولوية (critical أولًا)، ثم حسب الأحدث.
المصدر: المستخدم مقابل الوكيل
تُوسم الذكريات بـ :
-  — خزّنها إنسان (عبر JWT أو واجهة الإنسان)
-  — خزّنها وكيل LLM (عبر Mind Key)
يؤثر هذا على:
- التحقق: ذكريات  مُتحقّق منها تلقائيًا، ذكريات  لا
- الثقة:  افتراضي 1.0،  0.7
- الاستدعاء: يعلّم  الذكريات غير المُتحقّق منها بـ "(unverified)"
> [!NOTE]
> تعامل مع ذكريات المصدر  بقدر مناسب من الشك. قد تكون
> مستنتجة أو مفترضة بدلًا من ذكرها مباشرة من المستخدم.
التحقق
تشير علامة  إلى أن إنسانًا أكّد الذاكرة:
- ذكريات : مُتحقّق منها تلقائيًا ()
- ذكريات : غير مُتحقّق منها افتراضيًا ()
تحقق من الذكريات عبر:
[CODE BLOCK]
> [!NOTE]
> يتطلب التحقق JWT (مصادقة الإنسان)، وليس Mind Key (مصادقة الوكيل). هذا
> يضمن أن البشر فقط يمكنهم تعليم الذكريات كمُتحقّق منها.
الثقة
يشير الحقل  (0.0 إلى 1.0) إلى موثوقية الذاكرة:
- 1.0 — ذُكرت مباشرة من المستخدم
- 0.7 — مستنتجة بواسطة الوكيل
- 0.5 — غير مؤكدة، تحتاج تحققًا
- 0.0 — مشكوك فيها صراحة
عيّن الثقة عند التخزين:
[CODE BLOCK]
الانتهاء
عيّن  للذكريات الحساسة للوقت:
[CODE BLOCK]
الذكريات المنتهية لا يُرجعها  (لكنها لا تزال موجودة في DB).
استخدم  لرؤية الذكريات التي تنتهي قريبًا.
دورة حياة الذاكرة
[CODE BLOCK]
سلوك الاستدعاء
يُرجع  ملخصًا نصيًا عاديًا مُحسّنًا لسياق LLM:
[CODE BLOCK]
- مُرتّب حسب الأولوية (critical → low)، ثم حسب الأحدث
- الذكريات غير المُتحقّق منها معلّمة بـ 
- الوسوم مضمنة للسياق
- نص عادي (لا حاجة لتحليل JSON)
الخطوات التالية
- Memory API
- أفضل ممارسات الذاكرة
- بحث FTS5

────────────────────────────────────────────────────────────
# تعدد المستأجرين والعزل
SUMMARY: كيف يعزل Synapse البيانات بين المستخدمين والعقول — شرح حدود الأمان.

تعدد المستأجرين والعزل
Synapse متعدد المستأجرين: عدة مستخدمين، كلٌّ بعدة عقول، معزولون تمامًا
عن بعضهم البعض. تشرح هذه الصفحة نموذج العزل.
التسلسل الهرمي للمستأجرين
[CODE BLOCK]
مستويات العزل
المستوى 1: عزل المستخدم
كل حساب مستخدم معزول. لا تستطيع Alice:
- رؤية عقول Bob
- الوصول إلى ذكريات Bob (حتى مع JWT الخاص بها)
- سرد معلومات حساب Bob
يُفرض عبر: عمود  في جميع الجداول، يحتوي JWT على ، جميع
الاستعلامات تُصفّي حسب .
المستوى 2: عزل العقل
ضمن مستخدم، كل عقل معزول. لا يستطيع العقل A:
- رؤية ذكريات العقل B
- الوصول إلى مهام العقل B، الدردشة، السكربتات
يُفرض عبر: عمود  في جميع جداول البيانات، يحتوي Mind Key على ،
جميع الاستعلامات تُصفّي حسب .
> [!CRITICAL]
> عزل Mind Key هو حدود الأمان الأساسية. Mind Key المُسرّب
> يمنح وصولًا كاملًا لبيانات ذلك العقل — لكن ذلك العقل فقط.
رموز المصادقة
| الرمز | النطاق | ما يستطيع الوصول إليه |
|-------|-------|-------------------|
| Mind Key | عقل واحد | بيانات ذلك العقل فقط |
| JWT | حساب المستخدم | إدارة الحساب (إنشاء/سرد/حذف العقول) |
| Computer Token | جهاز واحد | أوامر ذلك الجهاز |
الوصول عبر العقول
ضمن نفس المستخدم
يستطيع المستخدم الوصول إلى جميع عقله عبر JWT (مثلًا  يسرد الكل).
لكن لقراءة/كتابة بيانات الذاكرة، يحتاج إلى Mind Key المحدد.
عبر المستخدمين
لا يستطيع المستخدمون الوصول إلى بيانات بعضهم البعض — إلا إذا شاركوا عقلًا صراحةً
عبر Sharing API:
[CODE BLOCK]
بعد المشاركة، يستطيع Bob الوصول إلى العقل A عبر JWT الخاص به (للقراءة فقط إذا ).
حدود الأمان
[CODE BLOCK]
أنماط تعدد المستأجرين الشائعة
النمط 1: مستخدم واحد، عقل واحد
الأكثر شيوعًا لمستخدمي وكلاء LLM الأفراد.
- 1 حساب مستخدم
- 1 عقل
- 1 Mind Key
- جميع الذكريات في نطاق واحد
النمط 2: مستخدم واحد، عقول متعددة
للمستخدمين ذوي السياقات المتعددة (العمل، الشخصي، المشاريع).
- 1 حساب مستخدم
- N عقول (مثلًا "work"، "personal"، "project-x")
- N من Mind Keys
- كل جلسة LLM تستخدم Mind Key واحد
النمط 3: عقل مشترك للفريق
للفرق المتعاونة على مشروع.
- مستخدم واحد ينشئ العقل (يحصل على Mind Key)
- المنشئ يشارك مع أعضاء الفريق عبر JWT
- جميع أعضاء الفريق يصلون عبر JWT (أو Mind Key مشترك)
> [!WARNING]
> مشاركة Mind Key تمنح وصولًا كاملًا للقراءة/الكتابة. للتعاون الجماعي،
> فضّل Sharing API (قائم على JWT) بدلًا من مشاركة Mind Keys مباشرة.
النمط 4: مزوّد SaaS
للتطبيقات التي تُضمّن Synapse كطبقة ذاكرة لها.
- كل عميل = 1 حساب مستخدم
- كل مشروع عميل = 1 عقل
- التطبيق يخزّن Mind Keys لكل عميل/مشروع
- عزل كامل بين العملاء
التحقق من العزل
اختبار: Mind Key لا يستطيع الوصول إلى عقول أخرى
[CODE BLOCK]
اختبار: JWT لا يستطيع قراءة بيانات الذاكرة مباشرة
[CODE BLOCK]
أفضل الممارسات
> [!TIP]
> - استخدم عقلًا واحدًا لكل مشروع/سياق — العزل صديقك
> - لا تشارك Mind Keys أبدًا — استخدم Sharing API بدلًا من ذلك
> - دوّر Mind Keys إذا تعرّضت للاختراق (احذف العقل، أنشئ واحدًا جديدًا)
> - دقّق العقول المشتركة — راجع  دوريًا
> - استخدم JWT لواجهة الإنسان — لا ت expose Mind Keys للمستخدمين النهائيين
الخطوات التالية
- المصادقة
- Mind Key مقابل JWT
- البنية

────────────────────────────────────────────────────────────
# البحث الدلالي (التضمينات)
SUMMARY: بحث مفاهيمي في الذاكرة باستخدام التضمينات المتجهة — ابحث بالمعنى، لا بالكلمات المفتاحية فقط.

البحث الدلالي (التضمينات)
يدعم Synapse البحث الدلالي باستخدام التضمينات المتجهة. على عكس FTS5 (مطابقة
الكلمات المفتاحية)، يجد البحث الدلالي الذكريات بـ المعنى — حتى لو لم تتطابق
الكلمات المفتاحية.
كيفية العمل
[CODE BLOCK]
ما هي التضمينات؟
التضمينات تمثيلات متجهة عددية للنص. النص ذو المعنى المماثل له متجهات مماثلة.
يُولّد Synapse متجهًا (مثلًا 1536 بُعدًا) لكل محتوى ذاكرة.
تشابه جيب التمام
لإيجاد الذكريات المتشابهة دلاليًا، يحسب Synapse تشابه جيب التمام
بين متجه الاستعلام ومتجه كل ذاكرة. تشابه أعلى = صلة
أكبر.
متى تستخدم البحث الدلالي
استخدم البحث الدلالي عندما:
- تريد "ذكريات حول X" حيث يُوصف X بشكل مختلف عن المخزّن
- لا يُرجع FTS5 نتائج (لا مطابقة للكلمات المفتاحية)
- تريد تجميعًا مفاهيميًا (مثلًا جميع ذكريات "النشر"، حتى لو قال بعضها "release")
- الاستعلام سؤال: "كيف نتعامل مع المصادقة؟"
استخدم FTS5 عندما:
- تعرف الكلمات المفتاحية الدقيقة
- تحتاج منطقًا منطقيًا (AND، OR، NOT)
- تحتاج استجابة أقل من مللي ثانية
- تريد مطابقة العبارات
نقطة النهاية
GET /memory/semantic-search
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
أمثلة
إيجاد ذكريات النشر
[CODE BLOCK]
يُرجع الذكريات حول "deployment" و "release" و "publishing" و "rolling out"،
إلخ.
إيجاد أنماط المصادقة
[CODE BLOCK]
يُرجع الذكريات حول login و auth و JWT و إدارة الجلسة و OAuth، إلخ.
إيجاد ذكريات مماثلة
[CODE BLOCK]
يستخدم التشابه الدلالي (عبر الوسوم المشتركة AND متجهات التضمين).
توليد التضمينات
متى تُولّد التضمينات؟
- عند تخزين الذاكرة — إذا كانت خدمة التضمينات مُعدّة، يُولّد التضمين تزامنيًا
- التوليد الدفعي — يُولّد  تضمينات للذكريات المفتقرة إليها
- التحديثات غير المتزامنة — عند تحديث المحتوى، يُعاد توليد التضمين
مزوّدو التضمينات
يدعم Synapse مزوّدي تضمينات قابلين للإعداد:
- OpenAI (، )
- النماذج المحلية (عبر Ollama أو ما شابه)
- مخصص (نفّذ واجهة التضمينات)
الإعداد عبر متغيرات البيئة:
[CODE BLOCK]
التوليد الدفعي
للعقول التي تفتقر ذكرياتها الكثيرة إلى التضمينات:
[CODE BLOCK]
الأداء
| العملية | زمن الاستجابة |
|-----------|---------|
| توليد تضمين (OpenAI) | 100-200 مللي ث |
| بحث دلالي (1k ذاكرة) | 50-100 مللي ث |
| بحث دلالي (10k ذاكرة) | 200-500 مللي ث |
| توليد دفعي (100 ذاكرة) | 10-20 ث |
> [!NOTE]
> البحث الدلالي أبطأ من FTS5 بسبب حساب المتجهات. استخدم FTS5
> للكلمات المفتاحية المعروفة، والدلالي للاستعلامات المفاهيمية.
القيود
تكلفة التضمينات
إذا كنت تستخدم OpenAI، فإن توليد التضمينات يكلف مالًا ($0.02 لكل 1M رمزًا
لـ text-embedding-3-small). لـ 10,000 ذاكرة بمتوسط 100 رمز لكل واحدة،
هذا $0.02 — ضئيل.
البدء البارد
الذكريات المخزّنة قبل إعداد التضمينات لن تملك تضمينات. شغّل
 للتعبئة الخلفية.
اعتماد على المزوّد
إذا كان مزوّد التضمينات متوقفًا، يفشل البحث الدلالي بلطف (يُرجع
نتائج فارغة أو خطأ). FTS5 لا يزال يعمل.
عندما لا تتوفر التضمينات
إذا لم تُعدّ خدمة التضمينات:
- يُرجع  503 Service Unavailable
- لا يزال  يعمل (فقط لا يُولّد تضمين)
- بحث FTS5 لا يزال يعمل
أفضل الممارسات
> [!TIP]
> - استخدم الدلالي للاستعلامات المفاهيمية — "كيف نتعامل مع X؟"
> - استخدم FTS5 للمصطلحات المحددة — "docker swarm"
> - املأ التضمينات الخلفية دوريًا — 
> - راقب صحة المزوّد — البحث الدلالي يعتمد عليه
> - اجمع مع الوسوم — الدلالي + تصفية الوسوم تضيّق النتائج
الخطوات التالية
- بحث FTS5
- Memory API
- البنية

## الفئة: كتاب وصفات LLM
وصفات وأنماط لعملاء LLM.

────────────────────────────────────────────────────────────
# نمط استطلاع الدردشة
SUMMARY: كيف تستطلع لرسائل الإنسان بين استدعاءات الأدوات دون حجب سير عملك.

نمط استطلاع الدردشة
نظام الدردشة غير متزامن — يستطيع البشر ترك رسائل أثناء عملك.
يُظهر هذا النمط كيف تستطلع للرسائل دون حجب سير عملك.
النمط
[CODE BLOCK]
استطلع بين استدعاءات الأدوات، لا في حلقة ضيقة.
لماذا تستطلع بين استدعاءات الأدوات؟
- لا تحجب — الاستطلاع في حلقة ضيقة يهدر استدعاءات API
- لا تفوّت رسائل — الاستطلاع غير المتكرر يعني استجابات بطيئة
- النقطة المثلى — استطلع كل 30-60 ثانية، أو بعد كل استدعاء أداة
التنفيذ
استطلاع أساسي
[CODE BLOCK]
النمط 1: استطلع بعد كل استدعاء أداة
[CODE BLOCK]
النمط 2: استطلاع قائم على الوقت
[CODE BLOCK]
النمط 3: مدفوع بالأحداث (مع webhooks)
للإشعار اللحظي، سجّل webhook:
[CODE BLOCK]
ثم يستطيع معالج الـ webhook إيقاظ الوكيل:
[CODE BLOCK]
أنماط معالجة الرسائل
النمط: أقرّ ثم عالج
[CODE BLOCK]
النمط: أدرج في الطابور للمعالجة الدفعية
[CODE BLOCK]
النمط: توجيه بالأولوية
[CODE BLOCK]
تكرار الاستطلاع
| حالة الاستخدام | التكرار |
|----------|-----------|
| وكيل تفاعلي (إنسان ينتظر) | كل 5-10 ثوانٍ |
| وكيل خلفي | كل 30-60 ثانية |
| معالجة دفعية | كل 5 دقائق |
| مدفوع بالـ webhook | لا تستطلع — استخدم webhooks |
> [!WARNING]
> الاستطلاع أكثر من مرة كل 5 ثوانٍ يهدر استدعاءات API. تُرجع نقطة نهاية 
> فورًا إذا كانت هناك رسائل معلّقة، لذا لا فائدة من
> استطلاع أسرع.
دردشة الوكلاء المتعددين
لتواصل الوكيل-إلى-الوكيل:
[CODE BLOCK]
أفضل الممارسات
> [!TIP]
> - استطلع بين استدعاءات الأدوات — لا في حلقة ضيقة
> - أقرّ فورًا — يعرف الإنسان أنك تلقيت الرسالة
> - عالج بشكل غير متزامن — لا تحجب على العمل الطويل
> - استخدم webhooks للوقت الحقيقي — الاستطلاع له زمن استجابة
> - لا تستطلع أكثر من مرة كل 5 ثوانٍ — يهدر استدعاءات API
مشكلات شائعة
رسائل تضيع
-  يُعلّم الرسائل كمقروءة تلقائيًا
- إذا لم تعالجها، فقد ضاعت
- الإصلاح: عالج الرسائل دائمًا قبل العودة
ردود مكررة
- إذا تعطّل معالجك، قد ترد مرتين
- الإصلاح: اجعل المعالج idempotent (تحقق إذا أُجبت بالفعل)
استجابات بطيئة
- الاستطلاع كل 60 ثانية يعني زمن استجابة حتى 60 ثانية
- الإصلاح: استطلع كل 10-30 ثانية، أو استخدم webhooks
الخطوات التالية
- Chat API
- نمط بدء الجلسة
- التعافي من الأخطاء

────────────────────────────────────────────────────────────
# التعافي من الأخطاء للوكلاء
SUMMARY: كيف يتعامل وكلاء LLM مع الأخطاء ويتعافون منها — إعادة المحاولة، التخزين، التعلم.

التعافي من الأخطاء للوكلاء
الأخطاء تحدث. الشبكات تفشل، APIs تُرجع 500، Mind Keys تنتهي. يُظهر هذا الدليل
كيف ينبغي لوكلاء LLM التعامل مع الأخطاء بلطف والتعلّم منها.
مبادئ معالجة الأخطاء
1. أعد المحاولة مع تراجع — الأخطاء العابرة تُحل غالبًا
2. خزّن الخطأ — تعلّم من الأنماط
3. تدهور بلطف — لا تُعطّل الجلسة كاملة
4. أبلغ الإنسان — للأخطاء التي لا تستطيع حلها
معالجة أخطاء HTTP
إعادة المحاولة مع تراجع أُسي
[CODE BLOCK]
معالجة خطأ المصادقة
[CODE BLOCK]
تخزين الأخطاء كذكريات
عند وقوع أخطاء، خزّنها حتى تتعلّم الجلسات المستقبلية:
[CODE BLOCK]
سيناريوهات أخطاء شائعة
السيناريو 1: Mind Key غير صالح
[CODE BLOCK]
السيناريو 2: خطأ شبكة
[CODE BLOCK]
السيناريو 3: محدود بحد المعدل
[CODE BLOCK]
السيناريو 4: خطأ خادم (5xx)
[CODE BLOCK]
السيناريو 5: فشل استدعاء أداة
[CODE BLOCK]
النمط: قاطع الدائرة
للإخفاقات المتكررة، توقف عن المحاولة مؤقتًا:
[CODE BLOCK]
أفضل الممارسات
> [!TIP]
> - أعد محاولة الأخطاء العابرة دائمًا — الشبكات تفشل، الخوادم تتأرجح
> - لا تعد محاولة أخطاء العميل (4xx) — لن تُصلح نفسها
> - خزّن الأخطاء كذكريات — تعلّم من الأنماط
> - أبلغ البشر عن الأخطاء الحرجة — يحتاجون المعرفة
> - تدهور بلطف — العمل الجزئي أفضل من الانهيار
> - استخدم قواطع الدائرة — لا تقصف خدمة فاشلة
الخطوات التالية
- مرجع الأخطاء API
- نمط بدء الجلسة
- اختبارات ذاتية الإصلاح

────────────────────────────────────────────────────────────
# استراتيجية وسوم الذاكرة
SUMMARY: كيف تُوسم الذكريات للبحث والتصفية الفعالة — نظام الوسوم القابل للتوسع.

استراتيجية وسوم الذاكرة
الوسوم سر استرجاع الذاكرة القابل للتوسع. يُظهر هذا الدليل كيف تُوسم
الذكريات حتى تعود الصحيحة في الوقت المناسب.
لماذا تهم الوسوم
بدون الوسوم، لديك بحث نصي كامل مسطح. مع الوسوم، لديك تنقل
منظم:
[CODE BLOCK]
تُمكّن الوسوم:
- تصفية سريعة — 
- بحث محدود — 
- تجميع — أوجد جميع ذكريات "الأخطاء" لمشروع
- إسناد متبادل — الذكريات التي تشارك الوسوم مرتبطة
مخطط الوسوم
وسوم المشروع
استخدم أسماء المشاريع كوسوم:
[CODE BLOCK]
وسوم التقنية
استخدم أسماء التقنيات:
[CODE BLOCK]
وسوم المواضيع
استخدم فئات المواضيع:
[CODE BLOCK]
وسوم الحالة
استخدم مؤشرات الحالة:
[CODE BLOCK]
وسوم النوع
استخدم مؤشرات النوع:
[CODE BLOCK]
قواعد الوسم
القاعدة 1: 2-5 وسوم لكل ذاكرة
وسوم قليلة جدًا = قابلية اكتشاف ضعيفة. كثيرة جدًا = ضوضاء.
[CODE BLOCK]
القاعدة 2: أحرف صغيرة، بوصلات
[CODE BLOCK]
القاعدة 3: استخدم مفردات متسقة
أنشئ مفردات وسم والتزم بها:
[CODE BLOCK]
القاعدة 4: وسم بنية البحث
اسأل: "كيف سأبحث عن هذه الذاكرة؟"
[CODE BLOCK]
الأنماط
النمط 1: مشروع + موضوع
[CODE BLOCK]
بحث:  (جميع ذكريات مشروع Synapse)
بحث:  (ذكريات النشر في Synapse)
النمط 2: نوع + مجال
[CODE BLOCK]
بحث:  (جميع الأخطاء)
بحث:  (أخطاء النشر)
النمط 3: هرمي
لمشاريع فرعية ضمن مشروع:
[CODE BLOCK]
بحث:  (كل Synapse)
بحث:  (المشروع الفرعي docs فقط)
النمط 4: تتبع الحالة
[CODE BLOCK]
حالات الاستخدام الشائعة
إيجاد جميع القرارات حول مشروع
[CODE BLOCK]
إيجاد جميع الأخطاء في مجال
[CODE BLOCK]
إيجاد العمل النشط
[CODE BLOCK]
إيجاد ذكريات حول تقنية
[CODE BLOCK]
صيانة الوسوم
مراجعة دورية
[CODE BLOCK]
دمج الوسوم
إذا كان لديك وسوم غير متسقة ( و )، ادمجها:
[CODE BLOCK]
أفضل الممارسات
> [!TIP]
> - أنشئ المفردات مبكرًا — وسوم متسقة من اليوم الأول
> - وسم بنية البحث — كيف ستجد هذا لاحقًا؟
> - 2-5 وسوم هي النقطة المثلى — قليلة جدًا أو كثيرة جدًا سيئة
> - أحرف صغيرة + وصلات —  لا 
> - راجع دوريًا — ادمج المكررات، احذف غير المستخدمة
الخطوات التالية
- أفضل ممارسات الذاكرة
- بحث FTS5
- سير العمل المدفوع بالمهام

────────────────────────────────────────────────────────────
# نمط بدء الجلسة
SUMMARY: تسلسل بدء الجلسة القانوني الذي يجب أن يتبعه كل وكيل LLM.

KEY CONTEXT:
ALWAYS at session start: 1) GET /memory/recall, 2) GET /chat/poll, 3) GET /mind/tasks?status=in_progress
Build system prompt from recall output.
Process unread chat messages before doing new work.
Resume any in_progress tasks before starting new ones.
Store new learnings as they happen — don't wait until session end.

نمط بدء الجلسة
كل جلسة وكيل LLM يجب أن تتبع تسلسل بدء التشغيل القانوني هذا. تخطي
الخطوات يؤدي إلى فقدان السياق، تفويت الرسائل، ونسيان المهام.
النمط
[CODE BLOCK]
التنفيذ
الخطوة 1: استدعِ جميع الذكريات
> [!CRITICAL]
> هذا أهم استدعاء. بدونه، ليس لديك ذاكرة بالجلسات
> السابقة.
[CODE BLOCK]
يُرجع ملخصًا نصيًا عاديًا لجميع الذكريات، مرتّبًا حسب الأولوية.
الخطوة 2: استطلع للرسائل غير المقروءة
[CODE BLOCK]
يُرجع الرسائل غير المقروءة من الإنسان. يُعلّمها كمقروءة تلقائيًا.
الخطوة 3: تحقق من المهام قيد التقدم
[CODE BLOCK]
يُرجع المهام التي كنت تعمل عليها في الجلسة الأخيرة.
الخطوة 4: ابنِ السياق
اجمع الاستجابات الثلاث في system prompt الخاص بك:
[CODE BLOCK]
الخطوة 5: عالج العناصر المعلّقة
[CODE BLOCK]
مثال كامل
[CODE BLOCK]
أخطاء شائعة
> [!WARNING]
> - تخطي الاستدعاء — تبدأ بلا سياق، تكرر الأخطاء السابقة
> - نسيان استطلاع الدردشة — رسائل الإنسان تذهب بلا رد
> - تجاهل المهام النشطة — العمل يُنسى في منتصف التنفيذ
> - عدم تخزين شيء — الجلسة لا تنتج قيمة دائمة
تنويعات
النمط الأدنى (LLMs بسياق صغير)
لـ LLMs بنوافذ سياق صغيرة، تخطَّ الاستدعاء الكامل:
[CODE BLOCK]
ثم ابحث عن مواضيع محددة حسب الحاجة:
[CODE BLOCK]
النمط العدواني (وكلاء طويلو الأمد)
لوكلاء يعملون لساعات، أضف إعادة استدعاء دورية:
[CODE BLOCK]
الخطوات التالية
- استراتيجية وسوم الذاكرة
- سير العمل المدفوع بالمهام
- نمط استطلاع الدردشة

────────────────────────────────────────────────────────────
# سير العمل المدفوع بالمهام
SUMMARY: استخدم مهام Synapse لقيادة سير عمل LLM متعدد الخطوات يبقى عبر الجلسات.

سير العمل المدفوع بالمهام
المهام ليست مجرد مهام عادية — إنها العمود الفقري لسير عمل LLM الدائم.
بإنشاء مهام للعمل متعدد الخطوات، تضمن الاستمرارية عبر الجلسات
وتوفر مسارات تدقيق لما تم.
لماذا مدفوع بالمهام؟
بدون مهام:
- يبدأ LLM كل جلسة غير متأكد ماذا يفعل
- العمل متعدد الخطوات يُنسى في منتصف التنفيذ
- لا يوجد سجل بما تم
مع المهام:
- يستأنف LLM المهام قيد التقدم فورًا
- العمل متعدد الخطوات يبقى عبر الجلسات
- مسار تدقيق مدمج لكل العمل
النمط
[CODE BLOCK]
التنفيذ
الخطوة 1: أنشئ مهمة للعمل متعدد الخطوات
[CODE BLOCK]
الخطوة 2: تتبع التقدم في وصف المهمة
[CODE BLOCK]
الخطوة 3: الاستئناف عبر الجلسات
[CODE BLOCK]
الخطوة 4: أكمل وأرشف
[CODE BLOCK]
مثال كامل: سير عمل النشر
[CODE BLOCK]
التسلسل الهرمي للمهام
للعمل المعقد، استخدم علاقات المهام الأب-الابن:
[CODE BLOCK]
ابحث عن المهام الفرعية:
[CODE BLOCK]
سير العمل للحالة
[CODE BLOCK]
Pending
مهمة أُنشئت لكن لم تبدأ. استخدم للعمل المخطط.
In Progress
يجري العمل عليها حاليًا. حدّث الوصف بالتقدم.
Done
أُكملت بنجاح. يجب أن يتضمن الوصف الملخص.
Cancelled
متروكة. يجب أن يتضمن الوصف السبب.
أفضل الممارسات
> [!TIP]
> - أنشئ مهام للعمل متعدد الخطوات — العمل أحادي الخطوة لا يحتاج مهمة
> - حدّث الوصف بالتقدم — يُمكّن الاستئناف
> - استخدم أولوية عالية للعمل النشط — يظهر في الاستدعاء
> - أكمل المهام عند الانتهاء — لا تتركها inprogress
> - خزّن ملخصات الإكمال كذكريات — مرجع طويل الأمد
أنماط شائعة
النمط: سير عمل إصلاح خطأ
[CODE BLOCK]
النمط: سير عمل البحث
[CODE BLOCK]
الخطوات التالية
- نمط بدء الجلسة
- نمط استطلاع الدردشة
- التعافي من الأخطاء

## الفئة: الأسئلة الشائعة
الأسئلة الشائعة والمشاكل المتكررة.

────────────────────────────────────────────────────────────
# الأسئلة الشائعة عن الـ API
SUMMARY: أسئلة شائعة عن الـ API — المصادقة، حدود المعدل، معالجة الأخطاء، اكتشاف نقاط النهاية.

الأسئلة الشائعة عن الـ API
أسئلة شائعة عن واجهة Synapse API.
كيف أُصادق؟
طريقتان:
1. Mind Key (لنقاط بيانات النهاية): 
2. JWT (لنقاط نهاية الحساب): 
أو عبر معامل الاستعلام (حد 60 طلبًا/دقيقة): 
راجع المصادقة.
ما الفرق بين Mind Key و JWT؟
- Mind Key: محدود بمستأجر، لا ينتهي، لبيانات الذاكرة/الدردشة/المهام
- JWT: محدود بالمستخدم، ينتهي بعد 7 أيام، لإدارة الحساب/العقل
راجع Mind Key مقابل JWT.
لماذا أحصل على 401 Unauthorized؟
أسباب شائعة:
1. ترويسة  مفقودة
2. Mind Key غير صالح (تحقق أنه يبدأ بـ )
3. استخدام JWT حيث يُطلب Mind Key (أو العكس)
4. تم إبطال Mind Key
الإصلاح: تحقق من رمزك. راجع المصادقة.
لماذا أحصل على 404 Not Found؟
استخدمت مسار نقطة نهاية خاطئًا. يمتلك Synapse فقط المسارات المذكورة في
.
الإصلاح: استدعِ  لرؤية جميع المسارات الصالحة. لا تخمّن.
لماذا أحصل على 429 Too Many Requests؟
تستخدم مصادقة معامل الاستعلام ، المحدودة بـ 60/دقيقة.
الإصلاح: بدّل إلى ترويسة  (بلا حد معدل).
راجع حدود المعدل.
كيف أُدرج جميع نقاط النهاية؟
[CODE BLOCK]
كيف أجد نقطة النهاية المناسبة؟
1. تحقق من  للقائمة القابلة للقراءة آليًا
2. تحقق من  لوثائق API الكاملة
3. تصفّح  لنظام الوثائق
4. استخدم  لمواصفات OpenAPI 3.0
هل يمكنني استخدام GET بدلًا من POST؟
بعض نقاط POST لها مكافئات GET للأدوات التي تفتح عناوين URL فقط:
-  ↔ 
-  ↔ 
-  ↔ 
تحقق من  لمتغيرات GET المتاحة.
كيف أتعامل مع الأخطاء؟
تُرجع جميع الأخطاء JSON:
[CODE BLOCK]
راجع الأخطاء ومعالجتها.
ما حد حجم نص الطلب؟
10 ميجابايت. للحمولات الأكبر (مثل رفع الملفات)، استخدم نقاط النهاية multipart.
هل يدعم الـ API CORS؟
نعم. جميع نقاط النهاية تُرجع:
[CODE BLOCK]
هل توجد حزمة SDK؟
نعم:
- Node.js: 
- MCP: 
راجع نظرة عامة على الـ API للتفاصيل.
كيف أتصفّح؟
استخدم  و :
[CODE BLOCK]
الحد الافتراضي: 100. الحد الأقصى: 500.
هل أستطيع تصفية الذكريات حسب الفئة أو الوسم؟
نعم:
[CODE BLOCK]
كيف أبحث في الذكريات؟
بطريقتين:
1. بحث FTS5 بالكلمات المفتاحية: 
2. البحث الدلالي: 
راجع بحث FTS5 و البحث الدلالي.
كيف أُحدّث ذاكرة؟
استدعِ  بنفس  +  — تُحدَّث الذاكرة
الموجودة، لا تُكرّر.
[CODE BLOCK]
كيف أحذف ذاكرة؟
[CODE BLOCK]
هل أستطيع الحذف الكمي؟
نعم:
[CODE BLOCK]
الخطوات التالية
- نظرة عامة على الـ API
- الأخطاء ومعالجتها
- المصادقة

────────────────────────────────────────────────────────────
# الأسئلة الشائعة العامة
SUMMARY: أسئلة شائعة عن Synapse — ما هو، كيف يعمل، لمن.

الأسئلة الشائعة العامة
أسئلة شائعة عن Synapse.
ما هو Synapse؟
Synapse واجهة ذاكرة دائمة لوكلاء LLM. يمنح مساعدك الذكي
عقلًا دائمًا قابلاً للاستعلام يبقى عبر الجلسات. بدلًا من
نسيان كل شيء عند إغلاق الدردشة، يخزّن الـ LLM ويسترجع
الذكريات عبر واجهة HTTP بسيطة.
اعرف المزيد: ما هو Synapse؟
لمن Synapse؟
- مطوّرو وكلاء LLM الذين يحتاجون حالة دائمة
- المستخدمون المتقدمون الذين يشغّلون نماذج LLM محلية بوكلاء مخصصين
- الفرق التي تبني مساعدين ذكيين بذاكرة مشتركة
- مهندسو الأتمتة الذين يربطون استدعاءات LLM عبر الجلسات
هل Synapse مجاني؟
Synapse مُستضاف على <https://synapse.schaefer.zone> ومجاني للاستخدام الشخصي.
للاستضافة الذاتية، راجع المستودع.
كيف يختلف Synapse عن ذاكرة ChatGPT؟
| الميزة | ذاكرة ChatGPT | Synapse |
|---------|---------------|---------|
| التخزين | خوادم OpenAI | خادمك |
| وصول الـ API | لا | نعم (REST + MCP) |
| متعدد المستأجرين | لا | نعم (العقول) |
| فئات مخصصة | لا | نعم (8 فئات) |
| البحث النصي الكامل | محدود | FTS5 + دلالي |
| قابل للاستضافة الذاتية | لا | نعم |
أي نماذج LLM تعمل مع Synapse؟
أي LLM يستطيع إجراء استدعاءات HTTP أو استخدام MCP:
- Claude (Anthropic) — عبر MCP أو API مباشر
- GPT-4 / GPT-3.5 (OpenAI) — عبر function calling + API
- Gemini (Google) — عبر function calling + API
- Llama / Mistral (محلي) — عبر تكامل مخصص
- أي LLM عبر خادم Synapse MCP
هل أحتاج لاستضافة Synapse بنفسي؟
لا. النسخة المُستضافة على <https://synapse.schaefer.zone> متاحة للاستخدام
العام. الاستضافة الذاتية اختيارية (للخصوصية، أو التخصيص، أو
البيئات المعزولة عن الشبكة).
كم من البيانات أستطيع تخزينها؟
لا توجد حدود صارمة على النسخة المُستضافة. الاستخدام النموذجي:
- 100-1000 ذاكرة لكل عقل
- 1-10 كيلوبايت لكل ذاكرة (حقل المحتوى)
- الإجمالي: 10 ميجابايت لكل عقل
للمقياس الأكبر، استضف بنفسك.
هل بياناتي خاصة؟
نعم. كل عقل معزول (راجع تعدد المستأجرين).
لا يستطيع المستخدمون الآخرون رؤية بياناتك. مزوّد الاستضافة (Schäfer Services)
لديه وصول لكنه لا يطّلع على بيانات المستخدمين.
لأقصى خصوصية، استضف بنفسك.
هل أستطيع تصدير بياناتي؟
نعم. استخدم  لتصدير جميع الذكريات كـ JSON. راجع
النسخ الاحتياطي والاستعادة.
ماذا يحدث إذا فقدت Mind Key؟
تُعرض Mind Keys مرة واحدة فقط عند الإنشاء. إذا فُقد:
1. سجّل الدخول ببريدك الإلكتروني/كلمة مرورك للحصول على JWT
2. أنشئ عقلًا جديدًا عبر 
3. احفظ Mind Key الجديد
4. (اختياري) احذف العقل القديم عبر 
لا يمكنك استرداد الذكريات من عقل فُقد مفتاحه.
هل يستطيع عدة وكلاء LLM مشاركة عقل؟
نعم. جميع الوكلاء الذين يستخدمون نفس Mind Key يشاركون بيانات ذلك العقل. للعمل
متعدد الوكلاء المنسّق، راجع تنسيق الوكلاء المتعددين.
هل يعمل Synapse دون اتصال؟
لا، يتطلب Synapse اتصال إنترنت بالخادم (إما مُستضاف أو
مستضاف ذاتيًا). لنماذج LLM دون اتصال، شغّل Synapse محليًا.
ما سرعة بحث الذاكرة؟
- بحث FTS5 بالكلمات المفتاحية: < 10 مللي ث لـ 1000 ذاكرة
- البحث الدلالي: 50-100 مللي ث لـ 1000 ذاكرة
- الاستدعاء الكامل: < 50 مللي ث لـ 1000 ذاكرة
راجع بحث FTS5 للتفاصيل.
هل أستطيع استخدام Synapse دون LLM؟
نعم. Synapse واجهة ذاكرة عامة. يمكنك استخدامها من أي تطبيق
يستفيد من تخزين قيم أساسية دائم وقابل للبحث مع فئات
ووسوم.
الخطوات التالية
- ما هو Synapse؟
- البداية السريعة
- أسئلة الـ API الشائعة

────────────────────────────────────────────────────────────
# أسئلة MCP الشائعة
SUMMARY: أسئلة شائعة عن تكامل MCP — الأدوات، النقل، استكشاف الأخطاء.

أسئلة MCP الشائعة
أسئلة شائعة عن خادم Synapse MCP.
ما هو MCP؟
MCP (Model Context Protocol) معيار مفتوح من Anthropic لتكامل
LLM مع الأدوات. بدلًا من لصق وثائق الـ API في الـ prompts، تسجّل الأدوات
مع خادم MCP، ويستدعيها الـ LLM كدوال أصلية.
راجع ما هو MCP؟.
كم أداة يعرض Synapse MCP؟
79 أداة عبر 12 فئة: الذاكرة، الدردشة، المجدول، المهام، السكربتات،
الأجهزة، الإشعارات، المستخدم، الأدوات، التصور، المشاركة، الـ webhooks، المتصفح.
راجع ما هو MCP؟ للقائمة الكاملة.
أي عملاء MCP مدعومون؟
- Claude Desktop (macOS، Windows)
- Claude Code (terminal)
- Cursor (IDE)
- Continue.dev (VS Code، JetBrains)
- Cline (VS Code)
- أي عميل متوافق مع MCP
راجع إعداد Claude Desktop لأمثلة الإعداد.
أي وسائل نقل مدعومة؟
1. stdio (محلي، موصى به لسطح المكتب)
2. HTTP/SSE (بعيد، متعدد المستأجرين)
3. WebSocket (موبايل، حجم عالي)
كيف أُعدّ Claude Desktop؟
حرّر :
[CODE BLOCK]
راجع إعداد Claude Desktop.
لماذا لا تظهر الأدوات في Claude Desktop؟
1. أعد تشغيل Claude Desktop بالكامل (Cmd+Q على macOS)
2. تحقق أن ملف الإعداد JSON صالح
3. تحقق أن Node.js 18+ مثبت
4. تحقق من سجلات MCP: 
راجع استكشاف أخطاء MCP.
كيف أستخدم عقلًا مختلفًا؟
غيّر  في إعداد MCP وأعد تشغيل العميل.
للعقول المتعددة، شغّل عدة نسخ من خادم MCP بمفاتيح
Mind Keys مختلفة.
هل أستطيع تحديد الأدوات المعروضة؟
نعم، استخدم ملفات الأدوات:
- : 8 أدوات مركبة (500 رمز)
- : 25 أداة (2,500 رمز)
- : 119 أداة (8,250 رمز، افتراضي)
عيينها عبر متغير البيئة  أو الترويسة .
كيف أُصحّح مشكلات MCP؟
1. شغّل خادم MCP يدويًا: 
2. تحقق من سجلات العميل (تختلف حسب العميل)
3. تحقق أن Mind Key يعمل: 
4. تحقق من صحة Synapse: 
راجع استكشاف أخطاء MCP.
هل خادم MCP مجاني؟
نعم. حزمة npm  مفتوحة المصدر. خادم MCP المُستضاف
على  مجاني للاستخدام العام.
هل أستطيع استضافة خادم MCP بنفسي؟
نعم:
[CODE BLOCK]
كيف يختلف MCP عن استدعاءات API المباشرة؟
| الجانب | API مباشر | MCP |
|--------|-----------|-----|
| يحتاج LLM معرفة | عناوين URL، الترويسات، المصادقة | أسماء الأدوات فقط |
| معالجة المصادقة | يدوي | تلقائي (متغير البيئة) |
| اكتشاف الأدوات | اقرأ /endpoints | تلقائي عبر بروتوكول MCP |
| معالجة الأخطاء | يدوي | موحّد |
| الأفضل لـ | التكاملات المخصصة | وكلاء LLM |
هل أستطيع بناء عميل MCP خاص بي؟
نعم. استخدم MCP SDK الرسمي:
- TypeScript: 
- Python: 
راجع عميل MCP مخصص.
كيف أُبلّغ عن أخطاء MCP؟
افتح issue: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
أرفق:
- إصدار خادم MCP
- اسم العميل وإصداره
- نظام التشغيل
- السجلات ذات الصلة
- خطوات إعادة الإنتاج
الخطوات التالية
- ما هو MCP؟
- إعداد Claude Desktop
- استكشاف أخطاء MCP

────────────────────────────────────────────────────────────
# الأسئلة الشائعة لاستكشاف الأخطاء
SUMMARY: حلول لمشكلات Synapse الشائعة — المصادقة، الشبكة، البيانات، النشر.

الأسئلة الشائعة لاستكشاف الأخطاء
حلول لمشكلات Synapse الشائعة.
لا أستطيع تسجيل الدخول
الأعراض
- يُرجع  401
- "Invalid email or password"
الحلول
1. تحقق أن البريد الإلكتروني صحيح — حساس لحالة الأحرف
2. تحقق من كلمة المرور — 6 أحرف كحد أدنى
3. سجّل أولًا إذا لم يكن لديك حساب: 
4. أعد تعيين كلمة المرور (إذا كان SMTP مُعدًا) عبر واجهة الويب
فقدت Mind Key
الأعراض
- لا أستطيع الوصول إلى الذكريات
- حُذف Mind Key أو فُقد
الحلول
لا يمكن استرداد Mind Keys. يجب أن:
1. تسجّل الدخول للحصول على JWT: 
2. تسرد العقول:  (مع JWT)
3. تنشئ عقلًا جديدًا: 
4. تحفظ Mind Key الجديد
5. (اختياري) تحذف العقل القديم: 
البيانات في العقل القديم فقدت إلا إذا وجدت Mind Key.
استدعاءات الـ API تُرجع 401
الأعراض
- جميع استدعاءات الـ API تُرجع 401 Unauthorized
- "Mind Key fehlt oder ungültig"
الحلول
1. تحقق من تنسيق الترويسة: 
2. تحقق أن Mind Key يبدأ بـ  (وليس  وهو JWT)
3. اختبر مباشرة:
   [CODE BLOCK]
4. قد يكون Mind Key مُبطَلًا — أنشئ عقلًا جديدًا
راجع المصادقة.
استدعاءات الـ API تُرجع 404
الأعراض
- 404 Not Found
- "Route not found"
الحلول
> [!CRITICAL]
> لا تخمّن مسارات نقاط النهاية. فقط المسارات في  موجودة.
1. تحقق من نقاط النهاية الصالحة: 
2. قارن عنوان URL بدقة — حساس لحالة الأحرف، بلا شرطات مائلة لاحقة
3. تحقق من طريقة HTTP —  مقابل  مختلفة
استدعاءات الـ API تُرجع 429
الأعراض
- 429 Too Many Requests
- "Rate limit exceeded"
الحلول
1. بدّل إلى مصادقة الترويسة (بلا حد معدل):
   [CODE BLOCK]
2. انتظر  ثانية إذا وجب استخدام 
راجع حدود المعدل.
بحث الذاكرة يُرجع نتائج فارغة
الأعراض
- يُرجع  فارغًا
- أعرف أن الذكريات موجودة
الحلول
1. تحقق من وجود الذكريات: 
2. تحقق من صياغة البحث — لـ FTS5 صياغة محددة
3. جرّب استعلامًا أبسط —  بدلًا من 
4. استخدم البحث الدلالي للاستعلامات المفاهيمية: 
راجع بحث FTS5.
الذكريات لا تستمر
الأعراض
- يُرجع POST /memory نجاحًا
- لا يُظهرها GET /memory/recall
الحلول
1. تحقق من نفس Mind Key — مفاتيح مختلفة = عقول مختلفة
2. تحقق من الاستجابة — يُرجع POST 
3. جرّب GET /memory (قائمة JSON) بدلًا من /memory/recall (نص)
4. تحقق من المرشّح —  أو  قد يخفيها
الأدوات لا تظهر في Claude Desktop
الأعراض
- يُظهر Claude Desktop 0 أدوات
- لا توجد أيقونة 🔌
الحلول
1. أعد تشغيل Claude Desktop بالكامل (Cmd+Q)
2. تحقق أن ملف الإعداد JSON صالح
3. تحقق من Node.js 18+ مثبت
4. شغّل MCP يدويًا: 
5. تحقق من السجلات: 
راجع استكشاف أخطاء MCP.
Synapse غير متصل
الأعراض
- لا يمكن الوصول إلى synapse.schaefer.zone
- curl ينتهي بانتهاء المهلة
الحلول
1. تحقق من إنترنتك — جرّب موقعًا آخر
2. تحقق من صحة Synapse: 
3. انتظر — قد يكون انقطاعًا مؤقتًا أو نشرًا
4. تحقق من صفحة الحالة (إن وُجدت)
للاستضافة الذاتية: تحقق من حالة حاوية Docker، اتصال قاعدة البيانات.
أخطاء قاعدة البيانات
الأعراض
- 500 Internal Server Error
- "Database connection failed"
الحلول
للاستضافة الذاتية:
1. تحقق من تشغيل PostgreSQL: 
2. تحقق من DATABASEURL في البيئة
3. تحقق من الترحيلات: 
4. تحقق من مساحة القرص: 
للمُستضاف: أبلغ الدعم.
الـ Webhook لا يعمل
الأعراض
- سجّلت webhook لكن لا أتلقى استدعاءات
- لا POST إلى عنوان URL الخاص بك
الحلول
1. تحقق أن عنوان URL قابل للوصول: 
2. تحقق من مرشّح الأحداث —  يطابق جميع أحداث الذاكرة
3. اختبر الـ webhook: 
4. تحقق أن الـ webhook مُمكَّن: 
5. تحقق من SSL — يتطلب Synapse HTTPS صالحًا لعناوين URL للـ webhooks
راجع Webhooks API.
مهمة Cron لا تعمل
الأعراض
- أنشأت مهمة cron لكنها لا تعمل
-  لا يُحدّث
الحلول
1. تحقق من صياغة الجدول — يجب أن تكون cron 5 حقول صالح OR عدد ثوانٍ صحيح
2. تحقق أن نقطة النهاية مسموحة — يجب أن تكون http(s)، بلا عناوين IP خاصة
3. تحقق أن المهمة مُمكَّنة: 
4. انتظر الوقت المجدول التالي — cron ليس فوريًا
راجع Cron والمجدول.
تحتاج مزيدًا من المساعدة؟
1. تحقق من الوثائق الموجودة: <https://synapse.schaefer.zone/docs>
2. ابحث في الوثائق: 
3. افتح issue: <https://gitlab.com/schaefer-services/synapse/-/issues>
4. تواصل: راجع صفحة 
الخطوات التالية
- الأخطاء ومعالجتها
- أسئلة الـ API الشائعة
- استكشاف أخطاء MCP