# Memory API
SUMMARY: مرجع كامل لنقاط نهاية الذاكرة الـ 22: التخزين، الاستدعاء، البحث، البحث الدلالي، المزامنة، التدقيق، والمزيد.

KEY CONTEXT:
Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)
ALWAYS call GET /memory/recall at session start.
POST /memory with same category+key updates the existing memory.
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
Search: GET /memory/search?q=... (FTS5 syntax: AND, OR, "phrases", prefix*)
Semantic: GET /memory/semantic-search?q=... (slower, conceptual)
Sync: GET /memory/diff?since=TIMESTAMP (incremental sync)
Export: GET /memory/mind-export (full JSON dump)

Memory API
Memory API هي قلب Synapse. تُوفّر 22 نقطة نهاية لتخزين واسترجاع وبحث وإدارة
الذكريات المنظمة. تتطلب جميع نقاط النهاية Mind Key للمصادقة.
> [!CRITICAL]
> استدعِ دائمًا  في بداية كل جلسة. هذه هي الطريقة
> الوحيدة لإعادة بناء السياق من الجلسات السابقة.
الفئات
تُنظّم الذكريات في 8 فئات:
| الفئة | حالة الاستخدام |
|----------|----------|
|  | اسم المستخدم، الدور، معلومات الاتصال، تفضيلات حول الذات |
|  | الإعجابات، عدم الإعجابات، أسلوب العمل، تفضيلات التواصل |
|  | حقائق قابلة للتحقق (تفاصيل المشروع، التواريخ، عناوين URL) |
|  | حالة المشروع، المعالم، البنية |
|  | الأشياء التي يبرع فيها المستخدم |
|  | أخطاء سابقة — تجنب تكرارها |
|  | سياق ذو صلة بالجلسة |
|  | ملاحظات متفرقة |
الأولويات
-  — جيد معرفته
-  — افتراضي
-  — مهم
-  — يجب ألا يُنسى أبدًا (هوية المستخدم، معلومات قانونية)
نقاط النهاية الأساسية
GET /memory/recall
يُرجع جميع الذكريات كنص عادي مُحسّن لنماذج LLM. استدعِ هذا عند بداية كل جلسة.
[CODE BLOCK]
الاستجابة (text/plain):
[CODE BLOCK]
POST /memory
تخزين ذاكرة جديدة أو تحديث ذاكرة موجودة (نفس الفئة + المفتاح = تحديث).
[CODE BLOCK]
الاستجابة: 
GET /memory
قائمة الذكريات مع مرشّحات اختيارية.
[CODE BLOCK]
PUT /memory/:id
تحديث ذاكرة محددة بالمعرّف.
[CODE BLOCK]
DELETE /memory/:id
حذف ذاكرة واحدة.
[CODE BLOCK]
نقاط نهاية البحث
GET /memory/search
بحث نصي كامل باستخدام FTS5.
[CODE BLOCK]
صياغة FTS5:
- كلمات متعددة = AND: 
- عبارة: 
- بادئة: 
- منطقي: 
- استبعاد: 
GET /memory/semantic-search
بحث مفاهيمي باستخدام التضمينات (أبطأ من FTS5 لكنه يفهم المعنى).
[CODE BLOCK]
يُرجع ذكريات متشابهة دلاليًا مع الاستعلام، حتى لو لم تتطابق الكلمات
المفتاحية. مفيد لـ "إيجاد ذكريات حول X" حيث يُوصف X بشكل مختلف.
GET /memory/by-tag
قائمة الذكريات حسب الوسم.
[CODE BLOCK]
GET /memory/related/:id
إيجاد ذكريات مرتبطة بذاكرة محددة (عبر الوسوم المشتركة).
[CODE BLOCK]
المزامنة والـ Diff
GET /memory/diff
مزامنة تزايدية — تُرجع الذكريات المتغيّرة منذ طابع زمني.
[CODE BLOCK]
الاستجابة: 
POST /memory/sync
تطبيق diff من نسخة أخرى (للمزامنة المستضافة ذاتيًا).
[CODE BLOCK]
العمليات الكمية
POST /memory/bulk-delete
حذف ذكريات متعددة بالمعرّف.
[CODE BLOCK]
POST /memory/embed-batch
توليد تضمينات للذكريات التي لا تملكها بعد (للبحث الدلالي).
[CODE BLOCK]
GET /memory/embed-batch-status
التحقق من تقدّم توليد التضمينات.
[CODE BLOCK]
التحقق
للذكريات علامة . الذكريات المخزّنة بواسطة الوكيل تكون غير مُتحقّق منها
افتراضيًا ()؛ الذكريات المخزّنة بواسطة الإنسان مُتحقّق منها
().
POST /memory/verify
تعليم ذاكرة كمُتحقّق منها (يتطلب JWT، وليس Mind Key).
[CODE BLOCK]
POST /memory/unverify
تعليم ذاكرة كغير مُتحقّق منها (يتطلب JWT).
[CODE BLOCK]
GET /memory/unverified
قائمة الذكريات بانتظار التحقق البشري.
[CODE BLOCK]
الإحصائيات والتدقيق
GET /memory/stats
إحصائيات تجميعية للعقل الحالي.
[CODE BLOCK]
يُرجع: 
GET /memory/audit
سجل تدقيق لجميع العمليات التي تُغيّر الحالة.
[CODE BLOCK]
GET /memory/contradictions
اكتشاف تناقضات محتملة في الذكريات المخزّنة.
[CODE BLOCK]
GET /memory/expiring
قائمة الذكريات التي تقترب تواريخ انتهائها.
[CODE BLOCK]
الحالة والتصدير
GET /memory/health
فحص حالة سريع لنظام الذاكرة.
[CODE BLOCK]
GET /memory/mind-export
تصدير JSON كامل لجميع الذكريات (للنسخ الاحتياطي).
[CODE BLOCK]
POST /memory/compact
ضغط الذكريات المتشابهة (تلخيص تلقائي).
[CODE BLOCK]
الخطوات التالية
- البداية السريعة لـ LLMs
- أفضل ممارسات الذاكرة
- بحث FTS5
- البحث الدلالي