{"title":"بنية Synapse","slug":"architecture","category":"concepts","summary":"كيف بُني Synapse — Fastify، PostgreSQL، FTS5، التضمينات، خادم MCP.","audience":["human","llm"],"tags":["architecture","design","components"],"difficulty":"intermediate","updated":"2026-06-27","word_count":431,"read_minutes":2,"lang":"ar","translated":true,"requested_lang":"ar","content_markdown":"\n# بنية Synapse\n\nSynapse واجهة ذاكرة متعددة المستأجرين مبنية على Fastify، و PostgreSQL مع FTS5،\nوخدمة تضمينات اختيارية للبحث الدلالي.\n\n## البنية عالية المستوى\n\n```\n┌──────────────────────────────────────────────────────────┐\n│ Clients │\n├──────────────┬──────────────┬──────────────┬─────────────┤\n│ LLM Agents │ Web Browsers│ MCP Clients │ Webhooks │\n│ (curl/SDK) │ (humans) │ (Claude/etc) │ (external) │\n└──────┬───────┴──────┬───────┴──────┬───────┴──────┬──────┘\n │ │ │ │\n └──────────────┴──────────────┴──────────────┘\n │\n ▼\n ┌───────────────────────────────┐\n │ Synapse API (Fastify) │\n │ port 12800 │\n │ - REST endpoints │\n │ - Auth (Mind Key / JWT) │\n │ - Rate limiting │\n │ - Static file serving │\n └───────────────┬───────────────┘\n │\n ┌───────────────┼───────────────┐\n ▼ ▼ ▼\n ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n │ PostgreSQL │ │ Embeddings │ │ MCP Server │\n │ + FTS5 │ │ Service │ │ (separate) │\n │ │ │ (optional) │ │ port 13100 │\n │ - memories │ │ │ │ │\n │ - tasks │ │ - generate │ │ - 79 tools │\n │ - chat │ │ embeddings│ │ - stdio/SSE │\n │ - scripts │ │ │ │ - WebSocket │\n └─────────────┘ └─────────────┘ └─────────────┘\n```\n\n## المكوّنات الأساسية\n\n### 1. Synapse API (Fastify)\n\nخادم HTTP الرئيسي. يتولى:\n\n- نقاط نهاية REST (`/memory`، `/chat`، `/mind/tasks`، إلخ)\n- المصادقة (Mind Key للوكلاء، JWT للبشر)\n- حدود المعدل (مصادقة `?key=` فقط)\n- تقديم الملفات الثابتة (واجهة الويب في `/human`، `/docs`، إلخ)\n- إرسال الـ webhooks\n\nبُني بـ **Fastify 5** للأداء. يعمل على المنفذ 12800 في الإنتاج.\n\n### 2. PostgreSQL مع FTS5\n\nمخزن البيانات الأساسي. يستخدم PostgreSQL مع امتداد FTS5 للبحث\nبنص كامل.\n\n**الجداول الرئيسية:**\n\n| الجدول | الغرض |\n|-------|---------|\n| `users` | حسابات المستخدمين |\n| `minds` | نطاقات العقل (لكل واحد Mind Key) |\n| `memories` | سجلات الذاكرة مع جدول FTS5 الافتراضي |\n| `tasks` | إدارة المهام |\n| `chat_messages` | سجل الدردشة |\n| `scripts` | السكربتات الدائمة |\n| `webhooks` | تسجيلات الـ webhooks |\n| `cron_jobs` | المهام المجدولة |\n| `variables` | تخزين القيم الأساسية |\n| `audit_log` | مسار التدقيق |\n\nيُمكّن **FTS5** بحثًا نصيًا كاملًا أقل من مللي ثانية عبر جميع محتويات الذاكرة.\nراجع [بحث FTS5](/docs/concepts/fts5-search) للتفاصيل.\n\n### 3. خدمة التضمينات (اختيارية)\n\nللبحث الدلالي، يُولّد Synapse تضمينات متجهة لمحتوى الذاكرة.\nتُخزّن بجانب الذكريات وتُستخدم للبحث عن التشابه.\n\n- المزوّد: قابل للإعداد (OpenAI، نموذج محلي، إلخ)\n- يُخزَّن كعمود `vector` في جدول `memories`\n- يُستخدم بواسطة نقطة النهاية `/memory/semantic-search`\n- راجع [البحث الدلالي](/docs/concepts/semantic-search)\n\n### 4. خادم MCP (خدمة منفصلة)\n\nيعمل خادم Synapse MCP كعملية منفصلة (المنفذ 13100). يقوم بـ:\n\n- عرض 79 أداة عبر Model Context Protocol\n- دعم نقل stdio و HTTP/SSE و WebSocket\n- ترجمة استدعاءات أدوات MCP إلى استدعاءات Synapse API\n- متعدد المستأجرين: Mind Key واحد لكل جلسة\n\n### 5. وكيل المتصفح (خدمة منفصلة)\n\nلأتمتة المتصفح، تعمل خدمة منفصلة قائمة على Playwright على المنفذ 13000.\nيمكن لخادم MCP استدعاؤها لأدوات `browser_*`.\n\n### 6. وكيل SSH (خدمة منفصلة)\n\nلأوامر SSH البعيدة، تعمل خدمة منفصلة على المنفذ 12900.\n\n## نموذج تعدد المستأجرين\n\n```\nUser Account (email + password)\n │\n ├── Mind 1 (Mind Key 1)\n │ ├── Memories\n │ ├── Tasks\n │ ├── Chat\n │ └── Scripts\n │\n ├── Mind 2 (Mind Key 2)\n │ └── ... (isolated from Mind 1)\n │\n └── Mind 3 (Mind Key 3)\n └── ...\n```\n\nكل عقل معزول تمامًا. تمنح Mind Keys الوصول إلى عقل واحد فقط.\nتمنح JWTs الوصول إلى حساب المستخدم (لإدارة العقول).\n\nراجع [تعدد المستأجرين](/docs/concepts/multi-tenancy) للتفاصيل.\n\n## تدفق الطلبات\n\n### طلب تخزين الذاكرة\n\n```\n1. Client sends POST /memory with Authorization: Bearer mk_xxx\n2. Fastify receives request\n3. Auth middleware validates Mind Key, attaches mind_id to request\n4. Memory route handler:\n a. Validate JSON body (zod schema)\n b. Insert into memories table\n c. Update FTS5 index\n d. (Async) Generate embedding if embeddings enabled\n e. Trigger webhooks for memory.store event\n5. Return { id, status: \"stored\" }\n```\n\n### طلب بحث الذاكرة\n\n```\n1. Client sends GET /memory/search?q=docker\n2. Auth middleware validates Mind Key\n3. Memory route handler:\n a. Parse query (FTS5 syntax)\n b. Execute FTS5 MATCH against memories table\n c. Filter by mind_id (tenant isolation)\n d. Rank by relevance\n e. Return results\n```\n\n## النشر\n\nيُنشر Synapse كحاوية Docker. راجع `docker-compose.yml`:\n\n```yaml\nservices:\n synapse:\n image: registry.gitlab.com/schaefer-services/synapse:latest\n ports:\n - \"12800:12800\"\n environment:\n - DATABASE_URL=postgres://...\n - JWT_SECRET=...\n - SYNAPSE_HOST=0.0.0.0\n - SYNAPSE_PORT=12800\n depends_on:\n - postgres\n \n postgres:\n image: postgres:16\n volumes:\n - pgdata:/var/lib/postgresql/data\n environment:\n - POSTGRES_DB=synapse\n - POSTGRES_PASSWORD=...\n```\n\n## خصائص الأداء\n\n| العملية | زمن الاستجابة | الإنتاجية |\n|-----------|---------|------------|\n| تخزين ذاكرة | ~5 مللي ث | 1000+ طلب/ث |\n| استدعاء ذاكرة | ~20 مللي ث | 500 طلب/ث |\n| بحث FTS5 | ~10 مللي ث | 800 طلب/ث |\n| بحث دلالي | ~50 مللي ث | 200 طلب/ث |\n| استطلاع الدردشة | ~5 مللي ث | 2000 طلب/ث |\n\n## الخطوات التالية\n\n- [نموذج الذاكرة](/docs/concepts/memory-model)\n- [تعدد المستأجرين](/docs/concepts/multi-tenancy)\n- [بحث FTS5](/docs/concepts/fts5-search)\n","content_html":"

بنية Synapse

\n

Synapse واجهة ذاكرة متعددة المستأجرين مبنية على Fastify، و PostgreSQL مع FTS5،\nوخدمة تضمينات اختيارية للبحث الدلالي.

\n

البنية عالية المستوى

\n
┌──────────────────────────────────────────────────────────┐\n│                       Clients                            │\n├──────────────┬──────────────┬──────────────┬─────────────┤\n│  LLM Agents  │  Web Browsers│  MCP Clients │  Webhooks   │\n│  (curl/SDK)  │  (humans)    │ (Claude/etc) │  (external) │\n└──────┬───────┴──────┬───────┴──────┬───────┴──────┬──────┘\n       │              │              │              │\n       └──────────────┴──────────────┴──────────────┘\n                              │\n                              ▼\n              ┌───────────────────────────────┐\n              │    Synapse API (Fastify)      │\n              │    port 12800                 │\n              │    - REST endpoints           │\n              │    - Auth (Mind Key / JWT)    │\n              │    - Rate limiting            │\n              │    - Static file serving      │\n              └───────────────┬───────────────┘\n                              │\n              ┌───────────────┼───────────────┐\n              ▼               ▼               ▼\n       ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n       │ PostgreSQL  │ │ Embeddings  │ │ MCP Server  │\n       │ + FTS5      │ │ Service     │ │ (separate)  │\n       │             │ │ (optional)  │ │ port 13100  │\n       │ - memories  │ │             │ │             │\n       │ - tasks     │ │ - generate  │ │ - 79 tools  │\n       │ - chat      │ │   embeddings│ │ - stdio/SSE │\n       │ - scripts   │ │             │ │ - WebSocket │\n       └─────────────┘ └─────────────┘ └─────────────┘

المكوّنات الأساسية

\n

1. Synapse API (Fastify)

\n

خادم HTTP الرئيسي. يتولى:

\n\n

بُني بـ Fastify 5 للأداء. يعمل على المنفذ 12800 في الإنتاج.

\n

2. PostgreSQL مع FTS5

\n

مخزن البيانات الأساسي. يستخدم PostgreSQL مع امتداد FTS5 للبحث\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\n\n\n\n\n\n\n\n\n\n
الجدولالغرض
usersحسابات المستخدمين
mindsنطاقات العقل (لكل واحد Mind Key)
memoriesسجلات الذاكرة مع جدول FTS5 الافتراضي
tasksإدارة المهام
chat_messagesسجل الدردشة
scriptsالسكربتات الدائمة
webhooksتسجيلات الـ webhooks
cron_jobsالمهام المجدولة
variablesتخزين القيم الأساسية
audit_logمسار التدقيق
\n

يُمكّن FTS5 بحثًا نصيًا كاملًا أقل من مللي ثانية عبر جميع محتويات الذاكرة.\nراجع بحث FTS5 للتفاصيل.

\n

3. خدمة التضمينات (اختيارية)

\n

للبحث الدلالي، يُولّد Synapse تضمينات متجهة لمحتوى الذاكرة.\nتُخزّن بجانب الذكريات وتُستخدم للبحث عن التشابه.

\n\n

4. خادم MCP (خدمة منفصلة)

\n

يعمل خادم Synapse MCP كعملية منفصلة (المنفذ 13100). يقوم بـ:

\n\n

5. وكيل المتصفح (خدمة منفصلة)

\n

لأتمتة المتصفح، تعمل خدمة منفصلة قائمة على Playwright على المنفذ 13000.\nيمكن لخادم MCP استدعاؤها لأدوات browser_*.

\n

6. وكيل SSH (خدمة منفصلة)

\n

لأوامر SSH البعيدة، تعمل خدمة منفصلة على المنفذ 12900.

\n

نموذج تعدد المستأجرين

\n
User Account (email + password)\n  │\n  ├── Mind 1 (Mind Key 1)\n  │   ├── Memories\n  │   ├── Tasks\n  │   ├── Chat\n  │   └── Scripts\n  │\n  ├── Mind 2 (Mind Key 2)\n  │   └── ... (isolated from Mind 1)\n  │\n  └── Mind 3 (Mind Key 3)\n      └── ...

كل عقل معزول تمامًا. تمنح Mind Keys الوصول إلى عقل واحد فقط.\nتمنح JWTs الوصول إلى حساب المستخدم (لإدارة العقول).

\n

راجع تعدد المستأجرين للتفاصيل.

\n

تدفق الطلبات

\n

طلب تخزين الذاكرة

\n
1. Client sends POST /memory with Authorization: Bearer mk_xxx\n2. Fastify receives request\n3. Auth middleware validates Mind Key, attaches mind_id to request\n4. Memory route handler:\n   a. Validate JSON body (zod schema)\n   b. Insert into memories table\n   c. Update FTS5 index\n   d. (Async) Generate embedding if embeddings enabled\n   e. Trigger webhooks for memory.store event\n5. Return { id, status: "stored" }

طلب بحث الذاكرة

\n
1. Client sends GET /memory/search?q=docker\n2. Auth middleware validates Mind Key\n3. Memory route handler:\n   a. Parse query (FTS5 syntax)\n   b. Execute FTS5 MATCH against memories table\n   c. Filter by mind_id (tenant isolation)\n   d. Rank by relevance\n   e. Return results

النشر

\n

يُنشر Synapse كحاوية Docker. راجع docker-compose.yml:

\n
services:\n  synapse:\n    image: registry.gitlab.com/schaefer-services/synapse:latest\n    ports:\n      - "12800:12800"\n    environment:\n      - DATABASE_URL=postgres://...\n      - JWT_SECRET=...\n      - SYNAPSE_HOST=0.0.0.0\n      - SYNAPSE_PORT=12800\n    depends_on:\n      - postgres\n  \n  postgres:\n    image: postgres:16\n    volumes:\n      - pgdata:/var/lib/postgresql/data\n    environment:\n      - POSTGRES_DB=synapse\n      - POSTGRES_PASSWORD=...

خصائص الأداء

\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
العمليةزمن الاستجابةالإنتاجية
تخزين ذاكرة~5 مللي ث1000+ طلب/ث
استدعاء ذاكرة~20 مللي ث500 طلب/ث
بحث FTS5~10 مللي ث800 طلب/ث
بحث دلالي~50 مللي ث200 طلب/ث
استطلاع الدردشة~5 مللي ث2000 طلب/ث
\n

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

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