{"title":"Memory API","slug":"memory","category":"api","summary":"مرجع كامل لنقاط نهاية الذاكرة الـ 22: التخزين، الاستدعاء، البحث، البحث الدلالي، المزامنة، التدقيق، والمزيد.","audience":["human","llm"],"tags":["api","memory","crud","search","fts5","semantic"],"difficulty":"intermediate","updated":"2026-06-27","word_count":501,"read_minutes":3,"llm_context":"Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)\nALWAYS call GET /memory/recall at session start.\nPOST /memory with same category+key updates the existing memory.\nCategories: identity, preference, fact, project, skill, mistake, context, note, credentials\nPriorities: low, normal, high, critical\nSearch: GET /memory/search?q=... (FTS5 syntax: AND, OR, \"phrases\", prefix*)\nSemantic: GET /memory/semantic-search?q=... (slower, conceptual)\nSync: GET /memory/diff?since=TIMESTAMP (incremental sync)\nExport: GET /memory/mind-export (full JSON dump)\n","lang":"ar","translated":true,"requested_lang":"ar","content_markdown":"\n# Memory API\n\nMemory API هي قلب Synapse. تُوفّر 22 نقطة نهاية لتخزين واسترجاع وبحث وإدارة\nالذكريات المنظمة. تتطلب جميع نقاط النهاية Mind Key للمصادقة.\n\n> [!CRITICAL]\n> **استدعِ دائمًا `GET /memory/recall` في بداية كل جلسة.** هذه هي الطريقة\n> الوحيدة لإعادة بناء السياق من الجلسات السابقة.\n\n## الفئات\n\nتُنظّم الذكريات في 8 فئات:\n\n| الفئة | حالة الاستخدام |\n|----------|----------|\n| `identity` | اسم المستخدم، الدور، معلومات الاتصال، تفضيلات حول الذات |\n| `preference` | الإعجابات، عدم الإعجابات، أسلوب العمل، تفضيلات التواصل |\n| `fact` | حقائق قابلة للتحقق (تفاصيل المشروع، التواريخ، عناوين URL) |\n| `project` | حالة المشروع، المعالم، البنية |\n| `skill` | الأشياء التي يبرع فيها المستخدم |\n| `mistake` | أخطاء سابقة — تجنب تكرارها |\n| `context` | سياق ذو صلة بالجلسة |\n| `note` | ملاحظات متفرقة |\n\n## الأولويات\n\n- `low` — جيد معرفته\n- `normal` — افتراضي\n- `high` — مهم\n- `critical` — يجب ألا يُنسى أبدًا (هوية المستخدم، معلومات قانونية)\n\n## نقاط النهاية الأساسية\n\n### GET /memory/recall\n\nيُرجع جميع الذكريات كنص عادي مُحسّن لنماذج LLM. استدعِ هذا عند بداية كل جلسة.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\nالاستجابة (text/plain):\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n user_name\n Michael Schäfer\n Tags: person, identity\n\n...\n```\n\n### POST /memory\n\nتخزين ذاكرة جديدة أو تحديث ذاكرة موجودة (نفس الفئة + المفتاح = تحديث).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"category\": \"fact\",\n \"key\": \"user_name\",\n \"content\": \"The user's name is Michael Schäfer\",\n \"tags\": [\"person\", \"identity\"],\n \"priority\": \"critical\"\n }'\n```\n\nالاستجابة: `{ \"id\": \"mem_001\", \"status\": \"stored\" }`\n\n### GET /memory\n\nقائمة الذكريات مع مرشّحات اختيارية.\n\n```bash\n# جميع الذكريات (JSON)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?limit=50&offset=0\"\n\n# تصفية حسب الفئة\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?category=project\"\n\n# تصفية حسب الوسم\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?tag=docker\"\n```\n\n### PUT /memory/:id\n\nتحديث ذاكرة محددة بالمعرّف.\n\n```bash\ncurl -X PUT https://synapse.schaefer.zone/memory/mem_001 \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Updated content\", \"priority\": \"high\"}'\n```\n\n### DELETE /memory/:id\n\nحذف ذاكرة واحدة.\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## نقاط نهاية البحث\n\n### GET /memory/search\n\nبحث نصي كامل باستخدام FTS5.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=docker+swarm\"\n```\n\nصياغة FTS5:\n\n- كلمات متعددة = AND: `docker swarm`\n- عبارة: `\"docker swarm\"`\n- بادئة: `docker*`\n- منطقي: `docker OR kubernetes`\n- استبعاد: `docker -swarm`\n\n### GET /memory/semantic-search\n\nبحث مفاهيمي باستخدام التضمينات (أبطأ من FTS5 لكنه يفهم المعنى).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\nيُرجع ذكريات متشابهة دلاليًا مع الاستعلام، حتى لو لم تتطابق الكلمات\nالمفتاحية. مفيد لـ \"إيجاد ذكريات حول X\" حيث يُوصف X بشكل مختلف.\n\n### GET /memory/by-tag\n\nقائمة الذكريات حسب الوسم.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/by-tag?tag=docker\"\n```\n\n### GET /memory/related/:id\n\nإيجاد ذكريات مرتبطة بذاكرة محددة (عبر الوسوم المشتركة).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/related/mem_001\n```\n\n## المزامنة والـ Diff\n\n### GET /memory/diff\n\nمزامنة تزايدية — تُرجع الذكريات المتغيّرة منذ طابع زمني.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/diff?since=1700000000\"\n```\n\nالاستجابة: `{ \"added\": [...], \"updated\": [...], \"deleted\": [...] }`\n\n### POST /memory/sync\n\nتطبيق diff من نسخة أخرى (للمزامنة المستضافة ذاتيًا).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/sync \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"added\": [...], \"updated\": [...], \"deleted\": [...]}'\n```\n\n## العمليات الكمية\n\n### POST /memory/bulk-delete\n\nحذف ذكريات متعددة بالمعرّف.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/bulk-delete \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n### POST /memory/embed-batch\n\nتوليد تضمينات للذكريات التي لا تملكها بعد (للبحث الدلالي).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"limit\": 100}'\n```\n\n### GET /memory/embed-batch-status\n\nالتحقق من تقدّم توليد التضمينات.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## التحقق\n\nللذكريات علامة `verified`. الذكريات المخزّنة بواسطة الوكيل تكون غير مُتحقّق منها\nافتراضيًا (`source=agent`)؛ الذكريات المخزّنة بواسطة الإنسان مُتحقّق منها\n(`source=user`).\n\n### POST /memory/verify\n\nتعليم ذاكرة كمُتحقّق منها (يتطلب JWT، وليس Mind Key).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### POST /memory/unverify\n\nتعليم ذاكرة كغير مُتحقّق منها (يتطلب JWT).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### GET /memory/unverified\n\nقائمة الذكريات بانتظار التحقق البشري.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/unverified?limit=100\"\n```\n\n## الإحصائيات والتدقيق\n\n### GET /memory/stats\n\nإحصائيات تجميعية للعقل الحالي.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/stats\n```\n\nيُرجع: `{ \"total\": 12, \"verified\": 10, \"unverified\": 2, \"by_category\": {...}, \"by_priority\": {...} }`\n\n### GET /memory/audit\n\nسجل تدقيق لجميع العمليات التي تُغيّر الحالة.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/audit?limit=100&action=store\"\n```\n\n### GET /memory/contradictions\n\nاكتشاف تناقضات محتملة في الذكريات المخزّنة.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/contradictions\n```\n\n### GET /memory/expiring\n\nقائمة الذكريات التي تقترب تواريخ انتهائها.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/expiring?within=7d\"\n```\n\n## الحالة والتصدير\n\n### GET /memory/health\n\nفحص حالة سريع لنظام الذاكرة.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/health\n```\n\n### GET /memory/mind-export\n\nتصدير JSON كامل لجميع الذكريات (للنسخ الاحتياطي).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mind-export > backup.json\n```\n\n### POST /memory/compact\n\nضغط الذكريات المتشابهة (تلخيص تلقائي).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/compact \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"dry_run\": true}'\n```\n\n## الخطوات التالية\n\n- [البداية السريعة لـ LLMs](/docs/getting-started/quick-start-llm)\n- [أفضل ممارسات الذاكرة](/docs/guides/memory-best-practices)\n- [بحث FTS5](/docs/concepts/fts5-search)\n- [البحث الدلالي](/docs/concepts/semantic-search)\n","content_html":"

Memory API

\n

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

\n

**استدعِ دائمًا `GET /memory/recall` في بداية كل جلسة.** هذه هي الطريقة\nالوحيدة لإعادة بناء السياق من الجلسات السابقة.

الفئات

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

الفئة	حالة الاستخدام
`identity`	اسم المستخدم، الدور، معلومات الاتصال، تفضيلات حول الذات
`preference`	الإعجابات، عدم الإعجابات، أسلوب العمل، تفضيلات التواصل
`fact`	حقائق قابلة للتحقق (تفاصيل المشروع، التواريخ، عناوين URL)
`project`	حالة المشروع، المعالم، البنية
`skill`	الأشياء التي يبرع فيها المستخدم
`mistake`	أخطاء سابقة — تجنب تكرارها
`context`	سياق ذو صلة بالجلسة
`note`	ملاحظات متفرقة

\n

الأولويات

\n

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

\n

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

\n

GET /memory/recall

\n

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

\n

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

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

\n

Mind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n...

POST /memory

\n

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

\n

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

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

\n

GET /memory

\n

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

\n

# جميع الذكريات (JSON)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?limit=50&offset=0"\n\n# تصفية حسب الفئة\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?category=project"\n\n# تصفية حسب الوسم\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?tag=docker"

PUT /memory/:id

\n

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

\n

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

DELETE /memory/:id

\n

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

\n

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

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

\n

GET /memory/search

\n

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

\n

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

صياغة FTS5:

\n

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

\n

GET /memory/semantic-search

\n

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

\n

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

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

\n

GET /memory/by-tag

\n

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

\n

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

GET /memory/related/:id

\n

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

\n

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

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

\n

GET /memory/diff

\n

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

\n

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

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

\n

POST /memory/sync

\n

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

\n

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

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

\n

POST /memory/bulk-delete

\n

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

\n

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

POST /memory/embed-batch

\n

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

\n

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

GET /memory/embed-batch-status

\n

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

\n

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

التحقق

\n

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

\n

POST /memory/verify

\n

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

\n

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

POST /memory/unverify

\n

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

\n

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

GET /memory/unverified

\n

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

\n

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

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

\n

GET /memory/stats

\n

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

\n

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

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

\n

GET /memory/audit

\n

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

\n

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

GET /memory/contradictions

\n

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

\n

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

GET /memory/expiring

\n

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

\n

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

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

\n

GET /memory/health

\n

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

\n

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

GET /memory/mind-export

\n

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

\n

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

POST /memory/compact

\n

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

\n

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

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

\n

\n","urls":{"html":"/docs/api/memory","text":"/docs/api/memory?format=text","json":"/docs/api/memory?format=json","llm":"/docs/api/memory?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}