# نموذج الذاكرة

نموذج ذاكرة Synapse مصمم لوكلاء LLM — منظّم بما يكفي
للاستدعاء الموثوق، ومرن بما يكفي لأي مجال.

## تشريح الذاكرة

```json
{
  "id": "mem_abc123",
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed on vps1. CI green.",
  "tags": ["synapse", "deployment", "v1.5.0"],
  "priority": "high",
  "source": "agent",
  "verified": false,
  "confidence": 0.85,
  "expires_at": null,
  "mind_id": "m_xyz789",
  "created_at": "2026-06-27T...",
  "updated_at": "2026-06-27T..."
}
```

## الحقول

| الحقل | النوع | مطلوب | الوصف |
|-------|------|----------|-------------|
| `id` | string | تلقائي | معرّف فريد (mem_xxx) |
| `category` | enum | ✅ | واحدة من 8 فئات |
| `key` | string | ✅ | مُعرّف ثابت (يُستخدم للتحديثات) |
| `content` | string | ✅ | محتوى الذاكرة (أي نص) |
| `tags` | string[] | – | للبحث والتصفية |
| `priority` | enum | – | low، normal، high، critical (افتراضي: normal) |
| `source` | enum | تلقائي | user، agent (من خزّنها) |
| `verified` | bool | تلقائي | هل تحقق منها إنسان؟ |
| `confidence` | float | – | 0.0 إلى 1.0 (افتراضي: 1.0 للمستخدم، 0.7 للوكيل) |
| `expires_at` | timestamp | – | متى تُنسى هذه الذاكرة |
| `mind_id` | string | تلقائي | أي عقل يملكها |
| `created_at` | timestamp | تلقائي | أول تخزين |
| `updated_at` | timestamp | تلقائي | آخر تعديل |

## الفئات

ثماني فئات تغطي حالات استخدام وكلاء LLM الشائعة:

| الفئة | الغرض | مثال على المحتوى |
|----------|---------|-----------------|
| `identity` | من هو المستخدم | "User is Michael Schäfer, software engineer in Berlin" |
| `preference` | تفضيلات المستخدم | "Prefers concise technical responses" |
| `fact` | حقائق قابلة للتحقق | "Office is in Berlin, timezone Europe/Berlin" |
| `project` | حالة المشروع | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| `skill` | مهارات المستخدم | "Advanced Python, 10+ years" |
| `mistake` | أخطاء سابقة | "Forgot to bump npm version — CI failed" |
| `context` | سياق الجلسة | "Currently reviewing PR #42" |
| `note` | ملاحظات متفرقة | "Try Redis for caching next sprint" |

## المفاتيح: مُعرّفات ثابتة

الحقل `key` حاسم — فهو كيف تُحدّث الذكريات دون إنشاء
مكررات.

```python
# التخزين الأول
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# التحديث بنفس المفتاح (يستبدل، لا يكرر)
store("project", "project_synapse_status", "v1.5.0 deployed", priority="high")
```

**قواعد المفتاح:**

- يجب أن يكون فريدًا ضمن (الفئة، العقل)
- استخدم `snake_case`
- أضف بادئة الفئة للوضوح: `preference_communication`، `mistake_npm_version`
- أبقِه ثابتًا — لا تغيّر المفاتيح بعد الإنشاء

## الوسوم: للبحث

تُمكّن الوسوم التصفية والبحث السريع:

```bash
# إيجاد جميع الذكريات بالوسم "docker"
GET /memory/by-tag?tag=docker

# بحث FTS5 ضمن مجموعة موسومة
GET /memory/search?q=swarm&tag=docker
```

**أفضل ممارسات الوسوم:**

- 2-5 وسوم لكل ذاكرة (لا تفرط في الوسم)
- أحرف صغيرة للاتساق
- استخدم أسماء المشاريع، المواضيع، التقنيات
- الوسوم غير حساسة لحالة الأحرف

## مستويات الأولوية

| الأولوية | متى تُستخدم | سلوك الاستدعاء |
|----------|-------------|-----------------|
| `critical` | الهوية، القانونية، غير القابلة للتراجع | دائمًا في أعلى الاستدعاء |
| `high` | المشاريع النشطة، التفضيلات الأساسية | بارز في الاستدعاء |
| `normal` | معظم الذكريات (افتراضي) | ترتيب استدعاء قياسي |
| `low` | عابرة، جيد معرفتها | قد تُلخّص |

