# Variables API

Variables API تخزين سريع للقيم الأساسية للحالة المؤقتة. على عكس
الذكريات (المُفهرَسة والقابلة للبحث والمنظمة)، المتغيرات مُحسّنة
للوصول السريع للقراءة/الكتابة — مثالية للعدّادات والأعلام وحالة
الجلسة.

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

### POST /var

تعيين متغير أو تحديثه.

```bash
curl -X POST https://synapse.schaefer.zone/var \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "last_session_at", "value": "2026-06-27T14:00:00Z"}'
```

### GET /var/:key

الحصول على متغير واحد.

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

الاستجابة:

```json
{ "key": "last_session_at", "value": "2026-06-27T14:00:00Z", "updated_at": "..." }
```

### GET /var

قائمة بجميع المتغيرات.

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

### DELETE /var/:key

حذف متغير.

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

## متى تستخدم المتغيرات مقابل الذاكرة

| حالة الاستخدام | استخدم |
|----------|-----|
| اسم المستخدم، التفضيلات | الذاكرة (قابلة للبحث، منظمة) |
| طابع زمني لآخر جلسة | متغير (حالة مؤقتة) |
| عدّاد (مثل الرسائل المُرسلة) | متغير (تحديثات متكررة) |
| حالة سير العمل ("الخطوة 3 من 5 مكتملة") | متغير (عابرة) |
| ملاحظات مشروع طويلة | الذاكرة (مفهرسة بنص كامل) |
| سكربتات قابلة لإعادة الاستخدام | تخزين السكربتات (مُسمّاة، مُصدَّرة) |

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

### تتبع آخر جلسة

```bash
# عند نهاية الجلسة
curl -X POST .../var -d '{"key": "last_session_at", "value": "'$(date -Iseconds)'"}'

# عند بدء الجلسة
LAST=$(curl .../var/last_session_at | jq -r .value)
curl .../memory/diff?since=$(date -d "$LAST" +%s)
```

### نمط العدّاد

```bash
# زيادة
N=$(curl .../var/api_calls | jq -r .value)
curl -X POST .../var -d "{\"key\": \"api_calls\", \"value\": $((N+1))}"
```

### أعلام الميزات

```bash
curl -X POST .../var -d '{"key": "feature_x_enabled", "value": "true"}'

# تحقق
ENABLED=$(curl .../var/feature_x_enabled | jq -r .value)
if [ "$ENABLED" = "true" ]; then ... fi
```

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

- [Memory API](/docs/api/memory) — للبيانات المنظمة القابلة للبحث
- [Cron والمجدول](/docs/api/cron)