Memory API

Memory API هي قلب Synapse. تُوفّر 22 نقطة نهاية لتخزين واسترجاع وبحث وإدارة الذكريات المنظمة. تتطلب جميع نقاط النهاية Mind Key للمصادقة.

الفئات

تُنظّم الذكريات في 8 فئات:

الأولويات

• low — جيد معرفته
• normal — افتراضي
• high — مهم
• critical — يجب ألا يُنسى أبدًا (هوية المستخدم، معلومات قانونية)

نقاط النهاية الأساسية

GET /memory/recall

يُرجع جميع الذكريات كنص عادي مُحسّن لنماذج LLM. استدعِ هذا عند بداية كل جلسة.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall

الاستجابة (text/plain):

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

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

...

POST /memory

تخزين ذاكرة جديدة أو تحديث ذاكرة موجودة (نفس الفئة + المفتاح = تحديث).

curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "fact",
    "key": "user_name",
    "content": "The user's name is Michael Schäfer",
    "tags": ["person", "identity"],
    "priority": "critical"
  }'

الاستجابة: { "id": "mem_001", "status": "stored" }

GET /memory

قائمة الذكريات مع مرشّحات اختيارية.

# جميع الذكريات (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# تصفية حسب الفئة
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# تصفية حسب الوسم
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"

PUT /memory/:id

تحديث ذاكرة محددة بالمعرّف.

curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'

DELETE /memory/:id

حذف ذاكرة واحدة.

curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001

نقاط نهاية البحث

GET /memory/search

بحث نصي كامل باستخدام FTS5.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=docker+swarm"

صياغة FTS5:

• كلمات متعددة = AND: docker swarm
• عبارة: "docker swarm"
• بادئة: docker*
• منطقي: docker OR kubernetes
• استبعاد: docker -swarm

GET /memory/semantic-search

بحث مفاهيمي باستخدام التضمينات (أبطأ من FTS5 لكنه يفهم المعنى).

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"

يُرجع ذكريات متشابهة دلاليًا مع الاستعلام، حتى لو لم تتطابق الكلمات المفتاحية. مفيد لـ "إيجاد ذكريات حول X" حيث يُوصف X بشكل مختلف.

GET /memory/by-tag

قائمة الذكريات حسب الوسم.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"

GET /memory/related/:id

إيجاد ذكريات مرتبطة بذاكرة محددة (عبر الوسوم المشتركة).

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001

المزامنة والـ Diff

GET /memory/diff

مزامنة تزايدية — تُرجع الذكريات المتغيّرة منذ طابع زمني.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"

الاستجابة: { "added": [...], "updated": [...], "deleted": [...] }

POST /memory/sync

تطبيق diff من نسخة أخرى (للمزامنة المستضافة ذاتيًا).

curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'

العمليات الكمية

POST /memory/bulk-delete

حذف ذكريات متعددة بالمعرّف.

curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'

POST /memory/embed-batch

توليد تضمينات للذكريات التي لا تملكها بعد (للبحث الدلالي).

curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

GET /memory/embed-batch-status

التحقق من تقدّم توليد التضمينات.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status

التحقق

للذكريات علامة verified. الذكريات المخزّنة بواسطة الوكيل تكون غير مُتحقّق منها افتراضيًا (source=agent)؛ الذكريات المخزّنة بواسطة الإنسان مُتحقّق منها (source=user).

POST /memory/verify

تعليم ذاكرة كمُتحقّق منها (يتطلب JWT، وليس Mind Key).

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

POST /memory/unverify

تعليم ذاكرة كغير مُتحقّق منها (يتطلب JWT).

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

GET /memory/unverified

قائمة الذكريات بانتظار التحقق البشري.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"

الإحصائيات والتدقيق

GET /memory/stats

إحصائيات تجميعية للعقل الحالي.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/stats

يُرجع: { "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }

GET /memory/audit

سجل تدقيق لجميع العمليات التي تُغيّر الحالة.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"

GET /memory/contradictions

اكتشاف تناقضات محتملة في الذكريات المخزّنة.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/contradictions

GET /memory/expiring

قائمة الذكريات التي تقترب تواريخ انتهائها.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"

الحالة والتصدير

GET /memory/health

فحص حالة سريع لنظام الذاكرة.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/health

GET /memory/mind-export

تصدير JSON كامل لجميع الذكريات (للنسخ الاحتياطي).

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mind-export > backup.json

POST /memory/compact

ضغط الذكريات المتشابهة (تلخيص تلقائي).

curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'

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

• البداية السريعة لـ LLMs
• أفضل ممارسات الذاكرة
• بحث FTS5
• البحث الدلالي