يُرتّب `/memory/recall` حسب الأولوية (critical أولًا)، ثم حسب الأحدث.

## المصدر: المستخدم مقابل الوكيل

تُوسم الذكريات بـ `source`:

- `user` — خزّنها إنسان (عبر JWT أو واجهة الإنسان)
- `agent` — خزّنها وكيل LLM (عبر Mind Key)

يؤثر هذا على:

- **التحقق**: ذكريات `user` مُتحقّق منها تلقائيًا، ذكريات `agent` لا
- **الثقة**: `user` افتراضي 1.0، `agent` 0.7
- **الاستدعاء**: يعلّم `/memory/recall` الذكريات غير المُتحقّق منها بـ "(unverified)"

> [!NOTE]
> تعامل مع ذكريات المصدر `agent` بقدر مناسب من الشك. قد تكون
> مستنتجة أو مفترضة بدلًا من ذكرها مباشرة من المستخدم.

## التحقق

تشير علامة `verified` إلى أن إنسانًا أكّد الذاكرة:

- ذكريات `user`: مُتحقّق منها تلقائيًا (`true`)
- ذكريات `agent`: غير مُتحقّق منها افتراضيًا (`false`)

تحقق من الذكريات عبر:

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

> [!NOTE]
> يتطلب التحقق JWT (مصادقة الإنسان)، وليس Mind Key (مصادقة الوكيل). هذا
> يضمن أن البشر فقط يمكنهم تعليم الذكريات كمُتحقّق منها.

## الثقة

يشير الحقل `confidence` (0.0 إلى 1.0) إلى موثوقية الذاكرة:

- 1.0 — ذُكرت مباشرة من المستخدم
- 0.7 — مستنتجة بواسطة الوكيل
- 0.5 — غير مؤكدة، تحتاج تحققًا
- 0.0 — مشكوك فيها صراحة

عيّن الثقة عند التخزين:

```json
{
  "category": "preference",
  "key": "prefers_dark_mode",
  "content": "User seems to prefer dark mode (based on their IDE screenshots)",
  "confidence": 0.5,
  "source": "agent"
}
```

## الانتهاء

عيّن `expires_at` للذكريات الحساسة للوقت:

```json
{
  "category": "context",
  "key": "current_meeting_topic",
  "content": "Discussing Q3 roadmap",
  "expires_at": "2026-06-28T00:00:00Z"
}
```

الذكريات المنتهية لا يُرجعها `/memory/recall` (لكنها لا تزال موجودة في DB).
استخدم `/memory/expiring?within=7d` لرؤية الذكريات التي تنتهي قريبًا.

## دورة حياة الذاكرة

```
                  ┌─────────────────┐
                  │     Create      │
                  │  POST /memory   │
                  └────────┬────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │     Active      │ ◀──── PUT /memory/:id (update)
                  │  (in recall)    │
                  └────────┬────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Expired  │ │ Verified │ │ Deleted  │
        │ (in DB)  │ │ (flag)   │ │ (gone)   │
        └──────────┘ └──────────┘ └──────────┘
```

## سلوك الاستدعاء

يُرجع `GET /memory/recall` ملخصًا نصيًا عاديًا مُحسّنًا لسياق LLM:

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

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

[002] preference (HIGH) [verified]
  communication_style
  Prefers concise technical responses
  Tags: communication

[003] project (HIGH) [unverified]
  synapse_status
  v1.5.0 deployed, working on v1.6.0 docs
  Tags: synapse, deployment

...
```

- مُرتّب حسب الأولوية (critical → low)، ثم حسب الأحدث
- الذكريات غير المُتحقّق منها معلّمة بـ `[unverified]`
- الوسوم مضمنة للسياق
- نص عادي (لا حاجة لتحليل JSON)

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

- [Memory API](/docs/api/memory)
- [أفضل ممارسات الذاكرة](/docs/guides/memory-best-practices)
- [بحث FTS5](/docs/concepts/fts5-search)