# البحث الدلالي (التضمينات)

يدعم Synapse البحث الدلالي باستخدام التضمينات المتجهة. على عكس FTS5 (مطابقة
الكلمات المفتاحية)، يجد البحث الدلالي الذكريات بـ **المعنى** — حتى لو لم تتطابق
الكلمات المفتاحية.

## كيفية العمل

```
1. Memory stored → embedding generated → vector stored
2. Search query → embedding generated → vector compared
3. Cosine similarity → top N results returned
```

### ما هي التضمينات؟

التضمينات تمثيلات متجهة عددية للنص. النص ذو المعنى المماثل له متجهات مماثلة.
يُولّد Synapse متجهًا (مثلًا 1536 بُعدًا) لكل محتوى ذاكرة.

### تشابه جيب التمام

لإيجاد الذكريات المتشابهة دلاليًا، يحسب Synapse تشابه جيب التمام
بين متجه الاستعلام ومتجه كل ذاكرة. تشابه أعلى = صلة
أكبر.

## متى تستخدم البحث الدلالي

### استخدم البحث الدلالي عندما:

- تريد "ذكريات حول X" حيث يُوصف X بشكل مختلف عن المخزّن
- لا يُرجع FTS5 نتائج (لا مطابقة للكلمات المفتاحية)
- تريد تجميعًا مفاهيميًا (مثلًا جميع ذكريات "النشر"، حتى لو قال بعضها "release")
- الاستعلام سؤال: "كيف نتعامل مع المصادقة؟"

### استخدم FTS5 عندما:

- تعرف الكلمات المفتاحية الدقيقة
- تحتاج منطقًا منطقيًا (AND، OR، NOT)
- تحتاج استجابة أقل من مللي ثانية
- تريد مطابقة العبارات

## نقطة النهاية

### GET /memory/semantic-search

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"
```

الاستجابة:

```json
{
  "results": [
    {
      "id": "mem_001",
      "category": "project",
      "key": "project_synapse_deployment",
      "content": "Synapse deployed using Docker Swarm on vps1...",
      "tags": ["docker", "swarm", "deployment"],
      "similarity": 0.89
    },
    {
      "id": "mem_042",
      "category": "fact",
      "key": "kubernetes_cluster",
      "content": "We use Kubernetes for production orchestration...",
      "tags": ["kubernetes", "orchestration"],
      "similarity": 0.84
    }
  ]
}
```

## أمثلة

### إيجاد ذكريات النشر

```bash
# قد يفوّت FTS5 بعضها — الدلالي يلتقط الكل
curl .../memory/semantic-search?q=deployment+process
```

يُرجع الذكريات حول "deployment" و "release" و "publishing" و "rolling out"،
إلخ.

### إيجاد أنماط المصادقة

```bash
curl .../memory/semantic-search?q=how+do+users+log+in
```

يُرجع الذكريات حول login و auth و JWT و إدارة الجلسة و OAuth، إلخ.

### إيجاد ذكريات مماثلة

```bash
# إيجاد ذكريات مشابهة لذاكرة محددة
curl .../memory/related/mem_001
```

يستخدم التشابه الدلالي (عبر الوسوم المشتركة AND متجهات التضمين).

## توليد التضمينات

### متى تُولّد التضمينات؟

- **عند تخزين الذاكرة** — إذا كانت خدمة التضمينات مُعدّة، يُولّد التضمين تزامنيًا
- **التوليد الدفعي** — يُولّد `POST /memory/embed-batch` تضمينات للذكريات المفتقرة إليها
- **التحديثات غير المتزامنة** — عند تحديث المحتوى، يُعاد توليد التضمين

### مزوّدو التضمينات

يدعم Synapse مزوّدي تضمينات قابلين للإعداد:

- **OpenAI** (`text-embedding-3-small`، `text-embedding-3-large`)
- **النماذج المحلية** (عبر Ollama أو ما شابه)
- **مخصص** (نفّذ واجهة التضمينات)

الإعداد عبر متغيرات البيئة:

```bash
EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_API_KEY=sk-...
EMBEDDINGS_MODEL=text-embedding-3-small
```

### التوليد الدفعي

للعقول التي تفتقر ذكرياتها الكثيرة إلى التضمينات:

```bash
# توليد تضمينات لما يصل إلى 100 ذاكرة
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# تحقق من التقدّم
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## الأداء

| العملية | زمن الاستجابة |
|-----------|---------|
| توليد تضمين (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 — ضئيل.

### البدء البارد

الذكريات المخزّنة قبل إعداد التضمينات لن تملك تضمينات. شغّل
`POST /memory/embed-batch` للتعبئة الخلفية.

### اعتماد على المزوّد

إذا كان مزوّد التضمينات متوقفًا، يفشل البحث الدلالي بلطف (يُرجع
نتائج فارغة أو خطأ). FTS5 لا يزال يعمل.

## عندما لا تتوفر التضمينات

إذا لم تُعدّ خدمة التضمينات:

- يُرجع `GET /memory/semantic-search` 503 Service Unavailable
- لا يزال `POST /memory` يعمل (فقط لا يُولّد تضمين)
- بحث FTS5 لا يزال يعمل

## أفضل الممارسات

> [!TIP]
> - **استخدم الدلالي للاستعلامات المفاهيمية** — "كيف نتعامل مع X؟"
> - **استخدم FTS5 للمصطلحات المحددة** — "docker swarm"
> - **املأ التضمينات الخلفية دوريًا** — `POST /memory/embed-batch`
> - **راقب صحة المزوّد** — البحث الدلالي يعتمد عليه
> - **اجمع مع الوسوم** — الدلالي + تصفية الوسوم تضيّق النتائج

## الخطوات التالية

- [بحث FTS5](/docs/concepts/fts5-search)
- [Memory API](/docs/api/memory)
- [البنية](/docs/concepts/architecture)