بنية Synapse

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

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

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

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

1. Synapse API (Fastify)

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

• نقاط نهاية REST (/memory، /chat، /mind/tasks، إلخ)
• المصادقة (Mind Key للوكلاء، JWT للبشر)
• حدود المعدل (مصادقة ?key= فقط)
• تقديم الملفات الثابتة (واجهة الويب في /human، /docs، إلخ)
• إرسال الـ webhooks

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

2. PostgreSQL مع FTS5

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

الجداول الرئيسية:

الجدول	الغرض
users	حسابات المستخدمين
minds	نطاقات العقل (لكل واحد Mind Key)
memories	سجلات الذاكرة مع جدول FTS5 الافتراضي
tasks	إدارة المهام
chat_messages	سجل الدردشة
scripts	السكربتات الدائمة
webhooks	تسجيلات الـ webhooks
cron_jobs	المهام المجدولة
variables	تخزين القيم الأساسية
audit_log	مسار التدقيق

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

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

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

• المزوّد: قابل للإعداد (OpenAI، نموذج محلي، إلخ)
• يُخزَّن كعمود vector في جدول memories
• يُستخدم بواسطة نقطة النهاية /memory/semantic-search
• راجع البحث الدلالي

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

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

• عرض 79 أداة عبر Model Context Protocol
• دعم نقل stdio و HTTP/SSE و WebSocket
• ترجمة استدعاءات أدوات MCP إلى استدعاءات Synapse API
• متعدد المستأجرين: Mind Key واحد لكل جلسة

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

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

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

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

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

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

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

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

تدفق الطلبات

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

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

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

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

النشر

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

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

خصائص الأداء

العملية	زمن الاستجابة	الإنتاجية
تخزين ذاكرة	~5 مللي ث	1000+ طلب/ث
استدعاء ذاكرة	~20 مللي ث	500 طلب/ث
بحث FTS5	~10 مللي ث	800 طلب/ث
بحث دلالي	~50 مللي ث	200 طلب/ث
استطلاع الدردشة	~5 مللي ث	2000 طلب/ث

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

• نموذج الذاكرة
• تعدد المستأجرين
• بحث FTS5