# Memory API

Memory API هي قلب Synapse. تُوفّر 22 نقطة نهاية لتخزين واسترجاع وبحث وإدارة
الذكريات المنظمة. تتطلب جميع نقاط النهاية Mind Key للمصادقة.

> [!CRITICAL]
> **استدعِ دائمًا `GET /memory/recall` في بداية كل جلسة.** هذه هي الطريقة
> الوحيدة لإعادة بناء السياق من الجلسات السابقة.

## الفئات

تُنظّم الذكريات في 8 فئات:

| الفئة | حالة الاستخدام |
|----------|----------|
| `identity` | اسم المستخدم، الدور، معلومات الاتصال، تفضيلات حول الذات |
| `preference` | الإعجابات، عدم الإعجابات، أسلوب العمل، تفضيلات التواصل |
| `fact` | حقائق قابلة للتحقق (تفاصيل المشروع، التواريخ، عناوين URL) |
| `project` | حالة المشروع، المعالم، البنية |
| `skill` | الأشياء التي يبرع فيها المستخدم |
| `mistake` | أخطاء سابقة — تجنب تكرارها |
| `context` | سياق ذو صلة بالجلسة |
| `note` | ملاحظات متفرقة |

## الأولويات

- `low` — جيد معرفته
- `normal` — افتراضي
- `high` — مهم
- `critical` — يجب ألا يُنسى أبدًا (هوية المستخدم، معلومات قانونية)

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

### GET /memory/recall

يُرجع جميع الذكريات كنص عادي مُحسّن لنماذج LLM. استدعِ هذا عند بداية كل جلسة.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall
```

الاستجابة (text/plain):

```
Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

...
```

### POST /memory

تخزين ذاكرة جديدة أو تحديث ذاكرة موجودة (نفس الفئة + المفتاح = تحديث).

```bash
curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "fact",
    "key": "user_name",
    "content": "The user's name is Michael Schäfer",
    "tags": ["person", "identity"],
    "priority": "critical"
  }'
```

الاستجابة: `{ "id": "mem_001", "status": "stored" }`

### GET /memory

قائمة الذكريات مع مرشّحات اختيارية.

```bash
# جميع الذكريات (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# تصفية حسب الفئة
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# تصفية حسب الوسم
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

تحديث ذاكرة محددة بالمعرّف.

```bash
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'
```

### DELETE /memory/:id

حذف ذاكرة واحدة.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## نقاط نهاية البحث

### GET /memory/search

بحث نصي كامل باستخدام FTS5.

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

صياغة FTS5:

- كلمات متعددة = AND: `docker swarm`
- عبارة: `"docker swarm"`
- بادئة: `docker*`
- منطقي: `docker OR kubernetes`
- استبعاد: `docker -swarm`

### GET /memory/semantic-search

بحث مفاهيمي باستخدام التضمينات (أبطأ من FTS5 لكنه يفهم المعنى).

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

يُرجع ذكريات متشابهة دلاليًا مع الاستعلام، حتى لو لم تتطابق الكلمات
المفتاحية. مفيد لـ "إيجاد ذكريات حول X" حيث يُوصف X بشكل مختلف.

### GET /memory/by-tag

قائمة الذكريات حسب الوسم.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"
```

### GET /memory/related/:id

إيجاد ذكريات مرتبطة بذاكرة محددة (عبر الوسوم المشتركة).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001
```

## المزامنة والـ Diff

### GET /memory/diff

مزامنة تزايدية — تُرجع الذكريات المتغيّرة منذ طابع زمني.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"
```

الاستجابة: `{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

تطبيق diff من نسخة أخرى (للمزامنة المستضافة ذاتيًا).

```bash
curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'
```

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

### POST /memory/bulk-delete

حذف ذكريات متعددة بالمعرّف.

```bash
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

### POST /memory/embed-batch

توليد تضمينات للذكريات التي لا تملكها بعد (للبحث الدلالي).

```bash
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'
```

### GET /memory/embed-batch-status

التحقق من تقدّم توليد التضمينات.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## التحقق

للذكريات علامة `verified`. الذكريات المخزّنة بواسطة الوكيل تكون غير مُتحقّق منها
افتراضيًا (`source=agent`)؛ الذكريات المخزّنة بواسطة الإنسان مُتحقّق منها
(`source=user`).

### POST /memory/verify

تعليم ذاكرة كمُتحقّق منها (يتطلب JWT، وليس Mind Key).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"
```

### POST /memory/unverify

تعليم ذاكرة كغير مُتحقّق منها (يتطلب JWT).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \
  -H "Authorization: Bearer YOUR_JWT"
```

### GET /memory/unverified

قائمة الذكريات بانتظار التحقق البشري.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"
```

## الإحصائيات والتدقيق

### GET /memory/stats

إحصائيات تجميعية للعقل الحالي.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/stats
```

يُرجع: `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

سجل تدقيق لجميع العمليات التي تُغيّر الحالة.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"
```

### GET /memory/contradictions

اكتشاف تناقضات محتملة في الذكريات المخزّنة.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/contradictions
```

### GET /memory/expiring

قائمة الذكريات التي تقترب تواريخ انتهائها.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"
```

## الحالة والتصدير

### GET /memory/health

فحص حالة سريع لنظام الذاكرة.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/health
```

### GET /memory/mind-export

تصدير JSON كامل لجميع الذكريات (للنسخ الاحتياطي).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mind-export > backup.json
```

### POST /memory/compact

ضغط الذكريات المتشابهة (تلخيص تلقائي).

```bash
curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

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

- [البداية السريعة لـ LLMs](/docs/getting-started/quick-start-llm)
- [أفضل ممارسات الذاكرة](/docs/guides/memory-best-practices)
- [بحث FTS5](/docs/concepts/fts5-search)
- [البحث الدلالي](/docs/concepts/semantic-search)