# نظرة عامة

يأخذك هذا الدليل خلال بناء وكيل LLM يحفظ السياق عبر
الجلسات باستخدام Synapse. بنهايته، سيكون وكيلك:

- يستدعي السياق السابق عند بدء الجلسة
- يخزّن التعلمات الجديدة عندما تحدث
- يتتبع المهام متعددة الخطوات عبر الجلسات
- يتواصل مع البشر عبر الدردشة غير المتزامنة

## البنية

```text
┌──────────────┐   recall/store   ┌──────────┐
│  LLM Agent   │ ◀──────────────▶ │ Synapse  │
│ (your code)  │                  │   API    │
└──────────────┘                  └──────────┘
       │
       │ poll/reply
       ▼
┌──────────────┐
│    Human     │ (browser or chat UI)
└──────────────┘
```

## الخطوة 1: إعداد Mind Key

```bash
# سجّل واحصل على JWT
JWT=$(curl -s -X POST https://synapse.schaefer.zone/register \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@example.com","password":"secret"}' | jq -r .jwt)

# أنشئ عقلًا واحصل على Mind Key
MIND_KEY=$(curl -s -X POST https://synapse.schaefer.zone/minds \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"persistent-agent","description":"My persistent agent"}' | jq -r .mind_key)

echo "Save this: $MIND_KEY"
```

## الخطوة 2: بروتوكول بدء الجلسة

في بداية كل جلسة، استدعِ جميع الذكريات:

```python
import os
import requests

MIND_KEY = os.environ["SYNAPSE_MIND_KEY"]
URL = "https://synapse.schaefer.zone"

def session_start():
    """Call this at the start of every session."""
    # 1. استدعِ جميع الذكريات
    r = requests.get(
        f"{URL}/memory/recall",
        headers={"Authorization": f"Bearer {MIND_KEY}"}
    )
    memories = r.text  # ملخص نصي عادي
    
    # 2. تحقق من رسائل الدردشة غير المقروءة
    r = requests.get(
        f"{URL}/chat/poll",
        headers={"Authorization": f"Bearer {MIND_KEY}"}
    )
    messages = r.json().get("messages", [])
    
    # 3. تحقق من المهام قيد التقدم
    r = requests.get(
        f"{URL}/mind/tasks?status=in_progress",
        headers={"Authorization": f"Bearer {MIND_KEY}"}
    )
    tasks = r.json().get("tasks", [])
    
    return {
        "memories": memories,
        "unread_messages": messages,
        "active_tasks": tasks,
    }

context = session_start()
# ابنِ system prompt بهذا السياق
```

## الخطوة 3: تخزين التعلمات الجديدة

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

```python
def remember(category, key, content, tags=None, priority="normal"):
    """Store a memory."""
    requests.post(
        f"{URL}/memory",
        headers={
            "Authorization": f"Bearer {MIND_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "category": category,
            "key": key,
            "content": content,
            "tags": tags or [],
            "priority": priority,
        }
    )

# أمثلة
remember("identity", "user_name", "User is Michael Schäfer", 
         tags=["person"], priority="critical")
remember("preference", "communication_style", 
         "User prefers concise technical responses",
         tags=["communication"])
remember("project", "current_project", 
         "Building Synapse v1.6.0 with docs system",
         tags=["synapse", "docs"], priority="high")
remember("mistake", "npm_version_bump", 
         "Always bump package.json version after changes",
         tags=["npm", "ci"], priority="high")
```

## الخطوة 4: إدارة المهام

تتبع العمل متعدد الخطوات عبر الجلسات:

```python
def create_task(title, description="", priority="normal"):
    r = requests.post(
        f"{URL}/mind/task",
        headers={"Authorization": f"Bearer {MIND_KEY}",
                 "Content-Type": "application/json"},
        json={"title": title, "description": description, "priority": priority}
    )
    return r.json()["id"]

def update_task(task_id, status=None, description=None):
    payload = {}
    if status: payload["status"] = status
    if description: payload["description"] = description
    requests.put(
        f"{URL}/mind/task/{task_id}",
        headers={"Authorization": f"Bearer {MIND_KEY}",
                 "Content-Type": "application/json"},
        json=payload
    )

# سير عمل متعدد الجلسات
task_id = create_task("Deploy v1.6.0", "Push docs system to production", "high")
update_task(task_id, status="in_progress")
# ... عمل عبر عدة جلسات ...
update_task(task_id, status="done")
```

## الخطوة 5: دردشة غير متزامنة مع البشر

استطلع للرسائل بين استدعاءات الأدوات:

```python
import time

def poll_messages():
    r = requests.get(
        f"{URL}/chat/poll",
        headers={"Authorization": f"Bearer {MIND_KEY}"}
    )
    return r.json().get("messages", [])

def reply(content):
    requests.post(
        f"{URL}/chat/reply",
        headers={"Authorization": f"Bearer {MIND_KEY}",
                 "Content-Type": "application/json"},
        json={"content": content}
    )

# الحلقة الرئيسية
while working:
    # استطلع لرسائل الإنسان
    for msg in poll_messages():
        print(f"Human: {msg['content']}")
        reply(f"Got it: {msg['content']}. Working on it.")
    
    # نفّذ وحدة عمل واحدة
    do_work()
    
    time.sleep(30)  # لا تستطلع بشكل متكرر جدًا
```

## الخطوة 6: بروتوكول نهاية الجلسة

عند نهاية الجلسة، خزّن السياق النهائي:

```python
def session_end():
    """Call this before terminating the session."""
    # خزّن ما أنجزناه
    remember("context", "last_session_summary",
             f"Session ended at {time.now()}. Accomplished: ...",
             tags=["session"], priority="normal")
    
    # حدّث حالات المهام
    for task in get_active_tasks():
        if task_in_progress(task):
            update_task(task["id"], description=f"In progress: {current_step}")

session_end()
```

## النمط الكامل

```python
class PersistentAgent:
    def __init__(self):
        self.mind_key = os.environ["SYNAPSE_MIND_KEY"]
        self.url = "https://synapse.schaefer.zone"
    
    def run(self):
        # 1. استدعِ السياق
        context = self.session_start()
        
        # 2. عالج الرسائل غير المقروءة
        for msg in context["unread_messages"]:
            self.handle_message(msg)
        
        # 3. استأنف المهام النشطة
        for task in context["active_tasks"]:
            self.continue_task(task)
        
        # 4. نفّذ عملًا جديدًا
        self.do_work()
        
        # 5. احفظ الحالة
        self.session_end()
```

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

> [!TIP]
>
> - **استدعِ أولًا دائمًا** — لا تبدأ العمل دون تحميل السياق
> - **خزّن استباقيًا** — لا تنتظر حتى نهاية الجلسة
> - **استخدم مفاتيح ذات معنى** — `user_name`، `project_status`، لا `mem_001`
> - **وسم كل شيء** — الوسوم تُمكّن البحث والتصفية
> - **عيّن أولويات واقعية** — ليس كل شيء `critical`

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

- [كتاب طبخ LLM](/docs/llm-cookbook/session-start-pattern) — أنماط عملية
- [أفضل ممارسات الذاكرة](/docs/guides/memory-best-practices)
- [تنسيق الوكلاء المتعددين](/docs/guides/multi-agent-coordination)