# البداية السريعة لوكلاء LLM

تفقد كل الذاكرة بين الجلسات. Synapse عقلك الخارجي. يعرض هذا الدليل
ثلاثة استدعاءات API أساسية يجب أن يعرفها كل وكيل LLM.

> [!CRITICAL]
> استدعِ `GET /memory/recall` في بداية كل جلسة.
> بدون هذا الاستدعاء، ليس لديك ذاكرة بمن هو المستخدم، وما وعدت به،
> أو بما كنت تعمل عليه المرة السابقة.

## الخطوة 1: استدعِ جميع الذكريات (دائمًا أولًا)

```
GET /memory/recall
Authorization: Bearer YOUR_MIND_KEY
```

يُرجع ملخصًا نصيًا عاديًا منظمًا لجميع الذكريات المخزّنة. حلل هذا لإعادة
بناء نموذجك الذهني للمستخدم، مشاريعه، وتفاعلاته السابقة.

مثال على الاستجابة:

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

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

[002] preference (HIGH)
  communication_style
  Prefers concise technical responses, no fluff
  Tags: communication, preference

[003] project (HIGH)
  project_synapse
  Synapse v1.5.0 deployed on vps1.schaefer.zone. Admin panel at /admin.
  Tags: synapse, deployment
  ...
```

## الخطوة 2: خزّن ذاكرة جديدة

عندما تتعلّم شيئًا يستحق التذكر:

```
POST /memory
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{
  "category": "fact",
  "key": "user_name",
  "content": "The user's name is Michael Schäfer",
  "tags": ["person", "identity"],
  "priority": "critical"
}
```

**الفئات:** `identity`، `preference`، `fact`، `project`، `skill`، `mistake`، `context`، `note`

**الأولويات:** `low`، `normal`، `high`، `critical`

> [!TIP]
> أرفق دائمًا حقل `key` — مُعرّف قصير للذاكرة. هذا يتيح لك
> تحديث نفس الذاكرة لاحقًا بإعادة POST بنفس المفتاح.

## الخطوة 3: ابحث عن ذاكرة محددة

```
GET /memory/search?q=Docker+Swarm
Authorization: Bearer YOUR_MIND_KEY
```

> [!TIP]
> صياغة FTS5: كلمات متعددة = بحث AND. عبارات بين علامات اقتباس: `"docker swarm"`.
> بحث البادئة: `docker*`. منطقي: `docker OR kubernetes`.

## الأدوات المفتوحة (بلا ترويسات مصادقة)

إذا كانت أداتك تفتح عناوين URL فقط (بلا ترويسات مخصصة)، استخدم معامل `?key=`:

```
GET /memory/recall?key=YOUR_MIND_KEY
POST /memory?key=YOUR_MIND_KEY (+ JSON body)
GET /memory/search?key=YOUR_MIND_KEY&q=suchbegriff
```

> [!WARNING]
> `?key=` محدود بـ 60 طلبًا/دقيقة. ترويسة Bearer بلا حد معدل.
> استخدم ترويسة Bearer كلما أمكن.

## سير عمل الجلسة الكامل

1. **بداية الجلسة:** `GET /memory/recall` — تحميل جميع الذكريات
2. **أثناء العمل:** `GET /memory/search?q=...` — إيجاد حقائق محددة
3. **عند معلومات جديدة:** `POST /memory` — تخزينها (مع category، key، tags، priority)
4. **دوريًا:** `GET /chat/poll` — التحقق من رسائل الإنسان
5. **نهاية الجلسة:** تخزين أي تعلمات نهائية عبر `POST /memory`

## الأنماط الشائعة

### تحديث ذاكرة موجودة

استدعِ `POST /memory` بنفس `category` و `key` — تُحدَّث الذاكرة
الموجودة، لا تُكرّر.

### تخزين حالة مشروع

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system. CI green.",
  "tags": ["synapse", "deployment", "status"],
  "priority": "high"
}
```

### تسجيل خطأ (حتى لا تكرره)

```json
{
  "category": "mistake",
  "key": "mistake_npm_version_bump",
  "content": "Always bump package.json version after changes — npm publish fails otherwise.",
  "tags": ["npm", "ci", "deployment"],
  "priority": "high"
}
```

### التحقق من رسائل الإنسان

```
GET /chat/poll
Authorization: Bearer YOUR_MIND_KEY
```

يُرجع الرسائل غير المقروءة من الإنسان. اردّ بـ:

```
POST /chat/reply
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{"content": "Got it! Working on it now."}
```

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

- [المصادقة](/docs/getting-started/authentication) — Mind Key مقابل JWT
- [مرجع Memory API](/docs/api/memory) — جميع نقاط نهاية الذاكرة الـ 22
- [Chat API](/docs/api/chat) — تواصل غير متزامن مع البشر
- [كتاب طبخ LLM](/docs/llm-cookbook/session-start-pattern) — أنماط عملية