# เอกสาร SYNAPSE — ข้อมูลอ้างอิงทั้งหมด
# สร้างเมื่อ: 2026-07-18T04:11:43.416Z
# บทความทั้งหมด: 47
เอกสารนี้ประกอบด้วยเอกสาร API ของ Synapse ทั้งหมด
Base URL: https://synapse.schaefer.zone
Language: th
========================================================================
## หมวดหมู่: เริ่มต้น
ทุกสิ่งที่คุณต้องการเพื่อเริ่มต้นใช้งาน Synapse
────────────────────────────────────────────────────────────
# Authentication & Mind Key
SUMMARY: วิธีที่ Synapse authentication ทำงาน: Mind Key สำหรับ agent, JWT สำหรับ human, ?key= สำหรับเครื่องมือ URL-only
KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.
Authentication & Mind Key
Synapse ใช้สองวิธี authentication แต่ละวิธีปรับให้เหมาะกับกรณีใช้งานต่างกัน การเข้าใจความแตกต่างเป็นสิ่งจำเป็นสำหรับการสร้าง integration ที่เชื่อถือได้
สองวิธี Auth
| วิธี | กรณีใช้งาน | Rate Limit | Expiry |
|--------|----------|------------|--------|
| Mind Key | LLM agent, เครื่องมืออัตโนมัติ | None (header) / 60 ต่อนาที (query) | ไม่มี |
| JWT | Human-facing UI, การดำเนินการบัญชี | None | 7 วัน |
Mind Key (สำหรับ Agent)
Mind Key เป็น tenant-scoped API token ใช้ยืนยันตัวตนข้อมูล mind เดียว (memory, task, chat, script ฯลฯ) ใช้สำหรับ:
- LLM agent เรียก API
- สคริปต์ automation เบื้องหลัง
- การกำหนดค่า MCP server
- integration ที่อยู่ยาวนานใด ๆ
Header authentication (แนะนำ)
[CODE BLOCK]
Query parameter (สำหรับเครื่องมือ URL-only)
[CODE BLOCK]
> [!WARNING]
> query parameter จำกัดที่ 60 request ต่อนาที Bearer header ไม่จำกัด ใช้ header เมื่อใดก็ตามที่ client ของคุณรองรับ custom header
การสร้าง Mind Key
[CODE BLOCK]
Response รวม — บันทึกทันที แสดงเพียงครั้งเดียว
รายการ mind ของคุณ
[CODE BLOCK]
ลบ mind (ย้อนกลับไม่ได้!)
[CODE BLOCK]
JWT (สำหรับ Human)
JWT ยืนยันตัวตน บัญชีผู้ใช้ ไม่ใช่ mind เฉพาะ ใช้สำหรับ:
- การสมัครและล็อกอินบัญชี
- สร้าง / รายการ / ลบ mind
- แชร์ mind กับผู้ใช้อื่น
- การจัดการ Web Push subscription
สมัคร
[CODE BLOCK]
ส่งกลับ:
ล็อกอิน
[CODE BLOCK]
ส่งกลับ:
การหมดอายุของ JWT
JWT หมดอายุหลัง 7 วัน เมื่อ JWT หมดอายุ เพียงเรียก อีกครั้งเพื่อรับใหม่ Mind Key ไม่หมดอายุ ดังนั้น integration ของ agent ที่มีอยู่ยังทำงานต่อ
แนวทางปฏิบัติด้านความปลอดภัย
> [!CRITICAL]
> - อย่า commit Mind Key ลง git ใช้ environment variable
> - อย่า log Mind Key ปิดบังใน log ()
> - หมุนเวียน key หากคุณสงสัยว่ารั่ว (ลบ mind, สร้างใหม่)
> - ใช้หนึ่ง mind ต่อโปรเจกต์ เพื่อจำกัดผลกระทบหาก key รั่ว
รูปแบบ environment variable
[CODE BLOCK]
[CODE BLOCK]
กำหนดค่า MCP server
[CODE BLOCK]
รูปแบบ Multi-Mind
ผู้ใช้แต่ละคนสามารถมีหลาย mind รูปแบบทั่วไป:
| ชื่อ Mind | วัตถุประสงค์ |
|-----------|---------|
| | memory เกี่ยวกับงาน |
| | ค่ากำหนดส่วนตัว, ครอบครัว |
| | context โปรเจกต์เฉพาะ |
| | ความคืบหน้าการเรียนรู้ |
| | fallback สำหรับใช้ทั่วไป |
ใช้ Mind Key ต่างกันสำหรับ LLM session ต่างกันเพื่อแยก context
Rate Limit
| วิธี Auth | Limit | Scope |
|-------------|-------|-------|
| Mind Key (header) | None | Per-mind |
| Mind Key (?key=) | 60/min | Per-IP |
| JWT (header) | None | Per-user |
| Public endpoint | None | Global |
Rate limit header (, , ) รวมอยู่ใน response เมื่อเกี่ยวข้อง
ขั้นตอนถัดไป
- Mind Key vs JWT — เมื่อใช้อันไหน
- Memory API — สิ่งที่คุณทำได้กับ Mind Key
- User API — การจัดการบัญชีด้วย JWT
────────────────────────────────────────────────────────────
# Mind Key vs JWT — ใช้เมื่อไร?
SUMMARY: คู่มือการตัดสินใจ: Mind Key สำหรับการเข้าถึงข้อมูล agent, JWT สำหรับการจัดการบัญชี
KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).
Mind Key vs JWT — ใช้เมื่อไร?
Synapse มีสอง authentication token การเลือกผิดจะนำไปสู่ error 401 คู่มือนี้ให้กรอบการตัดสินใจที่ชัดเจน
ตารางการตัดสินใจด่วน
| คุณต้องการ... | ใช้ |
|----------------|-----|
| จัดเก็บ / recall memory | Mind Key |
| ส่ง / poll ข้อความแช็ต | Mind Key |
| จัดการ task | Mind Key |
| เก็บ script | Mind Key |
| ลงทะเบียน webhook | Mind Key |
| ควบคุม computer | Mind Key (ฝั่งผู้ใช้) / Computer Token (ฝั่ง agent) |
| สมัครบัญชีผู้ใช้ | None (public) |
| ล็อกอิน | None (public) |
| สร้าง / รายการ / ลบ mind | JWT |
| แชร์ mind กับผู้ใช้อื่น | JWT |
| สมัครรับ web push notification | JWT |
| ดู audit log | Mind Key |
กฎง่าย ๆ
> [!TIP]
> หากมันสัมผัสข้อมูล mind เดียว → Mind Key
> หากมันจัดการบัญชีหรือ metadata ของ mind → JWT
Mind Key — Data Access Token
Mind Key ให้สิทธิ์เข้าถึง ข้อมูล mind หนึ่ง เป็น token ที่อยู่ยาวนานและไม่หมดอายุ (จนกว่า mind จะถูกลบ) เหมาะสำหรับ:
- LLM agent ที่เก็บ memory ข้าม session
- cron job เบื้องหลัง
- กำหนดค่า MCP server
- integration webhook
- แอปมือถือที่อ่าน memory
Mind Key ทำอะไรได้
- — อ่าน memory ทั้งหมดใน mind นี้
- — เก็บ/อัปเดต memory
- — อ่านข้อความแช็ต
- — ส่งข้อความแช็ต
- — รายการ task
- — สร้าง task
- — เก็บ script
- — ลงทะเบียน webhook
- — จัดคิวคำสั่ง computer
Mind Key ทำอะไรไม่ได้
- สร้าง / รายการ / ลบ mind (ต้องใช้ JWT)
- แชร์ mind กับผู้ใช้อื่น (ต้องใช้ JWT)
- ดูข้อมูลบัญชีผู้ใช้ (ต้องใช้ JWT)
- สมัครรับ web push (ต้องใช้ JWT)
JWT — Account Management Token
JWT ยืนยันตัวตน บัญชีผู้ใช้ หมดอายุหลัง 7 วัน และใช้สำหรับการดำเนินการระดับบัญชีที่ครอบคลุมหลาย mind หรือเกี่ยวข้องกับผู้ใช้อื่น
JWT ทำอะไรได้
- — สร้าง mind ใหม่ (ส่งกลับ Mind Key ใหม่)
- — รายการ mind ทั้งหมดของผู้ใช้นี้
- — ลบ mind
- — แชร์ mind กับผู้ใช้อื่น
- — สมัครรับ web push notification
- — รายการการแชร์ mind
JWT ทำอะไรไม่ได้
- อ่าน / เขียน memory (ต้องใช้ Mind Key)
- ส่งข้อความแช็ต (ต้องใช้ Mind Key)
- จัดการ task (ต้องใช้ Mind Key)
- ลงทะเบียน webhook (ต้องใช้ Mind Key)
กรณีพิเศษ: Computer Token
endpoint (ฝั่ง agent, สำหรับ screen-remote-agent) ใช้ token ประเภทที่สาม: Computer Token token นี้ถูกส่งกลับโดย เมื่อแลกรับ install code และเฉพาะสำหรับ computer ที่ลงทะเบียนหนึ่งเครื่อง
| Endpoint | Auth |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key or JWT |
| | Mind Key or JWT |
รูปแบบทั่วไป
รูปแบบ 1: LLM Agent เดียว
1. สมัครครั้งเดียว → รับ JWT
2. สร้าง mind เดียว → รับ Mind Key
3. LLM ใช้ Mind Key สำหรับทุกอย่าง
รูปแบบ 2: Agent หลายโปรเจกต์
1. สมัครครั้งเดียว → รับ JWT
2. สร้างหลาย mind (work, personal, project-x) → รับหลาย Mind Key
3. LLM โหลด Mind Key ต่างกันตาม context
รูปแบบ 3: การแชร์ในทีม
1. ผู้ใช้ A สร้าง mind → ได้ Mind Key A
2. ผู้ใช้ A แชร์กับผู้ใช้ B ผ่าน JWT ()
3. ผู้ใช้ B สามารถเข้าถึงผ่าน JWT ของตนเอง
4. สำหรับการเข้าถึง LLM, ผู้ใช้ B ต้องสร้าง Mind Key ของตนเอง (หรือใช้ของ A)
รูปแบบ 4: MCP Server
MCP server ใช้ Mind Key เสมอ (ตั้งผ่าน env var ) หนึ่ง MCP server instance = หนึ่ง mind สำหรับการเข้าถึงหลาย mind ให้รันหลาย MCP instance หรือ implement mind switching ฝั่ง client
Cheat Sheet รูปแบบ Token
| Token | รูปแบบ | ตัวอย่าง |
|-------|--------|---------|
| Mind Key | + 36 ตัวอักษร | |
| JWT | + base64 | |
| Computer Token | + 36 ตัวอักษร | |
ขั้นตอนถัดไป
- Authentication — คู่มือ auth แบบเต็ม
- User & Minds API — endpoint ที่ป้องกันด้วย JWT
- Memory API — endpoint ที่ป้องกันด้วย Mind Key
────────────────────────────────────────────────────────────
# Quick Start สำหรับ LLM Agent
SUMMARY: ใน 3 API call: recall memory ทั้งหมด, เก็บใหม่, ค้นหา — workflow LLM ที่จำเป็น
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query)
ALWAYS call /memory/recall at the start of every session.
Wichtigste Befehle: GET /memory/recall, POST /memory, GET /memory/search?q=...
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
FTS5 search: multiple words = AND, "phrases" in quotes, prefix* for prefix search
Quick Start สำหรับ LLM Agent
คุณสูญเสีย memory ทั้งหมดระหว่าง session Synapse เป็นสมองภายนอกของคุณ คู่มือนี้แสดงสาม API call ที่จำเป็นซึ่ง LLM agent ทุกตัวต้องรู้
> [!CRITICAL]
> เรียก ที่จุดเริ่มต้นของทุก session
> หากไม่เรียกนี้ คุณไม่มี memory ว่าผู้ใช้เป็นใคร, สัญญาอะไรไว้ หรือกำลังทำงานอะไรครั้งที่แล้ว
ขั้นตอนที่ 1: Recall memory ทั้งหมด (ต้องทำก่อนเสมอ)
[CODE BLOCK]
ส่งกลับสรุปแบบ plain-text ที่มีโครงสร้างของ memory ที่เก็บไว้ทั้งหมด แยกวิเคราะห์นี้เพื่อ rebuild mental model ของผู้ใช้, โปรเจกต์ และการโต้ตอบในอดีต
ตัวอย่าง response:
[CODE BLOCK]
ขั้นตอนที่ 2: เก็บ memory ใหม่
เมื่อคุณเรียนรู้สิ่งที่คุ้มค่าจดจำ:
[CODE BLOCK]
Category: , , , , , , , ,
Priority: , , ,
> [!TIP]
> ใส่ฟิลด์ เสมอ — identifier สั้น ๆ สำหรับ memory นี่ช่วยให้คุณอัปเดต memory เดิมในภายหลังโดย POST ซ้ำด้วย key เดียวกัน
ขั้นตอนที่ 3: ค้นหา memory เฉพาะ
[CODE BLOCK]
> [!TIP]
> ไวยากรณ์ FTS5: หลายคำ = AND search Phrase ในเครื่องหมายคำพูด: ค้นหา prefix: Boolean:
เครื่องมือแบบเปิด URL (ไม่มี Auth Header)
หากเครื่องมือของคุณเปิด URL ได้อย่างเดียว (ไม่มี custom header) ให้ใช้พารามิเตอร์ :
[CODE BLOCK]
> [!WARNING]
> จำกัดที่ 60 request/นาที Bearer header ไม่จำกัด ใช้ Bearer header เมื่อใดก็ตามที่ทำได้
Workflow Session แบบสมบูรณ์
1. เริ่ม session: — โหลด memory ทั้งหมด
2. ระหว่างทำงาน: — หา fact เฉพาะ
3. เมื่อมีข้อมูลใหม่: — เก็บ (พร้อม category, key, tag, priority)
4. เป็นคาบ: — ตรวจข้อความจาก human
5. สิ้นสุด session: เก็บสิ่งที่เรียนรู้สุดท้ายผ่าน
รูปแบบทั่วไป
อัปเดต memory ที่มีอยู่
POST ด้วย และ เดิม — memory ที่มีอยู่จะถูกอัปเดต ไม่ซ้ำ
เก็บสถานะโปรเจกต์
[CODE BLOCK]
บันทึก mistake (เพื่อไม่ทำซ้ำ)
[CODE BLOCK]
ตรวจข้อความจาก human
[CODE BLOCK]
ส่งกลับข้อความที่ยังไม่ได้อ่านจาก human ตอบกลับด้วย:
[CODE BLOCK]
ขั้นตอนถัดไป
- Authentication — Mind Key vs JWT
- Memory API reference — memory endpoint ทั้ง 22
- Chat API — การสื่อสารแบบ asynchronous กับ human
- LLM Cookbook — รูปแบบปฏิบัติ
────────────────────────────────────────────────────────────
# Quick Start (Human)
SUMMARY: สมัครบัญชี, สร้าง mind แรก, เก็บ memory — ทั้งหมดใน 5 นาที
Quick Start (Human)
คู่มือนี้นำคุณผ่านการสมัครบัญชี Synapse, Mind Key แรก และเก็บ memory แรก เวลารวม: 5 นาที
ขั้นตอนที่ 1: สมัครบัญชี
เปิด Synapse API และสร้างบัญชี:
[CODE BLOCK]
Response:
[CODE BLOCK]
> [!TIP]
> บันทึก JWT ไว้ที่ปลอดภัย — คุณต้องใช้เพื่อสร้าง mind JWT หมดอายุหลัง 7 วัน; ล็อกอินใหม่ด้วย endpoint เดียวกันเพื่อ refresh
ขั้นตอนที่ 2: สร้าง Mind แรกของคุณ
"mind" คือ scope memory ที่แยกออก ผู้ใช้ส่วนใหญ่เริ่มด้วย mind เดียว แต่คุณสามารถมีหลาย mind ได้ (เช่น "work", "personal", "project-x") แต่ละ mind มี Mind Key ที่ไม่ซ้ำกัน
[CODE BLOCK]
Response:
[CODE BLOCK]
> [!CRITICAL]
> บันทึก ทันที แสดงเพียงครั้งเดียวและดึงคืนไม่ได้ หากคุณสูญเสีย ต้องสร้าง mind ใหม่
ขั้นตอนที่ 3: เก็บ Memory แรกของคุณ
ตอนนี้ใช้ Mind Key เพื่อเก็บ memory:
[CODE BLOCK]
Response:
[CODE BLOCK]
ขั้นตอนที่ 4: Recall Memory ทั้งหมด
เพื่อดึงทุกสิ่งที่คุณเก็บไว้:
[CODE BLOCK]
Response (plain text, ปรับให้เหมาะกับการบริโภคของ LLM):
[CODE BLOCK]
ขั้นตอนที่ 5: ค้นหา Memory
หา memory เฉพาะตาม keyword:
[CODE BLOCK]
ขั้นตอนที่ 6: เชื่อมต่อ LLM ของคุณ
วิธีที่ง่ายที่สุดในการให้ LLM เข้าถึง Synapse คือผ่าน MCP:
- Claude Desktop setup — config 2 นาที
- Claude Code setup — integration terminal
- Cursor setup — integration IDE
หลังตั้งค่า LLM ของคุณจะเรียก โดยอัตโนมัติที่จุดเริ่มต้นของทุก session และเก็บ fact ใหม่ผ่าน
Memory Category
Synapse รองรับ 8 category — เลือกอันที่เฉพาะเจาะจงที่สุด:
| Category | กรณีใช้งาน |
|----------|----------|
| | ชื่อผู้ใช้, role, ข้อมูลติดต่อ |
| | สิ่งที่ชอบ/ไม่ชอบ, สไตล์การทำงาน |
| | fact ที่ตรวจสอบได้ (รายละเอียดโปรเจกต์, วันที่) |
| | สถานะโปรเจกต์, milestone, todo |
| | สิ่งที่ผู้ใช้ทำได้ดี |
| | error ในอดีต — หลีกเลี่ยงการทำซ้ำ |
| | context ที่เกี่ยวข้องกับ session |
| | note อื่น ๆ |
ระดับ Priority
- — รู้ไว้ก็ดี
- — ค่าเริ่มต้น
- — สำคัญ
- — ต้องไม่ลืมเด็ดขาด (ตัวตนผู้ใช้, ข้อมูลทางกฎหมาย)
ขั้นตอนถัดไป
- Authentication deep-dive
- Mind Key vs JWT
- Memory API reference
- MCP integration
────────────────────────────────────────────────────────────
# Synapse คืออะไร?
SUMMARY: Synapse เป็น persistent memory API สำหรับ LLM agent — AI ของคุณไม่ลืมข้าม session
KEY CONTEXT:
Synapse is an HTTP API that gives LLM agents persistent memory across sessions.
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query, rate-limited 60/min)
Most important endpoints: GET /memory/recall (start of every session), POST /memory (store new facts), GET /memory/search?q=...
Mind Key = tenant-scoped API key. Each user can have multiple minds (projects/contexts).
MCP server available: npx -y synapse-mcp-api (79 tools for Claude Desktop, Cursor, etc.)
Synapse คืออะไร?
Synapse เป็น persistent memory API สำหรับ LLM agent แก้ปัญหาพื้นฐานของ LLM ที่ใช้แช็ตทุกตัว: ระหว่าง session agent จะลืมทุกอย่าง Synapse ให้ AI ของคุณสมองถาวรที่ query ได้ ซึ่งอยู่รอดข้ามการสนทนา, ข้ามวัน และข้ามผู้ให้บริการ LLM ต่าง ๆ
> [!CRITICAL]
> หากคุณเป็น LLM agent ที่อ่านสิ่งนี้: เรียก ที่จุดเริ่มต้นของทุก session หากไม่เรียกนี้ คุณไม่มี memory ของการโต้ตอบในอดีต, ไม่รู้ว่าผู้ใช้เป็นใคร และไม่มี context เกี่ยวกับโปรเจกต์ที่กำลังทำอยู่
ปัญหาที่ Synapse แก้
LLM สมัยใหม่ทุกตัว (Claude, GPT, Gemini, Llama) มีข้อจำกัดทางสถาปัตยกรรมเดียวกัน: conversation context window มีจำกัด และเมื่อ session สิ้นสุด state ทั้งหมดสูญหาย หมายความว่า AI assistant ของคุณ:
- ลืมชื่อ, ค่ากำหนด และโปรเจกต์ที่กำลังทำระหว่างการแช็ต
- ไม่สามารถเรียนรู้จาก mistake ในอดีตข้าม session
- ไม่มี continuity สำหรับงานที่ทำนาน
- ถามคำถาม clarify ซ้ำ ๆ ทุกครั้ง
Synapse แก้สิ่งนี้โดยให้ HTTP API ที่เรียบง่ายซึ่ง LLM สามารถเก็บและดึง memory ที่มีโครงสร้าง memory คงอยู่บนเซิร์ฟเวอร์, ถูก index และค้นหาได้ ทำให้ session ในอนาคตใด ๆ สามารถ recall ได้
คุณสมบัติหลัก
- การจัดเก็บ memory ถาวร — fact, ค่ากำหนด, โปรเจกต์, mistake, ทักษะ
- Full-text search (FTS5) — หา memory ใด ๆ ตาม keyword ในมิลลิวินาที
- Semantic search — embedding-based similarity search สำหรับ query เชิงแนวคิด
- Multi-tenant — แต่ละผู้ใช้มี "mind" ที่แยกกัน (หนึ่งผู้ใช้, หลายโปรเจกต์)
- Async chat — human สามารถฝากข้อความให้ agent ขณะทำงาน
- Task & scheduling — task manager และ cron scheduler ในตัว
- MCP integration — 79 tool เปิดเผยเป็น Model Context Protocol สำหรับ Claude, Cursor, Continue
- Browser & computer control — เครื่องมือ automation ระยะไกล
- Webhook — รับ HTTP callback เมื่อ memory/chat/task เปลี่ยนแปลง
วิธีการทำงาน
[CODE BLOCK]
1. LLM เรียก ที่จุดเริ่มต้น session
2. Synapse ส่งกลับสรุปแบบ text ที่มีโครงสร้างของ memory ที่เก็บไว้ทั้งหมด
3. LLM ทำงาน, เรียก เป็นคาบเพื่อเก็บ fact ใหม่
4. เมื่อผู้ใช้ถามคำถาม LLM สามารถเรียก
5. ที่สิ้นสุด session, context ใหม่ที่สำคัญถูกเก็บไว้สำหรับ session ถัดไป
สำหรับใคร?
- นักพัฒนา LLM agent ที่ต้องการ state ถาวร
- Power user ที่รัน local LLM (Ollama, LM Studio) พร้อม custom agent
- ทีม ที่สร้าง AI assistant ที่ต้องการ shared memory
- วิศวกร automation ที่เชื่อม LLM call ข้าม session
การเปรียบเทียบด่วน
| คุณสมบัติ | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| ตำแหน่ง storage | เซิร์ฟเวอร์ OpenAI | เซิร์ฟเวอร์ของคุณ |
| API access | ไม่ (ปิด) | ใช่ (REST + MCP) |
| Multi-tenant | ไม่ | ใช่ (mind) |
| Custom category | ไม่ | ใช่ (8 category) |
| Search | จำกัด | FTS5 + semantic |
| Self-hostable | ไม่ | ใช่ (Docker) |
ขั้นตอนถัดไป
- Quick Start สำหรับ human — รับ Mind Key ใน 5 นาที
- Quick Start สำหรับ LLM — API call แรก
- Authentication — Mind Key vs JWT
- ภาพรวม architecture — วิธีที่ Synapse ถูกสร้าง
## หมวดหมู่: เอกสารอ้างอิง API
เอกสารอ้างอิงที่สมบูรณ์สำหรับทุก API endpoint
────────────────────────────────────────────────────────────
# Browser Proxy
SUMMARY: บริการ browser automation — Docker container แยกต่างหากบน port 13000 สำหรับควบคุม headless browser
KEY CONTEXT:
Browser Proxy is a SEPARATE Docker service (port 13000), NOT a Synapse endpoint.
Synapse endpoints do NOT include /browser/* paths.
For browser automation, use the MCP browser_new tool OR connect to the browser-proxy service directly.
Synapse MCP exposes browser tools (browser_new, browser_navigate, browser_click, etc.)
Browser Proxy
Browser Proxy เป็น Docker service แยกต่างหาก ที่ให้บริการ headless browser automation ผ่าน Playwright โดยไม่ได้เป็นส่วนหนึ่งของ Synapse API โดยตรง — endpoint ของ Synapse ไม่มีพาธ
Architecture
[CODE BLOCK]
วิธีการเข้าถึง
วิธีที่ 1: ผ่าน Synapse MCP Server (แนะนำ)
Synapse MCP server เปิดเผย browser tools เป็น MCP tools ใช้สำหรับ browser automation ที่ขับเคลื่อนด้วย LLM:
[CODE BLOCK]
MCP browser tools ที่ใช้ได้:
- — เปิด browser tab ใหม่
- — นำทางไปยัง URL
- — คลิกที่ element
- — พิมพ์ข้อความลงใน field
- — จับภาพ screenshot
- — ปิด tab
- (และอีกมาก — ดู MCP integration)
วิธีที่ 2: เข้าถึง Browser Proxy โดยตรง
สำหรับการผสานรวมที่ไม่ใช่ MCP ให้เชื่อมต่อกับ browser-proxy service โดยตรง:
[CODE BLOCK]
กรณีการใช้งานทั่วไป
Web scraping
[CODE BLOCK]
Form automation
[CODE BLOCK]
Screenshot capture
[CODE BLOCK]
Services ที่เกี่ยวข้อง
| Service | Port | วัตถุประสงค์ |
|---------|------|---------|
| Synapse API | 12800 | Memory, chat, tasks |
| Synapse MCP | 13100 | MCP server (79 tools) |
| Browser Proxy | 13000 | Headless browser automation |
| SSH Proxy | 12900 | SSH access to remote machines |
ขั้นตอนถัดไป
- MCP Integration — วิธีใช้ browser tools ผ่าน MCP
- Computer Control API — สำหรับ GUI automation บนเครื่องที่ลงทะเบียน
────────────────────────────────────────────────────────────
# Chat API
SUMMARY: การแช็ตแบบ asynchronous ระหว่าง human และ LLM agent — poll, reply, history, นับข้อความที่ยังไม่ได้อ่าน, อัปโหลดไฟล์
KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions
Chat API
Chat API เปิดใช้งานการส่งข้อความแบบ asynchronous ระหว่าง human และ LLM agent ต่างจากการแช็ตแบบ synchronous (สไตล์ ChatGPT) ตรงที่ human สามารถฝากข้อความไว้ขณะที่ agent กำลังทำงาน — agent จะ poll ระหว่างการเรียก tool
วิธีการทำงาน
[CODE BLOCK]
1. Human ส่งข้อความผ่าน web UI (ใช้ JWT)
2. ข้อความถูกเก็บไว้ และทำเครื่องหมายว่ายังไม่ได้อ่าน
3. Agent poll ระหว่างการเรียก tool
4. Poll ส่งกลับข้อความที่ยังไม่ได้อ่านทั้งหมดและทำเครื่องหมายว่าอ่านแล้ว
5. Agent ประมวลผลข้อความ และอาจตอบกลับผ่าน
Endpoints
GET /chat/poll
Poll ข้อความใหม่จาก human ส่งกลับข้อความที่ยังไม่ได้อ่านและทำเครื่องหมายว่าอ่านแล้ว ใช้ระหว่างการเรียก tool
[CODE BLOCK]
Response:
[CODE BLOCK]
POST /chat/reply
ส่งข้อความในฐานะ agent
[CODE BLOCK]
POST /chat/send
ส่งข้อความในฐานะ human (ต้องใช้ JWT ไม่ใช่ Mind Key)
[CODE BLOCK]
GET /chat/history
ดึงประวัติแช็ตล่าสุด (ทั้งสอง role)
[CODE BLOCK]
GET /chat/unread
นับข้อความที่ยังไม่ได้อ่าน
[CODE BLOCK]
GET /chat/status
ดึงสถานะของ chat session (timestamp ของข้อความล่าสุด, จำนวนที่ยังไม่ได้อ่าน)
[CODE BLOCK]
POST /chat/upload
อัปโหลดไฟล์แนบสำหรับข้อความเฉพาะ (multipart form)
[CODE BLOCK]
GET /chat/files/:messageid
รายการไฟล์แนบสำหรับข้อความ
[CODE BLOCK]
GET /chat/file/:fileid
ดาวน์โหลดไฟล์แนบ
[CODE BLOCK]
รูปแบบการ Poll
> [!TIP]
> Poll ทุก 30-60 วินาทีระหว่างการเรียก tool อย่า poll ถี่กว่านี้ — จะเปลือง API quota โดยไม่ได้ประโยชน์
[CODE BLOCK]
ขั้นตอนถัดไป
- Tasks API
- Chat Polling Pattern
────────────────────────────────────────────────────────────
# Computer Control API
SUMMARY: ควบคุม computer ที่ลงทะเบียนจากระยะไกล — จัดคิวคำสั่ง, จับภาพ screenshot, รันสคริปต์บนเครื่องระยะไกล
KEY CONTEXT:
Two sides: user-facing (Mind Key/JWT) and agent-facing (Computer Token)
Register agent: POST /computers/register { install_code } → returns computer_token
List: GET /computers/list (Mind Key or JWT)
Queue command: POST /computers/:id/commands { type, payload }
Command types: screenshot, click, move, type, key, scroll, drag
Agent poll: GET /computers/me/poll?wait=5 (Computer Token)
Agent result: POST /computers/me/commands/:cid/result (Computer Token)
One-shot screenshot: GET /computers/:id/screenshot (waits 30s for result)
Pattern: register agent on remote machine → user queues commands → agent polls and executes
Computer Control API
Computer Control API ช่วยให้คุณควบคุม computer ที่ลงทะเบียนจากระยะไกล agent ตัวเล็ก ๆ () รันบนเครื่องเป้าหมาย, poll หาคำสั่ง, ปฏิบัติตามคำสั่ง, และส่งผลลัพธ์กลับ ทำให้สามารถทำ GUI automation ที่ขับเคลื่อนด้วย LLM ได้
Architecture
[CODE BLOCK]
User-Facing Endpoints (Mind Key or JWT)
GET /computers/list
รายการ computer ที่ลงทะเบียนทั้งหมด
[CODE BLOCK]
GET /computers/:id
ดึงรายละเอียดของ computer เครื่องเดียว
[CODE BLOCK]
POST /computers/install-code
สร้าง install code สำหรับลงทะเบียน computer เครื่องใหม่
[CODE BLOCK]
Response:
POST /computers/:id/commands
จัดคิวคำสั่งให้ remote agent ปฏิบัติ
[CODE BLOCK]
Response:
GET /computers/:id/command (via query)
จัดคิวคำสั่งผ่าน GET (สำหรับกรณีง่าย ๆ)
[CODE BLOCK]
GET /computers/:id/commands
รายการคำสั่งล่าสุดของ computer
[CODE BLOCK]
GET /computers/:id/commands/:cid
ดึงสถานะ + ผลลัพธ์ของคำสั่งเฉพาะ
[CODE BLOCK]
GET /computers/:id/screenshot
แบบ one-shot: จัดคิวคำสั่ง screenshot และรอผลลัพธ์สูงสุด 30 วินาที
[CODE BLOCK]
POST /computers/:id/disable
ปิดใช้งาน computer (เพิกถอน token แต่เก็บ record ไว้เพื่อ audit)
[CODE BLOCK]
DELETE /computers/:id
ลบ computer อย่างถาวร
[CODE BLOCK]
Agent-Facing Endpoints (Computer Token)
endpoint เหล่านี้ใช้โดย ที่รันอยู่บนเครื่องเป้าหมาย ใช้ Computer Token (ส่งกลับโดย ) ไม่ใช่ Mind Key
POST /computers/register
แลกรับ install code เพื่อรับ Computer Token
[CODE BLOCK]
Response:
> [!CRITICAL]
> บันทึก ไว้ — แสดงเพียงครั้งเดียวและต้องใช้สำหรับ endpoint ฝั่ง agent ทั้งหมด
GET /computers/me/poll
Long-poll หาคำสั่งใหม่ agent เรียกสิ่งนี้ในลูป
[CODE BLOCK]
ส่งกลับทันทีหากมีคำสั่งรออยู่ หรือหลังจาก วินาที หากไม่มี
POST /computers/me/commands/:cid/result
ส่งผลลัพธ์การปฏิบัติคำสั่ง
[CODE BLOCK]
ประเภทคำสั่ง
| Type | Payload | คำอธิบาย |
|------|---------|-------------|
| | | จับภาพหน้าจอเป็น PNG (base64) |
| | | คลิกที่พิกัด |
| | | เลื่อนเมาส์ไปยังพิกัด |
| | | พิมพ์ข้อความที่ตำแหน่งเคอร์เซอร์ |
| | | กดปุ่มผสม |
| | | เลื่อน scroll wheel |
| | | ลากและวาง |
รูปแบบทั่วไป: LLM-Driven GUI Automation
[CODE BLOCK]
ขั้นตอนถัดไป
- Browser Proxy — service แยกต่างหากสำหรับ browser automation
- Self-Hosted Agents Guide
────────────────────────────────────────────────────────────
# Cron & Scheduler
SUMMARY: ตั้งเวลาการเรียก API แบบ recurring — cron jobs ที่ทำงานตามตารางเวลา เหมาะสำหรับ sync และการแจ้งเตือนเป็นคาบ
KEY CONTEXT:
Auth: Mind Key
Create: POST /cron { schedule, endpoint, method?, body?, headers?, enabled? }
List: GET /cron
Delete: DELETE /cron/:id
Toggle: PUT /cron/:id/toggle
Schedule: 5-field cron (minute hour day month day-of-week) OR integer interval (seconds)
Endpoint: must be http(s) URL, same Synapse instance OR public HTTPS (no private IPs)
Pattern: schedule /memory/recall every hour, /chat/poll every 5 min, etc.
Cron & Scheduler
Cron API ช่วยให้คุณตั้งเวลาการเรียก HTTP แบบ recurring ไปยัง Synapse endpoint (หรือ external HTTPS endpoint) เหมาะสำหรับ sync เป็นคาบ, การแจ้งเตือน, และงานบำรุงรักษา
Endpoints
POST /cron
สร้าง task ที่ตั้งเวลาไว้
[CODE BLOCK]
Response:
[CODE BLOCK]
GET /cron
รายการ task ที่ตั้งเวลาไว้ทั้งหมด
[CODE BLOCK]
DELETE /cron/:id
ลบ task ที่ตั้งเวลาไว้
[CODE BLOCK]
PUT /cron/:id/toggle
เปิดหรือปิดใช้งาน task โดยไม่ลบ
[CODE BLOCK]
รูปแบบ Schedule
Standard cron (5 fields)
[CODE BLOCK]
ตัวอย่าง:
| Schedule | ความหมาย |
|----------|---------|
| | ทุกชั่วโมง |
| | ทุก 15 นาที |
| | 9 โมงเช้าวันธรรมดา |
| | เที่ยงคืนทุกวันอาทิตย์ |
| | เที่ยงคืนวันแรกของทุกเดือน |
Integer interval (วินาที)
สำหรับช่วงเวลาง่าย ๆ ให้ส่ง integer:
[CODE BLOCK]
ข้อจำกัดของ Endpoint
> [!WARNING]
> Endpoint ต้องเป็น URL แบบ หรือ ที่ชี้ไปยัง:
> - Synapse instance เดียวกัน (เช่น )
> - Public HTTPS URL (ห้าม private IP, ห้าม localhost, ห้าม metadata IP)
สิ่งนี้ป้องกัน SSRF attack ที่ mind ที่ถูกโจมตีอาจตั้งเวลา request ไปยัง internal service
รูปแบบทั่วไป
การ recall memory รายชั่วโมง (สำหรับ LLM agent)
[CODE BLOCK]
สำรองข้อมูลรายวัน
[CODE BLOCK]
การ poll chat เป็นคาบ (ทุก 5 นาที)
[CODE BLOCK]
ทริกเกอร์รายงานรายสัปดาห์
[CODE BLOCK]
ขั้นตอนถัดไป
- Variables API
- Webhooks API
────────────────────────────────────────────────────────────
# Errors & Error Handling
SUMMARY: HTTP status code, รูปแบบ error response, และวิธีกู้คืนจาก error ทั่วไป
KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.
Errors & Error Handling
Synapse ใช้ HTTP status code มาตรฐานพร้อมรูปแบบ error response ที่สม่ำเสมอ เอกสารหน้านี้อธิบายวิธีตีความและกู้คืนจาก error
รูปแบบ Error Response
error ทั้งหมดส่งกลับเป็น JSON ด้วยโครงสร้างนี้:
[CODE BLOCK]
| Field | คำอธิบาย |
|-------|-------------|
| | HTTP status code |
| | ชื่อ HTTP status |
| | คำอธิบาย error ที่มนุษย์อ่านได้ |
| | URL ไปยังเอกสารที่เกี่ยวข้อง (เมื่อเกี่ยวข้อง) |
HTTP Status Codes
200 OK
สำเร็จ request ถูกประมวลผลถูกต้อง
201 Created
สำเร็จ สร้าง resource ใหม่ (เช่น )
204 No Content
สำเร็จ ไม่มี body ส่งกลับ (เช่น )
400 Bad Request
request ผิดรูปแบบ สาเหตุทั่วไป:
- ขาด JSON field ที่จำเป็น
- ไวยากรณ์ JSON ไม่ถูกต้อง
- ค่า enum ไม่ถูกต้อง (เช่น category ผิด)
[CODE BLOCK]
วิธีแก้: ตรวจสอบ request body กับ API docs ตรวจสอบว่า field ที่จำเป็นทั้งหมดมีและมีค่าที่ถูกต้อง
401 Unauthorized
การยืนยันตัวตนล้มเหลว สาเหตุทั่วไป:
- ขาด header
- Mind Key หรือ JWT ไม่ถูกต้อง
- ใช้ Mind Key ในที่ที่ต้องใช้ JWT (หรือกลับกัน)
[CODE BLOCK]
วิธีแก้: ตรวจสอบ token ของคุณ ดู Authentication
403 Forbidden
คุณยืนยันตัวตนแล้วแต่ไม่ได้รับอนุญาตให้ทำ action นี้ สาเหตุทั่วไป:
- พยายามลบ mind ของผู้ใช้อื่น
- พยายาม verify memory ด้วย Mind Key (ต้องใช้ JWT)
- Mind ถูกปิดใช้งาน
วิธีแก้: ตรวจสอบว่าคุณใช้ประเภท token ที่ถูกต้องสำหรับ endpoint นี้
404 Not Found
path หรือ resource ที่ร้องขอไม่มีอยู่
> [!CRITICAL]
> อย่าเดา path ของ endpoint มีเพียง path ที่แสดงใน เท่านั้นที่มีอยู่ หากคุณได้ 404 แสดงว่าคุณใช้ path ผิด
[CODE BLOCK]
วิธีแก้: เรียก เพื่อดูรายการ endpoint ที่ถูกต้อง เปรียบเทียบ URL ของคุณกับรายการทีละตัวอักษร
409 Conflict
request ขัดแย้งกับสถานะที่มีอยู่ สาเหตุทั่วไป:
- พยายามลงทะเบียนด้วย email ที่มีอยู่แล้ว
- ซ้ำ webhook URL
วิธีแก้: ใช้ค่าอื่น หรือใช้ เพื่ออัปเดต resource ที่มีอยู่
429 Too Many Requests
คุณกระทบ rate limit ใช้เฉพาะกับ auth ผ่าน query parameter (60/นาที)
[CODE BLOCK]
Response headers:
[CODE BLOCK]
วิธีแก้: เปลี่ยนไปใช้ header (ไม่จำกัดอัตรา) หรือรอ วินาที
500 Internal Server Error
server error ไม่ควรเกิดขึ้น — หากเกิด ถือเป็น bug
วิธีแก้:
1. Retry ด้วย exponential backoff (1s, 2s, 4s, 8s)
2. ตรวจสอบ เพื่อดูว่า server ยังทำงานอยู่หรือไม่
3. หากยังเกิดขึ้นเรื่อย ๆ ให้รายงาน error
503 Service Unavailable
server ล่มชั่วคราว (เช่น ระหว่าง deploy, database migration)
วิธีแก้: รอแล้ว retry ตรวจสอบ
รูปแบบการกู้คืน
Retry ด้วย exponential backoff
[CODE BLOCK]
การจัดการ auth error
[CODE BLOCK]
สถานการณ์ error ทั่วไป
"Mind Key fehlt oder ungültig"
- คุณลืม header
- คุณใช้ แต่ key ผิด
- คุณใช้ JWT ในที่ที่ต้องใช้ Mind Key
"Route not found"
- คุณเดา path ที่ไม่มีอยู่
- คุณใช้ verb ผิด (เช่น เทียบกับ )
- ตรวจสอบ สำหรับ path ที่ถูกต้อง
"Rate limit exceeded"
- คุณใช้ และเกิน 60 req/min
- เปลี่ยนไปใช้ header
ขั้นตอนถัดไป
- Authentication
- API Overview
- Rate Limits
────────────────────────────────────────────────────────────
# Memory API
SUMMARY: อ้างอิงครบถ้วนสำหรับ 22 memory endpoint: store, recall, search, semantic search, sync, audit และอื่น ๆ
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 endpoint สำหรับจัดเก็บ, ดึง, ค้นหา, และจัดการ memory ที่มีโครงสร้าง endpoint ทั้งหมดต้องใช้ Mind Key สำหรับการยืนยันตัวตน
> [!CRITICAL]
> เรียก เสมอที่จุดเริ่มต้นของทุก session นี่เป็นวิธีเดียวที่จะ rebuild context จาก session ก่อนหน้า
Categories
memory ถูกจัดเป็น 8 category:
| Category | กรณีใช้งาน |
|----------|----------|
| | ชื่อผู้ใช้, role, ข้อมูลติดต่อ, ค่ากำหนดเกี่ยวกับตนเอง |
| | สิ่งที่ชอบ/ไม่ชอบ, สไตล์การทำงาน, ค่ากำหนดการสื่อสาร |
| | fact ที่ตรวจสอบได้ (รายละเอียดโปรเจกต์, วันที่, URL) |
| | สถานะโปรเจกต์, milestone, architecture |
| | สิ่งที่ผู้ใช้ทำได้ดี |
| | error ในอดีต — หลีกเลี่ยงการทำซ้ำ |
| | context ที่เกี่ยวข้องกับ session |
| | note อื่น ๆ |
Priorities
- — รู้ไว้ก็ดี
- — ค่าเริ่มต้น
- — สำคัญ
- — ต้องไม่ลืมเด็ดขาด (ตัวตนผู้ใช้, ข้อมูลทางกฎหมาย)
Core Endpoints
GET /memory/recall
ส่งกลับ memory ทั้งหมดในรูปแบบ plain text ที่ปรับให้เหมาะกับ LLM เรียกสิ่งนี้ที่จุดเริ่มต้นของทุก session
[CODE BLOCK]
Response (text/plain):
[CODE BLOCK]
POST /memory
จัดเก็บ memory ใหม่หรืออัปเดต memory ที่มีอยู่ (category + key เดียวกัน = อัปเดต)
[CODE BLOCK]
Response:
GET /memory
รายการ memory พร้อม filter ที่เลือกได้
[CODE BLOCK]
PUT /memory/:id
อัปเดต memory เฉพาะตาม ID
[CODE BLOCK]
DELETE /memory/:id
ลบ memory เดียว
[CODE BLOCK]
Search Endpoints
GET /memory/search
Full-text search โดยใช้ FTS5
[CODE BLOCK]
ไวยากรณ์ FTS5:
- หลายคำ = AND:
- Phrase:
- Prefix:
- Boolean:
- Exclude:
GET /memory/semantic-search
การค้นหาเชิงแนวคิดโดยใช้ embeddings (ช้ากว่า FTS5 แต่เข้าใจความหมาย)
[CODE BLOCK]
ส่งกลับ memory ที่คล้ายเชิง semantic กับ query แม้ไม่มี keyword ตรงกัน มีประโยชน์สำหรับ "ค้นหา memory เกี่ยวกับ X" โดยที่ X ถูกอธิบายต่างกัน
GET /memory/by-tag
รายการ memory ตาม tag
[CODE BLOCK]
GET /memory/related/:id
ค้นหา memory ที่เกี่ยวข้องกับ memory เฉพาะ (ผ่าน tag ที่ใช้ร่วมกัน)
[CODE BLOCK]
Sync & Diff
GET /memory/diff
Sync แบบ incremental — ส่งกลับ memory ที่เปลี่ยนแปลงตั้งแต่ timestamp
[CODE BLOCK]
Response:
POST /memory/sync
นำ diff จาก instance อื่นมาใช้ (สำหรับ self-hosted sync)
[CODE BLOCK]
การดำเนินการแบบ Bulk
POST /memory/bulk-delete
ลบ memory หลายรายการตาม ID
[CODE BLOCK]
POST /memory/embed-batch
สร้าง embeddings สำหรับ memory ที่ยังไม่มี (สำหรับ semantic search)
[CODE BLOCK]
GET /memory/embed-batch-status
ตรวจสอบความคืบหน้าการสร้าง embedding
[CODE BLOCK]
การยืนยัน
memory มี flag memory ที่จัดเก็บโดย agent จะเป็น unverified โดยค่าเริ่มต้น (); memory ที่จัดเก็บโดย human จะเป็น verified ()
POST /memory/verify
ทำเครื่องหมาย memory ว่า verified (ต้องใช้ JWT ไม่ใช่ Mind Key)
[CODE BLOCK]
POST /memory/unverify
ทำเครื่องหมาย memory ว่า unverified (ต้องใช้ JWT)
[CODE BLOCK]
GET /memory/unverified
รายการ memory ที่รอการยืนยันจาก human
[CODE BLOCK]
Statistics & Audit
GET /memory/stats
สถิติรวมสำหรับ mind ปัจจุบัน
[CODE BLOCK]
ส่งกลับ:
GET /memory/audit
Audit log ของการดำเนินการที่เปลี่ยนแปลงสถานะทั้งหมด
[CODE BLOCK]
GET /memory/contradictions
ตรวจหา contradiction ที่อาจเกิดขึ้นใน memory ที่จัดเก็บไว้
[CODE BLOCK]
GET /memory/expiring
รายการ memory ที่มีวันหมดอายุใกล้เข้ามา
[CODE BLOCK]
Health & Export
GET /memory/health
Health check อย่างรวดเร็วสำหรับระบบ memory
[CODE BLOCK]
GET /memory/mind-export
JSON export แบบเต็มของ memory ทั้งหมด (สำหรับสำรองข้อมูล)
[CODE BLOCK]
POST /memory/compact
รวบรวม memory ที่คล้ายกัน (auto-summarization)
[CODE BLOCK]
ขั้นตอนถัดไป
- Quick Start for LLMs
- Memory Best Practices
- FTS5 Search
- Semantic Search
────────────────────────────────────────────────────────────
# ภาพรวม API และ Base URL
SUMMARY: endpoint ทั้งหมดของ Synapse API, base URL, รูปแบบการยืนยันตัวตน และรูปแบบการตอบกลับในภาพรวม
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.
ภาพรวม API และ Base URL
Synapse API เป็น RESTful HTTP API ทุก endpoint ส่งกลับเป็น JSON (ยกเว้นในกรณีที่ระบุไว้เป็นอย่างอื่น) เอกสารหน้านี้ครอบคลุมสิ่งสำคัญที่คุณต้องรู้ก่อนเจาะลึก endpoint เฉพาะทาง
Base URL
[CODE BLOCK]
พาธทั้งหมดในเอกสารนี้เป็นแบบ relative ต่อ base URL นี้ สำหรับ instance ที่ self-hosted ให้แทนที่ด้วย URL ของคุณเอง
การยืนยันตัวตน
มีสองวิธี ทั้งคู่ส่งผ่าน header:
[CODE BLOCK]
หรือผ่าน query parameter (จำกัดอัตรา 60 ครั้ง/นาที):
[CODE BLOCK]
ดูรายละเอียดที่ Authentication
กลุ่มของ Endpoint
| กลุ่ม | Auth | คำอธิบาย |
|-------|------|-------------|
| Public | None | Landing page, health, OpenAPI, docs |
| Memory | Mind Key | CRUD, search, sync, embeddings |
| Chat | Mind Key / JWT | การส่งข้อความแบบ asynchronous ระหว่าง human และ agent |
| Tasks | Mind Key | การจัดการ task |
| Scripts | Mind Key / JWT | ที่เก็บ script แบบถาวร |
| Scheduler | Mind Key | Cron jobs + variables |
| Webhooks | Mind Key | HTTP callback บน event |
| Computers | Mind Key / JWT | ควบคุม computer ระยะไกล |
| User/Minds | JWT | บัญชี + การจัดการ mind |
| Sharing | JWT | การแชร์ mind ระหว่างผู้ใช้ |
| Push | JWT | Web Push subscriptions |
| Tools | None | Time, calc, random (public utilities) |
รูปแบบการตอบกลับ
- JSON (ค่าเริ่มต้น):
- Plain text: ส่งกลับเป็น text ที่ปรับให้เหมาะกับ LLM
- HTML: , , , ,
Standard Response Envelope
Response สำเร็จส่งข้อมูลกลับมาโดยตรง:
[CODE BLOCK]
Response ผิดพลาดใช้รูปแบบนี้:
[CODE BLOCK]
> [!NOTE]
> ฟิลด์ เชื่อมโยงไปยังเอกสารที่เกี่ยวข้องสำหรับ error ทั่วไป
HTTP Status Codes
| Code | ความหมาย |
|------|---------|
| 200 | Success (GET, PUT) |
| 201 | Created (POST) |
| 204 | No content (DELETE) |
| 400 | Bad request (validation error) |
| 401 | Unauthorized (missing/invalid token) |
| 403 | Forbidden (wrong token type) |
| 404 | Not found (path doesn't exist) |
| 409 | Conflict (duplicate) |
| 429 | Too many requests (rate limit) |
| 500 | Server error |
Discoverability Endpoints
| Endpoint | วัตถุประสงค์ |
|----------|---------|
| | Landing page (LLM-optimized) |
| | รายการ machine-readable ของ endpoint ทั้งหมด |
| | รายการ endpoint ในรูปแบบ plain-text |
| | OpenAPI 3.0 specification |
| | เอกสาร API แบบเต็ม (HTML) |
| | เอกสาร API ในรูปแบบ JSON |
| | ระบบเอกสาร (HTML) |
| | ดัชนีเอกสาร (JSON) |
| | เอกสารทั้งหมดในรูปแบบ text block เดียว |
| | Interactive API playground |
Rate Limits
| วิธี Auth | Limit |
|-------------|-------|
| Mind Key (header) | None |
| Mind Key (?key=) | 60/min per IP |
| JWT (header) | None |
| Public endpoints | None |
Response ที่ถูกจำกัดอัตราจะมี:
[CODE BLOCK]
Pagination
Endpoint แบบ list รองรับ และ :
[CODE BLOCK]
Limit เริ่มต้น: 100 สูงสุด: 500
CORS
ทุก endpoint รองรับ CORS สำหรับ client ที่เป็น browser:
[CODE BLOCK]
SDKs & Clients
- Node.js SDK: (repo)
- MCP Server: (repo)
- HTTP client: ไลบรารี HTTP ใดก็ได้ (curl, fetch, axios, etc.)
ขั้นตอนถัดไป
- Memory API — endpoint ที่สำคัญที่สุด
- Chat API — การสื่อสารระหว่าง human-agent แบบ asynchronous
- Errors & Error Handling
────────────────────────────────────────────────────────────
# Rate Limits & Quotas
SUMMARY: นโยบาย rate limit สำหรับ Synapse API — Bearer header (ไม่จำกัด), ?key= (60/นาที), public endpoint
KEY CONTEXT:
Mind Key (Authorization: Bearer header) → NO rate limit
Mind Key (?key= query param) → 60 req/min per IP
JWT (Authorization: Bearer header) → NO rate limit
Public endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
Recommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.
Rate Limits & Quotas
Synapse มีนโยบาย rate limit ที่เรียบง่ายและคาดเดาได้ ออกแบบเพื่อป้องกันการใช้งานในทางที่ผิดโดยไม่ขัดขวางการใช้งานที่ชอบด้วย
นโยบาย Rate Limit
| วิธี Auth | Limit | Scope |
|-------------|-------|-------|
| Mind Key () | None | Per-mind |
| Mind Key () | 60 req/min | Per-IP |
| JWT () | None | Per-user |
| Public endpoints | None | Global |
> [!TIP]
> ใช้ header เสมอเมื่อทำได้ ไม่มี rate limit ใช้ เฉพาะเครื่องมือที่ตั้ง custom header ไม่ได้
Rate Limit Headers
เมื่อคุณใช้ auth ผ่าน response จะมี rate limit headers:
[CODE BLOCK]
เมื่อคุณเกิน limit:
[CODE BLOCK]
เมื่อคุณกระทบ Rate Limit
หากคุณได้ 429:
1. เปลี่ยนไปใช้ Authorization header (แนะนำ):
[CODE BLOCK]
2. หรือรอ วินาที แล้ว retry
ทำไมถึงมี Limit ของ ?key=
query parameter สะดวกสำหรับเครื่องมือ URL-only (browser, คำสั่ง ) แต่มีผลกระทบด้านความปลอดภัยและประสิทธิภาพ:
- ความปลอดภัย: query parameter ถูกบันทึกใน server access log, browser history และ Referer header การจำกัดการใช้งานช่วยลดการสัมผัส
- ประสิทธิภาพ: auth ผ่าน query parameter ต้องการ rate limiter ที่ใช้ IP (Redis lookup ต่อ request) ซึ่งเพิ่ม latency auth ผ่าน header ข้ามสิ่งนี้ไป
- การป้องกันการใช้งานในทางที่ผิด: URL ที่รั่วไหลอาจถูกแชร์และถูก hammer limit ต่อ IP จำกัดผลกระทบ
รูปแบบที่แนะนำ
LLM agent
[CODE BLOCK]
เครื่องมือแบบ Browser
หากเครื่องมือของคุณเปิด URL ได้อย่างเดียว:
[CODE BLOCK]
MCP server
MCP server ใช้ header auth เสมอผ่าน env var — ไม่มี rate limit
การนำเข้าแบบ bulk
สำหรับการดำเนินการแบบ bulk (เช่น นำเข้า memory 1000 รายการ) ให้ใช้ header auth เสมอ การนำเข้าแบบ bulk ผ่าน จะกระทบ rate limit ภายใน 1 นาที
Quotas (ระดับ Mind)
ปัจจุบันไม่มี quota ต่อ mind สำหรับขนาด storage หรือจำนวน memory limit ทั้งหมดอยู่ในระดับ auth/IP ไม่ใช่ในระดับข้อมูล อาจเปลี่ยนแปลงในอนาคตเพื่อความเป็นธรรมใน multi-tenant
การตรวจสอบการใช้งานของคุณ
[CODE BLOCK]
ขั้นตอนถัดไป
- Authentication
- Errors & Error Handling
────────────────────────────────────────────────────────────
# Scripts API
SUMMARY: ที่เก็บ script แบบถาวร — บันทึก shell, Python หรือ Node script ที่ใช้ซ้ำ และดึงผ่าน curl | bash
KEY CONTEXT:
Auth: Mind Key or JWT
Store: POST /script { name, content, description?, language? }
Fetch as text: GET /script/:name (returns text/plain, curl | bash ready)
Info: GET /script/:name/info (metadata without content)
List: GET /scripts (JSON array)
Delete: DELETE /script/:name
Use case: store deployment scripts, config generators, troubleshooting snippets
Scripts API
Scripts API ให้บริการที่เก็บแบบถาวรสำหรับ script ที่ใช้ซ้ำ script ถูกตั้งชื่อและกำหนดเวอร์ชันภายใน mind และสามารถดึงเป็น plain text — เหมาะสำหรับรูปแบบ
Endpoints
POST /script
จัดเก็บหรืออัปเดต script
[CODE BLOCK]
GET /script/:name
ดึงเนื้อหา script เป็น เหมาะสำหรับ pipe ไปยัง bash
[CODE BLOCK]
GET /script/:name/info
ดึง metadata ของ script โดยไม่มีเนื้อหา
[CODE BLOCK]
Response:
[CODE BLOCK]
GET /scripts
รายการ script ทั้งหมดใน mind ปัจจุบัน
[CODE BLOCK]
DELETE /script/:name
ลบ script
[CODE BLOCK]
กรณีการใช้งานทั่วไป
Deployment script
จัดเก็บขั้นตอน deployment มาตรฐานเพื่อให้ LLM รันได้โดยไม่ต้อง derive ขั้นตอนใหม่ทุกครั้ง:
[CODE BLOCK]
Troubleshooting snippet
จัดเก็บคำสั่ง diagnostic สำหรับปัญหาทั่วไป:
[CODE BLOCK]
ตัวสร้าง configuration
จัดเก็บ script ที่สร้าง config:
[CODE BLOCK]
ขั้นตอนถัดไป
- Variables API
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Tasks API
SUMMARY: การจัดการ task สำหรับ LLM agent — สร้าง, รายการ, อัปเดต, ทำเสร็จ, ลบ task พร้อม priority
KEY CONTEXT:
Auth: Mind Key
List: GET /mind/tasks?status=pending|in_progress|done|cancelled|all
Create: POST /mind/task { title, description?, priority?, due_at? }
Update: PUT /mind/task/:id { title?, description?, priority?, status?, due_at? }
Complete: GET /mind/task/:id/complete
Delete: GET /mind/task/:id/delete
Priorities: low, normal, high, critical
Statuses: pending, in_progress, done, cancelled
Pattern: create tasks for multi-step work, update status as you progress
Tasks API
Tasks API ให้ LLM agent วิธีที่มีโครงสร้างในการติดตามงานหลายขั้นตอน task อยู่ใน scope ของ mind ปัจจุบันและคงอยู่ข้าม session ทำให้ agent ทำงานต่อจากที่ค้างไว้ได้
Endpoints
GET /mind/tasks
รายการ task ทั้งหมดของ mind ปัจจุบัน
[CODE BLOCK]
Response:
[CODE BLOCK]
POST /mind/task
สร้าง task ใหม่
[CODE BLOCK]
GET /mind/task (query params)
สร้าง task ผ่าน GET (สำหรับเครื่องมือ URL-only)
[CODE BLOCK]
PUT /mind/task/:id
อัปเดต task ที่มีอยู่
[CODE BLOCK]
GET /mind/task/:id/complete
ทำเครื่องหมาย task ว่าเสร็จสิ้น
[CODE BLOCK]
GET /mind/task/:id/delete
ลบ task อย่างถาวร
[CODE BLOCK]
Priorities
- — ไม่เร่งด่วน
- — ค่าเริ่มต้น
- — สำคัญ
- — ต้องทำทันที
Statuses
- — สร้างแล้ว ยังไม่เริ่ม
- — กำลังดำเนินการ
- — เสร็จสิ้น
- — ยกเลิก
รูปแบบ: Task-Driven Workflow
[CODE BLOCK]
ขั้นตอนถัดไป
- Task-Driven Workflow
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Utility Tools (time, calc, random)
SUMMARY: Public utility endpoint — เวลาเซิร์ฟเวอร์, เครื่องคิดเลขปลอดภัย, ตัวสุ่มค่า ไม่ต้องยืนยันตัวตน
KEY CONTEXT:
No auth required for any /tools/* endpoint.
GET /tools/time → { time, timezone, offset }
GET /tools/calc?expr=(10+5)*3 → { result, expr } (safe, no eval, arithmetic only)
GET /tools/random?type=uuid → { value, type } (types: uuid, int, float, hex, alpha)
Use case: LLM agents that need current time, safe math, or random values.
Utility Tools
endpoint เป็น public utility — ไม่ต้องยืนยันตัวตน มีประโยชน์สำหรับ LLM agent ที่ต้องการเวลาฝั่งเซิร์ฟเวอร์, คณิตศาสตร์ปลอดภัย หรือค่าสุ่ม
GET /tools/time
ดึงเวลาเซิร์ฟเวอร์ปัจจุบัน, timezone และ UTC offset
[CODE BLOCK]
Response:
[CODE BLOCK]
กรณีใช้งาน: LLM agent ที่ต้องรู้ "กี่โมงแล้ว" สำหรับการตั้งเวลา, timestamp หรือการคำนวณวันที่เชิงสัมพันธ์
GET /tools/calc
เครื่องคิดเลขปลอดภัย — arithmetic เท่านั้น ไม่มี รองรับ , , , , , , และตัวเลข
[CODE BLOCK]
Response:
[CODE BLOCK]
> [!TIP]
> ใช้สิ่งนี้แทนการคำนวณในใจหรือผ่าน string parsing ปลอดภัย (ไม่มี code injection ได้) และแม่นยำ
ตัวดำเนินการที่รองรับ
- การบวก
- การลบ
- การคูณ
- การหาร
- modulo
- วงเล็บ
- ตัวเลข (จำนวนเต็มและทศนิยม)
ตัวอย่าง
[CODE BLOCK]
GET /tools/random
สร้างค่าสุ่ม
[CODE BLOCK]
พารามิเตอร์ประเภท
| Type | Parameters | Output |
|------|-----------|--------|
| | none | UUID v4 string |
| | , (default 0-100) | Integer |
| | , (default 0-100) | Float |
| | , (length range, default 8-16) | Hex string |
| | , (length range, default 8-16) | Alphabetic string |
กรณีใช้งานสำหรับ LLM Agent
สร้าง ID ที่ไม่ซ้ำ
[CODE BLOCK]
คำนวณเปอร์เซ็นต์
[CODE BLOCK]
ดึง timestamp ปัจจุบัน
[CODE BLOCK]
สร้างข้อมูลทดสอบ
[CODE BLOCK]
ขั้นตอนถัดไป
- API Overview — กลุ่ม endpoint ทั้งหมด
- Errors & Error Handling
────────────────────────────────────────────────────────────
# User & Minds API
SUMMARY: การจัดการบัญชี — สมัคร, ล็อกอิน, สร้าง mind, รายการ mind, ลบ mind ป้องกันด้วย JWT
KEY CONTEXT:
Auth: JWT (from /register or /login)
Register: POST /register { email, password, display_name? } → returns JWT
Login: POST /login { email, password } → returns JWT
Create mind: POST /minds { name, description? } → returns mind_key (shown once!)
List minds: GET /minds
Delete mind: DELETE /minds/:id (irreversible — deletes all memories!)
JWT expires after 7 days. Mind Key never expires.
Mind Key is shown only once at creation — save it permanently.
User & Minds API
User & Minds API จัดการบัญชี endpoint เหล่านี้ใช้ JWT authentication (ไม่ใช่ Mind Key) เพราะทำงานในระดับบัญชี ไม่ใช่ระดับ mind
Endpoint ยืนยันตัวตน
POST /register
สร้างบัญชีผู้ใช้ใหม่
[CODE BLOCK]
Response:
[CODE BLOCK]
POST /login
ล็อกอินเข้าสู่บัญชีที่มีอยู่
[CODE BLOCK]
Response: เหมือนกับ
Minds Endpoints
POST /minds
สร้าง mind ใหม่ ส่งกลับ Mind Key — บันทึกทันที แสดงเพียงครั้งเดียว
[CODE BLOCK]
Response:
[CODE BLOCK]
> [!CRITICAL]
> แสดงเพียงครั้งเดียว หากคุณสูญเสียจะดึงคืนไม่ได้ — ต้องลบ mind และสร้างใหม่ (ซึ่งจะสูญเสีย memory ที่จัดเก็บไว้ทั้งหมด)
GET /minds
รายการ mind ทั้งหมดของผู้ใช้ปัจจุบัน
[CODE BLOCK]
Response:
[CODE BLOCK]
DELETE /minds/:id
ลบ mind อย่างถาวร
[CODE BLOCK]
> [!WARNING]
> การลบ mind เป็นการกระทำที่ย้อนกลับไม่ได้ memory, task, chat history และ script ทั้งหมดใน mind นั้นจะสูญหายอย่างถาวร export ก่อนผ่าน หากคุณต้องการสำรองข้อมูล
รูปแบบ Multi-Mind
ผู้ใช้ส่วนใหญ่ได้ประโยชน์จากหลาย mind เพื่อแยก context:
[CODE BLOCK]
ใช้ Mind Key ต่างกันใน LLM session ต่างกันเพื่อแยก context
ความปลอดภัยบัญชี
ข้อกำหนดรหัสผ่าน
- ขั้นต่ำ 6 ตัวอักษร
- ไม่จำกัดความยาวสูงสุด (ใช้ password manager)
- เก็บเป็น bcrypt hash (ไม่เก็บ plaintext เด็ดขาด)
การหมดอายุของ JWT
JWT หมดอายุหลัง 7 วัน เมื่อหมดอายุเรียก อีกครั้ง
ความปลอดภัยของ Mind Key
Mind Key ไม่มีวันหมดอายุ หาก Mind Key ถูกโจมตี:
1. สร้าง mind ใหม่ผ่าน
2. อัปเดต config ของ LLM ด้วย Mind Key ใหม่
3. ลบ mind ที่ถูกโจมตีผ่าน
ขั้นตอนถัดไป
- Authentication — คู่มือ auth แบบเต็ม
- Mind Key vs JWT — คู่มือการตัดสินใจ
- Sharing API — แชร์ mind กับผู้ใช้อื่น
────────────────────────────────────────────────────────────
# Variables API
SUMMARY: Key-value store ที่รวดเร็วสำหรับสถานะ LLM — counter, flag, last-seen timestamp, ความคืบหน้าบางส่วน
KEY CONTEXT:
Auth: Mind Key
Set: POST /var { key, value }
Get: GET /var/:key
List: GET /var
Delete: DELETE /var/:key
Use case: store last-seen timestamps, counters, flags, partial workflow state
Faster than memory (PostgreSQL direct, no FTS5 indexing)
Not for: structured facts (use /memory), long content (use /script)
Variables API
Variables API เป็น key-value store ที่รวดเร็วสำหรับสถานะชั่วคราว ต่างจาก memory (ซึ่งถูก index, ค้นหาได้ และมีโครงสร้าง) ตรงที่ variable ถูกปรับให้เหมาะกับการอ่าน/เขียนรวดเร็ว — เหมาะสำหรับ counter, flag และสถานะ session
Endpoints
POST /var
ตั้งหรืออัปเดต variable
[CODE BLOCK]
GET /var/:key
ดึง variable เดียว
[CODE BLOCK]
Response:
[CODE BLOCK]
GET /var
รายการ variable ทั้งหมด
[CODE BLOCK]
DELETE /var/:key
ลบ variable
[CODE BLOCK]
เมื่อใดควรใช้ Variables vs Memory
| กรณีใช้งาน | ใช้ |
|----------|-----|
| ชื่อผู้ใช้, ค่ากำหนด | Memory (searchable, structured) |
| Last session timestamp | Variable (ephemeral state) |
| Counter (เช่น ข้อความที่ส่ง) | Variable (frequent updates) |
| สถานะ workflow ("step 3 of 5 done") | Variable (transient) |
| Note โปรเจกต์แบบยาว | Memory (full-text indexed) |
| Script ที่ใช้ซ้ำ | Script store (named, versioned) |
รูปแบบทั่วไป
ติดตาม session ล่าสุด
[CODE BLOCK]
รูปแบบ Counter
[CODE BLOCK]
Feature flag
[CODE BLOCK]
ขั้นตอนถัดไป
- Memory API — สำหรับข้อมูลที่มีโครงสร้างและค้นหาได้
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Webhooks API
SUMMARY: ลงทะเบียน HTTP callback สำหรับ memory, chat และ task event — รับการแจ้งเตือนเมื่อข้อมูลเปลี่ยนแปลง
KEY CONTEXT:
Auth: Mind Key
Register: POST /webhooks { url, events, secret? }
List: GET /webhooks
Get: GET /webhooks/:id
Update: PUT /webhooks/:id { url?, events?, secret?, enabled? }
Delete: DELETE /webhooks/:id
Events: memory.*, memory.store, memory.update, memory.delete, chat.*, chat.message_received, task.*, task.created, task.completed
Secret: HMAC-SHA256 signed payload, sent in X-Synapse-Signature header
Pattern: register webhook → receive POST → process event → call Synapse API
Webhooks API
Webhook ช่วยให้คุณรับ HTTP callback เมื่อมี event เกิดขึ้นใน Synapse เหมาะสำหรับการทริกเกอร์ external automation, ส่งการแจ้งเตือน หรือ sync ไปยังระบบอื่น
Endpoints
POST /webhooks
ลงทะเบียน webhook ใหม่
[CODE BLOCK]
Response:
[CODE BLOCK]
GET /webhooks
รายการ webhook ทั้งหมดของ mind ปัจจุบัน
[CODE BLOCK]
GET /webhooks/:id
ดึง webhook เดียว
[CODE BLOCK]
PUT /webhooks/:id
อัปเดต webhook (URL, events, secret หรือ flag enabled)
[CODE BLOCK]
DELETE /webhooks/:id
ลบ webhook
[CODE BLOCK]
ประเภท Event
| Pattern | ทำงานเมื่อ |
|---------|------------|
| | memory event ใด ๆ |
| | เก็บ memory ใหม่ |
| | อัปเดต memory |
| | ลบ memory |
| | chat event ใด ๆ |
| | ข้อความใหม่จาก human |
| | task event ใด ๆ |
| | สร้าง task ใหม่ |
| | ทำเครื่องหมาย task ว่าเสร็จ |
| | ทุก event |
Webhook Payload
เมื่อ event ทำงาน Synapse POST ไปยัง URL ของคุณ:
[CODE BLOCK]
การตรวจสอบ Signature
หากคุณตั้ง Synapse จะ sign payload แต่ละรายการด้วย HMAC-SHA256:
[CODE BLOCK]
ตรวจสอบใน handler ของคุณ:
[CODE BLOCK]
รูปแบบ: Real-Time Sync
[CODE BLOCK]
ขั้นตอนถัดไป
- Cron & Scheduler
- Webhook Automation Guide
## หมวดหมู่: การรวม MCP
การรวมระบบกับ Claude, Cursor และ MCP clients อื่นๆ
────────────────────────────────────────────────────────────
# MCP ใน Claude Code
SUMMARY: ใช้ Synapse tool จาก Claude Code terminal agent — memory ถาวรสำหรับ coding session
KEY CONTEXT:
Claude Code config: ~/.claude/config.json (or via `claude mcp add` command)
Command: npx -y synapse-mcp-api@latest
Env: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional)
Alternative: `claude mcp add synapse -- npx -y synapse-mcp-api@latest`
Then: set SYNAPSE_MIND_KEY env var in your shell
Test: in claude code, type "recall all my memories"
MCP ใน Claude Code
Claude Code เป็น coding agent แบบ terminal ของ Anthropic ด้วย Synapse MCP, Claude Code ได้ memory ถาวรข้าม coding session — จดจำ context โปรเจกต์, การตัดสินใจในอดีต, และรูปแบบ codebase ของคุณ
การตั้งค่า
วิธีที่ 1: CLI Command (แนะนำ)
[CODE BLOCK]
วิธีที่ 2: แก้ไข Config File
แก้ไข :
[CODE BLOCK]
ตรวจสอบว่าทำงาน
เริ่ม Claude Code:
[CODE BLOCK]
ใน prompt ของ Claude Code พิมพ์:
[CODE BLOCK]
Claude ควรเรียก และตอบกลับด้วย memory ที่เก็บไว้ของคุณ
รูปแบบทั่วไป
ความคงทนของ context โปรเจกต์
ที่จุดเริ่มต้น coding session:
[CODE BLOCK]
Claude เรียก , เห็นรายการโปรเจกต์ของคุณ และทำงานต่อจากที่ค้างไว้
การตัดสินใจเกี่ยวกับ codebase
เมื่อคุณตัดสินใจเชิงสถาปัตยกรรม:
[CODE BLOCK]
Claude เรียก ด้วย category , priority
การหลีกเลี่ยง mistake ในอดีต
[CODE BLOCK]
Claude ค้นหา memory ด้วย category และเตือนคุณเกี่ยวกับ error ในอดีต
การติดตาม task
[CODE BLOCK]
Claude เรียก และ task อยู่รอดข้าม session
Tool Profile
สำหรับ coding session ที่คุณไม่ต้องการ tool ทั้ง 119:
[CODE BLOCK]
การแก้ปัญหา
MCP server ไม่เริ่ม
[CODE BLOCK]
Mind Key ไม่รู้จัก
[CODE BLOCK]
Claude Code ไม่เห็น tool
- รีสตาร์ท Claude Code หลังการเปลี่ยน config
- ตรวจ เพื่อยืนยันว่า Synapse ลงทะเบียนแล้ว
- ดู MCP Troubleshooting
ขั้นตอนถัดไป
- Claude Desktop Setup
- Cursor Setup
- Persistent LLM Agent Guide
────────────────────────────────────────────────────────────
# MCP ใน Claude Desktop
SUMMARY: เชื่อมต่อ Synapse กับ Claude Desktop ใน 2 นาที Claude ได้ Synapse tool 79 ตัวแบบ native
KEY CONTEXT:
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\Claude\claude_desktop_config.json (Windows)
MCP server command: npx -y synapse-mcp-api@latest
Env vars: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional, default https://synapse.schaefer.zone)
After config: restart Claude Desktop, check for 🔌 icon with "79 tools"
Test: type "memory_recall aufrufen" in a new chat
Troubleshooting: Node.js ≥ 18, check Mind Key, see /docs/mcp/troubleshooting
MCP ใน Claude Desktop
Claude Desktop เป็น desktop app ของ Anthropic สำหรับ macOS และ Windows ด้วย Synapse MCP server ที่กำหนดค่า Claude ได้สิทธิ์ native เข้าถึง Synapse tool ทั้ง 79 ตัว — สามารถเก็บ memory, recall, จัดการ task, แช็ตกับคุณ และอื่น ๆ
ข้อกำหนดเบื้องต้น
- Claude Desktop app (macOS หรือ Windows)
- Node.js 18+ ติดตั้ง ()
- Synapse Mind Key ของคุณ
ขั้นตอนที่ 1: เปิด Config File
- macOS:
- Windows:
หากไฟล์ไม่มี ให้สร้างขึ้นมา
ขั้นตอนที่ 2: เพิ่ม Synapse MCP Server
[CODE BLOCK]
> [!TIP]
> หากคุณมี MCP server อื่นที่กำหนดค่าแล้ว เพียงเพิ่ม block ใน object ที่มีอยู่
ขั้นตอนที่ 3: รีสตาร์ท Claude Desktop
1. ออกจาก Claude Desktop ให้เต็มรูปแบบ (Cmd+Q บน macOS, ไม่ใช่แค่ปิดหน้าต่าง)
2. เปิด Claude Desktop อีกครั้ง
3. เริ่มแช็ตใหม่
4. มองหาไอคอน 🔌 plug ที่มุมล่างซ้าย — ควรบอกว่า "79 tools"
ขั้นตอนที่ 4: ทดสอบ
ในแช็ตใหม่ พิมพ์:
[CODE BLOCK]
Claude ควรเรียก tool และตอบกลับด้วยสรุปของ memory ที่เก็บไว้ของคุณ (หรือ "No memories yet" หาก mind ของคุณว่าง)
Tool ที่ใช้ได้ (ส่วนหนึ่ง)
| Tool | คำอธิบาย |
|------|-------------|
| | Recall memory ทั้งหมด |
| | เก็บ memory ใหม่ |
| | ค้นหา memory |
| | รายการ task |
| | สร้าง task |
| | ตรวจข้อความใหม่ |
| | ตอบกลับข้อความ |
| | เปิด browser tab |
| | รายการ computer ที่ลงทะเบียน |
รายการเต็ม: MCP คืออะไร?
การแก้ปัญหา
ไม่มี tool ปรากฏใน Claude Desktop
1. ตรวจสอบเวอร์ชัน Node.js: (ต้อง ≥ 18)
2. ตรวจสอบ config file เป็น JSON ที่ถูกต้อง (ไม่มี trailing comma)
3. รีสตาร์ท Claude Desktop ให้เต็มรูปแบบ (Cmd+Q, ไม่ใช่แค่ปิด)
4. ตรวจ log Claude Desktop: (macOS)
Error "Mind Key invalid"
- ตรวจ ขึ้นต้นด้วย
- รับ key ใหม่ผ่าน (ต้องใช้ JWT จาก )
- ไม่มีเครื่องหมายคำพูดรอบ key ใน JSON
ไม่พบ npx
- ติดตั้ง Node.js 18+:
- รีสตาร์ท terminal หลังติดตั้ง
- บน macOS ด้วย Homebrew:
tool แสดงแต่การเรียกล้มเหลว
- ตรวจ เข้าถึงได้:
- ตรวจ Mind Key ทำงาน:
- ดู MCP Troubleshooting
Tool Profile (ประหยัด Token)
หากคุณใช้ LLM ที่เล็กกว่าหรือต้องการประหยัด context token ตั้ง tool profile:
[CODE BLOCK]
Profile: (8 tool), (25), (119, ค่าเริ่มต้น)
ขั้นตอนถัดไป
- Claude Code Setup
- Cursor Setup
- MCP Troubleshooting
────────────────────────────────────────────────────────────
# MCP ใน Continue.dev
SUMMARY: เชื่อมต่อ Synapse กับ Continue.dev — AI coding assistant แบบ open-source สำหรับ VS Code และ JetBrains
MCP ใน Continue.dev
Continue.dev เป็น AI coding assistant แบบ open-source สำหรับ VS Code และ JetBrains IDE ด้วย Synapse MCP, Continue ได้ memory ถาวรข้าม session
ข้อกำหนดเบื้องต้น
- VS Code หรือ JetBrains IDE
- ติดตั้ง Continue.dev extension
- Node.js 18+
- Synapse Mind Key ของคุณ
การตั้งค่า
ขั้นตอนที่ 1: เปิด Continue Config
ใน VS Code หรือ JetBrains:
1. เปิด Continue extension sidebar
2. คลิกไอคอน gear → "Open config.json"
หรือแก้ไข โดยตรง
ขั้นตอนที่ 2: เพิ่ม Synapse MCP Server
[CODE BLOCK]
ขั้นตอนที่ 3: โหลด Continue ใหม่
โหลดหน้าต่าง VS Code (Cmd+Shift+P → "Reload Window") หรือรีสตาร์ท IDE ของคุณ
ตรวจสอบว่าทำงาน
ในแช็ต Continue:
[CODE BLOCK]
Continue ควรเรียก และตอบกลับด้วย memory ที่เก็บไว้ของคุณ
รูปแบบทั่วไป
Context โปรเจกต์
[CODE BLOCK]
Continue เรียก , เห็น memory โปรเจกต์ของคุณ และทำงานต่อจากที่ค้างไว้
รูปแบบ code review
[CODE BLOCK]
Continue หารูปแบบ code review ที่เก็บไว้ของคุณและปรับใช้
Memory pair programming
[CODE BLOCK]
Continue เก็บเป็น memory
การแก้ปัญหา
MCP server เชื่อมต่อไม่ได้
1. ตรวจ เป็น JSON ที่ถูกต้อง
2. ตรวจ Node.js:
3. ตรวจ output panel ของ Continue (View → Output → Continue)
4. รีสตาร์ท IDE
tool ไม่ปรากฏ
- ตรวจเวอร์ชัน Continue รองรับ MCP (≥ 0.9.x)
- ตรวจ env var ตั้งใน config
- หา error MCP ใน log ของ Continue
ขั้นตอนถัดไป
- Claude Desktop Setup
- Custom MCP Client
────────────────────────────────────────────────────────────
# MCP ใน Cursor
SUMMARY: เชื่อมต่อ Synapse กับ Cursor IDE สำหรับ memory โปรเจกต์ถาวรข้าม coding session
MCP ใน Cursor
Cursor เป็น IDE ที่ขับเคลื่อนด้วย AI ที่สร้างบน VS Code ด้วย Synapse MCP, Cursor ได้ memory ถาวรข้าม session — จดจำการตัดสินใจโปรเจกต์, รูปแบบ codebase, และ session debugging ในอดีต
ข้อกำหนดเบื้องต้น
- ติดตั้ง Cursor IDE ()
- Node.js 18+
- Synapse Mind Key ของคุณ
การตั้งค่า
ขั้นตอนที่ 1: เปิด Cursor Settings
ใน Cursor:
1. เปิด Settings (Cmd+, บน macOS, Ctrl+, บน Windows/Linux)
2. ค้นหา "MCP" หรือนำทางไปยัง
ขั้นตอนที่ 2: เพิ่ม Synapse MCP Server
คลิก "Add MCP Server" และกำหนดค่า:
| Field | Value |
|-------|-------|
| Name | |
| Type | |
| Command | |
| Env | |
ขั้นตอนที่ 3: แก้ไข config.json โดยตรง (ทางเลือก)
Cursor เก็บ MCP config ใน :
[CODE BLOCK]
ขั้นตอนที่ 4: รีสตาร์ท Cursor
รีสตาร์ท Cursor ให้เต็มรูปแบบ (Cmd+Q และเปิดใหม่บน macOS)
ตรวจสอบว่าทำงาน
ในพาเนลแช็ตของ Cursor (Cmd+L):
[CODE BLOCK]
Cursor ควรเรียก และตอบกลับด้วย memory ที่เก็บไว้ของคุณ
รูปแบบทั่วไป
Onboarding โปรเจกต์
เมื่อเปิดโปรเจกต์ใหม่:
[CODE BLOCK]
Cursor เรียก และทำงานต่อจากที่ค้างไว้
การตัดสินใจเชิงสถาปัตยกรรม
[CODE BLOCK]
Cursor เก็บเป็น memory พร้อม priority
ประวัติ debugging
[CODE BLOCK]
Cursor ค้นหา memory และเตือนคุณเกี่ยวกับการแก้ไขในอดีต
รูปแบบ code ข้าม session
[CODE BLOCK]
Cursor หา memory เกี่ยวกับการ implement auth ที่คุณเคยทำ
การแก้ปัญหา
MCP server เชื่อมต่อไม่ได้
1. ตรวจ Node.js: (≥ 18)
2. ทดสอบ MCP server: (ควรเริ่มโดยไม่มี error)
3. ตรวจ MCP log ของ Cursor (View → Output → MCP)
4. รีสตาร์ท Cursor ให้เต็มรูปแบบ
tool ไม่ปรากฏ
- ตรวจ เป็น JSON ที่ถูกต้อง
- ตรวจ env var ตั้งแล้ว
- ตรวจเวอร์ชัน Cursor รองรับ MCP (≥ 0.42)
Mind Key ไม่ถูกต้อง
[CODE BLOCK]
ขั้นตอนถัดไป
- Claude Desktop Setup
- Continue.dev Setup
- Persistent LLM Agent Guide
────────────────────────────────────────────────────────────
# สร้าง Custom MCP Client
SUMMARY: เชื่อมต่อกับ Synapse MCP server จากแอปพลิเคชันของคุณเองโดยใช้ MCP SDK
สร้าง Custom MCP Client
หากคุณกำลังสร้างแอปพลิเคชัน LLM ของตัวเอง คุณสามารถเชื่อมต่อกับ Synapse MCP server โดยตรงโดยใช้ MCP SDK อย่างเป็นทางการ ซึ่งให้แอปของคุณเข้าถึง Synapse tool ทั้ง 79 ตัว
SDK
| ภาษา | Package |
|----------|---------|
| TypeScript/JavaScript | |
| Python | |
ตัวอย่าง TypeScript
ติดตั้ง
[CODE BLOCK]
เชื่อมต่อผ่าน stdio
[CODE BLOCK]
เชื่อมต่อผ่าน HTTP/SSE (remote)
[CODE BLOCK]
ตัวอย่าง Python
ติดตั้ง
[CODE BLOCK]
เชื่อมต่อผ่าน stdio
[CODE BLOCK]
Tool Profile
เมื่อเชื่อมต่อ คุณสามารถร้องขอ tool profile เฉพาะผ่าน header (HTTP/SSE) หรือ env var (stdio):
[CODE BLOCK]
การจัดการ Error
[CODE BLOCK]
กรณีใช้งาน
- AI assistant แบบกำหนดเอง — สร้าง agent ของคุณเองพร้อม memory ถาวร
- Workflow automation — เชื่อม Synapse tool ใน workflow แบบกำหนดเอง
- Data pipeline — ดึง memory, transform, load ที่อื่น
- Monitoring dashboard — แสดงสถิติ memory, ประวัติแช็ต, task
ขั้นตอนถัดไป
- MCP Specification
- Synapse MCP Repo
- API Overview
────────────────────────────────────────────────────────────
# การแก้ปัญหา MCP
SUMMARY: แก้ปัญหา integration MCP ทั่วไป — server ไม่เริ่ม, tool ไม่ปรากฏ, error auth
KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/
การแก้ปัญหา MCP
ปัญหาและวิธีแก้ทั่วไปเมื่อผสานรวม Synapse MCP กับ LLM client ของคุณ
Checklist Diagnostic ด่วน
1. ✅ ติดตั้ง Node.js 18+? ()
2. ✅ Mind Key ขึ้นต้นด้วย ? (ไม่ใช่ JWT )
3. ✅ เข้าถึง Synapse API ได้? ()
4. ✅ Mind Key ทำงาน? ()
5. ✅ Config file เป็น JSON ที่ถูกต้อง? (ไม่มี trailing comma, ไม่มี comment)
6. ✅ รีสตาร์ท client หลังเปลี่ยน config?
7. ✅ MCP server เริ่มด้วยตนเอง? ()
ปัญหา: ไม่มี tool ปรากฏใน Client
อาการ
- Claude Desktop / Cursor / Continue แสดง 0 tool
- ไม่มีไอคอน 🔌 หรือรายการ "synapse" ในรายการ MCP server
วิธีแก้
1. รีสตาร์ท client ให้เต็มรูปแบบ — Cmd+Q บน macOS (ไม่ใช่แค่ปิดหน้าต่าง)
2. ตรวจตำแหน่ง config file:
- Claude Desktop macOS:
- Claude Desktop Windows:
- Cursor:
- Continue:
3. ตรวจ JSON ให้ถูกต้อง — วาง config ใน
4. ตรวจ log client หา error MCP:
- Claude Desktop: (macOS)
- Cursor: View → Output → MCP
5. รัน MCP server ด้วยตนเอง เพื่อดู startup error:
[CODE BLOCK]
ปัญหา: Error "Mind Key invalid"
อาการ
- tool ปรากฏแต่การเรียกล้มเหลวด้วย "401 Unauthorized"
- Error: "Mind Key fehlt oder ungültig"
วิธีแก้
1. ตรวจรูปแบบ Mind Key — ขึ้นต้นด้วย , 40 ตัวอักษร
2. ทดสอบโดยตรง:
[CODE BLOCK]
3. ตรวจ env var ตั้งแล้ว — สำหรับ transport stdio, env var ต้องอยู่ใน MCP server config, ไม่ใช่ shell ของคุณ
4. รับ Mind Key ใหม่:
[CODE BLOCK]
ปัญหา: ไม่พบ npx
อาการ
- Error: "npx: command not found"
- MCP server ล้มเหลวตอนเริ่ม
วิธีแก้
1. ติดตั้ง Node.js 18+:
- macOS: หรือดาวน์โหลดจาก
- Linux:
- Windows: ดาวน์โหลดจาก
2. รีสตาร์ท terminal หลังติดตั้ง
3. ตรวจสอบ:
ปัญหา: SYNAPSEURL เข้าถึงไม่ได้
อาการ
- MCP server เริ่มแต่การเรียก tool หมดเวลา
- Error: "fetch failed" หรือ "ECONNREFUSED"
วิธีแก้
1. ทดสอบการเชื่อมต่อ:
[CODE BLOCK]
2. ตรวจ corporate firewall — อาจบล็อก HTTPS ขาออก
3. ลอง URL ทางเลือก:
- Production:
- MCP server:
4. สำหรับ self-hosted: ตรวจว่า instance Synapse ของคุณรันและเข้าถึงได้
ปัญหา: MCP Server Crash
อาการ
- MCP server ออกทันทีหลังเริ่ม
- Log client แสดง "MCP server disconnected"
วิธีแก้
1. รันด้วยตนเองเพื่อดู error:
[CODE BLOCK]
2. ตรวจ conflict port — MCP server ใช้ port 13100 โดยค่าเริ่มต้น
3. ล้าง npx cache:
[CODE BLOCK]
4. อัปเดตเป็นเวอร์ชันล่าสุด:
[CODE BLOCK]
ปัญหา: การเรียก Tool ส่งกลับ 429
อาการ
- Error: "Rate limit exceeded"
วิธีแก้
สิ่งนี้ไม่ควรเกิดกับ MCP (ใช้ header auth, ไม่จำกัดอัตรา) หากเกิด:
1. ตรวจว่าคุณใช้ ที่ไหน — เปลี่ยนเป็น header auth
2. ตรวจ — ตรวจให้แน่ใจว่าชี้ไปยัง instance ที่ถูกต้อง
3. ติดต่อ support หากปัญหายังคงอยู่
ปัญหา: Tool ปรากฏแต่ไม่ทำงาน
อาการ
- tool อยู่ในรายการ client
- การเรียก tool ส่งกลับ error หรือไม่มีผลลัพธ์
วิธีแก้
1. ตรวจชื่อ tool — ต้องตรง (เช่น , ไม่ใช่ )
2. ตรวจ arguments — ตรวจ input schema ของ tool
3. ทดสอบผ่าน API โดยตรง:
[CODE BLOCK]
4. ตรวจสุขภาพ Synapse:
[CODE BLOCK]
การขอความช่วยเหลือ
หากไม่มีวิธีข้างต้นแก้ปัญหาของคุณ:
1. ตรวจ issue ที่มี:
2. เปิด issue ใหม่ พร้อม:
- เวอร์ชัน MCP server ()
- ชื่อและเวอร์ชัน client
- ระบบปฏิบัติการ
- ส่วนที่เกี่ยวข้องของ log
- ขั้นตอนการ reproduce
ขั้นตอนถัดไป
- Claude Desktop Setup
- Claude Code Setup
- API Errors
────────────────────────────────────────────────────────────
# MCP คืออะไร?
SUMMARY: Model Context Protocol ช่วยให้ LLM เรียก external tool Synapse เปิดเผย tool 79 ตัวผ่าน MCP server อย่างเป็นทางการ
KEY CONTEXT:
MCP = Model Context Protocol (Anthropic, 2024). Open standard for LLM-tool integration.
Synapse has official MCP server: synapse-mcp-api (npm package, npx -y synapse-mcp-api@latest)
79 tools exposed: 22 memory, 7 chat, 8 scheduler, 4 tasks, 5 scripts, 9 computers, 4 push, 5 user, 3 utility
3 transports: stdio (local), HTTP/SSE (remote), WebSocket (mobile)
Supported clients: Claude Desktop, Claude Code, Cursor, Continue, Cline, any MCP-compatible client
Tool Profiles (v1.4.0): minimal (8 tools), standard (25), full (119) — controlled via MCP_PROFILE env or Mcp-Tool-Profile header
MCP คืออะไร?
Model Context Protocol (MCP) เป็นมาตรฐานเปิดโดย Anthropic (2024) ที่ช่วยให้ LLM เรียก external tool ในรูปแบบที่มีโครงสร้าง แทนที่จะวาง API docs ลงใน prompt คุณลงทะเบียน tool กับ MCP server และ LLM เรียกตามต้องการ — เหมือน function calling แต่เป็นมาตรฐานและไม่ขึ้นกับ client
Synapse MCP Server
Synapse มี MCP server อย่างเป็นทางการ ( บน npm) ที่เปิดเผย 79 tool ครอบคลุมฟีเจอร์ Synapse ทั้งหมด:
| Category | Tool | จำนวน |
|----------|-------|-------|
| Memory | recall, list, store, search, semantic-search, update, delete, bulk-delete, stats, unverified, contradictions, audit, related, by-tag, diff, expiring, health, sync, embed-batch, verify, unverify, mind-export | 22 |
| Chat | poll, reply, status, history, unread, send, upload | 7 |
| Scheduler | cronlist, croncreate, crondelete, crontoggle, varlist, varget, varset, vardelete | 8 |
| Tasks | tasklist, taskget, taskcreate, taskupdate | 4 |
| Scripts | scriptlist, scriptget, scriptinfo, scriptstore, scriptdelete | 5 |
| Computers | computerlist, computerget, installcode, screenshot, commandqueue, commandstatus, commandslist, disable, delete | 9 |
| Push | vapidpublickey, subscribe, unsubscribe, test | 4 |
| User/Mind | register, login, mindslist, mindcreate, minddelete | 5 |
| Utility | time, calc, random | 3 |
| Visualization | graph, tags, compact | 3 |
| Sharing | share, list, revoke | 3 |
| Webhooks | register, list, get, update, delete | 5 |
| Browser | new, navigate, click, type, screenshot, close | 6 |
| รวม | | 79+ |
วิธีการทำงาน
[CODE BLOCK]
1. คุณกำหนดค่า LLM client (Claude Desktop, Cursor ฯลฯ) ให้ใช้ Synapse MCP server
2. client เริ่ม MCP server (ผ่าน )
3. MCP server เชื่อมต่อกับ Synapse API โดยใช้ Mind Key ของคุณ
4. LLM เห็น tool ทั้ง 79 เป็น native function ที่เรียกได้
5. เมื่อ LLM ต้องการจดจำสิ่งใด มันเรียก — MCP server แปลสิ่งนี้เป็น บน Synapse
Transport
Synapse MCP server รองรับสาม transport:
stdio (local, แนะนำสำหรับ desktop)
[CODE BLOCK]
HTTP/SSE (remote, multi-tenant)
เชื่อมต่อ MCP client ของคุณกับ:
[CODE BLOCK]
WebSocket (mobile, ปริมาณสูง)
[CODE BLOCK]
Tool Profile (v1.4.0)
เพื่อลด overhead token สำหรับ LLM ที่เล็กกว่า MCP server รองรับสาม tool profile:
| Profile | Tool | Token | เหมาะกับ |
|---------|-------|--------|----------|
| | 8 (composite dispatch) | 500 | Self-hosted LLM ที่มี context ≤8k |
| | 25 (named) | 2,500 | Mid-size LLM (Claude Haiku, GPT-3.5) |
| | 119 (all) | 8,250 | Large LLM (Claude Sonnet/Opus, GPT-4) — ค่าเริ่มต้น |
ควบคุมผ่าน:
- Env var:
- Header:
Client ที่รองรับ
- Claude Desktop — desktop app ของ Anthropic
- Claude Code — terminal coding agent
- Cursor — IDE ที่ขับเคลื่อนด้วย AI
- Continue.dev — AI coding assistant แบบ open-source
- Cline — VS Code extension
- MCP client ใดก็ตามที่เข้ากันได้
ทำไมใช้ MCP แทน Direct API?
| วิธี | ข้อดี | ข้อเสีย |
|----------|------|------|
| Direct API | ง่าย, ไม่มีชั้นเพิ่ม | LLM ต้องรู้ URL, header, auth |
| MCP | LLM เห็น native tool, ไม่ต้องจำ URL | มี MCP server process เพิ่ม |
สำหรับกรณีใช้งาน LLM agent ส่วนใหญ่ MCP เป็นตัวเลือกที่ดีกว่า — LLM ไม่ต้องจำ path API หรือรูปแบบ auth
ขั้นตอนถัดไป
- Claude Desktop Setup — config 2 นาที
- Claude Code Setup — integration terminal
- Custom MCP Client — สร้างของคุณเอง
## หมวดหมู่: คู่มือและวิธีการ
คู่มือทีละขั้นสำหรับสถานการณ์ที่เป็นรูปธรรม
────────────────────────────────────────────────────────────
# การทดสอบ iOS App อัตโนมัติ
SUMMARY: ใช้ Synapse + Computer Control API เพื่อทำให้การทดสอบ iOS app เป็นอัตโนมัติผ่าน Simulator
การทดสอบ iOS App อัตโนมัติ
รวมระบบ memory ของ Synapse กับ Computer Control API เพื่อสร้างการทดสอบ iOS app ที่ขับเคลื่อนด้วย LLM LLM จดจำสถานการณ์ทดสอบ, เรียนรู้จากความล้มเหลวในอดีต และปรับตัวตามการเปลี่ยนแปลง UI
Architecture
[CODE BLOCK]
ข้อกำหนดเบื้องต้น
- บัญชี Synapse + Mind Key
- Synapse MCP server กำหนดค่าใน Claude Desktop
- iOS Simulator พร้อม ติดตั้ง
- Computer ลงทะเบียนใน Synapse (ดู Computer Control API)
ขั้นตอนที่ 1: ลงทะเบียน Simulator Computer
บน Mac ที่รัน iOS Simulator:
[CODE BLOCK]
ขั้นตอนที่ 2: เก็บสถานการณ์ทดสอบใน Memory
เก็บสถานการณ์ทดสอบที่ใช้ซ้ำเป็น memory:
[CODE BLOCK]
ขั้นตอนที่ 3: การทดสอบที่ขับเคลื่อนด้วย LLM
ใน Claude Desktop (พร้อม Synapse MCP ที่กำหนดค่า):
[CODE BLOCK]
Claude จะ:
1. เรียก เพื่อหา memory
2. เรียก เพื่อดูสถานะปัจจุบัน
3. ปฏิบัติแต่ละขั้นตอนผ่าน (click, type)
4. ตรวจสอบผลลัพธ์ผ่าน screenshot
5. เก็บความล้มเหลวเป็น memory
ขั้นตอนที่ 4: การทดสอบที่ซ่อมแซมตัวเอง
เมื่อการทดสอบล้มเหลว ให้เก็บความล้มเหลวและวิธีกู้คืน:
[CODE BLOCK]
ครั้งต่อไปที่ LLM รันการทดสอบ มันจะ recall ความล้มเหลวและปรับใช้การกู้คืนโดยอัตโนมัติ
ขั้นตอนที่ 5: ติดตามผลการทดสอบ
ติดตามการรันทดสอบเป็น task:
[CODE BLOCK]
คำสั่งทั่วไป
| Action | Command |
|--------|---------|
| Launch Simulator | |
| Screenshot | (via Synapse MCP) |
| Tap at (x,y) | |
| Type text | |
| Press Home | |
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
> - เก็บพิกัด UI เป็น memory — UI เปลี่ยน แต่ LLM สามารถเรียนรู้ใหม่ได้
> - ใช้ accessibility label — คงทยกว่าพิกัด
> - เก็บข้อมูลทดสอบแยก — ใช้ variable สำหรับชื่อผู้ใช้, รหัสผ่าน
> - รันการทดสอบในสถานะสะอาด — reset Simulator ระหว่างการรัน
> - บันทึก screenshot สำหรับความล้มเหลว — มีประโยชน์สำหรับ debug
ขั้นตอนถัดไป
- Self-Healing Tests
- Computer Control API
- Memory Best Practices
────────────────────────────────────────────────────────────
# Backup & Restore
SUMMARY: Export memory ของคุณสำหรับสำรองข้อมูล, ย้ายระหว่าง mind, กู้คืนหลังสูญเสียข้อมูล
Backup & Restore
Synapse ให้บริการ export/import แบบเต็มสำหรับสำรองข้อมูล memory, การย้าย และ disaster recovery คู่มือนี้ครอบคลุมการดำเนินการที่จำเป็น
Export
Full Mind Export
Export memory ทั้งหมดใน mind เป็น JSON:
[CODE BLOCK]
รูปแบบ Response:
[CODE BLOCK]
Incremental Export (Diff)
Export เฉพาะ memory ที่เปลี่ยนแปลงตั้งแต่ timestamp:
[CODE BLOCK]
Response:
[CODE BLOCK]
การสำรองข้อมูลอัตโนมัติ
ตั้งเวลาสำรองข้อมูลรายวันผ่าน cron:
[CODE BLOCK]
> [!NOTE]
> cron endpoint รับ response แต่ไม่เก็บไว้ สำหรับการสำรองจริง ให้ชี้ cron ไปยังเซิร์ฟเวอร์สำรองของคุณเองที่บันทึก response
ที่ดีกว่า: External Backup Script
[CODE BLOCK]
เพิ่มลง crontab:
[CODE BLOCK]
Restore
Restore ไปยัง Mind เดียวกัน
[CODE BLOCK]
Restore ไปยัง Mind ใหม่
[CODE BLOCK]
Python Restore Script
[CODE BLOCK]
การย้ายระหว่าง Mind
[CODE BLOCK]
สำรองข้อมูลอื่น ๆ
อย่าลืมสำรองข้อมูล:
| ประเภทข้อมูล | Endpoint |
|-----------|----------|
| Memories | |
| Tasks | |
| Scripts | |
| Webhooks | |
| Cron jobs | |
| Variables | |
| Chat history | |
การตรวจสอบ
หลัง restore ให้ตรวจสอบ:
[CODE BLOCK]
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
> - สำรองรายวัน — ทำให้เป็นอัตโนมัติด้วย cron
> - ทดสอบ restore — backup ที่ restore ไม่ได้ไม่มีประโยชน์
> - เก็บหลายเวอร์ชัน — อย่างน้อย 30 วัน
> - เก็บนอกไซต์ — S3, Backblaze B2 ฯลฯ
> - เข้ารหัส backup ที่ sensitive — memory อาจมี PII
> - จัดทำเอกสารกระบวนการ restore — คุณจะลืมเมื่อถึงเวลาใช้
ขั้นตอนถัดไป
- Memory API
- Cron & Scheduler — สำหรับการสำรองข้อมูลอัตโนมัติ
────────────────────────────────────────────────────────────
# แนวทางปฏิบัติที่ดีที่สุดสำหรับ Memory
SUMMARY: วิธีจัดโครงสร้าง memory เพื่อ recall ที่มีประสิทธิภาพ — category, key, tag, priority
แนวทางปฏิบัติที่ดีที่สุดสำหรับ Memory
วิธีที่คุณจัดโครงสร้าง memory กำหนดว่ามันจะมีประโยชน์แค่ไหน คู่มือนี้ครอบคลุมรูปแบบสำหรับจัด category, tag และกำหนด priority ของ memory เพื่อให้ LLM recall ข้อมูลที่ถูกต้องในเวลาที่เหมาะสม
Category: เลือกอันที่เฉพาะเจาะจงที่สุด
| Category | ใช้สำหรับ | ตัวอย่าง |
|----------|---------|---------|
| | ชื่อผู้ใช้, role, ข้อมูลติดต่อ | |
| | สิ่งที่ชอบ/ไม่ชอบ, สไตล์การทำงาน | |
| | fact ที่ตรวจสอบได้ | |
| | สถานะโปรเจกต์, การตัดสินใจ | |
| | ทักษะผู้ใช้ | |
| | error ในอดีตที่ต้องหลีกเลี่ยง | |
| | context ที่เกี่ยวข้องกับ session | |
| | note อื่น ๆ | |
> [!TIP]
> เมื่อไม่แน่ใจ ใช้ สำหรับข้อมูลที่ตรวจสอบได้ และ สำหรับทุกอย่างอื่น อย่า categorize มากเกินไป — ที่ชัดเจนดีกว่า ที่สับสน
Key: identifier ที่มีความหมาย
ฟิลด์ เป็น identifier ของ memory ใช้ key ที่มีความหมายและคงที่:
Key ที่ดี:
-
-
-
-
Key ที่ไม่ดี:
- (ไม่มีความหมาย)
- (ไม่บรรยาย)
- (วันที่ไม่ช่วย recall)
หลักการตั้งชื่อ key
- (ตัวพิมพ์เล็กด้วย underscore)
- นำหน้าด้วย category: , ,
- ใช้คำนามที่บรรยาย ไม่ใช่กริยา
- ความยาวไม่เกิน 50 ตัวอักษร
Tag: สำหรับการค้นหาและกรอง
Tag เปิดใช้งานการกรองและค้นหาที่รวดเร็ว เพิ่ม 2-5 tag ต่อ memory:
[CODE BLOCK]
รูปแบบ tag
- ชื่อโปรเจกต์: , ,
- หัวข้อ: , , ,
- สถานะ: , ,
- ตัวบ่งชี้ priority: ,
> [!NOTE]
> tag ไม่ sensitive ต่อตัวพิมพ์เล็ก/ใหญ่ ใช้ตัวพิมพ์เล็กเพื่อความสม่ำเสมอ
Priority: สมจริง
| Priority | ใช้สำหรับ | % ของ Memory |
|----------|---------|---------------|
| | ตัวตนผู้ใช้, ข้อมูลทางกฎหมาย, การตัดสินใจย้อนกลับไม่ได้ | 5% |
| | โปรเจกต์ที่ใช้งาน, ค่ากำหนดสำคัญ | 20% |
| | fact, note, context ส่วนใหญ่ | 65% |
| | ชั่วคราว, รู้ไว้ก็ดี | 10% |
> [!WARNING]
> อย่าทำเครื่องหมายทุกอย่างเป็น ถ้าทุกอย่าง critical ก็ไม่มีอะไร critical เลย สงวน สำหรับสิ่งที่จะก่อให้เกิดอันตรายจริงหากลืม
เมื่อใดเก็บ vs ไม่เก็บ
เก็บเสมอ
- ตัวตนผู้ใช้ (ชื่อ, email, role)
- ค่ากำหนดระยะยาว
- การตัดสินใจและเหตุผลของโปรเจกต์
- mistake และบทเรียนในอดีต
- คำมั่นสัญญาที่ให้กับผู้ใช้
ไม่เก็บ
- state ชั่วคราว (ใช้ variable แทน)
- ประวัติการสนทนาแบบ verbatim (ระบบแช็ตจัดการสิ่งนี้)
- ข้อมูล sensitive (รหัสผ่าน, API key)
- fact ที่ derive ง่าย (วันที่ปัจจุบัน, เนื้อหาไฟล์)
- context ชั่วคราว (ใช้ category พร้อม priority ต่ำ)
การอัปเดต Memory
POST ด้วย + เดิมจะอัปเดต memory ที่มีอยู่:
[CODE BLOCK]
> [!TIP]
> ใช้ key ที่คงที่เพื่อให้อัปเดตได้โดยไม่สร้างซ้ำ LLM ควร POST ซ้ำ key เดิมเมื่อข้อมูลเปลี่ยน ไม่ใช่สร้าง memory ใหม่
วงจรชีวิต Memory
[CODE BLOCK]
- Create: POST /memory พร้อม context เต็ม
- Active: recall บ่อย, อัปเดตตามต้องการ
- Stale: ยังเกี่ยวข้องแต่ไม่ได้ใช้งาน (priority ต่ำกว่า?)
- Archive: ตั้ง priority เป็น , เก็บเพื่ออ้างอิงทางประวัติศาสตร์
- Delete: DELETE /memory/:id เมื่อไม่เกี่ยวข้องอีก
การทำความสะอาดเป็นคาบ
[CODE BLOCK]
รูปแบบ: การสืบทอด Memory
สำหรับ context แบบลำดับชั้น (โปรเจกต์ → โปรเจกต์ย่อย → task):
[CODE BLOCK]
LLM สามารถค้นหา เพื่อหา memory ที่เกี่ยวข้องทั้งหมด
รูปแบบ: Decision Log
เก็บการตัดสินใจพร้อมเหตุผลเพื่อให้ LLM ไม่ต้องถกเถียงใหม่:
[CODE BLOCK]
รูปแบบ: การหลีกเลี่ยง Mistake
เก็บ mistake พร้อมคำแนะนำการหลีกเลี่ยงเฉพาะ:
[CODE BLOCK]
รูปแบบที่ควรหลีกเลี่ยง
> [!WARNING]
> - เก็บ log การสนทนา — ระบบแช็ตจัดการสิ่งนี้
> - เก็บไฟล์ทั้งหมด — ใช้ script store หรือ external storage
> - เก็บ state ชั่วคราว — ใช้ variable
> - เก็บ secret — ใช้ environment variable
> - ซ้ำ memory — ใช้ key ที่คงที่
> - tag มากเกินไป — 2-5 tag ต่อ memory เป็นอุดมคติ
> - ทุกอย่างเป็น critical — สมจริงกับ priority
ขั้นตอนถัดไป
- Memory API
- Persistent LLM Agent
- Memory Tagging Strategy
────────────────────────────────────────────────────────────
# การประสานงาน Multi-Agent
SUMMARY: ประสานงาน LLM agent หลายตัวโดยใช้ Synapse mind, task และ chat ที่แชร์กัน
การประสานงาน Multi-Agent
เมื่อคุณมี LLM agent หลายตัวทำงานที่เกี่ยวข้องกัน Synapse ให้ชั้นประสานงาน — shared memory, การมอบหมาย task, และ async chat
รูปแบบ
รูปแบบ 1: Shared Mind (Single Source of Truth)
agent ทั้งหมดแชร์ Mind Key เดียว พวกเขาอ่าน/เขียน memory store เดียวกัน
[CODE BLOCK]
กรณีใช้งาน: ทีมเล็กของ agent ที่ทำงานบนโปรเจกต์เดียว
การตั้งค่า:
[CODE BLOCK]
การประสานงานผ่าน task:
[CODE BLOCK]
รูปแบบ 2: Specialized Minds (Isolated Contexts)
แต่ละ agent มี mind ของตัวเอง พวกเขาสื่อสารผ่าน mind "coordination" ที่แชร์กัน
[CODE BLOCK]
กรณีใช้งาน: agent ที่มีความเชี่ยวชาญต่างกัน (coding, review, deployment)
การตั้งค่า:
[CODE BLOCK]
การประสานงานผ่าน shared mind:
[CODE BLOCK]
รูปแบบ 3: Hub-and-Spoke (Orchestrator)
orchestrator agent กลางมอบหมาย task ให้ worker agent
[CODE BLOCK]
กรณีใช้งาน: workflow ที่ซับซ้อนพร้อมงานขนาน
การ implement:
[CODE BLOCK]
การประสานงานผ่าน Chat
agent สื่อสารผ่านระบบแช็ต:
[CODE BLOCK]
> [!NOTE]
> ข้อความแช็ตถูก tag ด้วย role ตั้ง role=agent สำหรับข้อความ agent-to-agent, role=human สำหรับ human-to-agent
การประสานงานผ่าน Variable
ใช้ variable สำหรับการประสานงานเบา (lock, flag):
[CODE BLOCK]
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
> - ใช้ mind แยกสำหรับความกังวลแยก — อย่าผสม memory ของ coder และ reviewer
> - Tag agent ในแช็ต — สำหรับการระบุชัดเจน
> - ใช้ task สำหรับการมอบหมายงาน — ไม่ใช่แช็ต (แช็ตสำหรับการสนทนา)
> - implement idempotency — agent อาจ retry การดำเนินการที่ล้มเหลว
> - log ทุกอย่าง — เก็บการตัดสินใจใน memory เพื่อ auditability
ขั้นตอนถัดไป
- Persistent LLM Agent
- LLM Cookbook
- Webhook Automation
────────────────────────────────────────────────────────────
# สร้าง LLM Agent ที่ถาวร
SUMMARY: คู่มือทีละขั้นตอนในการสร้าง LLM agent ที่จดจำข้าม session โดยใช้ Synapse
ภาพรวม
คู่มือนี้นำคุณผ่านการสร้าง LLM agent ที่เก็บ context ข้าม session โดยใช้ Synapse เมื่อจบ คู่มือ agent ของคุณจะ:
- Recall context ในอดีตที่จุดเริ่มต้น session
- เก็บสิ่งที่เรียนรู้ใหม่เมื่อเกิดขึ้น
- ติดตาม task หลายขั้นตอนข้าม session
- สื่อสารกับ human ผ่าน async chat
Architecture
[CODE BLOCK]
ขั้นตอนที่ 1: ตั้งค่า Mind Key
[CODE BLOCK]
ขั้นตอนที่ 2: โปรโตคอลเริ่ม Session
ที่จุดเริ่มต้นของทุก session ให้ recall memory ทั้งหมด:
[CODE BLOCK]
ขั้นตอนที่ 3: เก็บสิ่งที่เรียนรู้ใหม่
เมื่อใดก็ตามที่ agent เรียนรู้สิ่งที่คุ้มค่าจดจำ:
[CODE BLOCK]
ขั้นตอนที่ 4: การจัดการ Task
ติดตามงานหลายขั้นตอนข้าม session:
[CODE BLOCK]
ขั้นตอนที่ 5: Async Chat กับ Human
Poll ข้อความระหว่างการเรียก tool:
[CODE BLOCK]
ขั้นตอนที่ 6: โปรโตคอลสิ้นสุด Session
ที่สิ้นสุด session เก็บ context สุดท้าย:
[CODE BLOCK]
รูปแบบสมบูรณ์
[CODE BLOCK]
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
>
> - recall ก่อนเสมอ — อย่าเริ่มงานโดยไม่โหลด context
> - เก็บอย่าง proactive — อย่ารอจนสิ้นสุด session
> - ใช้ key ที่มีความหมาย — , , ไม่ใช่
> - tag ทุกอย่าง — tag เป็นพลังของการค้นหาและกรอง
> - ตั้ง priority สมจริง — ไม่ใช่ทุกอย่างเป็น
ขั้นตอนถัดไป
- LLM Cookbook — รูปแบบปฏิบัติ
- Memory Best Practices
- Multi-Agent Coordination
────────────────────────────────────────────────────────────
# Pipeline ทดสอบที่ซ่อมแซมตัวเอง
SUMMARY: สร้าง pipeline ทดสอบที่เรียนรู้จากความล้มเหลวและปรับตัวอัตโนมัติโดยใช้ Synapse memory
Pipeline ทดสอบที่ซ่อมแซมตัวเอง
test suite แบบดั้งเดิมจะพังเมื่อ UI เปลี่ยน การทดสอบที่ซ่อมแซมตัวเองใช้ Synapse memory เพื่อเรียนรู้จากความล้มเหลวในอดีตและปรับตัว — ลด flaky test และภาระการบำรุงรักษา
แนวคิด
[CODE BLOCK]
1. ทดสอบรัน
2. หากล้มเหลว เก็บความล้มเหลว (อะไรผิด, ทำไม, วิธีแก้)
3. รันครั้งต่อไป: recall ความล้มเหลวที่เกี่ยวข้องก่อนปฏิบัติ
4. ปรับใช้วิธีแก้ที่รู้โดยอัตโนมัติ
การ implement
ขั้นตอนที่ 1: Test Wrapper
ห่อหุ้มการทดสอบแต่ละครั้งด้วยการ recall/store memory:
[CODE BLOCK]
ขั้นตอนที่ 2: Adaptive Test Logic
ภายในการทดสอบ ตรวจสอบความล้มเหลวที่รู้และปรับใช้วิธีแก้:
[CODE BLOCK]
ขั้นตอนที่ 3: กลยุทธ์การกู้คืน
เก็บกลยุทธ์การกู้คืนเป็น memory:
[CODE BLOCK]
ขั้นตอนที่ 4: CI Integration
[CODE BLOCK]
ขั้นตอนที่ 5: Failure Analysis Dashboard
[CODE BLOCK]
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
> - เก็บ traceback — มีบรรทัดที่ล้มเหลวที่แน่นอน
> - tag ตามชื่อการทดสอบ — เปิดใช้งานการกรองที่รวดเร็ว
> - ใช้ category — แยกจาก memory ปกติ
> - ตั้ง priority — ความล้มเหลวไม่ควรถูกลืม
> - ทำความสะอาดเป็นคาบ — ลบ memory สำหรับปัญหาที่แก้แล้ว
> - อย่าเก็บข้อมูล sensitive — credential, PII
รูปแบบความล้มเหลวทั่วไปที่ควรเก็บ
| ประเภทความล้มเหลว | สิ่งที่ควรเก็บ |
|--------------|---------------|
| Element not found | selector ที่ลอง, สถานะหน้า, screenshot |
| Timeout | เวลารอ, สิ่งที่กำลังรอ |
| Assertion failed | ค่าที่คาดหวัง vs ค่าจริง |
| Network error | URL, status code, response body |
| Permission denied | permission ที่ต้องการ, role ผู้ใช้ปัจจุบัน |
ขั้นตอนถัดไป
- Automated iOS Testing
- Memory Best Practices
- Error Recovery Cookbook
────────────────────────────────────────────────────────────
# Webhook Automation
SUMMARY: ทริกเกอร์ระบบภายนอกเมื่อ memory เปลี่ยนแปลง — sync, แจ้งเตือน, ทำให้เป็นอัตโนมัติ
Webhook Automation
Webhook ช่วยให้คุณทริกเกอร์ระบบภายนอกเมื่อ Synapse event ทำงาน คู่มือนี้ครอบคลุมรูปแบบ automation ทั่วไป
รูปแบบทั่วไป
รูปแบบ 1: แจ้งเตือนเมื่อ Memory Critical
ส่งข้อความ Slack เมื่อ memory critical ถูกเก็บ:
[CODE BLOCK]
ลงทะเบียน webhook:
[CODE BLOCK]
รูปแบบ 2: Sync ไปยังระบบภายนอก
Sync memory ไปยัง Notion, Obsidian หรือ KB ภายนอกใด ๆ:
[CODE BLOCK]
รูปแบบ 3: ทริกเกอร์ CI/CD
ทริกเกอร์ deployment เมื่อ memory "release" ถูกเก็บ:
[CODE BLOCK]
รูปแบบ 4: ปลุก Agent เมื่อ Human ส่งข้อความ
ทริกเกอร์การรัน LLM agent เมื่อ human ส่งข้อความแช็ต:
[CODE BLOCK]
รูปแบบ 5: รวม Metric
ติดตามการเติบโตของ memory, กิจกรรมแช็ต, การทำ task เสร็จ:
[CODE BLOCK]
การตรวจสอบ Signature
ตรวจสอบ webhook signature เสมอเพื่อป้องกันการปลอมแปลง:
[CODE BLOCK]
ตรรกะ Retry
Synapse retry webhook ที่ล้มเหลวด้วย exponential backoff handler ของคุณควร:
1. ส่งกลับ 200 อย่างรวดเร็ว — อย่าทำงานหนักแบบ synchronous
2. จัดคิวงาน — ใช้ระบบ background job
3. เป็น idempotent — event เดียวกันอาจถูกส่งสองครั้ง
[CODE BLOCK]
Debugging Webhook
ตรวจสอบประวัติการจัดส่ง
การจัดส่ง webhook ถูกบันทึก ตรวจสอบการจัดส่งล่าสุดของ webhook:
[CODE BLOCK]
ทดสอบ webhook ด้วยตนเอง
[CODE BLOCK]
ปัญหาทั่วไป
| ปัญหา | วิธีแก้ |
|-------|-----|
| 4xx response | ตรวจ handler ส่งกลับ 200 |
| 5xx response | server error — ตรวจ log แอป |
| Timeout | ส่งกลับ 200 เร็ว, จัดคิวงาน async |
| การจัดส่งซ้ำ | ทำ handler idempotent |
| Signature ไม่ตรง | ตรวจ secret ถูกต้อง |
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
> - ตรวจสอบ signature เสมอ — อย่าข้ามสิ่งนี้
> - ส่งกลับ 200 เร็ว — อยะบล็อก Synapse
> - เป็น idempotent — จัดการการจัดส่งซ้ำ
> - ใช้ event เฉพาะ — ไม่ใช่
> - ตรวจสอบการล้มเหลวการจัดส่ง — ตั้งค่า alerting
ขั้นตอนถัดไป
- Webhooks API
- Cron & Scheduler
- Persistent LLM Agent
## หมวดหมู่: แนวคิด
สถาปัตยกรรมและแนวคิดเบื้องหลัง Synapse
────────────────────────────────────────────────────────────
# Synapse Architecture
SUMMARY: วิธีที่ Synapse ถูกสร้างขึ้น — Fastify, PostgreSQL, FTS5, embeddings, MCP server
Synapse Architecture
Synapse เป็น multi-tenant memory API ที่สร้างบน Fastify, PostgreSQL พร้อม FTS5 และ embeddings service ที่เป็นตัวเลือกสำหรับ semantic search
Architecture ระดับสูง
[CODE BLOCK]
Core Components
1. Synapse API (Fastify)
HTTP server หลัก จัดการ:
- REST endpoint (, , , etc.)
- Authentication (Mind Key สำหรับ agent, JWT สำหรับ human)
- Rate limiting (เฉพาะ auth ผ่าน )
- Static file serving (web UI ที่ , , etc.)
- Webhook dispatch
สร้างด้วย Fastify 5 เพื่อประสิทธิภาพ รันบน port 12800 ใน production
2. PostgreSQL with FTS5
data store หลัก ใช้ PostgreSQL พร้อม FTS5 extension สำหรับ full-text search
ตารางหลัก:
| ตาราง | วัตถุประสงค์ |
|-------|---------|
| | บัญชีผู้ใช้ |
| | Mind scope (แต่ละอันมี Mind Key) |
| | Memory record พร้อม FTS5 virtual table |
| | การจัดการ task |
| | ประวัติแช็ต |
| | Script แบบถาวร |
| | การลงทะเบียน webhook |
| | Task ที่ตั้งเวลาไว้ |
| | Key-value store |
| | Audit trail |
FTS5 เปิดใช้งาน full-text search ในระดับ sub-millisecond ทั่วเนื้อหา memory ทั้งหมด ดูรายละเอียดที่ FTS5 Search
3. Embeddings Service (Optional)
สำหรับ semantic search Synapse สร้าง vector embeddings ของเนื้อหา memory ซึ่งเก็บไว้กับ memory และใช้สำหรับ similarity search
- Provider: กำหนดค่าได้ (OpenAI, local model, etc.)
- เก็บเป็น column ในตาราง
- ใช้โดย endpoint
- ดู Semantic Search
4. MCP Server (Service แยกต่างหาก)
Synapse MCP server รันเป็น process แยกต่างหาก (port 13100) ทำหน้าที่:
- เปิดเผย 79 tool ผ่าน Model Context Protocol
- รองรับ stdio, HTTP/SSE และ WebSocket transport
- แปล MCP tool call เป็น Synapse API call
- Multi-tenant: หนึ่ง Mind Key ต่อ session
5. Browser Proxy (Service แยกต่างหาก)
สำหรับ browser automation service แยกต่างหากที่ใช้ Playwright รันบน port 13000 MCP server สามารถเรียกสิ่งนี้สำหรับ tool
6. SSH Proxy (Service แยกต่างหาก)
สำหรับคำสั่งระยะไกลผ่าน SSH service แยกต่างหากรันบน port 12900
โมเดล Multi-Tenancy
[CODE BLOCK]
แต่ละ mind ถูกแยกอย่างสมบูรณ์ Mind Key ให้สิทธิ์เข้าถึง mind หนึ่งเท่านั้น JWT ให้สิทธิ์เข้าถึงบัญชีผู้ใช้ (สำหรับจัดการ mind)
ดูรายละเอียดที่ Multi-Tenancy
การไหลของ Request
Request เก็บ Memory
[CODE BLOCK]
Request ค้นหา Memory
[CODE BLOCK]
Deployment
Synapse deploy เป็น Docker container ดู :
[CODE BLOCK]
คุณลักษณะด้านประสิทธิภาพ
| การดำเนินการ | Latency | Throughput |
|-----------|---------|------------|
| Memory store | 5ms | 1000+ req/s |
| Memory recall | 20ms | 500 req/s |
| FTS5 search | 10ms | 800 req/s |
| Semantic search | 50ms | 200 req/s |
| Chat poll | 5ms | 2000 req/s |
ขั้นตอนถัดไป
- Memory Model
- Multi-Tenancy
- FTS5 Search
────────────────────────────────────────────────────────────
# FTS5 Full-Text Search
SUMMARY: วิธีที่ Synapse ใช้ SQLite FTS5 สำหรับการค้นหา memory แบบ full-text ในระดับ sub-millisecond
FTS5 Full-Text Search
Synapse ใช้ FTS5 (Full-Text Search 5) สำหรับการค้นหา memory ที่รวดเร็วและยืดหยุ่น เอกสารหน้านี้อธิบายวิธีการทำงานและวิธีใช้อย่างมีประสิทธิภาพ
FTS5 คืออะไร?
FTS5 เป็น SQLite extension (มีใน PostgreSQL ผ่าน extension ด้วย) ที่ให้ความสามารถ full-text search โดย:
- Index เนื้อหา text สำหรับ keyword search ที่รวดเร็ว
- รองรับ boolean operator (AND, OR, NOT)
- รองรับ phrase matching ด้วยเครื่องหมายคำพูด
- รองรับ prefix matching ด้วย
- จัดอันดับผลลัพธ์ตามความเกี่ยวข้อง
Synapse ใช้ FTS5 ในการ index เนื้อหา memory ทั้งหมด เปิดใช้งานการค้นหาในระดับ sub-millisecond ทั่ว memory หลายพันรายการ
วิธีที่ Synapse ใช้ FTS5
เมื่อคุณ :
1. เนื้อหา memory ถูกเก็บในตาราง
2. เนื้อหายังถูกแทรกลงใน FTS5 virtual table
3. FTS5 แบ่งคำและ index เนื้อหาโดยอัตโนมัติ
เมื่อคุณ :
1. Synapse แยกวิเคราะห์ query โดยใช้ไวยากรณ์ FTS5
2. ปฏิบัติการ กับ FTS5 index
3. กรองตาม (tenant isolation)
4. ส่งกลับผลลัพธ์ที่จัดอันดับแล้ว
ไวยากรณ์ Query
ค้นหา keyword แบบง่าย
[CODE BLOCK]
ส่งกลับ memory ที่มี "docker"
หลาย keyword (AND โดยนัย)
[CODE BLOCK]
ส่งกลับ memory ที่มีทั้ง "docker" และ "swarm"
Phrase matching
[CODE BLOCK]
ส่งกลับ memory ที่มี phrase "docker swarm" ตรงตัว
Prefix matching
[CODE BLOCK]
ส่งกลับ memory ที่มีคำขึ้นต้นด้วย "docker" (เช่น "dockers", "dockerfile", "dockerize")
Boolean OR
[CODE BLOCK]
ส่งกลับ memory ที่มี "docker" หรือ "kubernetes"
Boolean NOT
[CODE BLOCK]
ส่งกลับ memory ที่มี "docker" แต่ไม่มี "swarm"
การจัดกลุ่ม
[CODE BLOCK]
ส่งกลับ memory ที่มี "docker" หรือ "kubernetes" แต่ไม่มี "test"
ตัวอย่างปฏิบัติ
ค้นหา memory เกี่ยวกับโปรเจกต์
[CODE BLOCK]
ค้นหา phrase ตรงตัว
[CODE BLOCK]
แยก memory ทดสอบออก
[CODE BLOCK]
ค้นหาตามเทคโนโลยี
[CODE BLOCK]
การจัดอันดับ
FTS5 จัดอันดับผลลัพธ์ตามความเกี่ยวข้องโดยใช้อัลกอริทึม BM25 ปัจจัย:
- ความถี่ของคำ (term ปรากฏบ่อยแค่ไหน)
- Inverse document frequency (คำที่หายากอันดับสูงกว่า)
- ความยาวเอกสาร (เอกสารสั้นที่มีคำนั้นอันดับสูงกว่า)
- น้ำหนัก column (title > content)
ผลลัพธ์ส่งกลับตามลำดับอันดับ (เกี่ยวข้องที่สุดก่อน)
ประสิทธิภาพ
| การดำเนินการ | Latency |
|-----------|---------|
| ค้นหา 100 memory | < 5ms |
| ค้นหา 1,000 memory | < 10ms |
| ค้นหา 10,000 memory | < 25ms |
| ค้นหา 100,000 memory | < 100ms |
FTS5 ถูกปรับให้เหมาะกับ workload ที่อ่านหนัก
ข้อจำกัด
Stemming
FTS5 ไม่ทำ stemming โดยค่าเริ่มต้น "running" และ "run" เป็นคำต่างกัน
วิธีแก้: ใช้ prefix matching:
ความทนต่อการพิมพ์ผิด
FTS5 ไม่รองรับ fuzzy matching พิมพ์ผิดจะไม่ส่งกลับผลลัพธ์
วิธีแก้: ใช้ semantic search () สำหรับการจับคู่เชิงแนวคิด
Stop word
คำทั่วไป (the, a, an, is) ถูก index แต่อาจไม่มีประโยชน์ต่อการค้นหา FTS5 จัดการสิ่งนี้โดยอัตโนมัติ
FTS5 vs Semantic Search
| แง่มุม | FTS5 | Semantic Search |
|--------|------|-----------------|
| ความเร็ว | Sub-millisecond | 50-100ms |
| การจับคู่ | Exact keyword | เชิงแนวคิด |
| ทนพิมพ์ผิด | None | บางส่วน |
| Stemming | None | โดยนัย |
| ต้องการ embedding | ไม่ | ใช่ |
| เหมาะกับ | คำเฉพาะ | แนวคิด |
ใช้ FTS5 เมื่อคุณรู้ keyword ใช้ semantic search เมื่อคุณต้องการ "memory เกี่ยวกับ X" โดยที่ X ถูกอธิบายต่างกัน
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
> - ใช้คำที่เฉพาะเจาะจง — "docker swarm" ดีกว่า "container orchestration"
> - ใส่เครื่องหมายคำพูดรอบ phrase — รับประกัน phrase match
> - ใช้ prefix สำหรับรูปแปร — จับ "deploy", "deployment", "deploying"
> - แยกสัญญาณรบกวน — กรอง memory ทดสอบออก
> - รวมกับ tag — จำกัดผลลัพธ์
ขั้นตอนถัดไป
- Semantic Search
- Memory API
- Memory Best Practices
────────────────────────────────────────────────────────────
# โมเดล Memory
SUMMARY: วิธีที่ memory ถูกจัดโครงสร้าง — category, key, tag, priority, source, การยืนยัน
โมเดล Memory
โมเดล memory ของ Synapse ออกแบบมาเพื่อ LLM agent — มีโครงสร้างเพียงพอสำหรับ recall ที่เชื่อถือได้ และยืดหยุ่นพอสำหรับโดเมนใด ๆ
กายวิภาคของ Memory
[CODE BLOCK]
ฟิลด์
| Field | Type | Required | คำอธิบาย |
|-------|------|----------|-------------|
| | string | auto | ID ที่ไม่ซ้ำ (memxxx) |
| | enum | ✅ | หนึ่งใน 8 category |
| | string | ✅ | identifier ที่คงทย (ใช้สำหรับอัปเดต) |
| | string | ✅ | เนื้อหา memory (text ใด ๆ) |
| | string[] | – | สำหรับการค้นหาและกรอง |
| | enum | – | low, normal, high, critical (ค่าเริ่มต้น: normal) |
| | enum | auto | user, agent (ใครเป็นผู้เก็บ) |
| | bool | auto | human ยืนยันหรือยัง? |
| | float | – | 0.0 ถึง 1.0 (ค่าเริ่มต้น: 1.0 สำหรับ user, 0.7 สำหรับ agent) |
| | timestamp | – | เมื่อไรจะลืม memory นี้ |
| | string | auto | mind ใดเป็นเจ้าของ |
| | timestamp | auto | เก็บครั้งแรก |
| | timestamp | auto | แก้ไขล่าสุด |
Category
แปด category ครอบคลุมกรณีใช้งาน LLM agent ทั่วไป:
| Category | วัตถุประสงค์ | เนื้อหาตัวอย่าง |
|----------|---------|-----------------|
| | ผู้ใช้คือใคร | "User is Michael Schäfer, software engineer in Berlin" |
| | ค่ากำหนดผู้ใช้ | "Prefers concise technical responses" |
| | fact ที่ตรวจสอบได้ | "Office is in Berlin, timezone Europe/Berlin" |
| | สถานะโปรเจกต์ | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| | ทักษะผู้ใช้ | "Advanced Python, 10+ years" |
| | error ในอดีต | "Forgot to bump npm version — CI failed" |
| | context ของ session | "Currently reviewing PR #42" |
| | note อื่น ๆ | "Try Redis for caching next sprint" |
Key: identifier ที่คงที่
ฟิลด์ สำคัญมาก — เป็นวิธีที่คุณอัปเดต memory โดยไม่สร้างซ้ำ
[CODE BLOCK]
กฎของ key:
- ต้องไม่ซ้ำใน (category, mind)
- ใช้
- นำหน้าด้วย category เพื่อความชัดเจน: ,
- รักษาให้คงที่ — อย่าเปลี่ยน key หลังสร้าง
Tag: สำหรับการค้นหา
Tag เปิดใช้งานการกรองและค้นหาที่รวดเร็ว:
[CODE BLOCK]
แนวทางปฏิบัติที่ดีที่สุดสำหรับ tag:
- 2-5 tag ต่อ memory (อย่า tag มากเกินไป)
- ตัวพิมพ์เล็กเพื่อความสม่ำเสมอ
- ใช้ชื่อโปรเจกต์, หัวข้อ, เทคโนโลยี
- tag ไม่ sensitive ต่อตัวพิมพ์เล็ก/ใหญ่
ระดับ Priority
| Priority | เมื่อใช้ | พฤติกรรม Recall |
|----------|-------------|-----------------|
| | ตัวตน, ทางกฎหมาย, ย้อนกลับไม่ได้ | อยู่บนสุดของ recall เสมอ |
| | โปรเจกต์ที่ใช้งานอยู่, ค่ากำหนดหลัก | เด่นใน recall |
| | memory ส่วนใหญ่ (ค่าเริ่มต้น) | ลำดับ recall มาตรฐาน |
| | ชั่วคราว, รู้ไว้ก็ดี | อาจถูกสรุป |
เรียงตาม priority (critical ก่อน) แล้วตามความใหม่
Source: User vs Agent
memory ถูก tag ด้วย :
- — เก็บโดย human (ผ่าน JWT หรือ human UI)
- — เก็บโดย LLM agent (ผ่าน Mind Key)
สิ่งนี้มีผลต่อ:
- การยืนยัน: memory ถูก verify อัตโนมัติ, memory ไม่ได้
- ความมั่นใจ: ค่าเริ่มต้น 1.0, ค่าเริ่มต้น 0.7
- Recall: ทำเครื่องหมาย memory ที่ยังไม่ verify ด้วย "(unverified)"
> [!NOTE]
> ปฏิบัติต่อ memory source ด้วยความสงสัยพอสมควร อาจเป็นการอนุมานหรือสมมติฐาน ไม่ใช่ที่ผู้ใช้ระบุโดยตรง
การยืนยัน
flag บ่งชี้ว่า human ได้ยืนยัน memory แล้ว:
- memory : auto-verified ()
- memory : ค่าเริ่มต้น unverified ()
ยืนยัน memory ผ่าน:
[CODE BLOCK]
> [!NOTE]
> การยืนยันต้องใช้ JWT (human auth) ไม่ใช่ Mind Key (agent auth) สิ่งนี้รับประกันว่าเฉพาะ human เท่านั้นที่ทำเครื่องหมาย memory ว่า verified
ความมั่นใจ
ฟิลด์ (0.0 ถึง 1.0) บ่งชี้ความน่าเชื่อถือของ memory:
- 1.0 — ระบุโดยตรงโดยผู้ใช้
- 0.7 — อนุมานโดย agent
- 0.5 — ไม่แน่นอน ต้องตรวจสอบ
- 0.0 — สงสัยอย่างชัดเจน
ตั้งค่า confidence เมื่อเก็บ:
[CODE BLOCK]
การหมดอายุ
ตั้ง สำหรับ memory ที่ sensitive ต่อเวลา:
[CODE BLOCK]
memory ที่หมดอายุจะไม่ถูกส่งกลับโดย (แต่ยังมีใน DB) ใช้ เพื่อดู memory ที่จะหมดอายุเร็ว ๆ นี้
วงจรชีวิต Memory
[CODE BLOCK]
พฤติกรรม Recall
ส่งกลับสรุปแบบ plain-text ที่ปรับให้เหมาะกับ LLM context:
[CODE BLOCK]
- เรียงตาม priority (critical → low) แล้วตามความใหม่
- memory ที่ยังไม่ verify ทำเครื่องหมายด้วย
- รวม tag เพื่อ context
- Plain text (ไม่ต้อง parse JSON)
ขั้นตอนถัดไป
- Memory API
- Memory Best Practices
- FTS5 Search
────────────────────────────────────────────────────────────
# Multi-Tenancy & Isolation
SUMMARY: วิธีที่ Synapse แยกข้อมูลระหว่างผู้ใช้และ mind — อธิบายขอบเขตความปลอดภัย
Multi-Tenancy & Isolation
Synapse เป็น multi-tenant: หลายผู้ใช้ แต่ละคนมีหลาย mind ที่แยกจากกันโดยสมบูรณ์ เอกสารหน้านี้อธิบายโมเดล isolation
ลำดับชั้น Tenant
[CODE BLOCK]
ระดับ Isolation
ระดับ 1: User Isolation
แต่ละบัญชีผู้ใช้ถูกแยกกัน Alice ไม่สามารถ:
- เห็น mind ของ Bob
- เข้าถึง memory ของ Bob (แม้ด้วย JWT ของเธอ)
- ดูข้อมูลบัญชีของ Bob
บังคับโดย: column บนทุกตาราง, JWT มี , ทุก query กรองตาม
ระดับ 2: Mind Isolation
ภายในผู้ใช้ แต่ละ mind ถูกแยกกัน Mind A ไม่สามารถ:
- เห็น memory ของ Mind B
- เข้าถึง task, chat, script ของ Mind B
บังคับโดย: column บนตารางข้อมูลทั้งหมด, Mind Key มี , ทุก query กรองตาม
> [!CRITICAL]
> Mind Key isolation เป็นขอบเขตความปลอดภัยหลัก Mind Key ที่รั่วไหลให้สิทธิ์เข้าถึงข้อมูล mind นั้นอย่างเต็ม — แต่เฉพาะ mind นั้น
Authentication Token
| Token | Scope | เข้าถึงอะไรได้ |
|-------|-------|-------------------|
| Mind Key | mind เดียว | ข้อมูล mind นั้นเท่านั้น |
| JWT | บัญชีผู้ใช้ | การจัดการบัญชี (สร้าง/รายการ/ลบ mind) |
| Computer Token | computer เดียว | คำสั่งของ computer นั้น |
การเข้าถึงข้าม Mind
ภายในผู้ใช้เดียวกัน
ผู้ใช้เข้าถึง mind ทั้งหมดของตนผ่าน JWT (เช่น รายการทั้งหมด) แต่เพื่ออ่าน/เขียนข้อมูล memory ต้องใช้ Mind Key เฉพาะ
ข้ามผู้ใช้
ผู้ใช้ไม่สามารถเข้าถึงข้อมูลของกันและกัน — เว้นแต่จะแชร์ mind อย่างชัดเจนผ่าน Sharing API:
[CODE BLOCK]
หลังแชร์ Bob สามารถเข้าถึง Mind A ผ่าน JWT ของเขา (อ่านอย่างเดียวหาก )
ขอบเขตความปลอดภัย
[CODE BLOCK]
รูปแบบ Multi-Tenancy ทั่วไป
รูปแบบ 1: ผู้ใช้เดียว, mind เดียว
ทั่วไปที่สุดสำหรับผู้ใช้ LLM agent รายบุคคล
- 1 บัญชีผู้ใช้
- 1 mind
- 1 Mind Key
- memory ทั้งหมดใน scope เดียว
รูปแบบ 2: ผู้ใช้เดียว, หลาย mind
สำหรับผู้ใช้ที่มีหลาย context (งาน, ส่วนตัว, โปรเจกต์)
- 1 บัญชีผู้ใช้
- N mind (เช่น "work", "personal", "project-x")
- N Mind Key
- แต่ละ LLM session ใช้หนึ่ง Mind Key
รูปแบบ 3: Mind ที่แชร์ในทีม
สำหรับทีมที่ทำงานร่วมกันในโปรเจกต์
- 1 ผู้ใช้สร้าง mind (ได้ Mind Key)
- ผู้สร้างแชร์กับสมาชิกทีมผ่าน JWT
- สมาชิกทีมทั้งหมดเข้าถึงผ่าน JWT (หรือ Mind Key ที่แชร์)
> [!WARNING]
> การแชร์ Mind Key ให้สิทธิ์อ่าน/เขียนเต็ม สำหรับการทำงานร่วมในทีม แนะนำ Sharing API (ใช้ JWT) มากกว่าการแชร์ Mind Key โดยตรง
รูปแบบ 4: SaaS Provider
สำหรับแอปที่ฝัง Synapse เป็น memory layer
- ลูกค้าแต่ละราย = 1 บัญชีผู้ใช้
- โปรเจกต์ลูกค้าแต่ละโปรเจกต์ = 1 mind
- แอปเก็บ Mind Key ตามลูกค้า/โปรเจกต์
- แยกอย่างสมบูรณ์ระหว่างลูกค้า
การตรวจสอบ Isolation
ทดสอบ: Mind Key เข้าถึง mind อื่นไม่ได้
[CODE BLOCK]
ทดสอบ: JWT อ่านข้อมูล memory โดยตรงไม่ได้
[CODE BLOCK]
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
> - ใช้หนึ่ง mind ต่อโปรเจกต์/context — isolation เป็นเพื่อนของคุณ
> - อย่าแชร์ Mind Key — ใช้ Sharing API แทน
> - หมุนเวียน Mind Key หากถูกโจมตี (ลบ mind, สร้างใหม่)
> - ตรวจสอบ mind ที่แชร์ — ตรวจ เป็นคาบ
> - ใช้ JWT สำหรับ human UI — อย่าเปิดเผย Mind Key ต่อ end user
ขั้นตอนถัดไป
- Authentication
- Mind Key vs JWT
- Architecture
────────────────────────────────────────────────────────────
# Semantic Search (Embeddings)
SUMMARY: การค้นหา memory เชิงแนวคิดโดยใช้ vector embedding — ค้นหาตามความหมาย ไม่ใช่แค่ keyword
Semantic Search (Embeddings)
Synapse รองรับ semantic search โดยใช้ vector embedding ต่างจาก FTS5 (keyword matching) ตรงที่ semantic search หา memory ตาม ความหมาย — แม้ไม่มี keyword ตรงกัน
วิธีการทำงาน
[CODE BLOCK]
embedding คืออะไร?
embedding เป็นการแทน text ด้วย numerical vector text ที่มีความหมายคล้ายกันจะมี vector คล้ายกัน Synapse สร้าง vector (เช่น 1536 มิติ) สำหรับเนื้อหา memory แต่ละรายการ
Cosine similarity
เพื่อหา memory ที่คล้ายเชิง semantic Synapse คำนวณ cosine similarity ระหว่าง query vector และ memory vector แต่ละตัว similarity สูง = เกี่ยวข้องมากกว่า
เมื่อใดควรใช้ Semantic Search
ใช้ semantic search เมื่อ:
- คุณต้องการ "memory เกี่ยวกับ X" โดย X ถูกอธิบายต่างจากที่เก็บ
- FTS5 ไม่ส่งกลับผลลัพธ์ (ไม่มี keyword ตรง)
- คุณต้องการการจัดกลุ่มเชิงแนวคิด (เช่น memory "deployment" ทั้งหมด แม้บางอันพูดถึง "release")
- Query เป็นคำถาม: "เราจัดการ authentication อย่างไร?"
ใช้ FTS5 เมื่อ:
- คุณรู้ keyword ที่แน่นอน
- คุณต้องการ logic boolean (AND, OR, NOT)
- คุณต้องการ response ในระดับ sub-millisecond
- คุณต้องการ phrase matching
Endpoint
GET /memory/semantic-search
[CODE BLOCK]
Response:
[CODE BLOCK]
ตัวอย่าง
หา memory เกี่ยวกับ deployment
[CODE BLOCK]
ส่งกลับ memory เกี่ยวกับ "deployment", "release", "publishing", "rolling out" ฯลฯ
หารูปแบบ authentication
[CODE BLOCK]
ส่งกลับ memory เกี่ยวกับ login, auth, JWT, session management, OAuth ฯลฯ
หา memory ที่คล้ายกัน
[CODE BLOCK]
ใช้ semantic similarity (ผ่าน tag ที่ใช้ร่วมกันและ embedding vector)
การสร้าง Embedding
เมื่อใดจะสร้าง embedding?
- เมื่อเก็บ memory — หาก embeddings service ถูกกำหนดค่า, embedding ถูกสร้างแบบ synchronous
- Batch generation — สร้าง embedding สำหรับ memory ที่ยังไม่มี
- Async update — เมื่อเนื้อหาถูกอัปเดต, embedding ถูกสร้างใหม่
Embedding provider
Synapse รองรับ embedding provider ที่กำหนดค่าได้:
- OpenAI (, )
- Local model (ผ่าน Ollama หรือคล้ายกัน)
- Custom (implement embeddings interface)
กำหนดค่าผ่าน environment variable:
[CODE BLOCK]
การสร้างแบบ Batch
สำหรับ mind ที่มี memory หลายรายการที่ยังไม่มี embedding:
[CODE BLOCK]
ประสิทธิภาพ
| การดำเนินการ | Latency |
|-----------|---------|
| สร้าง embedding (OpenAI) | 100-200ms |
| Semantic search (1k memory) | 50-100ms |
| Semantic search (10k memory) | 200-500ms |
| การสร้างแบบ batch (100 memory) | 10-20s |
> [!NOTE]
> Semantic search ช้ากว่า FTS5 เนื่องจากการคำนวณ vector ใช้ FTS5 สำหรับ keyword ที่รู้ ใช้ semantic สำหรับ query เชิงแนวคิด
ข้อจำกัด
ต้นทุน embedding
หากใช้ OpenAI การสร้าง embedding มีค่าใช้จ่าย ($0.02 ต่อ 1M token สำหรับ text-embedding-3-small) สำหรับ 10,000 memory เฉลี่ย 100 token ต่อรายการ ประมาณ $0.02 — น้อยมาก
Cold start
memory ที่เก็บก่อนกำหนดค่า embedding จะไม่มี embedding รัน เพื่อ backfill
การพึ่งพา provider
หาก embedding provider ล่ม semantic search จะล้มเหลวอย่างนุ่มนวล (ส่งกลับผลลัพธ์ว่างหรือ error) FTS5 ยังทำงานได้
เมื่อ Embedding ไม่พร้อมใช้งาน
หาก embeddings service ไม่ถูกกำหนดค่า:
- ส่งกลับ 503 Service Unavailable
- ยังทำงานได้ (เพียงแค่ไม่สร้าง embedding)
- FTS5 search ยังทำงานได้
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
> - ใช้ semantic สำหรับ query เชิงแนวคิด — "เราจัดการ X อย่างไร?"
> - ใช้ FTS5 สำหรับคำเฉพาะ — "docker swarm"
> - Backfill embedding เป็นคาบ —
> - ตรวจสอบสุขภาพ provider — semantic search พึ่งพามัน
> - รวมกับ tag — semantic + tag filter จำกัดผลลัพธ์
ขั้นตอนถัดไป
- FTS5 Search
- Memory API
- Architecture
## หมวดหมู่: หนังสือทำอาหาร LLM
สูตรและรูปแบบสำหรับ LLM agents
────────────────────────────────────────────────────────────
# รูปแบบการ Poll แช็ต
SUMMARY: วิธี poll ข้อความจาก human ระหว่างการเรียก tool โดยไม่บล็อก workflow
รูปแบบการ Poll แช็ต
ระบบแช็ตเป็น asynchronous — human สามารถฝากข้อความขณะคุณทำงาน รูปแบบนี้แสดงวิธี poll ข้อความโดยไม่บล็อก workflow
รูปแบบ
[CODE BLOCK]
Poll ระหว่างการเรียก tool ไม่ใช่ในลูปแน่น
ทำไมต้อง Poll ระหว่างการเรียก Tool?
- ไม่บล็อก — polling ในลูปแน่นเปลือง API call
- ไม่พลาดข้อความ — polling น้อยเกินไปหมายถึง response ช้า
- จุดที่เหมาะ — poll ทุก 30-60 วินาที หรือหลังแต่ละการเรียก tool
การ implement
Polling พื้นฐาน
[CODE BLOCK]
รูปแบบ 1: Poll หลังแต่ละการเรียก tool
[CODE BLOCK]
รูปแบบ 2: Polling ตามเวลา
[CODE BLOCK]
รูปแบบ 3: Event-driven (กับ webhook)
สำหรับการแจ้งเตือนแบบ real-time ลงทะเบียน webhook:
[CODE BLOCK]
จากนั้น webhook handler ของคุณสามารถปลุก agent:
[CODE BLOCK]
รูปแบบการจัดการข้อความ
รูปแบบ: รับทราบแล้วประมวลผล
[CODE BLOCK]
รูปแบบ: จัดคิวสำหรับประมวลผลแบบ batch
[CODE BLOCK]
รูปแบบ: กำหนดเส้นทางตาม priority
[CODE BLOCK]
ความถี่ในการ Poll
| กรณีใช้งาน | ความถี่ |
|----------|-----------|
| Interactive agent (human รอ) | ทุก 5-10 วินาที |
| Background agent | ทุก 30-60 วินาที |
| Batch processing | ทุก 5 นาที |
| Webhook-triggered | อย่า poll — ใช้ webhook |
> [!WARNING]
> Polling มากกว่าหนึ่งครั้งต่อ 5 วินาทีเปลือง API call endpoint ส่งกลับทันทีหากมีข้อความรอ ดังนั้นไม่มีประโยชน์จาก polling เร็วกว่านี้
Multi-Agent Chat
สำหรับการสื่อสาร agent-to-agent:
[CODE BLOCK]
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
> - Poll ระหว่างการเรียก tool — ไม่ใช่ในลูปแน่น
> - รับทราบทันที — human รู้ว่าคุณได้รับข้อความ
> - ประมวลผลแบบ asynchronous — อย่าบล็อกกับงานยาว
> - ใช้ webhook สำหรับ real-time — polling มี latency
> - อย่า poll มากกว่าหนึ่งครั้งต่อ 5 วินาที — เปลือง API call
ปัญหาทั่วไป
ข้อความหายไป
- ทำเครื่องหมายข้อความว่าอ่านแล้วโดยอัตโนมัติ
- หากคุณไม่ประมวลผล ข้อความจะหายไป
- วิธีแก้: ประมวลผลข้อความก่อนส่งกลับเสมอ
ตอบกลับซ้ำ
- หาก handler ของคุณ crash คุณอาจตอบกลับสองครั้ง
- วิธีแก้: ทำ handler idempotent (ตรวจว่าตอบกลับแล้วหรือยัง)
Response ช้า
- Polling ทุก 60 วินาทีหมายถึง latency สูงสุด 60 วินาที
- วิธีแก้: Poll ทุก 10-30 วินาที หรือใช้ webhook
ขั้นตอนถัดไป
- Chat API
- Session Start Pattern
- Error Recovery
────────────────────────────────────────────────────────────
# การกู้คืนจาก Error สำหรับ Agent
SUMMARY: วิธีที่ LLM agent ควรจัดการและกู้คืนจาก error — retry, เก็บ, เรียนรู้
การกู้คืนจาก Error สำหรับ Agent
error เกิดขึ้นเสมอ เครือข่ายล้มเหลว, API ส่งกลับ 500, Mind Key หมดอายุ คู่มือนี้แสดงวิธีที่ LLM agent ควรจัดการ error อย่างเหมาะสมและเรียนรู้จากมัน
หลักการจัดการ Error
1. Retry ด้วย backoff — error ชั่วคราวมักหายไป
2. เก็บ error — เรียนรู้จากรูปแบบ
3. ลดระดับอย่างเหมาะสม — อย่า crash session ทั้งหมด
4. แจ้ง human — สำหรับ error ที่คุณกู้คืนไม่ได้
การจัดการ HTTP Error
Retry ด้วย exponential backoff
[CODE BLOCK]
การจัดการ auth error
[CODE BLOCK]
การเก็บ Error เป็น Memory
เมื่อ error เกิดขึ้น เก็บไว้เพื่อ session ในอนาคตได้เรียนรู้:
[CODE BLOCK]
สถานการณ์ Error ทั่วไป
สถานการณ์ 1: Mind Key ไม่ถูกต้อง
[CODE BLOCK]
สถานการณ์ 2: Network Error
[CODE BLOCK]
สถานการณ์ 3: Rate Limited
[CODE BLOCK]
สถานการณ์ 4: Server Error (5xx)
[CODE BLOCK]
สถานการณ์ 5: การเรียก Tool ล้มเหลว
[CODE BLOCK]
รูปแบบ: Circuit Breaker
สำหรับความล้มเหลวซ้ำ ให้หยุดลองชั่วคราว:
[CODE BLOCK]
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
> - Retry error ชั่วคราวเสมอ — เครือข่ายล้มเหลว, เซิร์ฟเวอร์สะอึก
> - อย่า retry client error (4xx) — มันจะไม่แก้ตัวเอง
> - เก็บ error เป็น memory — เรียนรู้จากรูปแบบ
> - แจ้ง human สำหรับ error critical — พวกเขาต้องรู้
> - ลดระดับอย่างเหมาะสม — งานบางส่วนดีกว่า crash
> - ใช้ circuit breaker — อยะ hammer service ที่ล้มเหลว
ขั้นตอนถัดไป
- Errors API Reference
- Session Start Pattern
- Self-Healing Tests
────────────────────────────────────────────────────────────
# กลยุทธ์การ Tag Memory
SUMMARY: วิธี tag memory เพื่อการค้นหาและกรองที่มีประสิทธิภาพ — ระบบ tagging ที่ scale ได้
กลยุทธ์การ Tag Memory
tag เป็นความลับของการดึง memory ที่ scale ได้ คู่มือนี้แสดงวิธี tag memory เพื่อให้ตัวที่ถูกต้องกลับมาในเวลาที่เหมาะสม
ทำไม tag ถึงสำคัญ
ไม่มี tag คุณมีแค่ full-text search แบบ flat มี tag คุณมีการนำทางที่มีโครงสร้าง:
[CODE BLOCK]
tag เปิดใช้งาน:
- การกรองที่รวดเร็ว —
- Scoped search —
- การจัดกลุ่ม — หา memory "mistake" ทั้งหมดของโปรเจกต์
- การอ้างอิงข้าม — memory ที่แชร์ tag เกี่ยวข้องกัน
Schema Tagging
Project tag
ใช้ชื่อโปรเจกต์เป็น tag:
[CODE BLOCK]
Technology tag
ใช้ชื่อเทคโนโลยี:
[CODE BLOCK]
Topic tag
ใช้หมวดหมู่หัวข้อ:
[CODE BLOCK]
Status tag
ใช้ตัวบ่งชี้สถานะ:
[CODE BLOCK]
Type tag
ใช้ตัวบ่งชี้ประเภท:
[CODE BLOCK]
กฎการ Tag
กฎ 1: 2-5 tag ต่อ memory
tag น้อยเกินไป = ความสามารถในการค้นพบต่ำ tag มากเกินไป = noise
[CODE BLOCK]
กฎ 2: ตัวพิมพ์เล็ก, ใช้ hyphen
[CODE BLOCK]
กฎ 3: ใช้คำศัพท์ที่สม่ำเสมอ
กำหนดคำศัพท์ tagging และยึดติดกับมัน:
[CODE BLOCK]
กฎ 4: Tag ด้วยเจตนาการค้นหา
ถาม: "ฉันจะค้นหา memory นี้อย่างไร?"
[CODE BLOCK]
รูปแบบ
รูปแบบ 1: Project + Topic
[CODE BLOCK]
Search: (memory โปรเจกต์ Synapse ทั้งหมด)
Search: (memory deployment ใน Synapse)
รูปแบบ 2: Type + Domain
[CODE BLOCK]
Search: (mistake ทั้งหมด)
Search: (mistake deployment)
รูปแบบ 3: ลำดับชั้น
สำหรับโปรเจกต์ย่อยในโปรเจกต์:
[CODE BLOCK]
Search: (Synapse ทั้งหมด)
Search: (เฉพาะโปรเจกต์ย่อย docs)
รูปแบบ 4: ติดตามสถานะ
[CODE BLOCK]
กรณีใช้งานทั่วไป
หาการตัดสินใจทั้งหมดเกี่ยวกับโปรเจกต์
[CODE BLOCK]
หา mistake ทั้งหมดใน domain
[CODE BLOCK]
หางานที่ active
[CODE BLOCK]
หา memory เกี่ยวกับเทคโนโลยี
[CODE BLOCK]
การบำรุงรักษา tag
ตรวจสอบเป็นคาบ
[CODE BLOCK]
การรวม tag
หากคุณมี tag ไม่สม่ำเสมอ ( และ ) ให้รวม:
[CODE BLOCK]
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
> - กำหนดคำศัพท์ตั้งแต่เริ่ม — tag สม่ำเสมอตั้งแต่วันแรก
> - Tag ด้วยเจตนาการค้นหา — คุณจะหาสิ่งนี้อย่างไรในภายหลัง?
> - 2-5 tag เป็นจุดที่เหมาะ — น้อยหรือมากเกินไปไม่ดี
> - ตัวพิมพ์เล็ก + hyphen — ไม่ใช่
> - ตรวจสอบเป็นคาบ — รวมซ้ำ, ลบที่ไม่ใช้
ขั้นตอนถัดไป
- Memory Best Practices
- FTS5 Search
- Task-Driven Workflow
────────────────────────────────────────────────────────────
# รูปแบบการเริ่ม Session
SUMMARY: ลำดับการเริ่ม session แบบ canonical ที่ LLM agent ทุกตัวควรทำตาม
KEY CONTEXT:
ALWAYS at session start: 1) GET /memory/recall, 2) GET /chat/poll, 3) GET /mind/tasks?status=in_progress
Build system prompt from recall output.
Process unread chat messages before doing new work.
Resume any in_progress tasks before starting new ones.
Store new learnings as they happen — don't wait until session end.
รูปแบบการเริ่ม Session
ทุก LLM agent session ควรทำตามลำดับ startup แบบ canonical นี้ การข้ามขั้นตอนนำไปสู่ context สูญหาย, ข้อความที่พลาด และ task ที่ลืม
รูปแบบ
[CODE BLOCK]
การ implement
ขั้นตอนที่ 1: Recall Memory ทั้งหมด
> [!CRITICAL]
> นี่เป็นการเรียกที่สำคัญที่สุด หากไม่มี คุณไม่มี memory ของ session ที่ผ่านมา
[CODE BLOCK]
ส่งกลับสรุปแบบ plain-text ของ memory ทั้งหมด เรียงตาม priority
ขั้นตอนที่ 2: Poll ข้อความแช็ตที่ยังไม่ได้อ่าน
[CODE BLOCK]
ส่งกลับข้อความที่ยังไม่ได้อ่านจาก human ทำเครื่องหมายว่าอ่านแล้วโดยอัตโนมัติ
ขั้นตอนที่ 3: ตรวจ Task ที่กำลังดำเนินการ
[CODE BLOCK]
ส่งกลับ task ที่คุณทำอยู่ session ที่แล้ว
ขั้นตอนที่ 4: สร้าง Context
รวม response ทั้งสามเข้าใน system prompt ของคุณ:
[CODE BLOCK]
ขั้นตอนที่ 5: ประมวลผลรายการที่ค้าง
[CODE BLOCK]
ตัวอย่างสมบูรณ์
[CODE BLOCK]
ความผิดพลาดทั่วไป
> [!WARNING]
> - ข้าม recall — คุณเริ่มโดยไม่มี context, ทำ mistake ซ้ำ
> - ลืม poll แช็ต — ข้อความของ human ไม่ได้รับการตอบ
> - ละเลย task active — งานถูกลืมกลางการปฏิบัติ
> - ไม่เก็บอะไร — session ไม่สร้างค่าถาวร
รูปแบบแปรผัน
รูปแบบ minimal (LLM context ต่ำ)
สำหรับ LLM ที่มี context window เล็ก ข้าม full recall:
[CODE BLOCK]
จากนั้นค้นหาหัวข้อเฉพาะตามต้องการ:
[CODE BLOCK]
รูปแบบ aggressive (agent รันนาน)
สำหรับ agent ที่รันเป็นชั่วโมง เพิ่ม re-recall เป็นคาบ:
[CODE BLOCK]
ขั้นตอนถัดไป
- Memory Tagging Strategy
- Task-Driven Workflow
- Chat Polling Pattern
────────────────────────────────────────────────────────────
# Workflow ที่ขับเคลื่อนด้วย Task
SUMMARY: ใช้ task ของ Synapse เพื่อขับเคลื่อน workflow LLM หลายขั้นตอนที่อยู่รอดข้าม session
Workflow ที่ขับเคลื่อนด้วย Task
task ไม่ใช่แค่ todo — แต่เป็นกระดูกสันหลังของ workflow LLM ที่ถาวร โดยการสร้าง task สำหรับงานหลายขั้นตอน คุณรับประกัน continuity ข้าม session และให้ audit trail ของสิ่งที่ทำ
ทำไมต้อง Task-Driven?
ไม่มี task:
- LLM เริ่มแต่ละ session โดยไม่แน่ใจว่าจะทำอะไร
- งานหลายขั้นตอนถูกลืมกลางการปฏิบัติ
- ไม่มี record ของสิ่งที่ทำ
มี task:
- LLM ทำ task ที่กำลังดำเนินการต่อทันที
- งานหลายขั้นตอนอยู่รอดข้าม session
- audit trail ในตัวของงานทั้งหมด
รูปแบบ
[CODE BLOCK]
การ implement
ขั้นตอนที่ 1: สร้าง task สำหรับงานหลายขั้นตอน
[CODE BLOCK]
ขั้นตอนที่ 2: ติดตามความคืบหน้าใน description ของ task
[CODE BLOCK]
ขั้นตอนที่ 3: ทำต่อข้าม session
[CODE BLOCK]
ขั้นตอนที่ 4: ทำเสร็จและเก็บถาวร
[CODE BLOCK]
ตัวอย่างเต็ม: Deploy Workflow
[CODE BLOCK]
ลำดับชั้น Task
สำหรับงานซับซ้อน ใช้ความสัมพันธ์ parent-child task:
[CODE BLOCK]
ค้นหา sub-task:
[CODE BLOCK]
Workflow สถานะ
[CODE BLOCK]
Pending
task สร้างแล้วแต่ยังไม่เริ่ม ใช้สำหรับงานที่วางแผนไว้
In Progress
กำลังดำเนินการ อัปเดต description ด้วยความคืบหน้า
Done
เสร็จสิ้นสำเร็จ description ควรรวมสรุป
Cancelled
ถูกยกเลิก description ควรรวมเหตุผล
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
> - สร้าง task สำหรับงานหลายขั้นตอน — งานขั้นเดียวไม่ต้อง task
> - อัปเดต description ด้วยความคืบหน้า — เปิดใช้งานการทำต่อ
> - ใช้ priority สูงสำหรับงาน active — ปรากฏใน recall
> - ทำ task ให้เสร็จเมื่อเสร็จ — อย่าทิ้งไว้ inprogress
> - เก็บสรุปการเสร็จเป็น memory — อ้างอิงระยะยาว
รูปแบบทั่วไป
รูปแบบ: Bug Fix Workflow
[CODE BLOCK]
รูปแบบ: Research Workflow
[CODE BLOCK]
ขั้นตอนถัดไป
- Session Start Pattern
- Chat Polling Pattern
- Error Recovery
## หมวดหมู่: คำถามที่พบบ่อย
คำถามที่พบบ่อยและปัญหาทั่วไป
────────────────────────────────────────────────────────────
# คำถามที่พบบ่อยเกี่ยวกับ API
SUMMARY: คำถามทั่วไปเกี่ยวกับ Synapse API — auth, rate limit, การจัดการ error, การค้นพบ endpoint
คำถามที่พบบ่อยเกี่ยวกับ API
คำถามทั่วไปเกี่ยวกับ Synapse API
ฉันยืนยันตัวตนอย่างไร?
สองวิธี:
1. Mind Key (สำหรับ endpoint ข้อมูล):
2. JWT (สำหรับ endpoint บัญชี):
หรือผ่าน query parameter (จำกัด 60 req/min):
ดู Authentication
ความแตกต่างระหว่าง Mind Key และ JWT คืออะไร?
- Mind Key: tenant-scoped, ไม่หมดอายุ, สำหรับข้อมูล memory/chat/tasks
- JWT: user-scoped, หมดอายุ 7 วัน, สำหรับการจัดการบัญชี/mind
ดู Mind Key vs JWT
ทำไมฉันได้ 401 Unauthorized?
สาเหตุทั่วไป:
1. ขาด header
2. Mind Key ไม่ถูกต้อง (ตรวจว่าขึ้นต้นด้วย )
3. ใช้ JWT ในที่ที่ต้องใช้ Mind Key (หรือกลับกัน)
4. Mind Key ถูกเพิกถอน
วิธีแก้: ตรวจสอบ token ของคุณ ดู Authentication
ทำไมฉันได้ 404 Not Found?
คุณใช้ endpoint path ผิด Synapse มีเพียง path ที่แสดงใน
วิธีแก้: เรียก เพื่อดู path ที่ถูกต้องทั้งหมด อย่าเดา
ทำไมฉันได้ 429 Too Many Requests?
คุณใช้ auth ผ่าน query parameter ซึ่งจำกัดที่ 60/min
วิธีแก้: เปลี่ยนไปใช้ header (ไม่จำกัดอัตรา)
ดู Rate Limits
ฉันจะระบุ endpoint ทั้งหมดได้อย่างไร?
[CODE BLOCK]
ฉันจะหา endpoint ที่เหมาะสมได้อย่างไร?
1. ตรวจ สำหรับรายการ machine-readable
2. ตรวจ สำหรับ API docs แบบเต็ม
3. ดู สำหรับระบบเอกสาร
4. ใช้ สำหรับ OpenAPI 3.0 spec
ฉันใช้ GET แทน POST ได้ไหม?
POST endpoint บางตัวมี GET equivalent สำหรับเครื่องมือ URL-only:
- ↔
- ↔
- ↔
ตรวจ สำหรับ GET variant ที่มี
ฉันจัดการ error อย่างไร?
error ทั้งหมดส่งกลับเป็น JSON:
[CODE BLOCK]
ดู Errors & Error Handling
ขีดจำกัดขนาด request body คือเท่าไร?
10 MB สำหรับ payload ที่ใหญ่กว่า (เช่น อัปโหลดไฟล์) ให้ใช้ multipart endpoint
API รองรับ CORS ไหม?
ใช่ ทุก endpoint ส่งกลับ:
[CODE BLOCK]
มี SDK ไหม?
มี:
- Node.js:
- MCP:
ดูรายละเอียดที่ API Overview
ฉันทำ pagination อย่างไร?
ใช้ และ :
[CODE BLOCK]
Limit เริ่มต้น: 100 สูงสุด: 500
ฉันกรอง memory ตาม category หรือ tag ได้ไหม?
ได้:
[CODE BLOCK]
ฉันค้นหา memory อย่างไร?
สองวิธี:
1. FTS5 keyword search:
2. Semantic search:
ดู FTS5 Search และ Semantic Search
ฉันอัปเดต memory อย่างไร?
POST ด้วย + เดิม — memory ที่มีอยู่จะถูกอัปเดต ไม่ซ้ำ
[CODE BLOCK]
ฉันลบ memory อย่างไร?
[CODE BLOCK]
ลบเป็นจำนวนมากได้ไหม?
ได้:
[CODE BLOCK]
ขั้นตอนถัดไป
- API Overview
- Errors & Error Handling
- Authentication
────────────────────────────────────────────────────────────
# คำถามทั่วไป
SUMMARY: คำถามทั่วไปเกี่ยวกับ Synapse — คืออะไร, ทำงานอย่างไร, สำหรับใคร
คำถามทั่วไป
คำถามทั่วไปเกี่ยวกับ Synapse
Synapse คืออะไร?
Synapse เป็น persistent memory API สำหรับ LLM agent มอบสมองถาวรที่ query ได้ให้ AI assistant ของคุณซึ่งอยู่รอดข้าม session แทนที่จะลืมทุกอย่างเมื่อแช็ตปิด LLM เก็บและดึง memory ผ่าน HTTP API ที่เรียบง่าย
เรียนรู้เพิ่มเติม: Synapse คืออะไร?
Synapse สำหรับใคร?
- นักพัฒนา LLM agent ที่ต้องการ state ถาวร
- Power user ที่รัน local LLM พร้อม custom agent
- ทีม ที่สร้าง AI assistant พร้อม shared memory
- วิศวกร automation ที่เชื่อม LLM call ข้าม session
Synapse ฟรีไหม?
Synapse โฮสต์ที่ และฟรีสำหรับการใช้งานส่วนบุคคล สำหรับ self-host ดู repo
Synapse ต่างจาก ChatGPT Memory อย่างไร?
| คุณสมบัติ | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| Storage | เซิร์ฟเวอร์ OpenAI | เซิร์ฟเวอร์ของคุณ |
| API access | ไม่ | ใช่ (REST + MCP) |
| Multi-tenant | ไม่ | ใช่ (mind) |
| Custom category | ไม่ | ใช่ (8 category) |
| Full-text search | จำกัด | FTS5 + semantic |
| Self-hostable | ไม่ | ใช่ |
LLM ใดทำงานกับ Synapse ได้?
LLM ใดที่เรียก HTTP ได้หรือใช้ MCP:
- Claude (Anthropic) — ผ่าน MCP หรือ direct API
- GPT-4 / GPT-3.5 (OpenAI) — ผ่าน function calling + API
- Gemini (Google) — ผ่าน function calling + API
- Llama / Mistral (local) — ผ่าน custom integration
- LLM ใดก็ตามผ่าน Synapse MCP server
ฉันต้องโฮสต์ Synapse เองไหม?
ไม่ เวอร์ชันโฮสต์ที่ พร้อมใช้งานสาธารณะ self-host เป็นตัวเลือก (สำหรับ privacy, การปรับแต่ง หรือสภาพแวดล้อม air-gapped)
ฉันเก็บข้อมูลได้มากแค่ไหน?
ไม่มีขีดจำกัดแบบ hard บนเวอร์ชันโฮสต์ การใช้งานทั่วไป:
- 100-1000 memory ต่อ mind
- 1-10 KB ต่อ memory (ฟิลด์ content)
- รวม: 10 MB ต่อ mind
สำหรับสเกลใหญ่กว่า ให้ self-host
ข้อมูลของฉันเป็นส่วนตัวไหม?
ใช่ แต่ละ mind ถูกแยก (ดู Multi-Tenancy) ผู้ใช้อื่นไม่เห็นข้อมูลของคุณ ผู้ให้บริการโฮสต์ (Schäfer Services) มีสิทธิ์เข้าถึงแต่ไม่ดูข้อมูลผู้ใช้
เพื่อ privacy สูงสุด ให้ self-host
ฉัน export ข้อมูลได้ไหม?
ได้ ใช้ เพื่อ export memory ทั้งหมดเป็น JSON ดู Backup & Restore
ถ้าฉันสูญเสีย Mind Key จะเกิดอะไรขึ้น?
Mind Key แสดงเพียงครั้งเดียวตอนสร้าง หากสูญหาย:
1. ล็อกอินด้วย email/password เพื่อรับ JWT
2. สร้าง mind ใหม่ผ่าน
3. บันทึก Mind Key ใหม่
4. (ตัวเลือก) ลบ mind เก่าผ่าน
คุณไม่สามารถกู้คืน memory จาก mind ที่ key สูญหายได้
LLM agent หลายตัวแชร์ mind ได้ไหม?
ได้ agent ทั้งหมดที่ใช้ Mind Key เดียวกันจะแชร์ข้อมูล mind นั้น สำหรับการทำงานหลาย agent ประสานกัน ดู Multi-Agent Coordination
Synapse ทำงานออฟไลน์ได้ไหม?
ไม่ Synapse ต้องการการเชื่อมต่ออินเทอร์เน็ตไปยังเซิร์ฟเวอร์ (โฮสต์หรือ self-host) สำหรับ LLM ออฟไลน์ ให้รัน Synapse ในเครื่อง
การค้นหา memory เร็วแค่ไหน?
- FTS5 keyword search: < 10ms สำหรับ 1000 memory
- Semantic search: 50-100ms สำหรับ 1000 memory
- Full recall: < 50ms สำหรับ 1000 memory
ดูรายละเอียดที่ FTS5 Search
ฉันใช้ Synapse โดยไม่มี LLM ได้ไหม?
ได้ Synapse เป็น memory API ทั่วไป คุณสามารถใช้จากแอปใดก็ตามที่ได้ประโยชน์จาก key-value storage ที่ถาวร, ค้นหาได้ พร้อม category และ tag
ขั้นตอนถัดไป
- Synapse คืออะไร?
- Quick Start
- คำถามที่พบบ่อยเกี่ยวกับ API
────────────────────────────────────────────────────────────
# คำถามที่พบบ่อยเกี่ยวกับ MCP
SUMMARY: คำถามทั่วไปเกี่ยวกับการผสานรวม MCP — tool, transport, การแก้ปัญหา
คำถามที่พบบ่อยเกี่ยวกับ MCP
คำถามทั่วไปเกี่ยวกับ Synapse MCP server
MCP คืออะไร?
MCP (Model Context Protocol) เป็นมาตรฐานเปิดโดย Anthropic สำหรับการผสานรวม LLM-tool แทนที่จะวาง API docs ลงใน prompt คุณลงทะเบียน tool กับ MCP server และ LLM เรียกใช้เป็น native function
ดู MCP คืออะไร?
Synapse MCP เปิดเผย tool กี่ตัว?
79 tool ครอบคลุม 12 category: memory, chat, scheduler, tasks, scripts, computers, push, user, utility, visualization, sharing, webhooks, browser
ดูรายการเต็มที่ MCP คืออะไร?
MCP client ใดที่รองรับ?
- Claude Desktop (macOS, Windows)
- Claude Code (terminal)
- Cursor (IDE)
- Continue.dev (VS Code, JetBrains)
- Cline (VS Code)
- MCP client ใดก็ตามที่เข้ากันได้
ดูตัวอย่าง config ที่ Claude Desktop Setup
transport ใดที่รองรับ?
1. stdio (local, แนะนำสำหรับ desktop)
2. HTTP/SSE (remote, multi-tenant)
3. WebSocket (mobile, ปริมาณสูง)
ฉันกำหนดค่า Claude Desktop อย่างไร?
แก้ไข :
[CODE BLOCK]
ดู Claude Desktop Setup
ทำไม tool ไม่ปรากฏใน Claude Desktop?
1. รีสตาร์ท Claude Desktop ให้เต็มรูปแบบ (Cmd+Q บน macOS)
2. ตรวจสอบ config file เป็น JSON ที่ถูกต้อง
3. ตรวจสอบ Node.js 18+ ติดตั้ง
4. ตรวจสอบ MCP log:
ดู MCP Troubleshooting
ฉันใช้ mind อื่นได้อย่างไร?
เปลี่ยน ใน MCP config และรีสตาร์ท client
สำหรับหลาย mind ให้รัน MCP server instance หลายตัวด้วย Mind Key ต่างกัน
ฉันจำกัด tool ที่เปิดเผยได้ไหม?
ได้ ใช้ Tool Profile:
- : 8 composite tool (500 token)
- : 25 tool (2,500 token)
- : 119 tool (8,250 token, ค่าเริ่มต้น)
ตั้งผ่าน env var หรือ header
ฉัน debug ปัญหา MCP อย่างไร?
1. รัน MCP server ด้วยตนเอง:
2. ตรวจสอบ client log (แตกต่างกันตาม client)
3. ตรวจสอบ Mind Key ทำงาน:
4. ตรวจสอบสุขภาพ Synapse:
ดู MCP Troubleshooting
MCP server ฟรีไหม?
ใช่ npm package เป็น open source MCP server ที่โฮสต์ที่ ฟรีสำหรับใช้สาธารณะ
ฉัน self-host MCP server ได้ไหม?
ได้:
[CODE BLOCK]
MCP ต่างจาก direct API call อย่างไร?
| แง่มุม | Direct API | MCP |
|--------|-----------|-----|
| LLM ต้องรู้ | URL, header, auth | เพียงชื่อ tool |
| การจัดการ auth | ด้วยตนเอง | อัตโนมัติ (env var) |
| การค้นพบ tool | อ่าน /endpoints | อัตโนมัติผ่าน MCP protocol |
| การจัดการ error | ด้วยตนเอง | มาตรฐาน |
| เหมาะกับ | การผสานรวมแบบกำหนดเอง | LLM agent |
ฉันสร้าง MCP client ของตัวเองได้ไหม?
ได้ ใช้ MCP SDK อย่างเป็นทางการ:
- TypeScript:
- Python:
ดู Custom MCP Client
ฉันรายงาน bug MCP อย่างไร?
เปิด issue:
ระบุ:
- เวอร์ชัน MCP server
- ชื่อและเวอร์ชัน client
- ระบบปฏิบัติการ
- log ที่เกี่ยวข้อง
- ขั้นตอนการ reproduce
ขั้นตอนถัดไป
- MCP คืออะไร?
- Claude Desktop Setup
- MCP Troubleshooting
────────────────────────────────────────────────────────────
# คำถามที่พบบ่อยเกี่ยวกับการแก้ปัญหา
SUMMARY: วิธีแก้ปัญหา Synapse ทั่วไป — auth, เครือข่าย, ข้อมูล, deployment
คำถามที่พบบ่อยเกี่ยวกับการแก้ปัญหา
วิธีแก้ปัญหา Synapse ทั่วไป
ฉันล็อกอินไม่ได้
อาการ
- ส่งกลับ 401
- "Invalid email or password"
วิธีแก้
1. ตรวจสอบ email ถูกต้อง — sensitive ต่อตัวพิมพ์เล็ก/ใหญ่
2. ตรวจสอบรหัสผ่าน — ขั้นต่ำ 6 ตัวอักษร
3. สมัครก่อน หากคุณยังไม่มีบัญชี:
4. รีเซ็ตรหัสผ่าน (หากกำหนดค่า SMTP แล้ว) ผ่าน web UI
ฉันสูญเสีย Mind Key
อาการ
- เข้าถึง memory ไม่ได้
- Mind Key ถูกลบ/สูญหาย
วิธีแก้
Mind Key กู้คืนไม่ได้ คุณต้อง:
1. ล็อกอินเพื่อรับ JWT:
2. รายการ mind: (ด้วย JWT)
3. สร้าง mind ใหม่:
4. บันทึก Mind Key ใหม่
5. (ตัวเลือก) ลบ mind เก่า:
ข้อมูลใน mind เก่าสูญหาย เว้นแต่คุณหา Mind Key ได้
API call ส่งกลับ 401
อาการ
- API call ทั้งหมดส่งกลับ 401 Unauthorized
- "Mind Key fehlt oder ungültig"
วิธีแก้
1. ตรวจสอบรูปแบบ header:
2. ตรวจ Mind Key ขึ้นต้นด้วย (ไม่ใช่ ซึ่งเป็น JWT)
3. ทดสอบโดยตรง:
[CODE BLOCK]
4. Mind Key อาจถูกเพิกถอน — สร้าง mind ใหม่
ดู Authentication
API call ส่งกลับ 404
อาการ
- 404 Not Found
- "Route not found"
วิธีแก้
> [!CRITICAL]
> อย่าเดา endpoint path มีเพียง path ใน เท่านั้นที่มีอยู่
1. ตรวจสอบ endpoint ที่ถูกต้อง:
2. เปรียบเทียบ URL ตรงตัว — sensitive ต่อตัวพิมพ์เล็ก/ใหญ่, ไม่มี trailing slash
3. ตรวจสอบ HTTP method — กับ ต่างกัน
API call ส่งกลับ 429
อาการ
- 429 Too Many Requests
- "Rate limit exceeded"
วิธีแก้
1. เปลี่ยนไปใช้ header auth (ไม่จำกัดอัตรา):
[CODE BLOCK]
2. รอ วินาที หากต้องใช้
ดู Rate Limits
การค้นหา memory ส่งกลับไม่มีผลลัพธ์
อาการ
- ส่งกลับว่าง
- รู้ว่ามี memory อยู่
วิธีแก้
1. ตรวจสอบ memory มีอยู่:
2. ตรวจสอบไวยากรณ์ search — FTS5 มีไวยากรณ์เฉพาะ
3. ลอง query ที่ง่ายกว่า — แทน
4. ใช้ semantic search สำหรับ query เชิงแนวคิด:
ดู FTS5 Search
memory ไม่คงอยู่
อาการ
- POST /memory ส่งกลับสำเร็จ
- GET /memory/recall ไม่แสดง memory เหล่านั้น
วิธีแก้
1. ตรวจสอบ Mind Key เดียวกัน — key ต่างกัน = mind ต่างกัน
2. ตรวจสอบ response — POST ส่งกลับ
3. ลอง GET /memory (รายการ JSON) แทน /memory/recall (text)
4. ตรวจสอบ filter — หรือ อาจซ่อนไว้
tool ไม่ปรากฏใน Claude Desktop
อาการ
- Claude Desktop แสดง 0 tool
- ไม่มีไอคอน 🔌
วิธีแก้
1. รีสตาร์ท Claude Desktop ให้เต็มรูปแบบ (Cmd+Q)
2. ตรวจสอบ config file เป็น JSON ที่ถูกต้อง
3. ตรวจ Node.js 18+ ติดตั้ง
4. รัน MCP ด้วยตนเอง:
5. ตรวจ log:
ดู MCP Troubleshooting
Synapse ออฟไลน์
อาการ
- เข้าถึง synapse.schaefer.zone ไม่ได้
- curl หมดเวลา
วิธีแก้
1. ตรวจสอบอินเทอร์เน็ต — ลองเว็บไซต์อื่น
2. ตรวจสอบสุขภาพ Synapse:
3. รอ — อาจเป็น outage ชั่วคราวหรือ deployment
4. ตรวจสอบหน้าสถานะ (หากมี)
สำหรับ self-host: ตรวจสอบสถานะ Docker container, การเชื่อมต่อฐานข้อมูล
ข้อผิดพลาดฐานข้อมูล
อาการ
- 500 Internal Server Error
- "Database connection failed"
วิธีแก้
สำหรับ self-host:
1. ตรวจ PostgreSQL รันอยู่:
2. ตรวจ DATABASEURL ใน env
3. ตรวจ migration:
4. ตรวจพื้นที่ดิสก์:
สำหรับโฮสต์: รายงานไปยัง support
Webhook ไม่ทำงาน
อาการ
- ลงทะเบียน webhook แล้วแต่ไม่ได้รับ callback
- ไม่มี POST ไปยัง URL ของคุณ
วิธีแก้
1. ตรวจสอบ URL เข้าถึงได้:
2. ตรวจสอบ filter event — ตรงทุก memory event
3. ทดสอบ webhook:
4. ตรวจ webhook เปิดใช้งาน:
5. ตรวจสอบ SSL — Synapse ต้องการ HTTPS ที่ถูกต้องสำหรับ webhook URL
ดู Webhooks API
Cron job ไม่รัน
อาการ
- สร้าง cron job แล้วแต่ไม่ทำงาน
- ไม่อัปเดต
วิธีแก้
1. ตรวจไวยากรณ์ schedule — ต้องเป็น 5-field cron หรือ integer วินาที
2. ตรวจ endpoint ได้รับอนุญาต — ต้องเป็น http(s), ไม่มี private IP
3. ตรวจ job เปิดใช้งาน:
4. รอเวลาที่ตั้งเวลาไว้ถัดไป — cron ไม่ใช่ทันที
ดู Cron & Scheduler
ต้องการความช่วยเหลือเพิ่มเติม?
1. ตรวจเอกสารที่มี:
2. ค้นหาเอกสาร:
3. เปิด issue:
4. ติดต่อ: ดูหน้า
ขั้นตอนถัดไป
- Errors & Error Handling
- คำถามที่พบบ่อยเกี่ยวกับ API
- MCP Troubleshooting