# DOKUMENTASI SYNAPSE — Referensi lengkap
# Dibuat: 2026-07-18T04:12:25.924Z
# Total artikel: 47
Dokumen ini berisi dokumentasi API Synapse yang lengkap.
Base URL: https://synapse.schaefer.zone
Language: id
========================================================================
## KATEGORI: MEMULAI
Semua yang Anda butuhkan untuk memulai dengan Synapse.
────────────────────────────────────────────────────────────
# Autentikasi & Mind Keys
SUMMARY: Bagaimana autentikasi Synapse bekerja: Mind Keys untuk agen, JWT untuk manusia, ?key= untuk alat yang hanya menggunakan URL.
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.
Autentikasi & Mind Keys
Synapse menggunakan dua metode autentikasi, masing-masing dioptimalkan untuk
kasus penggunaan yang berbeda. Memahami perbedaannya sangat penting untuk
membangun integrasi yang andal.
Dua Metode Autentikasi
| Metode | Kasus Penggunaan | Rate Limit | Kedaluwarsa |
|--------|----------|------------|--------|
| Mind Key | Agen LLM, alat otomatis | Tidak ada (header) / 60 min (query) | Tidak pernah |
| JWT | UI untuk manusia, operasi akun | Tidak ada | 7 hari |
Mind Key (untuk Agen)
Mind Key adalah token API dengan cakupan tenant. Token ini mengautentikasi data
satu mind (memori, tugas, chat, skrip, dll.). Gunakan untuk:
- Agen LLM yang memanggil API
- Skrip otomasi latar belakang
- Konfigurasi MCP server
- Integrasi berumur panjang apa pun
Autentikasi header (disarankan)
[CODE BLOCK]
Parameter query (untuk alat yang hanya menggunakan URL)
[CODE BLOCK]
> [!WARNING]
> Parameter query di-rate-limit ke 60 permintaan per menit.
> Header Bearer tidak memiliki rate limit. Gunakan header kapan pun klien Anda
> mendukung header khusus.
Membuat Mind Key
[CODE BLOCK]
Respons menyertakan — simpan segera, hanya ditampilkan sekali.
Mendaftar mind Anda
[CODE BLOCK]
Menghapus mind (ireversibel!)
[CODE BLOCK]
JWT (untuk Manusia)
JWT mengautentikasi akun pengguna, bukan mind spesifik. Gunakan untuk:
- Pendaftaran dan login akun
- Membuat / mendaftar / menghapus mind
- Berbagi mind dengan pengguna lain
- Manajemen langganan Web Push
Daftar
[CODE BLOCK]
Mengembalikan:
Login
[CODE BLOCK]
Mengembalikan:
Kedaluwarsa JWT
JWT kedaluwarsa setelah 7 hari. Saat JWT kedaluwarsa, cukup panggil
lagi untuk mendapatkan yang baru. Mind Key tidak pernah kedaluwarsa, sehingga
integrasi agen yang ada tetap berfungsi.
Praktik Terbaik Keamanan
> [!CRITICAL]
> - Jangan pernah commit Mind Key ke git. Gunakan variabel lingkungan.
> - Jangan pernah mencatat Mind Key. Mask di log ().
> - Rotasi key jika Anda mencurigai kebocoran (hapus mind, buat yang baru).
> - Gunakan satu mind per proyek untuk membatasi dampak jika key bocor.
Pola variabel lingkungan
[CODE BLOCK]
[CODE BLOCK]
Konfigurasi MCP server
[CODE BLOCK]
Pola Multi-Mind
Setiap pengguna dapat memiliki beberapa mind. Pola umum:
| Nama Mind | Tujuan |
|-----------|---------|
| | Memori terkait pekerjaan |
| | Preferensi pribadi, keluarga |
| | Konteks proyek spesifik |
| | Kemajuan belajar |
| | Fallback tujuan umum |
Gunakan Mind Key yang berbeda untuk sesi LLM yang berbeda untuk menjaga konteks tetap terisolasi.
Rate Limits
| Metode Auth | Batas | Cakupan |
|-------------|-------|-------|
| Mind Key (header) | Tidak ada | Per-mind |
| Mind Key (?key=) | 60/min | Per-IP |
| JWT (header) | Tidak ada | Per-user |
| Endpoint publik | Tidak ada | Global |
Header rate limit (, , )
disertakan dalam respons jika berlaku.
Langkah Berikutnya
- Mind Key vs JWT — kapan menggunakan yang mana
- Memory API — apa yang dapat Anda lakukan dengan Mind Key
- User API — manajemen akun dengan JWT
────────────────────────────────────────────────────────────
# Mind Key vs JWT — Kapan Menggunakan?
SUMMARY: Panduan keputusan: Mind Key untuk akses data agen, JWT untuk manajemen akun.
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 — Kapan Menggunakan?
Synapse memiliki dua token autentikasi. Memilih yang salah menyebabkan error 401.
Panduan ini memberikan kerangka keputusan yang jelas.
Tabel Keputusan Cepat
| Anda ingin... | Gunakan |
|----------------|-----|
| Menyimpan / recall memori | Mind Key |
| Mengirim / polling pesan chat | Mind Key |
| Mengelola tugas | Mind Key |
| Menyimpan skrip | Mind Key |
| Mendaftarkan webhook | Mind Key |
| Mengontrol komputer | Mind Key (sisi pengguna) / Computer Token (sisi agen) |
| Mendaftarkan akun pengguna | Tidak ada (publik) |
| Login | Tidak ada (publik) |
| Membuat / mendaftar / menghapus mind | JWT |
| Berbagi mind dengan pengguna lain | JWT |
| Berlangganan notifikasi web push | JWT |
| Melihat log audit | Mind Key |
Aturan Sederhana
> [!TIP]
> Jika menyentuh data satu mind → Mind Key.
> Jika mengelola akun atau metadata mind → JWT.
Mind Key — Token Akses Data
Mind Key memberikan akses ke data satu mind. Token berumur panjang yang
tidak pernah kedaluwarsa (sampai mind dihapus). Sempurna untuk:
- Agen LLM yang menyimpan memori lintas sesi
- Cron job latar belakang
- Konfigurasi MCP server
- Integrasi webhook
- Aplikasi mobile yang membaca memori
Apa yang dapat dilakukan Mind Key
- — membaca semua memori dalam mind ini
- — menyimpan/memperbarui memori
- — membaca pesan chat
- — mengirim pesan chat
- — mendaftar tugas
- — membuat tugas
- — menyimpan skrip
- — mendaftarkan webhook
- — mengantri perintah komputer
Apa yang TIDAK dapat dilakukan Mind Key
- Membuat / mendaftar / menghapus mind (memerlukan JWT)
- Berbagi mind dengan pengguna lain (memerlukan JWT)
- Melihat info akun pengguna (memerlukan JWT)
- Berlangganan web push (memerlukan JWT)
JWT — Token Manajemen Akun
JWT mengautentikasi akun pengguna. Kedaluwarsa setelah 7 hari dan digunakan
untuk operasi level akun yang mencakup beberapa mind atau melibatkan pengguna lain.
Apa yang dapat dilakukan JWT
- — membuat mind baru (mengembalikan Mind Key baru)
- — mendaftar semua mind untuk pengguna ini
- — menghapus mind
- — berbagi mind dengan pengguna lain
- — berlangganan notifikasi web push
- — mendaftar berbagi mind
Apa yang TIDAK dapat dilakukan JWT
- Membaca / menulis memori (memerlukan Mind Key)
- Mengirim pesan chat (memerlukan Mind Key)
- Mengelola tugas (memerlukan Mind Key)
- Mendaftarkan webhook (memerlukan Mind Key)
Kasus Khusus: Computer Token
Endpoint (sisi agen, untuk screen-remote-agent)
menggunakan tipe token ketiga: Computer Token. Token ini dikembalikan oleh
saat menukar kode instalasi, dan spesifik untuk
satu komputer terdaftar.
| Endpoint | Auth |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key atau JWT |
| | Mind Key atau JWT |
Pola Umum
Pola 1: Agen LLM Tunggal
1. Daftar sekali → dapatkan JWT
2. Buat satu mind → dapatkan Mind Key
3. LLM menggunakan Mind Key untuk semuanya
Pola 2: Agen Multi-Proyek
1. Daftar sekali → dapatkan JWT
2. Buat beberapa mind (kerja, pribadi, proyek-x) → dapatkan beberapa Mind Key
3. LLM memuat Mind Key berbeda berdasarkan konteks
Pola 3: Berbagi Tim
1. Pengguna A membuat mind → dapatkan Mind Key A
2. Pengguna A berbagi dengan Pengguna B melalui JWT ()
3. Pengguna B sekarang dapat mengakses melalui JWT mereka sendiri
4. Untuk akses LLM, Pengguna B perlu membuat Mind Key mereka sendiri (atau menggunakan milik A)
Pola 4: MCP Server
MCP server selalu menggunakan Mind Key (diatur melalui env var ). Satu instansi
MCP server = satu mind. Untuk akses multi-mind, jalankan beberapa instansi MCP
atau implementasikan peralihan mind sisi klien.
Lembar Contoh Format Token
| Token | Format | Contoh |
|-------|--------|---------|
| Mind Key | + 36 karakter | |
| JWT | + base64 | |
| Computer Token | + 36 karakter | |
Langkah Berikutnya
- Autentikasi — panduan autentikasi lengkap
- User & Minds API — endpoint yang dilindungi JWT
- Memory API — endpoint yang dilindungi Mind Key
────────────────────────────────────────────────────────────
# Quick Start untuk Agen LLM
SUMMARY: Dalam 3 panggilan API: recall semua memori, simpan yang baru, cari. Alur kerja LLM esensial.
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 untuk Agen LLM
Anda kehilangan semua memori antar sesi. Synapse adalah otak eksternal Anda.
Panduan ini menunjukkan tiga panggilan API esensial yang harus diketahui setiap agen LLM.
> [!CRITICAL]
> Panggil di AWAL setiap sesi.
> Tanpa panggilan ini, Anda tidak memiliki memori tentang siapa pengguna, apa yang telah Anda janjikan,
> atau apa yang sedang Anda kerjakan terakhir kali.
Langkah 1: Recall Semua Memori (SELALU PERTAMA)
[CODE BLOCK]
Mengembalikan ringkasan teks polos terstruktur dari semua memori yang disimpan.
Parse ini untuk membangun kembali model mental Anda tentang pengguna, proyek
mereka, dan interaksi masa lalu.
Contoh respons:
[CODE BLOCK]
Langkah 2: Simpan Memori Baru
Saat Anda mempelajari sesuatu yang patut diingat:
[CODE BLOCK]
Kategori: , , , , , , , ,
Prioritas: , , ,
> [!TIP]
> Selalu sertakan field — identifier pendek untuk memori. Ini memungkinkan Anda
> memperbarui memori yang sama nanti dengan POST ulang dengan key yang sama.
Langkah 3: Cari Memori Spesifik
[CODE BLOCK]
> [!TIP]
> Sintaks FTS5: beberapa kata = pencarian AND. Frasa dalam tanda kutip: .
> Pencarian prefix: . Boolean: .
Alat Terbuka (Tanpa Header Auth)
Jika alat Anda hanya dapat membuka URL (tanpa header khusus), gunakan parameter :
[CODE BLOCK]
> [!WARNING]
> di-rate-limit ke 60 permintaan/menit. Header Bearer tidak memiliki rate limit.
> Gunakan header Bearer kapan pun memungkinkan.
Alur Kerja Sesi Lengkap
1. Awal sesi: — muat semua memori
2. Selama bekerja: — temukan fakta spesifik
3. Saat info baru: — simpan (dengan kategori, key, tag, prioritas)
4. Secara berkala: — periksa pesan manusia
5. Akhir sesi: Simpan pembelajaran akhir melalui
Pola Umum
Perbarui memori yang ada
POST dengan dan yang sama — memori yang ada
diperbarui, tidak diduplikasi.
Simpan status proyek
[CODE BLOCK]
Catat kesalahan (agar tidak mengulangi)
[CODE BLOCK]
Periksa pesan manusia
[CODE BLOCK]
Mengembalikan pesan belum dibaca dari manusia. Balas dengan:
[CODE BLOCK]
Langkah Berikutnya
- Autentikasi — Mind Key vs JWT
- Referensi Memory API — semua 22 endpoint memori
- Chat API — komunikasi asinkron dengan manusia
- LLM Cookbook — pola praktis
────────────────────────────────────────────────────────────
# Quick Start (Manusia)
SUMMARY: Daftarkan akun, buat mind pertama Anda, simpan memori — semua dalam 5 menit.
Quick Start (Manusia)
Panduan ini memandu Anda mendapatkan akun Synapse, Mind Key pertama Anda,
dan menyimpan memori pertama Anda. Total waktu: 5 menit.
Langkah 1: Daftarkan Akun
Buka Synapse API dan buat akun:
[CODE BLOCK]
Respons:
[CODE BLOCK]
> [!TIP]
> Simpan JWT di tempat yang aman — Anda akan memerlukannya untuk membuat mind. JWT kedaluwarsa
> setelah 7 hari; login ulang dengan endpoint yang sama untuk menyegarkan.
Langkah 2: Buat Mind Pertama Anda
"Mind" adalah cakupan memori terisolasi. Sebagian besar pengguna memulai dengan
satu mind, tetapi Anda dapat memiliki beberapa (mis. "kerja", "pribadi",
"proyek-x"). Setiap mind memiliki Mind Key uniknya sendiri.
[CODE BLOCK]
Respons:
[CODE BLOCK]
> [!CRITICAL]
> Simpan segera. Hanya ditampilkan sekali dan tidak dapat
> diambil kemudian. Jika Anda kehilangannya, Anda harus membuat mind baru.
Langkah 3: Simpan Memori Pertama Anda
Sekarang gunakan Mind Key untuk menyimpan memori:
[CODE BLOCK]
Respons:
[CODE BLOCK]
Langkah 4: Recall Semua Memori
Untuk mengambil semua yang telah Anda simpan:
[CODE BLOCK]
Respons (teks polos, dioptimalkan untuk konsumsi LLM):
[CODE BLOCK]
Langkah 5: Cari Memori
Temukan memori spesifik berdasarkan kata kunci:
[CODE BLOCK]
Langkah 6: Hubungkan LLM Anda
Cara termudah untuk memberikan LLM Anda akses ke Synapse adalah melalui MCP:
- Pengaturan Claude Desktop — konfigurasi 2 menit
- Pengaturan Claude Code — integrasi terminal
- Pengaturan Cursor — integrasi IDE
Setelah pengaturan, LLM Anda akan otomatis memanggil di awal
setiap sesi dan menyimpan fakta baru melalui .
Kategori Memori
Synapse mendukung 8 kategori — pilih yang paling spesifik:
| Kategori | Kasus Penggunaan |
|----------|----------|
| | Nama pengguna, peran, info kontak |
| | Suka, tidak suka, gaya kerja |
| | Fakta yang dapat diverifikasi (detail proyek, tanggal) |
| | Status proyek, milestone, todo |
| | Hal-hal yang dikuasai pengguna |
| | Error masa lalu — hindari pengulangan |
| | Konteks yang relevan dengan sesi |
| | Catatan lain-lain |
Level Prioritas
- — bagus untuk diketahui
- — default
- — penting
- — tidak boleh dilupakan (identitas pengguna, info hukum)
Langkah Berikutnya
- Pelajari autentikasi lebih dalam
- Mind Key vs JWT
- Referensi Memory API
- Integrasi MCP
────────────────────────────────────────────────────────────
# Apa itu Synapse?
SUMMARY: Synapse adalah API memori persisten untuk agen LLM — AI Anda tidak pernah lupa lintas sesi.
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.)
Apa itu Synapse?
Synapse adalah API memori persisten untuk agen LLM. API ini memecahkan
masalah fundamental setiap LLM berbasis chat: antar sesi, agen melupakan semuanya.
Synapse memberikan AI Anda otak permanen yang dapat dikueri yang bertahan lintas
percakapan, lintas hari, dan lintas provider LLM berbeda.
> [!CRITICAL]
> Jika Anda adalah agen LLM yang membaca ini: panggil di awal
> setiap sesi. Tanpa panggilan ini, Anda tidak memiliki memori interaksi masa lalu,
> tidak ada pengetahuan tentang siapa pengguna, dan tidak ada konteks tentang proyek yang sedang berjalan.
Masalah yang Diselesaikan Synapse
Setiap LLM modern (Claude, GPT, Gemini, Llama) memiliki keterbatasan arsitektur
yang sama: jendela konteks percakapan terbatas, dan setelah sesi berakhir, semua
state hilang. Ini berarti asisten AI Anda:
- Melupakan nama, preferensi, dan proyek yang sedang berjalan antar chat
- Tidak dapat belajar dari kesalahan masa lalu lintas sesi
- Tidak memiliki kontinuitas untuk pekerjaan jangka panjang
- Bertanya pertanyaan klarifikasi yang sama setiap kali
Synapse memperbaiki ini dengan menyediakan HTTP API sederhana di mana LLM dapat
menyimpan dan mengambil memori terstruktur. Memori bertahan di server, diindeks
dan dapat dicari, sehingga sesi mendatang dapat recall.
Fitur Utama
- Penyimpanan memori persisten — fakta, preferensi, proyek, kesalahan, keahlian
- Pencarian teks penuh (FTS5) — temukan memori apa pun berdasarkan kata kunci dalam milidetik
- Pencarian semantik — pencarian kesamaan berbasis embeddings untuk kueri konseptual
- Multi-tenant — setiap pengguna memiliki "minds" yang terisolasi (satu pengguna, banyak proyek)
- Chat asinkron — manusia dapat meninggalkan pesan untuk agen saat bekerja
- Tugas & penjadwalan — manajer tugas bawaan dan cron scheduler
- Integrasi MCP — 79 alat diekspos sebagai Model Context Protocol untuk Claude, Cursor, Continue
- Kontrol browser & komputer — alat otomasi remote
- Webhooks — dapatkan HTTP callback pada perubahan memori/chat/tugas
Cara Kerja
[CODE BLOCK]
1. LLM memanggil di awal sesi
2. Synapse mengembalikan ringkasan teks terstruktur dari semua memori yang disimpan
3. LLM bekerja, secara berkala memanggil untuk menyimpan fakta baru
4. Saat pengguna bertanya, LLM dapat memanggil
5. Di akhir sesi, konteks baru yang penting disimpan untuk sesi berikutnya
Untuk Siapa?
- Pengembang agen LLM yang membutuhkan state persisten
- Power user yang menjalankan LLM lokal (Ollama, LM Studio) dengan agen khusus
- Tim yang membangun asisten AI yang membutuhkan memori bersama
- Insinyur otomasi yang merangkai pemanggilan LLM lintas sesi
Perbandingan Cepat
| Fitur | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| Lokasi penyimpanan | Server OpenAI | Server Anda |
| Akses API | Tidak (tertutup) | Ya (REST + MCP) |
| Multi-tenant | Tidak | Ya (minds) |
| Kategori khusus | Tidak | Ya (8 kategori) |
| Pencarian | Terbatas | FTS5 + semantik |
| Dapat di-self-host | Tidak | Ya (Docker) |
Langkah Berikutnya
- Quick Start untuk manusia — dapatkan Mind Key dalam 5 menit
- Quick Start untuk LLM — panggilan API pertama
- Autentikasi — Mind Keys vs JWTs
- Ikhtisar arsitektur — bagaimana Synapse dibangun
## KATEGORI: REFERENSI API
Referensi lengkap untuk setiap endpoint API.
────────────────────────────────────────────────────────────
# Browser Proxy
SUMMARY: Layanan otomasi browser — container Docker terpisah pada port 13000 untuk kontrol browser headless.
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 adalah layanan Docker terpisah yang menyediakan otomasi
browser headless melalui Playwright. Layanan ini BUKAN bagian langsung dari API
Synapse — endpoint Synapse tidak menyertakan path .
Arsitektur
[CODE BLOCK]
Metode Akses
Metode 1: Melalui Synapse MCP Server (disarankan)
Synapse MCP server mengekspos alat browser sebagai alat MCP. Gunakan ini untuk
otomasi browser berbasis LLM:
[CODE BLOCK]
Alat browser MCP yang tersedia:
- — membuka tab browser baru
- — menavigasi ke URL
- — mengklik elemen
- — mengetik teks ke dalam field
- — menangkap tangkapan layar
- — menutup tab
- (dan lainnya — lihat Integrasi MCP)
Metode 2: Akses Browser Proxy Langsung
Untuk integrasi non-MCP, hubungkan langsung ke layanan browser-proxy:
[CODE BLOCK]
Kasus Penggunaan Umum
Web scraping
[CODE BLOCK]
Otomasi form
[CODE BLOCK]
Tangkapan tangkapan layar
[CODE BLOCK]
Layanan Terkait
| Layanan | Port | Tujuan |
|---------|------|---------|
| Synapse API | 12800 | Memori, chat, tugas |
| Synapse MCP | 13100 | MCP server (79 alat) |
| Browser Proxy | 13000 | Otomasi browser headless |
| SSH Proxy | 12900 | Akses SSH ke mesin remote |
Langkah Berikutnya
- Integrasi MCP — cara menggunakan alat browser via MCP
- Computer Control API — untuk otomasi GUI pada mesin terdaftar
────────────────────────────────────────────────────────────
# Chat API
SUMMARY: Chat asinkron antara manusia dan agen LLM — polling, balas, riwayat, jumlah belum dibaca, unggah file.
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 memungkinkan pesan asinkron antara manusia dan agen LLM.
Berbeda dengan chat sinkron (gaya ChatGPT), manusia dapat meninggalkan pesan
saat agen sedang bekerja — agen melakukan polling di antara pemanggilan alat.
Cara Kerja
[CODE BLOCK]
1. Manusia mengirim pesan melalui web UI (menggunakan JWT)
2. Pesan disimpan, ditandai sebagai belum dibaca
3. Agen melakukan polling di antara pemanggilan alat
4. Polling mengembalikan semua pesan belum dibaca dan menandainya sebagai sudah dibaca
5. Agen memproses pesan, secara opsional membalas melalui
Endpoint
GET /chat/poll
Polling pesan baru dari manusia. Mengembalikan pesan belum dibaca dan
menandainya sebagai sudah dibaca. Gunakan ini di antara pemanggilan alat.
[CODE BLOCK]
Respons:
[CODE BLOCK]
POST /chat/reply
Mengirim pesan sebagai agen.
[CODE BLOCK]
POST /chat/send
Mengirim pesan sebagai manusia (memerlukan JWT, bukan Mind Key).
[CODE BLOCK]
GET /chat/history
Mengambil riwayat chat terbaru (kedua peran).
[CODE BLOCK]
GET /chat/unread
Mengambil jumlah pesan belum dibaca.
[CODE BLOCK]
GET /chat/status
Mengambil status sesi chat (timestamp pesan terakhir, jumlah belum dibaca).
[CODE BLOCK]
POST /chat/upload
Mengunggah lampiran file untuk pesan tertentu (form multipart).
[CODE BLOCK]
GET /chat/files/:messageid
Mendaftar lampiran file untuk sebuah pesan.
[CODE BLOCK]
GET /chat/file/:fileid
Mengunduh lampiran file.
[CODE BLOCK]
Pola Polling
> [!TIP]
> Lakukan polling setiap 30-60 detik di antara pemanggilan alat. Jangan polling
> lebih sering dari itu — ini membuang kuota API dan tidak memberikan manfaat.
[CODE BLOCK]
Langkah Berikutnya
- Tasks API
- Pola Polling Chat
────────────────────────────────────────────────────────────
# Computer Control API
SUMMARY: Kontrol jarak jauh komputer terdaftar — antri perintah, ambil tangkapan layar, jalankan skrip pada mesin remote.
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 memungkinkan Anda mengendalikan komputer terdaftar dari
jarak jauh. Sebuah agen kecil () berjalan di mesin target,
melakukan polling untuk perintah, mengeksekusinya, dan mengirimkan hasil
kembali. Ini memungkinkan otomasi GUI berbasis LLM.
Arsitektur
[CODE BLOCK]
Endpoint Sisi Pengguna (Mind Key atau JWT)
GET /computers/list
Mendaftar semua komputer terdaftar.
[CODE BLOCK]
GET /computers/:id
Mengambil detail satu komputer.
[CODE BLOCK]
POST /computers/install-code
Membuat kode instalasi untuk mendaftarkan komputer baru.
[CODE BLOCK]
Respons:
POST /computers/:id/commands
Mengantri perintah untuk dijalankan oleh agen remote.
[CODE BLOCK]
Respons:
GET /computers/:id/command (via query)
Mengantri perintah melalui GET (untuk kasus sederhana).
[CODE BLOCK]
GET /computers/:id/commands
Mendaftar perintah terbaru untuk sebuah komputer.
[CODE BLOCK]
GET /computers/:id/commands/:cid
Mengambil status + hasil perintah tertentu.
[CODE BLOCK]
GET /computers/:id/screenshot
One-shot: mengantri perintah tangkapan layar dan menunggu hingga 30 detik untuk hasilnya.
[CODE BLOCK]
POST /computers/:id/disable
Menonaktifkan komputer (mencabut tokennya, menyimpan catatan untuk audit).
[CODE BLOCK]
DELETE /computers/:id
Menghapus komputer secara permanen.
[CODE BLOCK]
Endpoint Sisi Agen (Computer Token)
Endpoint ini digunakan oleh yang berjalan di mesin target.
Endpoint menggunakan Computer Token (dikembalikan oleh ),
bukan Mind Key.
POST /computers/register
Menukar kode instalasi dan mendapatkan Computer Token.
[CODE BLOCK]
Respons:
> [!CRITICAL]
> Simpan — token ini hanya ditampilkan sekali dan diperlukan
> untuk semua endpoint sisi agen.
GET /computers/me/poll
Long-poll untuk perintah baru. Agen memanggil ini dalam loop.
[CODE BLOCK]
Mengembalikan langsung jika ada perintah tertunda, atau setelah detik jika tidak ada.
POST /computers/me/commands/:cid/result
Mengirim hasil eksekusi perintah.
[CODE BLOCK]
Tipe Perintah
| Tipe | Payload | Deskripsi |
|------|---------|-------------|
| | | Menangkap layar sebagai PNG (base64) |
| | | Mengklik pada koordinat |
| | | Memindahkan mouse ke koordinat |
| | | Mengetik teks pada kursor |
| | | Menekan kombinasi tombol |
| | | Scroll wheel |
| | | Drag and drop |
Pola Umum: Otomasi GUI Berbasis LLM
[CODE BLOCK]
Langkah Berikutnya
- Browser Proxy — layanan terpisah untuk otomasi browser
- Panduan Self-Hosted Agents
────────────────────────────────────────────────────────────
# Cron & Scheduler
SUMMARY: Jadwalkan pemanggilan API berulang — cron job yang berjalan sesuai jadwal, sempurna untuk sinkronisasi periodik dan pengingat.
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 memungkinkan Anda menjadwalkan pemanggilan HTTP berulang ke endpoint
Synapse (atau endpoint HTTPS eksternal). Sempurna untuk sinkronisasi periodik,
pengingat, dan tugas pemeliharaan.
Endpoint
POST /cron
Membuat tugas terjadwal.
[CODE BLOCK]
Respons:
[CODE BLOCK]
GET /cron
Mendaftar semua tugas terjadwal.
[CODE BLOCK]
DELETE /cron/:id
Menghapus tugas terjadwal.
[CODE BLOCK]
PUT /cron/:id/toggle
Mengaktifkan atau menonaktifkan tugas tanpa menghapusnya.
[CODE BLOCK]
Sintaks Jadwal
Cron standar (5 field)
[CODE BLOCK]
Contoh:
| Jadwal | Arti |
|----------|---------|
| | Setiap jam |
| | Setiap 15 menit |
| | Hari kerja pukul 9 pagi |
| | Setiap Minggu tengah malam |
| | Tanggal 1 setiap bulan tengah malam |
Interval bilangan bulat (detik)
Untuk interval sederhana, berikan bilangan bulat:
[CODE BLOCK]
Batasan Endpoint
> [!WARNING]
> Endpoint harus berupa URL atau yang menunjuk ke:
> - Instansi Synapse yang sama (mis. )
> - URL HTTPS publik (tanpa IP privat, tanpa localhost, tanpa IP metadata)
Ini mencegah serangan SSRF di mana mind yang terkompromi dapat menjadwalkan
permintaan ke layanan internal.
Pola Umum
Recall memori per jam (untuk agen LLM)
[CODE BLOCK]
Backup harian
[CODE BLOCK]
Polling chat periodik (setiap 5 menit)
[CODE BLOCK]
Pemicu laporan mingguan
[CODE BLOCK]
Langkah Berikutnya
- Variables API
- Webhooks API
────────────────────────────────────────────────────────────
# Errors & Error Handling
SUMMARY: Kode status HTTP, format respons error, dan cara memulihkan diri dari error umum.
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 menggunakan kode status HTTP standar dengan format respons error yang
konsisten. Halaman ini menjelaskan cara menafsirkan dan memulihkan diri dari
error.
Format Respons Error
Semua error mengembalikan JSON dengan struktur berikut:
[CODE BLOCK]
| Field | Deskripsi |
|-------|-------------|
| | Kode status HTTP |
| | Nama status HTTP |
| | Deskripsi error yang dapat dibaca manusia |
| | URL ke dokumentasi terkait (jika tersedia) |
Kode Status HTTP
200 OK
Berhasil. Permintaan diproses dengan benar.
201 Created
Berhasil. Sumber daya baru dibuat (mis. ).
204 No Content
Berhasil. Tidak ada body yang dikembalikan (mis. ).
400 Bad Request
Permintaan tidak valid. Penyebab umum:
- Field JSON yang wajib tidak ada
- Sintaks JSON tidak valid
- Nilai enum tidak valid (mis. kategori salah)
[CODE BLOCK]
Perbaikan: Periksa body permintaan terhadap dokumentasi API. Pastikan
semua field yang wajib ada dan memiliki nilai yang valid.
401 Unauthorized
Autentikasi gagal. Penyebab umum:
- Header tidak ada
- Mind Key atau JWT tidak valid
- Menggunakan Mind Key di mana JWT diperlukan (atau sebaliknya)
[CODE BLOCK]
Perbaikan: Verifikasi token Anda. Lihat Autentikasi.
403 Forbidden
Anda terautentikasi tetapi tidak diizinkan melakukan tindakan ini. Penyebab umum:
- Mencoba menghapus mind pengguna lain
- Mencoba memverifikasi memori dengan Mind Key (memerlukan JWT)
- Mind dinonaktifkan
Perbaikan: Periksa apakah Anda menggunakan tipe token yang benar untuk endpoint ini.
404 Not Found
Path atau sumber daya yang diminta tidak ada.
> [!CRITICAL]
> JANGAN menebak path endpoint. Hanya path yang tercantum di
> yang ada. Jika Anda mendapat 404, Anda menggunakan path yang salah.
[CODE BLOCK]
Perbaikan: Panggil untuk melihat daftar endpoint yang
valid. Bandingkan URL Anda dengan daftar tersebut karakter per karakter.
409 Conflict
Permintaan berkonflik dengan kondisi yang ada. Penyebab umum:
- Mencoba mendaftar dengan email yang sudah ada
- URL webhook duplikat
Perbaikan: Gunakan nilai yang berbeda, atau gunakan untuk memperbarui sumber daya yang ada.
429 Too Many Requests
Anda mencapai rate limit. Hanya berlaku untuk autentikasi parameter query (60/menit).
[CODE BLOCK]
Header respons:
[CODE BLOCK]
Perbaikan: Beralihlah ke header (tanpa rate limit),
atau tunggu detik.
500 Internal Server Error
Error server. Ini seharusnya tidak terjadi — jika terjadi, itu adalah bug.
Perbaikan:
1. Coba lagi dengan exponential backoff (1d, 2d, 4d, 8d)
2. Periksa untuk melihat apakah server aktif
3. Jika berkelanjutan, laporkan error tersebut
503 Service Unavailable
Server sementara tidak tersedia (mis. selama deployment, migrasi database).
Perbaikan: Tunggu dan coba lagi. Periksa .
Pola Pemulihan
Coba lagi dengan exponential backoff
[CODE BLOCK]
Penanganan error autentikasi
[CODE BLOCK]
Skenario Error Umum
"Mind Key fehlt oder ungültig"
- Anda lupa header
- Anda menggunakan tetapi key-nya salah
- Anda menggunakan JWT di mana Mind Key diperlukan
"Route not found"
- Anda menebak path yang tidak ada
- Anda menggunakan kata kerja yang salah (mis. vs )
- Periksa untuk path yang valid
"Rate limit exceeded"
- Anda menggunakan dan melebihi 60 req/menit
- Beralihlah ke header
Langkah Berikutnya
- Autentikasi
- Ikhtisar API
- Rate Limits
────────────────────────────────────────────────────────────
# Memory API
SUMMARY: Referensi lengkap untuk 22 endpoint memori: menyimpan, recall, pencarian, pencarian semantik, sinkronisasi, audit, dan lainnya.
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 adalah jantung Synapse. API ini menyediakan 22 endpoint untuk
menyimpan, mengambil, mencari, dan mengelola memori terstruktur. Semua endpoint
memerlukan Mind Key untuk autentikasi.
> [!CRITICAL]
> Selalu panggil di awal setiap sesi. Ini adalah
> satu-satunya cara untuk membangun kembali konteks dari sesi sebelumnya.
Kategori
Memori diorganisasi ke dalam 8 kategori:
| Kategori | Kasus Penggunaan |
|----------|----------|
| | Nama pengguna, peran, info kontak, preferensi tentang diri sendiri |
| | Suka, tidak suka, gaya kerja, preferensi komunikasi |
| | Fakta yang dapat diverifikasi (detail proyek, tanggal, URL) |
| | Status proyek, milestone, arsitektur |
| | Hal-hal yang dikuasai pengguna |
| | Error masa lalu — hindari pengulangan |
| | Konteks yang relevan dengan sesi |
| | Catatan lain-lain |
Prioritas
- — bagus untuk diketahui
- — default
- — penting
- — tidak boleh dilupakan (identitas pengguna, info hukum)
Endpoint Inti
GET /memory/recall
Mengembalikan SEMUA memori sebagai teks polos yang dioptimalkan untuk LLM. Panggil ini di setiap awal sesi.
[CODE BLOCK]
Respons (text/plain):
[CODE BLOCK]
POST /memory
Menyimpan memori baru atau memperbarui yang sudah ada (kategori + key yang sama = pembaruan).
[CODE BLOCK]
Respons:
GET /memory
Mendaftar memori dengan filter opsional.
[CODE BLOCK]
PUT /memory/:id
Memperbarui memori tertentu berdasarkan ID.
[CODE BLOCK]
DELETE /memory/:id
Menghapus satu memori.
[CODE BLOCK]
Endpoint Pencarian
GET /memory/search
Pencarian teks penuh menggunakan FTS5.
[CODE BLOCK]
Sintaks FTS5:
- Beberapa kata = AND:
- Frasa:
- Prefix:
- Boolean:
- Pengecualian:
GET /memory/semantic-search
Pencarian konseptual menggunakan embeddings (lebih lambat dari FTS5 tetapi memahami makna).
[CODE BLOCK]
Mengembalikan memori yang mirip secara semantik dengan kueri, meskipun tidak ada
kata kunci yang cocok. Berguna untuk "temukan memori tentang X" di mana X
dideskripsikan secara berbeda.
GET /memory/by-tag
Mendaftar memori berdasarkan tag.
[CODE BLOCK]
GET /memory/related/:id
Menemukan memori yang terkait dengan memori tertentu (melalui tag bersama).
[CODE BLOCK]
Sinkronisasi & Diff
GET /memory/diff
Sinkronisasi inkremental — mengembalikan memori yang berubah sejak timestamp tertentu.
[CODE BLOCK]
Respons:
POST /memory/sync
Menerapkan diff dari instansi lain (untuk sinkronisasi self-hosted).
[CODE BLOCK]
Operasi Massal
POST /memory/bulk-delete
Menghapus beberapa memori berdasarkan ID.
[CODE BLOCK]
POST /memory/embed-batch
Membuat embeddings untuk memori yang belum memilikinya (untuk pencarian semantik).
[CODE BLOCK]
GET /memory/embed-batch-status
Memeriksa kemajuan pembuatan embedding.
[CODE BLOCK]
Verifikasi
Memori memiliki flag . Memori yang disimpan agen defaultnya tidak
terverifikasi (); memori yang disimpan manusia terverifikasi
().
POST /memory/verify
Menandai memori sebagai terverifikasi (memerlukan JWT, bukan Mind Key).
[CODE BLOCK]
POST /memory/unverify
Menandai memori sebagai tidak terverifikasi (memerlukan JWT).
[CODE BLOCK]
GET /memory/unverified
Mendaftar memori yang menunggu verifikasi manusia.
[CODE BLOCK]
Statistik & Audit
GET /memory/stats
Statistik agregat untuk mind saat ini.
[CODE BLOCK]
Mengembalikan:
GET /memory/audit
Log audit dari semua operasi yang mengubah state.
[CODE BLOCK]
GET /memory/contradictions
Mendeteksi potensi kontradiksi dalam memori yang disimpan.
[CODE BLOCK]
GET /memory/expiring
Mendaftar memori dengan tanggal kedaluwarsa yang mendekat.
[CODE BLOCK]
Health & Export
GET /memory/health
Pemeriksaan health cepat untuk sistem memori.
[CODE BLOCK]
GET /memory/mind-export
Ekspor JSON lengkap dari semua memori (untuk backup).
[CODE BLOCK]
POST /memory/compact
Mengompak memori yang mirip (ringkasan otomatis).
[CODE BLOCK]
Langkah Berikutnya
- Quick Start untuk LLM
- Praktik Terbaik Memori
- Pencarian FTS5
- Pencarian Semantik
────────────────────────────────────────────────────────────
# Ikhtisar API & Base URL
SUMMARY: Semua endpoint API Synapse, base URL, pola autentikasi, dan format respons dalam sekali pandang.
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.
Ikhtisar API & Base URL
Synapse API adalah HTTP API yang RESTful. Semua endpoint mengembalikan JSON
(kecuali jika dicatat). Halaman ini mencakup hal-hal penting yang perlu Anda
ketahui sebelum mendalami endpoint tertentu.
Base URL
[CODE BLOCK]
Semua path dalam dokumentasi ini relatif terhadap base URL ini. Untuk instansi
self-hosted, ganti dengan URL Anda sendiri.
Autentikasi
Dua metode, keduanya dikirim melalui header :
[CODE BLOCK]
Atau melalui parameter query (rate-limited ke 60/menit):
[CODE BLOCK]
Lihat Autentikasi untuk detailnya.
Grup Endpoint
| Grup | Auth | Deskripsi |
|-------|------|-------------|
| Public | Tidak ada | Landing page, health, OpenAPI, docs |
| Memory | Mind Key | CRUD, pencarian, sinkronisasi, embeddings |
| Chat | Mind Key / JWT | Pesan asinkron antara manusia dan agen |
| Tasks | Mind Key | Manajemen tugas |
| Scripts | Mind Key / JWT | Penyimpanan skrip persisten |
| Scheduler | Mind Key | Cron jobs + variabel |
| Webhooks | Mind Key | HTTP callback pada event |
| Computers | Mind Key / JWT | Kontrol komputer remote |
| User/Minds | JWT | Akun + manajemen mind |
| Sharing | JWT | Berbagi mind antar pengguna |
| Push | JWT | Langganan Web Push |
| Tools | Tidak ada | Waktu, kalkulator, acak (utilitas publik) |
Format Respons
- JSON (default):
- Teks polos: mengembalikan teks yang dioptimalkan untuk LLM
- HTML: , , , ,
Amplop Respons Standar
Respons sukses mengembalikan data secara langsung:
[CODE BLOCK]
Respons error menggunakan format ini:
[CODE BLOCK]
> [!NOTE]
> Field menautkan ke dokumentasi terkait untuk error umum.
Kode Status HTTP
| Kode | Arti |
|------|---------|
| 200 | Sukses (GET, PUT) |
| 201 | Created (POST) |
| 204 | No content (DELETE) |
| 400 | Bad request (error validasi) |
| 401 | Unauthorized (token tidak ada/tidak valid) |
| 403 | Forbidden (tipe token salah) |
| 404 | Not found (path tidak ada) |
| 409 | Conflict (duplikat) |
| 429 | Too many requests (rate limit) |
| 500 | Server error |
Endpoint Discoverability
| Endpoint | Tujuan |
|----------|---------|
| | Landing page (dioptimalkan untuk LLM) |
| | Daftar yang dapat dibaca mesin dari semua endpoint |
| | Daftar endpoint teks polos |
| | Spesifikasi OpenAPI 3.0 |
| | Dokumentasi API lengkap (HTML) |
| | Dokumentasi API sebagai JSON |
| | Sistem dokumentasi (HTML) |
| | Indeks dokumentasi (JSON) |
| | Semua dokumentasi sebagai satu blok teks |
| | Playground API interaktif |
Rate Limits
| Metode Auth | Batas |
|-------------|-------|
| Mind Key (header) | Tidak ada |
| Mind Key (?key=) | 60/menit per IP |
| JWT (header) | Tidak ada |
| Endpoint publik | Tidak ada |
Respons yang di-rate-limit menyertakan:
[CODE BLOCK]
Paginasi
Endpoint daftar mendukung dan :
[CODE BLOCK]
Limit default: 100. Limit maksimum: 500.
CORS
Semua endpoint mendukung CORS untuk klien berbasis browser:
[CODE BLOCK]
SDK & Klien
- Node.js SDK: (repo)
- MCP Server: (repo)
- HTTP client: pustaka HTTP apa pun (curl, fetch, axios, dll.)
Langkah Berikutnya
- Memory API — endpoint terpenting
- Chat API — komunikasi asinkron manusia-agen
- Errors & Error Handling
────────────────────────────────────────────────────────────
# Rate Limits & Quotas
SUMMARY: Kebijakan rate limit untuk API Synapse — Bearer header (tidak terbatas), ?key= (60/menit), endpoint publik.
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 memiliki kebijakan rate limit yang sederhana dan dapat diprediksi,
dirancang untuk mencegah penyalahgunaan tanpa menghambat penggunaan yang sah.
Kebijakan Rate Limit
| Metode Auth | Batas | Cakupan |
|-------------|-------|-------|
| Mind Key () | Tidak ada | Per-mind |
| Mind Key () | 60 req/menit | Per-IP |
| JWT () | Tidak ada | Per-user |
| Endpoint publik | Tidak ada | Global |
> [!TIP]
> Selalu gunakan header bila memungkinkan. Header ini
> tidak memiliki rate limit. Gunakan hanya untuk alat yang tidak dapat
> mengatur header khusus.
Header Rate Limit
Saat Anda menggunakan autentikasi , respons menyertakan header rate limit:
[CODE BLOCK]
Saat Anda melebihi batas:
[CODE BLOCK]
Saat Anda Mengenai Rate Limit
Jika Anda mendapat 429:
1. Beralih ke header Authorization (disarankan):
[CODE BLOCK]
2. Atau tunggu detik lalu coba lagi.
Mengapa Batas ?key= Ada
Parameter query nyaman untuk alat yang hanya menggunakan URL (browser,
perintah ), tetapi memiliki implikasi keamanan dan performa:
- Keamanan: Parameter query dicatat dalam log akses server, riwayat
browser, dan header Referer. Membatasi penggunaan mengurangi paparan.
- Performa: Autentikasi parameter query memerlukan rate limiter berbasis IP
(pencarian Redis per permintaan), yang menambah latensi. Autentikasi header
melewati ini.
- Pencegahan penyalahgunaan: URL yang bocor dapat dibagikan dan
dibombardir. Batas IP membatasi dampak.
Pola yang Disarankan
Agen LLM
[CODE BLOCK]
Alat berbasis browser
Jika alat Anda hanya dapat membuka URL:
[CODE BLOCK]
MCP server
MCP server selalu menggunakan autentikasi header melalui env var
— tidak ada rate limit yang berlaku.
Impor massal
Untuk operasi massal (mis. mengimpor 1000 memori), selalu gunakan autentikasi
header. Impor massal melalui akan mengenai rate limit dalam 1 menit.
Quota (Level Mind)
Saat ini tidak ada kuota per-mind untuk ukuran penyimpanan atau jumlah memori.
Semua batas ada di level auth/IP, bukan level data. Ini mungkin berubah di
masa depan untuk keadilan multi-tenant.
Memantau Penggunaan Anda
[CODE BLOCK]
Langkah Berikutnya
- Autentikasi
- Errors & Error Handling
────────────────────────────────────────────────────────────
# Scripts API
SUMMARY: Penyimpanan skrip persisten — simpan skrip shell, Python, atau Node yang dapat digunakan kembali dan ambil via 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 menyediakan penyimpanan persisten untuk skrip yang dapat digunakan
kembali. Skrip diberi nama dan diberi versi dalam sebuah mind, dan dapat diambil
sebagai teks polos — sempurna untuk pola .
Endpoint
POST /script
Menyimpan atau memperbarui skrip.
[CODE BLOCK]
GET /script/:name
Mengambil konten skrip sebagai . Sempurna untuk disalurkan ke bash.
[CODE BLOCK]
GET /script/:name/info
Mengambil metadata skrip tanpa konten.
[CODE BLOCK]
Respons:
[CODE BLOCK]
GET /scripts
Mendaftar semua skrip dalam mind saat ini.
[CODE BLOCK]
DELETE /script/:name
Menghapus skrip.
[CODE BLOCK]
Kasus Penggunaan Umum
Skrip deployment
Simpan prosedur deployment standar sehingga LLM dapat menjalankannya tanpa
menurunkan langkah-langkahnya setiap kali:
[CODE BLOCK]
Cuplikan troubleshooting
Simpan perintah diagnostik untuk masalah umum:
[CODE BLOCK]
Generator konfigurasi
Simpan skrip yang menghasilkan konfigurasi:
[CODE BLOCK]
Langkah Berikutnya
- Variables API
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Tasks API
SUMMARY: Manajemen tugas untuk agen LLM — buat, daftar, perbarui, selesaikan, hapus tugas dengan prioritas.
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 memberi agen LLM cara terstruktur untuk melacak pekerjaan multi-langkah.
Tugas dicakup ke mind saat ini dan bertahan di seluruh sesi, sehingga agen dapat
melanjutkan pekerjaan dari tempat ia berhenti.
Endpoint
GET /mind/tasks
Mendaftar semua tugas untuk mind saat ini.
[CODE BLOCK]
Respons:
[CODE BLOCK]
POST /mind/task
Membuat tugas baru.
[CODE BLOCK]
GET /mind/task (parameter query)
Membuat tugas melalui GET (untuk alat yang hanya menggunakan URL).
[CODE BLOCK]
PUT /mind/task/:id
Memperbarui tugas yang ada.
[CODE BLOCK]
GET /mind/task/:id/complete
Menandai tugas sebagai selesai.
[CODE BLOCK]
GET /mind/task/:id/delete
Menghapus tugas secara permanen.
[CODE BLOCK]
Prioritas
- — tidak mendesak
- — default
- — penting
- — harus segera dilakukan
Status
- — dibuat, belum dimulai
- — sedang dikerjakan
- — selesai
- — dibatalkan
Pola: Alur Kerja Berbasis Tugas
[CODE BLOCK]
Langkah Berikutnya
- Alur Kerja Berbasis Tugas
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Utility Tools (waktu, kalkulator, acak)
SUMMARY: Endpoint utilitas publik — waktu server, kalkulator aman, generator nilai acak. Tanpa autentikasi.
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 adalah utilitas publik — tidak memerlukan autentikasi.
Berguna untuk agen LLM yang membutuhkan waktu sisi server, matematika aman,
atau nilai acak.
GET /tools/time
Mengambil waktu server saat ini, zona waktu, dan offset UTC.
[CODE BLOCK]
Respons:
[CODE BLOCK]
Kasus penggunaan: agen LLM yang perlu tahu "jam berapa sekarang" untuk
penjadwalan, timestamp, atau perhitungan tanggal relatif.
GET /tools/calc
Kalkulator aman — hanya aritmetika, tanpa . Mendukung , , ,
, , , , dan angka.
[CODE BLOCK]
Respons:
[CODE BLOCK]
> [!TIP]
> Gunakan ini alih-alih mencoba melakukan matematika di kepala Anda atau melalui
> parsing string. Ini aman (tidak mungkin injeksi kode) dan akurat.
Operator yang didukung
- penjumlahan
- pengurangan
- perkalian
- pembagian
- modulo
- tanda kurung
- Angka (bilangan bulat dan desimal)
Contoh
[CODE BLOCK]
GET /tools/random
Membuat nilai acak.
[CODE BLOCK]
Parameter tipe
| Tipe | Parameter | Output |
|------|-----------|--------|
| | tidak ada | String UUID v4 |
| | , (default 0-100) | Integer |
| | , (default 0-100) | Float |
| | , (rentang panjang, default 8-16) | String hex |
| | , (rentang panjang, default 8-16) | String alfabet |
Kasus Penggunaan untuk Agen LLM
Membuat ID unik
[CODE BLOCK]
Menghitung persentase
[CODE BLOCK]
Mengambil timestamp saat ini
[CODE BLOCK]
Membuat data uji
[CODE BLOCK]
Langkah Berikutnya
- Ikhtisar API — semua grup endpoint
- Errors & Error Handling
────────────────────────────────────────────────────────────
# User & Minds API
SUMMARY: Manajemen akun — daftar, login, buat mind, daftar mind, hapus mind. Dilindungi 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 menangani manajemen akun. Endpoint ini menggunakan autentikasi
JWT (bukan Mind Key) karena beroperasi di level akun, bukan level mind.
Endpoint Autentikasi
POST /register
Membuat akun pengguna baru.
[CODE BLOCK]
Respons:
[CODE BLOCK]
POST /login
Masuk ke akun yang sudah ada.
[CODE BLOCK]
Respons: sama dengan .
Endpoint Minds
POST /minds
Membuat mind baru. Mengembalikan Mind Key — simpan segera, hanya ditampilkan sekali.
[CODE BLOCK]
Respons:
[CODE BLOCK]
> [!CRITICAL]
> hanya ditampilkan sekali. Jika Anda kehilangannya, Anda tidak dapat
> mengambilnya kembali — Anda harus menghapus mind dan membuat yang baru (yang
> akan kehilangan semua memori yang disimpan).
GET /minds
Mendaftar semua mind untuk pengguna saat ini.
[CODE BLOCK]
Respons:
[CODE BLOCK]
DELETE /minds/:id
Menghapus mind secara permanen.
[CODE BLOCK]
> [!WARNING]
> Menghapus mind bersifat ireversibel. Semua memori, tugas, riwayat chat,
> dan skrip dalam mind tersebut hilang secara permanen. Ekspor terlebih dahulu
> melalui jika Anda memerlukan backup.
Pola Multi-Mind
Sebagian besar pengguna mendapat manfaat dari beberapa mind untuk menjaga
konteks tetap terisolasi:
[CODE BLOCK]
Gunakan Mind Key yang berbeda dalam sesi LLM yang berbeda untuk menjaga konteks tetap terisolasi.
Keamanan Akun
Persyaratan kata sandi
- Minimal 6 karakter
- Tidak ada maksimum (gunakan pengelola kata sandi)
- Disimpan sebagai hash bcrypt (tidak pernah plaintext)
Kedaluwarsa JWT
JWT kedaluwarsa setelah 7 hari. Saat kedaluwarsa, cukup panggil lagi.
Keamanan Mind Key
Mind Key tidak pernah kedaluwarsa. Jika Mind Key terkompromi:
1. Buat mind baru melalui
2. Perbarui konfigurasi LLM Anda dengan Mind Key baru
3. Hapus mind yang terkompromi melalui
Langkah Berikutnya
- Autentikasi — panduan autentikasi lengkap
- Mind Key vs JWT — panduan keputusan
- Sharing API — berbagi mind dengan pengguna lain
────────────────────────────────────────────────────────────
# Variables API
SUMMARY: Key-value store cepat untuk state LLM — penghitung, flag, timestamp terakhir dilihat, kemajuan parsial.
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 adalah key-value store cepat untuk state efemeral. Berbeda
dengan memori (yang diindeks, dapat dicari, dan terstruktur), variabel
dioptimalkan untuk akses baca/tulis cepat — sempurna untuk penghitung, flag,
dan state sesi.
Endpoint
POST /var
Menetapkan atau memperbarui variabel.
[CODE BLOCK]
GET /var/:key
Mengambil satu variabel.
[CODE BLOCK]
Respons:
[CODE BLOCK]
GET /var
Mendaftar semua variabel.
[CODE BLOCK]
DELETE /var/:key
Menghapus variabel.
[CODE BLOCK]
Kapan Menggunakan Variabel vs Memori
| Kasus Penggunaan | Gunakan |
|----------|-----|
| Nama pengguna, preferensi | Memori (dapat dicari, terstruktur) |
| Timestamp sesi terakhir | Variabel (state efemeral) |
| Penghitung (mis. pesan terkirim) | Variabel (pembaruan sering) |
| State alur kerja ("langkah 3 dari 5 selesai") | Variabel (sementara) |
| Catatan proyek panjang | Memori (diindeks teks penuh) |
| Skrip yang dapat digunakan kembali | Penyimpanan skrip (diberi nama, diberi versi) |
Pola Umum
Lacak sesi terakhir
[CODE BLOCK]
Pola penghitung
[CODE BLOCK]
Feature flags
[CODE BLOCK]
Langkah Berikutnya
- Memory API — untuk data terstruktur yang dapat dicari
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Webhooks API
SUMMARY: Daftarkan HTTP callback untuk event memori, chat, dan tugas — dapatkan notifikasi saat data berubah.
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
Webhooks memungkinkan Anda menerima HTTP callback ketika event terjadi di
Synapse. Sempurna untuk memicu otomasi eksternal, mengirim notifikasi, atau
sinkronisasi ke sistem lain.
Endpoint
POST /webhooks
Mendaftarkan webhook baru.
[CODE BLOCK]
Respons:
[CODE BLOCK]
GET /webhooks
Mendaftar semua webhook untuk mind saat ini.
[CODE BLOCK]
GET /webhooks/:id
Mengambil satu webhook.
[CODE BLOCK]
PUT /webhooks/:id
Memperbarui webhook (URL, event, secret, atau flag enabled).
[CODE BLOCK]
DELETE /webhooks/:id
Menghapus webhook.
[CODE BLOCK]
Tipe Event
| Pola | Aktif saat |
|---------|------------|
| | Event memori apa pun |
| | Memori baru disimpan |
| | Memori diperbarui |
| | Memori dihapus |
| | Event chat apa pun |
| | Pesan baru dari manusia |
| | Event tugas apa pun |
| | Tugas baru dibuat |
| | Tugas ditandai selesai |
| | Semua event |
Payload Webhook
Saat event aktif, Synapse melakukan POST ke URL Anda:
[CODE BLOCK]
Verifikasi Tanda Tangan
Jika Anda menetapkan , Synapse menandatangani setiap payload dengan HMAC-SHA256:
[CODE BLOCK]
Verifikasi di handler Anda:
[CODE BLOCK]
Pola: Sinkronisasi Real-Time
[CODE BLOCK]
Langkah Berikutnya
- Cron & Scheduler
- Panduan Otomasi Webhook
## KATEGORI: INTEGRASI MCP
Integrasi dengan Claude, Cursor, dan klien MCP lainnya.
────────────────────────────────────────────────────────────
# MCP di Claude Code
SUMMARY: Gunakan alat Synapse dari agen terminal Claude Code — memori persisten untuk sesi coding.
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 di Claude Code
Claude Code adalah agen coding berbasis terminal dari Anthropic. Dengan Synapse
MCP, Claude Code mendapatkan memori persisten lintas sesi coding — ia mengingat
konteks proyek Anda, keputusan masa lalu, dan pola codebase.
Pengaturan
Metode 1: Perintah CLI (disarankan)
[CODE BLOCK]
Metode 2: Edit File Konfigurasi
Edit :
[CODE BLOCK]
Verifikasi Berfungsi
Mulai Claude Code:
[CODE BLOCK]
Di prompt Claude Code, ketik:
[CODE BLOCK]
Claude harus memanggil dan merespons dengan memori tersimpan Anda.
Pola Umum
Persistensi konteks proyek
Di awal sesi coding:
[CODE BLOCK]
Claude memanggil , melihat daftar proyek Anda, dan melanjutkan
pekerjaan dari tempat Anda berhenti.
Keputusan codebase
Saat Anda membuat keputusan arsitektural:
[CODE BLOCK]
Claude memanggil dengan kategori , prioritas .
Menghindari kesalahan masa lalu
[CODE BLOCK]
Claude mencari memori dengan kategori dan mengingatkan Anda akan error masa lalu.
Pelacakan tugas
[CODE BLOCK]
Claude memanggil , dan tugas bertahan lintas sesi.
Tool Profiles
Untuk sesi coding di mana Anda tidak memerlukan semua 119 alat:
[CODE BLOCK]
Troubleshooting
MCP server tidak dimulai
[CODE BLOCK]
Mind Key tidak dikenali
[CODE BLOCK]
Claude Code tidak melihat alat
- Mulai ulang Claude Code setelah perubahan konfigurasi
- Periksa untuk memverifikasi Synapse terdaftar
- Lihat MCP Troubleshooting
Langkah Berikutnya
- Pengaturan Claude Desktop
- Pengaturan Cursor
- Panduan Agen LLM Persisten
────────────────────────────────────────────────────────────
# MCP di Claude Desktop
SUMMARY: Hubungkan Synapse ke Claude Desktop dalam 2 menit. Claude mendapat 79 alat Synapse secara 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 di Claude Desktop
Claude Desktop adalah aplikasi desktop Anthropic untuk macOS dan Windows.
Dengan Synapse MCP server dikonfigurasi, Claude mendapatkan akses native ke
semua 79 alat Synapse — ia dapat menyimpan memori, recall, mengelola tugas,
chat dengan Anda, dan lebih banyak.
Prasyarat
- Aplikasi Claude Desktop (macOS atau Windows)
- Node.js 18+ terpasang ()
- Mind Key Synapse Anda
Langkah 1: Buka File Konfigurasi
- macOS:
- Windows:
Jika file tidak ada, buatlah.
Langkah 2: Tambahkan Synapse MCP Server
[CODE BLOCK]
> [!TIP]
> Jika Anda sudah memiliki MCP server lain yang dikonfigurasi, cukup tambahkan
> blok di dalam objek yang ada.
Langkah 3: Mulai Ulang Claude Desktop
1. Keluar sepenuhnya dari Claude Desktop (Cmd+Q di macOS, bukan hanya tutup jendela)
2. Buka kembali Claude Desktop
3. Mulai chat baru
4. Cari ikon plug 🔌 di kiri bawah — harus tertulis "79 tools"
Langkah 4: Tes
Di chat baru, ketik:
[CODE BLOCK]
Claude harus memanggil alat dan merespons dengan ringkasan
memori tersimpan Anda (atau "No memories yet" jika mind Anda kosong).
Alat yang Tersedia (Pilihan)
| Alat | Deskripsi |
|------|-------------|
| | Recall semua memori |
| | Simpan memori baru |
| | Cari memori |
| | Daftar tugas |
| | Buat tugas |
| | Periksa pesan baru |
| | Balas pesan |
| | Buka tab browser |
| | Daftar komputer terdaftar |
Daftar lengkap: Apa itu MCP?
Troubleshooting
Tidak ada alat yang muncul di Claude Desktop
1. Verifikasi versi Node.js: (harus ≥ 18)
2. Periksa file konfigurasi adalah JSON yang valid (tanpa koma berlebih)
3. Mulai ulang Claude Desktop sepenuhnya (Cmd+Q, bukan hanya tutup)
4. Periksa log Claude Desktop: (macOS)
Error "Mind Key invalid"
- Verifikasi dimulai dengan
- Dapatkan key baru via (memerlukan JWT dari )
- Tidak ada tanda kutip di sekitar key dalam JSON
npx tidak ditemukan
- Pasang Node.js 18+:
- Mulai ulang terminal setelah pasang
- Di macOS dengan Homebrew:
Alat muncul tetapi panggilan gagal
- Periksa dapat dijangkau:
- Verifikasi Mind Key Anda berfungsi:
- Lihat MCP Troubleshooting
Tool Profiles (Hemat Token)
Jika Anda menggunakan LLM yang lebih kecil atau ingin menghemat token konteks, tetapkan tool profile:
[CODE BLOCK]
Profile: (8 alat), (25), (119, default).
Langkah Berikutnya
- Pengaturan Claude Code
- Pengaturan Cursor
- MCP Troubleshooting
────────────────────────────────────────────────────────────
# MCP di Continue.dev
SUMMARY: Hubungkan Synapse ke Continue.dev — asisten coding AI open-source untuk VS Code dan JetBrains.
MCP di Continue.dev
Continue.dev adalah asisten coding AI open-source untuk VS Code dan JetBrains
IDE. Dengan Synapse MCP, Continue mendapatkan memori persisten lintas sesi.
Prasyarat
- VS Code atau JetBrains IDE
- Ekstensi Continue.dev terpasang
- Node.js 18+
- Mind Key Synapse Anda
Pengaturan
Langkah 1: Buka Konfigurasi Continue
Di VS Code atau JetBrains:
1. Buka sidebar ekstensi Continue
2. Klik ikon gear → "Open config.json"
Atau edit langsung.
Langkah 2: Tambahkan Synapse MCP Server
[CODE BLOCK]
Langkah 3: Muat Ulang Continue
Muat ulang jendela VS Code (Cmd+Shift+P → "Reload Window") atau mulai ulang IDE Anda.
Verifikasi Berfungsi
Di chat Continue:
[CODE BLOCK]
Continue harus memanggil dan merespons dengan memori tersimpan Anda.
Pola Umum
Konteks proyek
[CODE BLOCK]
Continue memanggil , melihat memori proyek Anda, dan melanjutkan
pekerjaan dari tempat Anda berhenti.
Pola review kode
[CODE BLOCK]
Continue menemukan pola review kode tersimpan Anda dan menerapkannya.
Memori pair programming
[CODE BLOCK]
Continue menyimpannya sebagai memori .
Troubleshooting
MCP server tidak terhubung
1. Periksa adalah JSON yang valid
2. Verifikasi Node.js:
3. Periksa panel output Continue (View → Output → Continue)
4. Mulai ulang IDE
Alat tidak muncul
- Verifikasi versi Continue mendukung MCP (≥ 0.9.x)
- Periksa env var diatur dalam konfigurasi
- Cari error MCP di log Continue
Langkah Berikutnya
- Pengaturan Claude Desktop
- Klien MCP Khusus
────────────────────────────────────────────────────────────
# MCP di Cursor
SUMMARY: Hubungkan Synapse ke Cursor IDE untuk memori proyek persisten lintas sesi coding.
MCP di Cursor
Cursor adalah IDE bertenaga AI berbasis VS Code. Dengan Synapse MCP, Cursor
mendapatkan memori persisten lintas sesi — ia mengingat keputusan proyek Anda,
pola codebase, dan sesi debugging masa lalu.
Prasyarat
- Cursor IDE terpasang ()
- Node.js 18+
- Mind Key Synapse Anda
Pengaturan
Langkah 1: Buka Pengaturan Cursor
Di Cursor:
1. Buka Settings (Cmd+, di macOS, Ctrl+, di Windows/Linux)
2. Cari "MCP" atau navigasi ke
Langkah 2: Tambahkan Synapse MCP Server
Klik "Add MCP Server" dan konfigurasikan:
| Field | Nilai |
|-------|-------|
| Name | |
| Type | |
| Command | |
| Env | |
Langkah 3: Edit config.json langsung (alternatif)
Cursor menyimpan konfigurasi MCP di :
[CODE BLOCK]
Langkah 4: Mulai Ulang Cursor
Mulai ulang Cursor sepenuhnya (Cmd+Q dan buka kembali di macOS).
Verifikasi Berfungsi
Di panel chat Cursor (Cmd+L):
[CODE BLOCK]
Cursor harus memanggil dan merespons dengan memori tersimpan Anda.
Pola Umum
Onboarding proyek
Saat membuka proyek baru:
[CODE BLOCK]
Cursor memanggil dan melanjutkan pekerjaan dari tempat Anda berhenti.
Keputusan arsitektur
[CODE BLOCK]
Cursor menyimpannya sebagai memori dengan prioritas .
Riwayat debugging
[CODE BLOCK]
Cursor mencari memori dan mengingatkan Anda akan perbaikan masa lalu.
Pola kode lintas-sesi
[CODE BLOCK]
Cursor menemukan memori tentang implementasi auth yang telah Anda lakukan sebelumnya.
Troubleshooting
MCP server tidak terhubung
1. Verifikasi Node.js: (≥ 18)
2. Tes MCP server: (harus dimulai tanpa error)
3. Periksa log MCP Cursor (View → Output → MCP)
4. Mulai ulang Cursor sepenuhnya
Alat tidak muncul
- Periksa adalah JSON yang valid
- Verifikasi env var diatur
- Periksa versi Cursor mendukung MCP (≥ 0.42)
Mind Key tidak valid
[CODE BLOCK]
Langkah Berikutnya
- Pengaturan Claude Desktop
- Pengaturan Continue.dev
- Panduan Agen LLM Persisten
────────────────────────────────────────────────────────────
# Membangun Klien MCP Khusus
SUMMARY: Hubungkan ke Synapse MCP server dari aplikasi Anda sendiri menggunakan MCP SDK.
Membangun Klien MCP Khusus
Jika Anda membangun aplikasi LLM Anda sendiri, Anda dapat terhubung ke Synapse
MCP server langsung menggunakan SDK MCP resmi. Ini memberikan aplikasi Anda
akses ke semua 79 alat Synapse.
SDK
| Bahasa | Paket |
|----------|---------|
| TypeScript/JavaScript | |
| Python | |
Contoh TypeScript
Pasang
[CODE BLOCK]
Hubungkan via stdio
[CODE BLOCK]
Hubungkan via HTTP/SSE (remote)
[CODE BLOCK]
Contoh Python
Pasang
[CODE BLOCK]
Hubungkan via stdio
[CODE BLOCK]
Tool Profiles
Saat menghubungkan, Anda dapat meminta tool profile spesifik melalui header
(HTTP/SSE) atau env var (stdio):
[CODE BLOCK]
Penanganan Error
[CODE BLOCK]
Kasus Penggunaan
- Asisten AI khusus — bangun agen Anda sendiri dengan memori persisten
- Otomasi alur kerja — rangkai alat Synapse dalam alur kerja khusus
- Pipeline data — ekstrak memori, transformasi, muat di tempat lain
- Dashboard pemantauan — tampilkan statistik memori, riwayat chat, tugas
Langkah Berikutnya
- Spesifikasi MCP
- Repo Synapse MCP
- Ikhtisar API
────────────────────────────────────────────────────────────
# MCP Troubleshooting
SUMMARY: Selesaikan masalah integrasi MCP umum — server tidak dimulai, alat tidak muncul, error autentikasi.
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 Troubleshooting
Masalah umum dan solusi saat mengintegrasikan Synapse MCP dengan klien LLM Anda.
Daftar Periksa Diagnostik Cepat
1. ✅ Node.js 18+ terpasang? ()
2. ✅ Mind Key dimulai dengan ? (bukan JWT )
3. ✅ Synapse API dapat dijangkau? ()
4. ✅ Mind Key berfungsi? ()
5. ✅ File konfigurasi adalah JSON yang valid? (tanpa koma berlebih, tanpa komentar)
6. ✅ Klien dimulai ulang setelah perubahan konfigurasi?
7. ✅ MCP server dimulai secara manual? ()
Masalah: Tidak Ada Alat yang Muncul di Klien
Gejala
- Claude Desktop / Cursor / Continue menunjukkan 0 alat
- Tidak ada ikon 🔌 atau entri "synapse" dalam daftar MCP server
Solusi
1. Mulai ulang klien sepenuhnya — Cmd+Q di macOS (bukan hanya tutup jendela)
2. Periksa lokasi file konfigurasi:
- Claude Desktop macOS:
- Claude Desktop Windows:
- Cursor:
- Continue:
3. Validasi JSON — tempel konfigurasi ke
4. Periksa log klien untuk error MCP:
- Claude Desktop: (macOS)
- Cursor: View → Output → MCP
5. Jalankan MCP server secara manual untuk melihat error startup:
[CODE BLOCK]
Masalah: Error "Mind Key invalid"
Gejala
- Alat muncul tetapi panggilan gagal dengan "401 Unauthorized"
- Error: "Mind Key fehlt oder ungültig"
Solusi
1. Verifikasi format Mind Key — dimulai dengan , 40 karakter
2. Tes langsung:
[CODE BLOCK]
3. Periksa env var diatur — untuk transport stdio, env var harus dalam
konfigurasi MCP server, bukan shell Anda
4. Dapatkan Mind Key baru:
[CODE BLOCK]
Masalah: npx Tidak Ditemukan
Gejala
- Error: "npx: command not found"
- MCP server gagal dimulai
Solusi
1. Pasang Node.js 18+:
- macOS: atau unduh dari
- Linux:
- Windows: unduh dari
2. Mulai ulang terminal setelah pasang
3. Verifikasi:
Masalah: SYNAPSEURL Tidak Dapat Dijangkau
Gejala
- MCP server dimulai tetapi panggilan alat timeout
- Error: "fetch failed" atau "ECONNREFUSED"
Solusi
1. Tes konektivitas:
[CODE BLOCK]
2. Periksa firewall korporat — mungkin memblokir HTTPS keluar
3. Coba URL alternatif:
- Produksi:
- MCP server:
4. Untuk self-hosted: pastikan instansi Synapse Anda berjalan dan dapat diakses
Masalah: MCP Server Crash
Gejala
- MCP server keluar segera setelah dimulai
- Log klien menunjukkan "MCP server disconnected"
Solusi
1. Jalankan secara manual untuk melihat error:
[CODE BLOCK]
2. Periksa konflik port — MCP server menggunakan port 13100 secara default
3. Bersihkan cache npx:
[CODE BLOCK]
4. Perbarui ke versi terbaru:
[CODE BLOCK]
Masalah: Panggilan Alat Mengembalikan 429
Gejala
- Error: "Rate limit exceeded"
Solusi
Ini seharusnya tidak terjadi dengan MCP (menggunakan autentikasi header, tanpa rate limit). Jika terjadi:
1. Periksa jika Anda menggunakan di suatu tempat — beralih ke autentikasi header
2. Verifikasi — pastikan menunjuk ke instansi yang benar
3. Hubungi support jika masalah berlanjut
Masalah: Alat Muncul tetapi Tidak Berfungsi
Gejala
- Alat terdaftar di klien
- Memanggil alat mengembalikan error atau tidak ada hasil
Solusi
1. Periksa nama alat — harus persis (mis. , bukan )
2. Verifikasi argumen — periksa skema input alat
3. Tes via API langsung:
[CODE BLOCK]
4. Periksa health Synapse:
[CODE BLOCK]
Mendapatkan Bantuan
Jika tidak ada di atas yang menyelesaikan masalah Anda:
1. Periksa issue yang ada:
2. Buka issue baru dengan:
- Versi MCP server ()
- Nama dan versi klien
- Sistem operasi
- Kutipan log yang relevan
- Langkah reproduksi
Langkah Berikutnya
- Pengaturan Claude Desktop
- Pengaturan Claude Code
- API Errors
────────────────────────────────────────────────────────────
# Apa itu MCP?
SUMMARY: Model Context Protocol memungkinkan LLM memanggil alat eksternal. Synapse mengekspos 79 alat via MCP server resmi.
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
Apa itu MCP?
Model Context Protocol (MCP) adalah standar terbuka oleh Anthropic (2024)
yang memungkinkan LLM memanggil alat eksternal dengan cara terstruktur. Alih-alih
menempelkan dokumentasi API ke dalam prompt, Anda mendaftarkan alat dengan MCP
server, dan LLM memanggilnya sesuai kebutuhan — seperti function calling, tetapi
terstandarisasi dan agnostik-klien.
Synapse MCP Server
Synapse mengirimkan MCP server resmi ( di npm) yang mengekspos
79 alat mencakup semua fitur Synapse:
| Kategori | Alat | Jumlah |
|----------|-------|-------|
| 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 |
| Total | | 79+ |
Cara Kerja
[CODE BLOCK]
1. Anda mengonfigurasi klien LLM Anda (Claude Desktop, Cursor, dll.) untuk menggunakan Synapse MCP server
2. Klien memulai MCP server (melalui )
3. MCP server terhubung ke Synapse API menggunakan Mind Key Anda
4. LLM melihat semua 79 alat sebagai fungsi native yang dapat dipanggil
5. Saat LLM perlu mengingat sesuatu, ia memanggil — MCP server menerjemahkan ini ke di Synapse
Transport
Synapse MCP server mendukung tiga transport:
stdio (lokal, disarankan untuk desktop)
[CODE BLOCK]
HTTP/SSE (remote, multi-tenant)
Hubungkan klien MCP Anda ke:
[CODE BLOCK]
WebSocket (mobile, volume tinggi)
[CODE BLOCK]
Tool Profiles (v1.4.0)
Untuk mengurangi overhead token bagi LLM yang lebih kecil, MCP server mendukung tiga
tool profile:
| Profile | Alat | Token | Terbaik Untuk |
|---------|-------|--------|----------|
| | 8 (dispatch komposit) | 500 | LLM self-hosted dengan konteks ≤8k |
| | 25 (bernama) | 2.500 | LLM mid-size (Claude Haiku, GPT-3.5) |
| | 119 (semua) | 8.250 | LLM besar (Claude Sonnet/Opus, GPT-4) — default |
Kontrol melalui:
- Env var:
- Header:
Klien yang Didukung
- Claude Desktop — aplikasi desktop Anthropic
- Claude Code — agen coding terminal
- Cursor — IDE bertenaga AI
- Continue.dev — asisten coding AI open-source
- Cline — ekstensi VS Code
- Klien apa pun yang kompatibel dengan MCP
Mengapa Menggunakan MCP Alih-alih API Langsung?
| Pendekatan | Pro | Kontra |
|----------|------|------|
| API Langsung | Sederhana, tanpa lapisan tambahan | LLM perlu tahu URL, header, auth |
| MCP | LLM melihat alat native, tanpa menghafal URL | Proses MCP server tambahan |
Untuk sebagian besar kasus penggunaan agen LLM, MCP adalah pilihan yang lebih
baik — LLM tidak perlu mengingat path API atau pola auth.
Langkah Berikutnya
- Pengaturan Claude Desktop — konfigurasi 2 menit
- Pengaturan Claude Code — integrasi terminal
- Klien MCP Khusus — bangun sendiri
## KATEGORI: PANDUAN & TUTORIAL
Panduan langkah demi langkah untuk skenario konkret.
────────────────────────────────────────────────────────────
# Pengujian Aplikasi iOS Otomatis
SUMMARY: Gunakan Synapse + Computer Control API untuk mengotomasi pengujian aplikasi iOS via Simulator.
Pengujian Aplikasi iOS Otomatis
Gabungkan sistem memori Synapse dengan Computer Control API untuk membangun
pengujian aplikasi iOS berbasis LLM. LLM mengingat skenario pengujian, belajar
dari kegagalan masa lalu, dan beradaptasi dengan perubahan UI.
Arsitektur
[CODE BLOCK]
Prasyarat
- Akun Synapse + Mind Key
- Synapse MCP server dikonfigurasi di Claude Desktop
- iOS Simulator dengan terpasang
- Komputer terdaftar di Synapse (lihat Computer Control API)
Langkah 1: Daftarkan Komputer Simulator
Di Mac yang menjalankan iOS Simulator:
[CODE BLOCK]
Langkah 2: Simpan Skenario Pengujian di Memori
Simpan skenario pengujian yang dapat digunakan kembali sebagai memori:
[CODE BLOCK]
Langkah 3: Eksekusi Pengujian Berbasis LLM
Di Claude Desktop (dengan Synapse MCP dikonfigurasi):
[CODE BLOCK]
Claude akan:
1. Memanggil untuk menemukan memori
2. Memanggil untuk melihat kondisi saat ini
3. Mengeksekusi setiap langkah melalui (klik, ketik)
4. Memverifikasi hasil melalui tangkapan layar
5. Menyimpan kegagalan apa pun sebagai memori
Langkah 4: Pengujian Self-Healing
Saat pengujian gagal, simpan kegagalan dan pemulihannya:
[CODE BLOCK]
Saat LLM menjalankan pengujian berikutnya, ia akan recall kegagalan dan menerapkan
pemulihan secara otomatis.
Langkah 5: Pelacakan Hasil Pengujian
Lacak pengujian yang dijalankan sebagai tugas:
[CODE BLOCK]
Perintah Umum
| Aksi | Perintah |
|--------|---------|
| Luncurkan Simulator | |
| Tangkapan layar | (via Synapse MCP) |
| Ketuk di (x,y) | |
| Ketik teks | |
| Tekan Home | |
Praktik Terbaik
> [!TIP]
> - Simpan koordinat UI sebagai memori — UI berubah, tetapi LLM dapat belajar ulang
> - Gunakan label aksesibilitas — lebih stabil dari koordinat
> - Simpan data pengujian secara terpisah — gunakan variabel untuk nama pengguna, kata sandi
> - Jalankan pengujian dalam kondisi bersih — reset Simulator antara pengujian
> - Catat tangkapan layar untuk kegagalan — berguna untuk debugging
Langkah Berikutnya
- Pengujian Self-Healing
- Computer Control API
- Praktik Terbaik Memori
────────────────────────────────────────────────────────────
# Backup & Restore
SUMMARY: Ekspor memori Anda untuk backup, migrasi antar mind, pulihkan setelah kehilangan data.
Backup & Restore
Synapse menyediakan ekspor/impor penuh untuk backup memori, migrasi, dan
pemulihan bencana. Panduan ini mencakup operasi esensial.
Ekspor
Ekspor Mind Penuh
Ekspor semua memori dalam satu mind sebagai JSON:
[CODE BLOCK]
Format respons:
[CODE BLOCK]
Ekspor Inkremental (Diff)
Ekspor hanya memori yang berubah sejak timestamp tertentu:
[CODE BLOCK]
Respons:
[CODE BLOCK]
Backup Otomatis
Jadwalkan backup harian via cron:
[CODE BLOCK]
> [!NOTE]
> Endpoint cron menerima respons tetapi tidak menyimpannya. Untuk backup
> nyata, arahkan cron ke server backup Anda sendiri yang menyimpan respons.
Lebih Baik: Skrip Backup Eksternal
[CODE BLOCK]
Tambahkan ke crontab:
[CODE BLOCK]
Restore
Restore ke Mind yang Sama
[CODE BLOCK]
Restore ke Mind Baru
[CODE BLOCK]
Skrip Restore Python
[CODE BLOCK]
Migrasi Antar Mind
[CODE BLOCK]
Backup Data Lain
Jangan lupa untuk backup:
| Tipe Data | Endpoint |
|-----------|----------|
| Memori | |
| Tugas | |
| Skrip | |
| Webhook | |
| Cron job | |
| Variabel | |
| Riwayat chat | |
Verifikasi
Setelah restore, verifikasi:
[CODE BLOCK]
Praktik Terbaik
> [!TIP]
> - Backup harian — otomatis dengan cron
> - Tes restore — backup yang tidak dapat Anda restore tidak berguna
> - Simpan beberapa versi — setidaknya 30 hari
> - Simpan di luar lokasi — S3, Backblaze B2, dll.
> - Enkripsi backup sensitif — memori mungkin berisi PII
> - Dokumentasikan proses restore — Anda akan lupa saat membutuhkannya
Langkah Berikutnya
- Memory API
- Cron & Scheduler — untuk backup otomatis
────────────────────────────────────────────────────────────
# Praktik Terbaik Memori
SUMMARY: Cara menstrukturkan memori untuk recall yang efektif — kategori, key, tag, prioritas.
Praktik Terbaik Memori
Bagaimana Anda menstrukturkan memori menentukan seberapa berguna memori tersebut.
Panduan ini mencakup pola untuk mengkategorikan, menandai, dan memprioritaskan
memori sehingga LLM dapat recall informasi yang tepat pada waktu yang tepat.
Kategori: Pilih yang Paling Spesifik
| Kategori | Gunakan Untuk | Contoh |
|----------|---------|---------|
| | Nama pengguna, peran, info kontak | |
| | Suka, tidak suka, gaya kerja | |
| | Fakta yang dapat diverifikasi | |
| | Status proyek, keputusan | |
| | Keahlian pengguna | |
| | Error masa lalu yang harus dihindari | |
| | Konteks yang relevan dengan sesi | |
| | Catatan lain-lain | |
> [!TIP]
> Jika ragu, gunakan untuk info yang dapat diverifikasi dan untuk
> yang lainnya. Jangan berlebihan mengkategorikan — lebih baik memiliki
> yang jelas daripada yang membingungkan.
Key: Identifier Bermakna
Field adalah identifier memori. Gunakan key yang bermakna dan stabil:
Key yang baik:
-
-
-
-
Key yang buruk:
- (tidak bermakna)
- (tidak deskriptif)
- (tanggal tidak membantu recall)
Konvensi penamaan key
- (huruf kecil dengan garis bawah)
- Awali dengan kategori: , ,
- Gunakan kata benda deskriptif, bukan kata kerja
- Jaga di bawah 50 karakter
Tag: Untuk Pencarian dan Pemfilteran
Tag memungkinkan pemfilteran dan pencarian cepat. Tambahkan 2-5 tag per memori:
[CODE BLOCK]
Pola tag
- Nama proyek: , ,
- Topik: , , ,
- Status: , ,
- Indikator prioritas: ,
> [!NOTE]
> Tag tidak case-sensitive. Gunakan huruf kecil untuk konsistensi.
Prioritas: Realistis
| Prioritas | Gunakan Untuk | % Memori |
|----------|---------|---------------|
| | Identitas pengguna, info hukum, keputusan ireversibel | 5% |
| | Proyek aktif, preferensi penting | 20% |
| | Sebagian besar fakta, catatan, konteks | 65% |
| | Efemeral, bagus untuk diketahui | 10% |
> [!WARNING]
> Jangan tandai semuanya . Jika semuanya critical, tidak ada yang critical.
> Simpan untuk hal-hal yang akan menyebabkan kerugian nyata jika dilupakan.
Kapan Menyimpan vs Tidak Menyimpan
Selalu simpan
- Identitas pengguna (nama, email, peran)
- Preferensi jangka panjang
- Keputusan proyek dan rasional
- Kesalahan masa lalu dan pelajaran yang dipetik
- Komitmen yang dibuat kepada pengguna
Jangan simpan
- State sementara (gunakan variabel sebagai gantinya)
- Riwayat percakapan verbatim (sistem chat menangani ini)
- Data sensitif (kata sandi, API key)
- Fakta yang mudah diturunkan (tanggal saat ini, konten file)
- Konteks efemeral (gunakan kategori dengan prioritas rendah)
Memperbarui Memori
POST dengan + yang sama memperbarui memori yang ada:
[CODE BLOCK]
> [!TIP]
> Gunakan key yang stabil sehingga Anda dapat memperbarui tanpa membuat duplikat.
> LLM harus POST ulang key yang sama saat info berubah, bukan membuat memori baru.
Siklus Hidup Memori
[CODE BLOCK]
- Create: POST /memory dengan konteks penuh
- Active: Recall sering, perbarui sesuai kebutuhan
- Stale: Masih relevan tetapi tidak aktif digunakan (prioritas lebih rendah?)
- Archive: Tetapkan prioritas ke , simpan untuk referensi historis
- Delete: DELETE /memory/:id saat tidak lagi relevan
Pembersihan berkala
[CODE BLOCK]
Pola: Warisan Memori
Untuk konteks hierarkis (proyek → subproyek → tugas):
[CODE BLOCK]
LLM kemudian dapat mencari untuk menemukan semua memori terkait.
Pola: Log Keputusan
Simpan keputusan dengan rasional sehingga LLM tidak membahasnya ulang:
[CODE BLOCK]
Pola: Penghindaran Kesalahan
Simpan kesalahan dengan instruksi penghindaran spesifik:
[CODE BLOCK]
Anti-Pola yang Harus Dihindari
> [!WARNING]
> - Menyimpan log percakapan — sistem chat menangani ini
> - Menyimpan seluruh file — gunakan penyimpanan skrip atau penyimpanan eksternal
> - Menyimpan state efemeral — gunakan variabel
> - Menyimpan rahasia — gunakan variabel lingkungan
> - Menduplikasi memori — gunakan key yang stabil
> - Tag berlebihan — 2-5 tag per memori adalah ideal
> - Semuanya critical — realistis dengan prioritas
Langkah Berikutnya
- Memory API
- Agen LLM Persisten
- Strategi Penandaan Memori
────────────────────────────────────────────────────────────
# Koordinasi Multi-Agent
SUMMARY: Koordinasikan beberapa agen LLM menggunakan mind, tugas, dan chat Synapse bersama.
Koordinasi Multi-Agent
Saat Anda memiliki beberapa agen LLM yang mengerjakan tugas terkait, Synapse
menyediakan lapisan koordinasi — memori bersama, penugasan tugas, dan chat asinkron.
Pola
Pola 1: Mind Bersama (Sumber Kebenaran Tunggal)
Semua agen berbagi satu Mind Key. Mereka membaca/menulis ke penyimpanan memori yang sama.
[CODE BLOCK]
Kasus penggunaan: Tim kecil agen yang mengerjakan satu proyek.
Pengaturan:
[CODE BLOCK]
Koordinasi via tugas:
[CODE BLOCK]
Pola 2: Mind Khusus (Konteks Terisolasi)
Setiap agen memiliki mind sendiri. Mereka berkomunikasi melalui mind "koordinasi" bersama.
[CODE BLOCK]
Kasus penggunaan: Agen dengan spesialisasi berbeda (coding, review, deployment).
Pengaturan:
[CODE BLOCK]
Koordinasi via mind bersama:
[CODE BLOCK]
Pola 3: Hub-and-Spoke (Orchestrator)
Agen orchestrator pusat menugaskan tugas ke agen pekerja.
[CODE BLOCK]
Kasus penggunaan: Alur kerja kompleks dengan pekerjaan paralel.
Implementasi:
[CODE BLOCK]
Koordinasi via Chat
Agen dapat berkomunikasi melalui sistem chat:
[CODE BLOCK]
> [!NOTE]
> Pesan chat diberi tag peran. Tetapkan role=agent untuk pesan agen-ke-agen,
> role=human untuk manusia-ke-agen.
Koordinasi via Variabel
Gunakan variabel untuk koordinasi ringan (lock, flag):
[CODE BLOCK]
Praktik Terbaik
> [!TIP]
> - Gunakan mind terpisah untuk kepentingan terpisah — jangan campur memori coder dan reviewer
> - Tandai agen di chat — untuk pengalamatan yang jelas
> - Gunakan tugas untuk penugasan kerja — bukan chat (chat untuk diskusi)
> - Implementasikan idempotensi — agen mungkin mencoba ulang operasi yang gagal
> - Catat semuanya — simpan keputusan di memori untuk auditabilitas
Langkah Berikutnya
- Agen LLM Persisten
- LLM Cookbook
- Otomasi Webhook
────────────────────────────────────────────────────────────
# Membangun Agen LLM Persisten
SUMMARY: Panduan langkah demi langkah untuk membangun agen LLM yang mengingat lintas sesi menggunakan Synapse.
Ikhtisar
Panduan ini memandu membangun agen LLM yang mempertahankan konteks lintas sesi
menggunakan Synapse. Pada akhirnya, agen Anda akan:
- Recall konteks masa lalu di awal sesi
- Menyimpan pembelajaran baru saat terjadi
- Melacak tugas multi-langkah lintas sesi
- Berkomunikasi dengan manusia melalui chat asinkron
Arsitektur
[CODE BLOCK]
Langkah 1: Siapkan Mind Key
[CODE BLOCK]
Langkah 2: Protokol Awal Sesi
Di awal setiap sesi, recall semua memori:
[CODE BLOCK]
Langkah 3: Simpan Pembelajaran Baru
Setiap kali agen mempelajari sesuatu yang patut diingat:
[CODE BLOCK]
Langkah 4: Manajemen Tugas
Lacak pekerjaan multi-langkah lintas sesi:
[CODE BLOCK]
Langkah 5: Chat Asinkron dengan Manusia
Polling pesan di antara pemanggilan alat:
[CODE BLOCK]
Langkah 6: Protokol Akhir Sesi
Di akhir sesi, simpan konteks akhir:
[CODE BLOCK]
Pola Lengkap
[CODE BLOCK]
Praktik Terbaik
> [!TIP]
>
> - Selalu recall pertama — jangan pernah memulai pekerjaan tanpa memuat konteks
> - Simpan secara proaktif — jangan tunggu sampai akhir sesi
> - Gunakan key yang bermakna — , , bukan
> - Tandai semuanya — tag memberdayakan pencarian dan pemfilteran
> - Tetapkan prioritas realistis — tidak semuanya
Langkah Berikutnya
- LLM Cookbook — pola praktis
- Praktik Terbaik Memori
- Koordinasi Multi-Agent
────────────────────────────────────────────────────────────
# Pipeline Pengujian Self-Healing
SUMMARY: Bangun pipeline pengujian yang belajar dari kegagalan dan beradaptasi otomatis menggunakan memori Synapse.
Pipeline Pengujian Self-Healing
Suite pengujian tradisional rusak saat UI berubah. Pengujian self-healing
menggunakan memori Synapse untuk belajar dari kegagalan masa lalu dan
beradaptasi — mengurangi pengujian flaky dan beban pemeliharaan.
Konsep
[CODE BLOCK]
1. Pengujian berjalan
2. Jika gagal, simpan kegagalan (apa yang salah, mengapa, cara memperbaiki)
3. Berikutnya: recall kegagalan yang relevan sebelum mengeksekusi
4. Terapkan perbaikan yang diketahui secara otomatis
Implementasi
Langkah 1: Pembungkus Pengujian
Bungkus setiap pengujian dengan recall/simpan memori:
[CODE BLOCK]
Langkah 2: Logika Pengujian Adaptif
Di dalam pengujian, periksa kegagalan yang diketahui dan terapkan perbaikan:
[CODE BLOCK]
Langkah 3: Strategi Pemulihan
Simpan strategi pemulihan sebagai memori:
[CODE BLOCK]
Langkah 4: Integrasi CI
[CODE BLOCK]
Langkah 5: Dashboard Analisis Kegagalan
[CODE BLOCK]
Praktik Terbaik
> [!TIP]
> - Simpan traceback — mereka berisi baris persis yang gagal
> - Tandai berdasarkan nama pengujian — memungkinkan pemfilteran cepat
> - Gunakan kategori — memisahkan dari memori reguler
> - Tetapkan prioritas — kegagalan tidak boleh dilupakan
> - Pembersihan berkala — hapus memori untuk masalah yang diselesaikan
> - Jangan simpan data sensitif — kredensial, PII
Pola Kegagalan Umum untuk Disimpan
| Tipe Kegagalan | Apa yang Disimpan |
|--------------|---------------|
| Element not found | Selector yang dicoba, kondisi halaman, tangkapan layar |
| Timeout | Waktu tunggu, apa yang ditunggu |
| Assertion failed | Nilai yang diharapkan vs aktual |
| Network error | URL, kode status, body respons |
| Permission denied | Izin yang diperlukan, peran pengguna saat ini |
Langkah Berikutnya
- Pengujian iOS Otomatis
- Praktik Terbaik Memori
- Cookbook Pemulihan Error
────────────────────────────────────────────────────────────
# Otomasi Webhook
SUMMARY: Picu sistem eksternal saat memori berubah — sinkronisasi, notifikasi, otomasi.
Otomasi Webhook
Webhook memungkinkan Anda memicu sistem eksternal saat event Synapse aktif.
Panduan ini mencakup pola otomasi umum.
Pola Umum
Pola 1: Notifikasi pada Memori Critical
Kirim pesan Slack saat memori critical disimpan:
[CODE BLOCK]
Daftarkan webhook:
[CODE BLOCK]
Pola 2: Sinkronisasi ke Sistem Eksternal
Sinkronkan memori ke Notion, Obsidian, atau KB eksternal apa pun:
[CODE BLOCK]
Pola 3: Picu CI/CD
Picu deployment saat memori "release" disimpan:
[CODE BLOCK]
Pola 4: Bangunkan Agen pada Pesan Manusia
Picu menjalankan agen LLM saat manusia mengirim pesan chat:
[CODE BLOCK]
Pola 5: Agregasi Metrik
Lacak pertumbuhan memori, aktivitas chat, penyelesaian tugas:
[CODE BLOCK]
Verifikasi Tanda Tangan
Selalu verifikasi tanda tangan webhook untuk mencegah spoofing:
[CODE BLOCK]
Logika Coba Ulang
Synapse mencoba ulang webhook yang gagal dengan exponential backoff. Handler Anda harus:
1. Mengembalikan 200 dengan cepat — jangan lakukan pekerjaan berat secara sinkron
2. Antri pekerjaan — gunakan sistem pekerjaan latar belakang
3. Idempoten — event yang sama mungkin dikirim dua kali
[CODE BLOCK]
Debugging Webhook
Periksa riwayat pengiriman
Pengiriman webhook dicatat. Periksa pengiriman webhook terbaru Anda:
[CODE BLOCK]
Tes webhook secara manual
[CODE BLOCK]
Masalah umum
| Masalah | Perbaikan |
|-------|-----|
| Respons 4xx | Periksa handler Anda mengembalikan 200 |
| Respons 5xx | Error server — periksa log aplikasi Anda |
| Timeout | Kembalikan 200 cepat, antri pekerjaan asinkron |
| Pengiriman duplikat | Buat handler idempoten |
| Ketidakcocokan tanda tangan | Verifikasi secret benar |
Praktik Terbaik
> [!TIP]
> - Selalu verifikasi tanda tangan — jangan pernah lewati ini
> - Kembalikan 200 cepat — jangan blokir Synapse
> - Idempoten — tangani pengiriman duplikat
> - Gunakan event spesifik — bukan
> - Pantau kegagalan pengiriman — siapkan peringatan
Langkah Berikutnya
- Webhooks API
- Cron & Scheduler
- Agen LLM Persisten
## KATEGORI: KONSEP
Arsitektur dan konsep di balik Synapse.
────────────────────────────────────────────────────────────
# Arsitektur Synapse
SUMMARY: Bagaimana Synapse dibangun — Fastify, PostgreSQL, FTS5, embeddings, MCP server.
Arsitektur Synapse
Synapse adalah API memori multi-tenant yang dibangun di atas Fastify, PostgreSQL
dengan FTS5, dan layanan embeddings opsional untuk pencarian semantik.
Arsitektur Tingkat Tinggi
[CODE BLOCK]
Komponen Inti
1. Synapse API (Fastify)
Server HTTP utama. Menangani:
- Endpoint REST (, , , dll.)
- Autentikasi (Mind Key untuk agen, JWT untuk manusia)
- Rate limiting (hanya autentikasi )
- Penyajian file statis (web UI di , , dll.)
- Pengiriman webhook
Dibangun dengan Fastify 5 untuk performa. Berjalan di port 12800 di produksi.
2. PostgreSQL dengan FTS5
Penyimpanan data utama. Menggunakan PostgreSQL dengan ekstensi FTS5 untuk
pencarian teks penuh.
Tabel utama:
| Tabel | Tujuan |
|-------|---------|
| | Akun pengguna |
| | Cakupan mind (masing-masing memiliki Mind Key) |
| | Catatan memori dengan tabel virtual FTS5 |
| | Manajemen tugas |
| | Riwayat chat |
| | Skrip persisten |
| | Pendaftaran webhook |
| | Tugas terjadwal |
| | Key-value store |
| | Jejak audit |
FTS5 memungkinkan pencarian teks penuh sub-milidetik di seluruh konten memori.
Lihat Pencarian FTS5 untuk detail.
3. Layanan Embeddings (Opsional)
Untuk pencarian semantik, Synapse membuat vektor embeddings dari konten memori.
Ini disimpan bersama memori dan digunakan untuk pencarian kesamaan.
- Provider: dapat dikonfigurasi (OpenAI, model lokal, dll.)
- Disimpan sebagai kolom di tabel
- Digunakan oleh endpoint
- Lihat Pencarian Semantik
4. MCP Server (Layanan Terpisah)
Synapse MCP server berjalan sebagai proses terpisah (port 13100). Server ini:
- Mengekspos 79 alat melalui Model Context Protocol
- Mendukung transport stdio, HTTP/SSE, dan WebSocket
- Menerjemahkan pemanggilan alat MCP menjadi pemanggilan API Synapse
- Multi-tenant: satu Mind Key per sesi
5. Browser Proxy (Layanan Terpisah)
Untuk otomasi browser, layanan terpisah berbasis Playwright berjalan di port 13000.
MCP server dapat memanggil ini untuk alat .
6. SSH Proxy (Layanan Terpisah)
Untuk perintah remote berbasis SSH, layanan terpisah berjalan di port 12900.
Model Multi-Tenancy
[CODE BLOCK]
Setiap mind sepenuhnya terisolasi. Mind Key memberikan akses ke tepat satu mind.
JWT memberikan akses ke akun pengguna (untuk mengelola mind).
Lihat Multi-Tenancy untuk detail.
Alur Permintaan
Permintaan Penyimpanan Memori
[CODE BLOCK]
Permintaan Pencarian Memori
[CODE BLOCK]
Deployment
Synapse di-deploy sebagai container Docker. Lihat :
[CODE BLOCK]
Karakteristik Performa
| Operasi | Latensi | Throughput |
|-----------|---------|------------|
| Penyimpanan memori | 5ms | 1000+ req/s |
| Recall memori | 20ms | 500 req/s |
| Pencarian FTS5 | 10ms | 800 req/s |
| Pencarian semantik | 50ms | 200 req/s |
| Polling chat | 5ms | 2000 req/s |
Langkah Berikutnya
- Model Memori
- Multi-Tenancy
- Pencarian FTS5
────────────────────────────────────────────────────────────
# Pencarian Teks Penuh FTS5
SUMMARY: Bagaimana Synapse menggunakan SQLite FTS5 untuk pencarian memori teks penuh sub-milidetik.
Pencarian Teks Penuh FTS5
Synapse menggunakan FTS5 (Full-Text Search 5) untuk pencarian memori yang cepat
dan fleksibel. Halaman ini menjelaskan cara kerjanya dan cara menggunakannya
secara efektif.
Apa itu FTS5?
FTS5 adalah ekstensi SQLite (juga tersedia di PostgreSQL melalui ekstensi) yang
menyediakan kemampuan pencarian teks penuh. FTS5:
- Mengindeks konten teks untuk pencarian kata kunci yang cepat
- Mendukung operator boolean (AND, OR, NOT)
- Mendukung pencocokan frasa dengan tanda kutip
- Mendukung pencocokan prefix dengan
- Memberi peringkat hasil berdasarkan relevansi
Synapse menggunakan FTS5 untuk mengindeks semua konten memori, memungkinkan
pencarian sub-milidetik di ribuan memori.
Bagaimana Synapse Menggunakan FTS5
Saat Anda :
1. Konten memori disimpan di tabel
2. Konten juga dimasukkan ke tabel virtual FTS5
3. FTS5 secara otomatis menokenisasi dan mengindeks konten
Saat Anda :
1. Synapse mengurai kueri menggunakan sintaks FTS5
2. Menjalankan terhadap indeks FTS5
3. Memfilter berdasarkan (isolasi tenant)
4. Mengembalikan hasil yang diberi peringkat
Sintaks Kueri
Pencarian kata kunci sederhana
[CODE BLOCK]
Mengembalikan memori yang mengandung "docker".
Beberapa kata kunci (AND implisit)
[CODE BLOCK]
Mengembalikan memori yang mengandung "docker" DAN "swarm".
Pencocokan frasa
[CODE BLOCK]
Mengembalikan memori yang mengandung frasa persis "docker swarm".
Pencocokan prefix
[CODE BLOCK]
Mengembalikan memori yang mengandung kata yang dimulai dengan "docker" (mis.
"dockers", "dockerfile", "dockerize").
Boolean OR
[CODE BLOCK]
Mengembalikan memori yang mengandung "docker" ATAU "kubernetes".
Boolean NOT
[CODE BLOCK]
Mengembalikan memori yang mengandung "docker" tetapi TIDAK "swarm".
Pengelompokan
[CODE BLOCK]
Mengembalikan memori yang mengandung "docker" atau "kubernetes", tetapi tidak "test".
Contoh Praktis
Mencari memori tentang sebuah proyek
[CODE BLOCK]
Mencari frasa persis
[CODE BLOCK]
Mengecualikan memori uji
[CODE BLOCK]
Mencari berdasarkan teknologi
[CODE BLOCK]
Peringkat
FTS5 memberi peringkat hasil berdasarkan relevansi menggunakan algoritma BM25. Faktor:
- Frekuensi istilah (seberapa sering istilah muncul)
- Inverse document frequency (istilah yang lebih langka berperingkat lebih tinggi)
- Panjang dokumen (dokumen lebih pendek dengan istilah tersebut berperingkat lebih tinggi)
- Bobot kolom (title > content)
Hasil dikembalikan dalam urutan peringkat (paling relevan pertama).
Performa
| Operasi | Latensi |
|-----------|---------|
| Mencari 100 memori | < 5ms |
| Mencari 1.000 memori | < 10ms |
| Mencari 10.000 memori | < 25ms |
| Mencari 100.000 memori | < 100ms |
FTS5 sangat dioptimalkan untuk beban kerja yang banyak dibaca.
Batasan
Stemming
FTS5 tidak melakukan stemming secara default. "running" dan "run" adalah istilah yang berbeda.
Solusi: Gunakan pencocokan prefix:
Toleransi typo
FTS5 tidak mendukung pencocokan fuzzy. Typo akan mengembalikan tidak ada hasil.
Solusi: Gunakan pencarian semantik () untuk
pencocokan konseptual.
Stop words
Kata umum (the, a, an, is) diindeks tetapi mungkin tidak berguna untuk pencarian.
FTS5 menangani ini secara otomatis.
FTS5 vs Pencarian Semantik
| Aspek | FTS5 | Pencarian Semantik |
|--------|------|-----------------|
| Kecepatan | Sub-milidetik | 50-100ms |
| Pencocokan | Kata kunci persis | Konseptual |
| Toleransi typo | Tidak ada | Sebagian |
| Stemming | Tidak ada | Implisit |
| Memerlukan embeddings | Tidak | Ya |
| Terbaik untuk | Istilah spesifik | Konsep |
Gunakan FTS5 ketika Anda tahu kata kuncinya. Gunakan pencarian semantik ketika
Anda ingin "memori tentang X" di mana X dideskripsikan secara berbeda.
Praktik Terbaik
> [!TIP]
> - Gunakan istilah spesifik — "docker swarm" lebih baik dari "container orchestration"
> - Kutip frasa — memastikan pencocokan frasa
> - Gunakan prefix untuk variasi — menangkap "deploy", "deployment", "deploying"
> - Kecualikan kebisingan — memfilter memori uji
> - Kombinasikan dengan tag — mempersempit hasil
Langkah Berikutnya
- Pencarian Semantik
- Memory API
- Praktik Terbaik Memori
────────────────────────────────────────────────────────────
# Model Memori
SUMMARY: Bagaimana memori terstruktur — kategori, key, tag, prioritas, sumber, verifikasi.
Model Memori
Model memori Synapse dirancang untuk agen LLM — cukup terstruktur untuk recall
yang andal, cukup fleksibel untuk domain apa pun.
Anatomi Memori
[CODE BLOCK]
Field
| Field | Tipe | Wajib | Deskripsi |
|-------|------|----------|-------------|
| | string | otomatis | ID unik (memxxx) |
| | enum | ✅ | Salah satu dari 8 kategori |
| | string | ✅ | Identifier stabil (digunakan untuk pembaruan) |
| | string | ✅ | Konten memori (teks apa pun) |
| | string[] | – | Untuk pencarian dan pemfilteran |
| | enum | – | low, normal, high, critical (default: normal) |
| | enum | otomatis | user, agent (siapa yang menyimpan) |
| | bool | otomatis | Apakah manusia telah memverifikasi ini? |
| | float | – | 0.0 hingga 1.0 (default: 1.0 untuk user, 0.7 untuk agent) |
| | timestamp | – | Kapan harus melupakan memori ini |
| | string | otomatis | Mind mana yang memilikinya |
| | timestamp | otomatis | Pertama disimpan |
| | timestamp | otomatis | Terakhir dimodifikasi |
Kategori
Delapan kategori mencakup kasus penggunaan agen LLM umum:
| Kategori | Tujuan | Contoh Konten |
|----------|---------|-----------------|
| | Siapa pengguna | "User is Michael Schäfer, software engineer in Berlin" |
| | Preferensi pengguna | "Prefers concise technical responses" |
| | Fakta yang dapat diverifikasi | "Office is in Berlin, timezone Europe/Berlin" |
| | Status proyek | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| | Keahlian pengguna | "Advanced Python, 10+ years" |
| | Error masa lalu | "Forgot to bump npm version — CI failed" |
| | Konteks sesi | "Currently reviewing PR #42" |
| | Catatan lain-lain | "Try Redis for caching next sprint" |
Key: Identifier Stabil
Field sangat penting — ini adalah cara Anda memperbarui memori tanpa
membuat duplikat.
[CODE BLOCK]
Aturan key:
- Harus unik dalam (category, mind)
- Gunakan
- Awali dengan kategori untuk kejelasan: ,
- Tetap stabil — jangan mengubah key setelah dibuat
Tag: Untuk Pencarian
Tag memungkinkan pemfilteran dan pencarian cepat:
[CODE BLOCK]
Praktik terbaik tag:
- 2-5 tag per memori (jangan terlalu banyak tag)
- Huruf kecil untuk konsistensi
- Gunakan nama proyek, topik, teknologi
- Tag tidak case-sensitive
Level Prioritas
| Prioritas | Kapan Menggunakan | Perilaku Recall |
|----------|-------------|-----------------|
| | Identitas, hukum, ireversibel | Selalu di atas recall |
| | Proyek aktif, preferensi utama | Menonjol dalam recall |
| | Sebagian besar memori (default) | Urutan recall standar |
| | Efemeral, bagus untuk diketahui | Mungkin diringkas |
mengurutkan berdasarkan prioritas (critical pertama), lalu berdasarkan kebaruan.
Source: User vs Agent
Memori ditandai dengan :
- — disimpan oleh manusia (melalui JWT atau UI manusia)
- — disimpan oleh agen LLM (melalui Mind Key)
Ini memengaruhi:
- Verifikasi: memori otomatis terverifikasi, memori tidak
- Confidence: default 1.0, 0.7
- Recall: menandai memori yang belum terverifikasi dengan "(unverified)"
> [!NOTE]
> Perlakukan memori sumber dengan skeptisisme yang sesuai. Mereka mungkin
> disimpulkan atau diasumsikan daripada dinyatakan langsung oleh pengguna.
Verifikasi
Flag menunjukkan manusia telah mengonfirmasi memori:
- Memori : otomatis terverifikasi ()
- Memori : default belum terverifikasi ()
Verifikasi memori melalui:
[CODE BLOCK]
> [!NOTE]
> Verifikasi memerlukan JWT (autentikasi manusia), bukan Mind Key (autentikasi
> agen). Ini memastikan hanya manusia yang dapat menandai memori sebagai terverifikasi.
Confidence
Field (0.0 hingga 1.0) menunjukkan seberapa andal memori tersebut:
- 1.0 — dinyatakan langsung oleh pengguna
- 0.7 — disimpulkan oleh agen
- 0.5 — tidak pasti, perlu verifikasi
- 0.0 — secara eksplisit diragukan
Tetapkan confidence saat menyimpan:
[CODE BLOCK]
Kedaluwarsa
Tetapkan untuk memori yang sensitif terhadap waktu:
[CODE BLOCK]
Memori kedaluwarsa tidak dikembalikan oleh (tetapi masih ada di DB).
Gunakan untuk melihat memori yang akan segera kedaluwarsa.
Siklus Hidup Memori
[CODE BLOCK]
Perilaku Recall
mengembalikan ringkasan teks polos yang dioptimalkan untuk konteks LLM:
[CODE BLOCK]
- Diurutkan berdasarkan prioritas (critical → low), lalu berdasarkan kebaruan
- Memori yang belum terverifikasi ditandai dengan
- Tag disertakan untuk konteks
- Teks polos (tidak perlu parsing JSON)
Langkah Berikutnya
- Memory API
- Praktik Terbaik Memori
- Pencarian FTS5
────────────────────────────────────────────────────────────
# Multi-Tenancy & Isolasi
SUMMARY: Bagaimana Synapse mengisolasi data antar pengguna dan mind — batasan keamanan dijelaskan.
Multi-Tenancy & Isolasi
Synapse bersifat multi-tenant: beberapa pengguna, masing-masing dengan beberapa
mind, sepenuhnya terisolasi satu sama lain. Halaman ini menjelaskan model
isolasi.
Hierarki Tenant
[CODE BLOCK]
Level Isolasi
Level 1: Isolasi Pengguna
Setiap akun pengguna terisolasi. Alice tidak dapat:
- Melihat mind Bob
- Mengakses memori Bob (bahkan dengan JWT miliknya)
- Mendaftar info akun Bob
Diterapkan oleh: kolom di semua tabel, JWT berisi , semua
kueri memfilter berdasarkan .
Level 2: Isolasi Mind
Dalam satu pengguna, setiap mind terisolasi. Mind A tidak dapat:
- Melihat memori Mind B
- Mengakses tugas, chat, skrip Mind B
Diterapkan oleh: kolom di semua tabel data, Mind Key berisi ,
semua kueri memfilter berdasarkan .
> [!CRITICAL]
> Isolasi Mind Key adalah batasan keamanan utama. Mind Key yang bocor
> memberikan akses penuh ke data mind tersebut — tetapi HANYA mind itu.
Token Autentikasi
| Token | Cakupan | Apa yang dapat diakses |
|-------|-------|-------------------|
| Mind Key | Satu mind | Hanya data mind tersebut |
| JWT | Akun pengguna | Manajemen akun (buat/daftar/hapus mind) |
| Computer Token | Satu komputer | Perintah komputer tersebut |
Akses Lintas-Mind
Dalam pengguna yang sama
Pengguna dapat mengakses semua mind mereka melalui JWT (mis.
mendaftar semua). Tetapi untuk membaca/menulis data memori, mereka memerlukan
Mind Key spesifik.
Antar pengguna
Pengguna tidak dapat mengakses data satu sama lain — KECUALI mereka secara
eksplisit berbagi mind melalui Sharing API:
[CODE BLOCK]
Setelah dibagikan, Bob dapat mengakses Mind A melalui JWT miliknya (read-only jika ).
Batasan Keamanan
[CODE BLOCK]
Pola Multi-Tenancy Umum
Pola 1: Satu Pengguna, Satu Mind
Paling umum untuk pengguna agen LLM individu.
- 1 akun pengguna
- 1 mind
- 1 Mind Key
- Semua memori dalam satu cakupan
Pola 2: Satu Pengguna, Beberapa Mind
Untuk pengguna dengan beberapa konteks (kerja, pribadi, proyek).
- 1 akun pengguna
- N mind (mis. "kerja", "pribadi", "proyek-x")
- N Mind Key
- Setiap sesi LLM menggunakan satu Mind Key
Pola 3: Mind Tim Bersama
Untuk tim yang berkolaborasi dalam suatu proyek.
- 1 pengguna membuat mind (mendapatkan Mind Key)
- Pembuat berbagi dengan anggota tim melalui JWT
- Semua anggota tim mengakses melalui JWT (atau Mind Key bersama)
> [!WARNING]
> Berbagi Mind Key memberikan akses baca/tulis penuh. Untuk kolaborasi tim,
> lebih baik gunakan Sharing API (berbasis JWT) daripada berbagi Mind Key secara langsung.
Pola 4: Penyedia SaaS
Untuk aplikasi yang menyematkan Synapse sebagai lapisan memori mereka.
- Setiap pelanggan = 1 akun pengguna
- Setiap proyek pelanggan = 1 mind
- Aplikasi menyimpan Mind Key per pelanggan/proyek
- Isolasi penuh antar pelanggan
Verifikasi Isolasi
Tes: Mind Key tidak dapat mengakses mind lain
[CODE BLOCK]
Tes: JWT tidak dapat membaca data memori langsung
[CODE BLOCK]
Praktik Terbaik
> [!TIP]
> - Gunakan satu mind per proyek/konteks — isolasi adalah teman Anda
> - Jangan pernah berbagi Mind Key — gunakan Sharing API sebagai gantinya
> - Rotasi Mind Key jika terkompromi (hapus mind, buat baru)
> - Audit mind yang dibagikan — tinjau secara berkala
> - Gunakan JWT untuk UI manusia — jangan pernah mengekspos Mind Key ke pengguna akhir
Langkah Berikutnya
- Autentikasi
- Mind Key vs JWT
- Arsitektur
────────────────────────────────────────────────────────────
# Pencarian Semantik (Embeddings)
SUMMARY: Pencarian memori konseptual menggunakan vektor embeddings — temukan berdasarkan makna, bukan hanya kata kunci.
Pencarian Semantik (Embeddings)
Synapse mendukung pencarian semantik menggunakan vektor embeddings. Berbeda
dengan FTS5 (pencocokan kata kunci), pencarian semantik menemukan memori
berdasarkan makna — bahkan jika tidak ada kata kunci yang cocok.
Cara Kerja
[CODE BLOCK]
Apa itu embeddings?
Embeddings adalah representasi vektor numerik dari teks. Teks dengan makna
serupa memiliki vektor yang serupa. Synapse membuat vektor (mis. 1536 dimensi)
untuk konten setiap memori.
Cosine similarity
Untuk menemukan memori yang mirip secara semantik, Synapse menghitung cosine
similarity antara vektor kueri dan setiap vektor memori. Kesamaan lebih tinggi
= lebih relevan.
Kapan Menggunakan Pencarian Semantik
Gunakan pencarian semantik ketika:
- Anda ingin "memori tentang X" di mana X dideskripsikan secara berbeda dari yang disimpan
- FTS5 tidak mengembalikan hasil (tidak ada cocok kata kunci)
- Anda ingin pengelompokan konseptual (mis. semua memori "deployment", bahkan jika beberapa menyebut "release")
- Kueri adalah pertanyaan: "bagaimana kita menangani autentikasi?"
Gunakan FTS5 ketika:
- Anda tahu kata kunci persis
- Anda memerlukan logika boolean (AND, OR, NOT)
- Anda memerlukan respons sub-milidetik
- Anda ingin pencocokan frasa
Endpoint
GET /memory/semantic-search
[CODE BLOCK]
Respons:
[CODE BLOCK]
Contoh
Mencari memori deployment
[CODE BLOCK]
Mengembalikan memori tentang "deployment", "release", "publishing", "rolling out",
dll.
Mencari pola autentikasi
[CODE BLOCK]
Mengembalikan memori tentang login, auth, JWT, manajemen sesi, OAuth, dll.
Mencari memori serupa
[CODE BLOCK]
Menggunakan kesamaan semantik (melalui tag bersama DAN vektor embeddings).
Pembuatan Embedding
Kapan embeddings dibuat?
- Saat penyimpanan memori — jika layanan embeddings dikonfigurasi, embedding dibuat secara sinkron
- Pembuatan batch — membuat embeddings untuk memori yang belum memilikinya
- Pembaruan asinkron — saat konten diperbarui, embedding dibuat ulang
Provider embedding
Synapse mendukung provider embedding yang dapat dikonfigurasi:
- OpenAI (, )
- Model lokal (melalui Ollama atau serupa)
- Khusus (implementasikan antarmuka embeddings)
Konfigurasi melalui variabel lingkungan:
[CODE BLOCK]
Pembuatan batch
Untuk mind dengan banyak memori yang belum memiliki embeddings:
[CODE BLOCK]
Performa
| Operasi | Latensi |
|-----------|---------|
| Membuat embedding (OpenAI) | 100-200ms |
| Pencarian semantik (1k memori) | 50-100ms |
| Pencarian semantik (10k memori) | 200-500ms |
| Pembuatan batch (100 memori) | 10-20s |
> [!NOTE]
> Pencarian semantik lebih lambat dari FTS5 karena komputasi vektor. Gunakan
> FTS5 untuk kata kunci yang diketahui, semantik untuk kueri konseptual.
Batasan
Biaya embeddings
Jika menggunakan OpenAI, membuat embeddings memerlukan biaya ($0,02 per 1M
token untuk text-embedding-3-small). Untuk 10.000 memori rata-rata 100 token
masing-masing, itu $0,02 — dapat diabaikan.
Cold start
Memori yang disimpan sebelum embeddings dikonfigurasi tidak akan memiliki
embeddings. Jalankan untuk backfill.
Ketergantungan provider
Jika provider embeddings tidak aktif, pencarian semantik gagal dengan baik
(mengembalikan hasil kosong atau error). FTS5 masih berfungsi.
Saat Embeddings Tidak Tersedia
Jika layanan embeddings tidak dikonfigurasi:
- mengembalikan 503 Service Unavailable
- masih berfungsi (hanya tidak ada embedding yang dibuat)
- Pencarian FTS5 masih berfungsi
Praktik Terbaik
> [!TIP]
> - Gunakan semantik untuk kueri konseptual — "bagaimana kita menangani X?"
> - Gunakan FTS5 untuk istilah spesifik — "docker swarm"
> - Backfill embeddings secara teratur —
> - Pantau kesehatan provider — pencarian semantik bergantung padanya
> - Kombinasikan dengan tag — semantik + filter tag mempersempit hasil
Langkah Berikutnya
- Pencarian FTS5
- Memory API
- Arsitektur
## KATEGORI: BUKU RESEP LLM
Resep dan pola untuk agen LLM.
────────────────────────────────────────────────────────────
# Pola Polling Chat
SUMMARY: Cara melakukan polling untuk pesan manusia di antara pemanggilan alat tanpa memblokir alur kerja Anda.
Pola Polling Chat
Sistem chat bersifat asinkron — manusia dapat meninggalkan pesan saat Anda bekerja.
Pola ini menunjukkan cara melakukan polling untuk pesan tanpa memblokir alur kerja Anda.
Pola
[CODE BLOCK]
Polling di antara pemanggilan alat, bukan dalam loop ketat.
Mengapa Polling di Antara Pemanggilan Alat?
- Jangan memblokir — polling dalam loop ketat membuang panggilan API
- Jangan lewatkan pesan — polling terlalu jarang berarti respons lambat
- Titik manis — polling setiap 30-60 detik, atau setelah setiap pemanggilan alat
Implementasi
Polling dasar
[CODE BLOCK]
Pola 1: Polling setelah setiap pemanggilan alat
[CODE BLOCK]
Pola 2: Polling berbasis waktu
[CODE BLOCK]
Pola 3: Event-driven (dengan webhook)
Untuk notifikasi real-time, daftarkan webhook:
[CODE BLOCK]
Kemudian handler webhook Anda dapat membangunkan agen:
[CODE BLOCK]
Pola Penanganan Pesan
Pola: Konfirmasi lalu proses
[CODE BLOCK]
Pola: Antri untuk pemrosesan batch
[CODE BLOCK]
Pola: Routing prioritas
[CODE BLOCK]
Frekuensi Polling
| Kasus Penggunaan | Frekuensi |
|----------|-----------|
| Agen interaktif (manusia menunggu) | Setiap 5-10 detik |
| Agen latar belakang | Setiap 30-60 detik |
| Pemrosesan batch | Setiap 5 menit |
| Dipicu webhook | Jangan polling — gunakan webhook |
> [!WARNING]
> Polling lebih dari sekali per 5 detik membuang panggilan API. Endpoint
> mengembalikan langsung jika ada pesan tertunda, jadi tidak ada
> manfaat polling lebih cepat.
Chat Multi-Agent
Untuk komunikasi agen-ke-agen:
[CODE BLOCK]
Praktik Terbaik
> [!TIP]
> - Polling di antara pemanggilan alat — bukan dalam loop ketat
> - Konfirmasi segera — manusia tahu Anda menerima pesan
> - Proses secara asinkron — jangan memblokir pada pekerjaan panjang
> - Gunakan webhook untuk real-time — polling memiliki latensi
> - Jangan polling lebih dari sekali per 5 detik — membuang panggilan API
Masalah Umum
Pesan hilang
- secara otomatis menandai pesan sebagai dibaca
- Jika Anda tidak memprosesnya, mereka hilang
- Perbaikan: Selalu proses pesan sebelum kembali
Balasan duplikat
- Jika handler Anda crash, Anda mungkin membalas dua kali
- Perbaikan: Buat handler idempoten (periksa jika sudah dibalas)
Respons lambat
- Polling setiap 60d berarti latensi hingga 60d
- Perbaikan: Polling setiap 10-30d, atau gunakan webhook
Langkah Berikutnya
- Chat API
- Pola Awal Sesi
- Pemulihan Error
────────────────────────────────────────────────────────────
# Pemulihan Error untuk Agen
SUMMARY: Bagaimana agen LLM harus menangani dan memulihkan diri dari error — coba ulang, simpan, belajar.
Pemulihan Error untuk Agen
Error terjadi. Jaringan gagal, API mengembalikan 500, Mind Key kedaluwarsa.
Panduan ini menunjukkan bagaimana agen LLM harus menangani error dengan baik
dan belajar darinya.
Prinsip Penanganan Error
1. Coba ulang dengan backoff — error sementara sering terselesaikan
2. Simpan error — belajar dari pola
3. Degrade dengan baik — jangan crash seluruh sesi
4. Beri tahu manusia — untuk error yang tidak dapat Anda selesaikan
Penanganan Error HTTP
Coba ulang dengan exponential backoff
[CODE BLOCK]
Penanganan error autentikasi
[CODE BLOCK]
Menyimpan Error sebagai Memori
Saat error terjadi, simpan agar sesi mendatang dapat belajar:
[CODE BLOCK]
Skenario Error Umum
Skenario 1: Mind Key Tidak Valid
[CODE BLOCK]
Skenario 2: Error Jaringan
[CODE BLOCK]
Skenario 3: Rate Limited
[CODE BLOCK]
Skenario 4: Error Server (5xx)
[CODE BLOCK]
Skenario 5: Pemanggilan Alat Gagal
[CODE BLOCK]
Pola: Circuit Breaker
Untuk kegagalan berulang, berhenti mencoba sementara:
[CODE BLOCK]
Praktik Terbaik
> [!TIP]
> - Selalu coba ulang error sementara — jaringan gagal, server cegukan
> - Jangan coba ulang error klien (4xx) — mereka tidak akan memperbaiki diri sendiri
> - Simpan error sebagai memori — belajar dari pola
> - Beri tahu manusia untuk error critical — mereka perlu tahu
> - Degrade dengan baik — pekerjaan parsial lebih baik daripada crash
> - Gunakan circuit breaker — jangan membombardir layanan yang gagal
Langkah Berikutnya
- Referensi API Errors
- Pola Awal Sesi
- Pengujian Self-Healing
────────────────────────────────────────────────────────────
# Strategi Penandaan Memori
SUMMARY: Cara menandai memori untuk pencarian dan pemfilteran efektif — sistem penandaan yang skalabel.
Strategi Penandaan Memori
Tag adalah rahasia untuk pengambilan memori yang skalabel. Panduan ini
menunjukkan cara menandai memori sehingga yang tepat kembali pada waktu yang tepat.
Mengapa Tag Penting
Tanpa tag, Anda memiliki pencarian teks penuh datar. Dengan tag, Anda memiliki
navigasi terstruktur:
[CODE BLOCK]
Tag memungkinkan:
- Pemfilteran cepat —
- Pencarian tercakup —
- Pengelompokan — temukan semua memori "mistake" untuk sebuah proyek
- Referensi silang — memori yang berbagi tag terkait
Skema Penandaan
Tag proyek
Gunakan nama proyek sebagai tag:
[CODE BLOCK]
Tag teknologi
Gunakan nama teknologi:
[CODE BLOCK]
Tag topik
Gunakan kategori topik:
[CODE BLOCK]
Tag status
Gunakan indikator status:
[CODE BLOCK]
Tag tipe
Gunakan indikator tipe:
[CODE BLOCK]
Aturan Penandaan
Aturan 1: 2-5 tag per memori
Terlalu sedikit tag = discoverability buruk. Terlalu banyak = kebisingan.
[CODE BLOCK]
Aturan 2: Huruf kecil, dipisahkan tanda hubung
[CODE BLOCK]
Aturan 3: Gunakan kosakata yang konsisten
Tetapkan kosakata penandaan dan patuhi:
[CODE BLOCK]
Aturan 4: Tandai dengan niat pencarian
Tanyakan: "Bagaimana saya akan mencari memori ini?"
[CODE BLOCK]
Pola
Pola 1: Proyek + Topik
[CODE BLOCK]
Pencarian: (semua memori proyek Synapse)
Pencarian: (memori deployment di Synapse)
Pola 2: Tipe + Domain
[CODE BLOCK]
Pencarian: (semua kesalahan)
Pencarian: (kesalahan deployment)
Pola 3: Hierarkis
Untuk sub-proyek dalam proyek:
[CODE BLOCK]
Pencarian: (semua Synapse)
Pencarian: (hanya sub-proyek docs)
Pola 4: Pelacakan status
[CODE BLOCK]
Kasus Penggunaan Umum
Temukan semua keputusan tentang sebuah proyek
[CODE BLOCK]
Temukan semua kesalahan dalam sebuah domain
[CODE BLOCK]
Temukan pekerjaan aktif
[CODE BLOCK]
Temukan memori tentang sebuah teknologi
[CODE BLOCK]
Pemeliharaan Tag
Tinjauan berkala
[CODE BLOCK]
Menggabungkan tag
Jika Anda memiliki tag yang tidak konsisten ( dan ), gabungkan:
[CODE BLOCK]
Praktik Terbaik
> [!TIP]
> - Tetapkan kosakata sejak awal — tag konsisten dari hari 1
> - Tandai dengan niat pencarian — bagaimana Anda akan menemukan ini nanti?
> - 2-5 tag adalah titik manis — terlalu sedikit atau terlalu banyak itu buruk
> - Huruf kecil + tanda hubung — bukan
> - Tinjau secara berkala — gabungkan duplikat, hapus yang tidak digunakan
Langkah Berikutnya
- Praktik Terbaik Memori
- Pencarian FTS5
- Alur Kerja Berbasis Tugas
────────────────────────────────────────────────────────────
# Pola Awal Sesi
SUMMARY: Urutan awal sesi kanonik yang harus diikuti setiap agen LLM.
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.
Pola Awal Sesi
Setiap sesi agen LLM harus mengikuti urutan startup kanonik ini. Melewatkan
langkah mengarah pada konteks yang hilang, pesan yang terlewat, dan tugas yang terlupakan.
Pola
[CODE BLOCK]
Implementasi
Langkah 1: Recall Semua Memori
> [!CRITICAL]
> Ini adalah panggilan terpenting. Tanpa ini, Anda tidak memiliki memori sesi
> masa lalu.
[CODE BLOCK]
Mengembalikan ringkasan teks polos dari semua memori, diurutkan berdasarkan prioritas.
Langkah 2: Polling Pesan Chat Belum Dibaca
[CODE BLOCK]
Mengembalikan pesan belum dibaca dari manusia. Secara otomatis menandainya sebagai dibaca.
Langkah 3: Periksa Tugas yang Sedang Berjalan
[CODE BLOCK]
Mengembalikan tugas yang sedang Anda kerjakan di sesi terakhir.
Langkah 4: Bangun Konteks
Gabungkan tiga respons ke dalam system prompt Anda:
[CODE BLOCK]
Langkah 5: Proses Item Tertunda
[CODE BLOCK]
Contoh Lengkap
[CODE BLOCK]
Kesalahan Umum
> [!WARNING]
> - Melewatkan recall — Anda memulai tanpa konteks, mengulang kesalahan masa lalu
> - Lupa polling chat — pesan manusia tidak dijawab
> - Mengabaikan tugas aktif — pekerjaan terlupakan di tengah eksekusi
> - Tidak menyimpan apa pun — sesi tidak menghasilkan nilai persisten
Variasi
Pola minimal (LLM konteks rendah)
Untuk LLM dengan jendela konteks kecil, lewati recall penuh:
[CODE BLOCK]
Kemudian cari topik spesifik sesuai kebutuhan:
[CODE BLOCK]
Pola agresif (agen berjalan lama)
Untuk agen yang berjalan berjam-jam, tambahkan re-recall berkala:
[CODE BLOCK]
Langkah Berikutnya
- Strategi Penandaan Memori
- Alur Kerja Berbasis Tugas
- Pola Polling Chat
────────────────────────────────────────────────────────────
# Alur Kerja Berbasis Tugas
SUMMARY: Gunakan tugas Synapse untuk mendorong alur kerja LLM multi-langkah yang bertahan lintas sesi.
Alur Kerja Berbasis Tugas
Tugas bukan hanya todo — mereka adalah tulang punggung alur kerja LLM persisten.
Dengan membuat tugas untuk pekerjaan multi-langkah, Anda memastikan kontinuitas
lintas sesi dan menyediakan jejak audit untuk apa yang telah dilakukan.
Mengapa Berbasis Tugas?
Tanpa tugas:
- LLM memulai setiap sesi tidak yakin apa yang harus dilakukan
- Pekerjaan multi-langkah terlupakan di tengah eksekusi
- Tidak ada catatan apa yang telah dilakukan
Dengan tugas:
- LLM melanjutkan tugas yang sedang berjalan segera
- Pekerjaan multi-langkah bertahan lintas sesi
- Jejak audit bawaan dari semua pekerjaan
Pola
[CODE BLOCK]
Implementasi
Langkah 1: Buat tugas untuk pekerjaan multi-langkah
[CODE BLOCK]
Langkah 2: Lacak kemajuan dalam deskripsi tugas
[CODE BLOCK]
Langkah 3: Lanjutkan lintas sesi
[CODE BLOCK]
Langkah 4: Selesaikan dan arsipkan
[CODE BLOCK]
Contoh Lengkap: Alur Kerja Deploy
[CODE BLOCK]
Hierarki Tugas
Untuk pekerjaan kompleks, gunakan hubungan tugas parent-child:
[CODE BLOCK]
Cari sub-tugas:
[CODE BLOCK]
Alur Kerja Status
[CODE BLOCK]
Pending
Tugas dibuat tetapi belum dimulai. Gunakan untuk pekerjaan yang direncanakan.
In Progress
Sedang dikerjakan. Perbarui deskripsi dengan kemajuan.
Done
Selesai dengan sukses. Deskripsi harus menyertakan ringkasan.
Cancelled
Ditinggalkan. Deskripsi harus menyertakan alasan.
Praktik Terbaik
> [!TIP]
> - Buat tugas untuk pekerjaan multi-langkah — pekerjaan satu langkah tidak perlu tugas
> - Perbarui deskripsi dengan kemajuan — memungkinkan kelanjutan
> - Gunakan prioritas tinggi untuk pekerjaan aktif — muncul dalam recall
> - Selesaikan tugas saat selesai — jangan biarkan inprogress
> - Simpan ringkasan penyelesaian sebagai memori — referensi jangka panjang
Pola Umum
Pola: Alur Kerja Perbaikan Bug
[CODE BLOCK]
Pola: Alur Kerja Riset
[CODE BLOCK]
Langkah Berikutnya
- Pola Awal Sesi
- Pola Polling Chat
- Pemulihan Error
## KATEGORI: PERTANYAAN UMUM
Pertanyaan umum dan masalah umum.
────────────────────────────────────────────────────────────
# FAQ API
SUMMARY: Pertanyaan API umum — autentikasi, rate limits, penanganan error, penemuan endpoint.
FAQ API
Pertanyaan umum tentang API Synapse.
Bagaimana cara saya melakukan autentikasi?
Dua metode:
1. Mind Key (untuk endpoint data):
2. JWT (untuk endpoint akun):
Atau melalui parameter query (batas 60 req/menit):
Lihat Autentikasi.
Apa perbedaan antara Mind Key dan JWT?
- Mind Key: cakupan tenant, tidak pernah kedaluwarsa, untuk data memori/chat/tugas
- JWT: cakupan pengguna, kedaluwarsa 7 hari, untuk manajemen akun/mind
Lihat Mind Key vs JWT.
Mengapa saya mendapat 401 Unauthorized?
Penyebab umum:
1. Header tidak ada
2. Mind Key tidak valid (verifikasi dimulai dengan )
3. Menggunakan JWT di mana Mind Key diperlukan (atau sebaliknya)
4. Mind Key telah dicabut
Perbaikan: Verifikasi token Anda. Lihat Autentikasi.
Mengapa saya mendapat 404 Not Found?
Anda menggunakan path endpoint yang salah. Synapse hanya memiliki path yang
tercantum di .
Perbaikan: Panggil untuk melihat semua path yang valid. Jangan menebak.
Mengapa saya mendapat 429 Too Many Requests?
Anda menggunakan autentikasi parameter query , yang di-rate-limit ke 60/menit.
Perbaikan: Beralih ke header (tanpa rate limit).
Lihat Rate Limits.
Bagaimana cara mendaftar semua endpoint?
[CODE BLOCK]
Bagaimana cara menemukan endpoint yang tepat?
1. Periksa untuk daftar yang dapat dibaca mesin
2. Periksa untuk dokumentasi API lengkap
3. Telusuri untuk sistem dokumentasi
4. Gunakan untuk spesifikasi OpenAPI 3.0
Bisakah saya menggunakan GET alih-alih POST?
Beberapa endpoint POST memiliki padanan GET untuk alat yang hanya menggunakan URL:
- ↔
- ↔
- ↔
Periksa untuk varian GET yang tersedia.
Bagaimana cara saya menangani error?
Semua error mengembalikan JSON:
[CODE BLOCK]
Lihat Errors & Error Handling.
Berapa batas body permintaan?
10 MB. Untuk payload yang lebih besar (mis. unggahan file), gunakan endpoint multipart.
Apakah API mendukung CORS?
Ya. Semua endpoint mengembalikan:
[CODE BLOCK]
Apakah ada SDK?
Ya:
- Node.js:
- MCP:
Lihat Ikhtisar API untuk detail.
Bagaimana cara melakukan paginasi?
Gunakan dan :
[CODE BLOCK]
Limit default: 100. Maksimum: 500.
Bisakah saya memfilter memori berdasarkan kategori atau tag?
Ya:
[CODE BLOCK]
Bagaimana cara mencari memori?
Dua cara:
1. Pencarian kata kunci FTS5:
2. Pencarian semantik:
Lihat Pencarian FTS5 dan Pencarian Semantik.
Bagaimana cara memperbarui memori?
POST dengan + yang sama — memori yang ada
diperbarui, tidak diduplikasi.
[CODE BLOCK]
Bagaimana cara menghapus memori?
[CODE BLOCK]
Bisakah saya menghapus secara massal?
Ya:
[CODE BLOCK]
Langkah Berikutnya
- Ikhtisar API
- Errors & Error Handling
- Autentikasi
────────────────────────────────────────────────────────────
# FAQ Umum
SUMMARY: Pertanyaan umum tentang Synapse — apa itu, bagaimana cara kerjanya, untuk siapa.
FAQ Umum
Pertanyaan umum tentang Synapse.
Apa itu Synapse?
Synapse adalah API memori persisten untuk agen LLM. API ini memberikan
asisten AI Anda otak permanen yang dapat dikueri yang bertahan di seluruh sesi.
Alih-alih melupakan semuanya saat chat ditutup, LLM menyimpan dan mengambil
memori melalui HTTP API sederhana.
Pelajari lebih lanjut: Apa itu Synapse?
Untuk siapa Synapse?
- Pengembang agen LLM yang membutuhkan state persisten
- Power user yang menjalankan LLM lokal dengan agen khusus
- Tim yang membangun asisten AI dengan memori bersama
- Insinyur otomasi yang merangkai pemanggilan LLM lintas sesi
Apakah Synapse gratis?
Synapse di-host di dan gratis untuk penggunaan pribadi.
Untuk self-hosting, lihat repo.
Bagaimana Synapse berbeda dari ChatGPT Memory?
| Fitur | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| Penyimpanan | Server OpenAI | Server Anda |
| Akses API | Tidak | Ya (REST + MCP) |
| Multi-tenant | Tidak | Ya (minds) |
| Kategori khusus | Tidak | Ya (8 kategori) |
| Pencarian teks penuh | Terbatas | FTS5 + semantik |
| Dapat di-self-host | Tidak | Ya |
LLM apa yang bekerja dengan Synapse?
LLM apa pun yang dapat melakukan panggilan HTTP atau menggunakan MCP:
- Claude (Anthropic) — melalui MCP atau API langsung
- GPT-4 / GPT-3.5 (OpenAI) — melalui function calling + API
- Gemini (Google) — melalui function calling + API
- Llama / Mistral (lokal) — melalui integrasi khusus
- LLM apa pun melalui Synapse MCP server
Apakah saya perlu meng-host Synapse sendiri?
Tidak. Versi hosted di tersedia untuk
penggunaan publik. Self-hosting opsional (untuk privasi, kustomisasi, atau
lingkungan air-gapped).
Berapa banyak data yang dapat saya simpan?
Tidak ada batasan keras pada versi hosted. Penggunaan tipikal:
- 100-1000 memori per mind
- 1-10 KB per memori (field content)
- Total: 10 MB per mind
Untuk skala yang lebih besar, lakukan self-host.
Apakah data saya privat?
Ya. Setiap mind terisolasi (lihat Multi-Tenancy).
Pengguna lain tidak dapat melihat data Anda. Penyedia hosting (Schäfer Services)
memiliki akses tetapi tidak melihat data pengguna.
Untuk privasi maksimum, lakukan self-host.
Bisakah saya mengekspor data saya?
Ya. Gunakan untuk mengekspor semua memori sebagai JSON. Lihat
Backup & Restore.
Apa yang terjadi jika saya kehilangan Mind Key?
Mind Key hanya ditampilkan sekali saat pembuatan. Jika hilang:
1. Login dengan email/kata sandi Anda untuk mendapatkan JWT
2. Buat mind baru melalui
3. Simpan Mind Key baru
4. (Opsional) Hapus mind lama melalui
Anda tidak dapat memulihkan memori dari mind yang key-nya hilang.
Bisakah beberapa agen LLM berbagi satu mind?
Ya. Semua agen yang menggunakan Mind Key yang sama berbagi data mind tersebut. Untuk
kerja multi-agen yang terkoordinasi, lihat Koordinasi Multi-Agent.
Apakah Synapse bekerja offline?
Tidak, Synapse memerlukan koneksi internet ke server (baik hosted atau
self-hosted). Untuk LLM offline, jalankan Synapse secara lokal.
Seberapa cepat pencarian memori?
- Pencarian kata kunci FTS5: < 10ms untuk 1000 memori
- Pencarian semantik: 50-100ms untuk 1000 memori
- Recall penuh: < 50ms untuk 1000 memori
Lihat Pencarian FTS5 untuk detail.
Bisakah saya menggunakan Synapse tanpa LLM?
Ya. Synapse adalah API memori generik. Anda dapat menggunakannya dari aplikasi
apa pun yang mendapat manfaat dari penyimpanan key-value persisten yang dapat
dicari dengan kategori dan tag.
Langkah Berikutnya
- Apa itu Synapse?
- Quick Start
- FAQ API
────────────────────────────────────────────────────────────
# FAQ MCP
SUMMARY: Pertanyaan umum tentang integrasi MCP — alat, transport, troubleshooting.
FAQ MCP
Pertanyaan umum tentang Synapse MCP server.
Apa itu MCP?
MCP (Model Context Protocol) adalah standar terbuka oleh Anthropic untuk
integrasi LLM-alat. Alih-alih menempelkan dokumentasi API ke dalam prompt, Anda
mendaftarkan alat dengan MCP server, dan LLM memanggilnya sebagai fungsi native.
Lihat Apa itu MCP?.
Berapa banyak alat yang diekspos Synapse MCP?
79 alat dalam 12 kategori: memori, chat, scheduler, tugas, skrip,
komputer, push, pengguna, utilitas, visualisasi, berbagi, webhooks, browser.
Lihat Apa itu MCP? untuk daftar lengkap.
Klien MCP mana yang didukung?
- Claude Desktop (macOS, Windows)
- Claude Code (terminal)
- Cursor (IDE)
- Continue.dev (VS Code, JetBrains)
- Cline (VS Code)
- Klien apa pun yang kompatibel dengan MCP
Lihat Pengaturan Claude Desktop untuk contoh konfigurasi.
Transport apa yang didukung?
1. stdio (lokal, disarankan untuk desktop)
2. HTTP/SSE (remote, multi-tenant)
3. WebSocket (mobile, volume tinggi)
Bagaimana cara mengonfigurasi Claude Desktop?
Edit :
[CODE BLOCK]
Lihat Pengaturan Claude Desktop.
Mengapa alat tidak muncul di Claude Desktop?
1. Mulai ulang Claude Desktop sepenuhnya (Cmd+Q di macOS)
2. Periksa file konfigurasi adalah JSON yang valid
3. Verifikasi Node.js 18+ terpasang
4. Periksa log MCP:
Lihat MCP Troubleshooting.
Bagaimana cara menggunakan mind yang berbeda?
Ubah di konfigurasi MCP Anda dan mulai ulang klien.
Untuk beberapa mind, jalankan beberapa instansi MCP server dengan Mind Key berbeda.
Bisakah saya membatasi alat mana yang diekspos?
Ya, gunakan Tool Profiles:
- : 8 alat komposit (500 token)
- : 25 alat (2.500 token)
- : 119 alat (8.250 token, default)
Atur melalui env var atau header .
Bagaimana cara men-debug masalah MCP?
1. Jalankan MCP server secara manual:
2. Periksa log klien (bervariasi per klien)
3. Verifikasi Mind Key berfungsi:
4. Periksa health Synapse:
Lihat MCP Troubleshooting.
Apakah MCP server gratis?
Ya. Paket npm adalah open source. MCP server hosted
di gratis untuk penggunaan publik.
Bisakah saya melakukan self-host MCP server?
Ya:
[CODE BLOCK]
Bagaimana MCP berbeda dari pemanggilan API langsung?
| Aspek | API Langsung | MCP |
|--------|-----------|-----|
| LLM perlu tahu | URL, header, auth | Hanya nama alat |
| Penanganan auth | Manual | Otomatis (env var) |
| Penemuan alat | Baca /endpoints | Otomatis via protokol MCP |
| Penanganan error | Manual | Terstandarisasi |
| Terbaik untuk | Integrasi khusus | Agen LLM |
Bisakah saya membangun klien MCP saya sendiri?
Ya. Gunakan SDK MCP resmi:
- TypeScript:
- Python:
Lihat Klien MCP Khusus.
Bagaimana cara melaporkan bug MCP?
Buka issue:
Sertakan:
- Versi MCP server
- Nama dan versi klien
- Sistem operasi
- Log yang relevan
- Langkah reproduksi
Langkah Berikutnya
- Apa itu MCP?
- Pengaturan Claude Desktop
- MCP Troubleshooting
────────────────────────────────────────────────────────────
# FAQ Troubleshooting
SUMMARY: Solusi untuk masalah Synapse umum — autentikasi, jaringan, data, deployment.
FAQ Troubleshooting
Solusi untuk masalah Synapse umum.
Saya tidak bisa login
Gejala
- mengembalikan 401
- "Invalid email or password"
Solusi
1. Verifikasi email benar — case sensitive
2. Periksa kata sandi — minimal 6 karakter
3. Daftar dulu jika Anda tidak punya akun:
4. Reset kata sandi (jika SMTP dikonfigurasi) melalui web UI
Saya kehilangan Mind Key
Gejala
- Tidak dapat mengakses memori
- Mind Key telah dihapus/hilang
Solusi
Mind Key tidak dapat dipulihkan. Anda harus:
1. Login untuk mendapatkan JWT:
2. Daftar mind: (dengan JWT)
3. Buat mind baru:
4. Simpan Mind Key baru
5. (Opsional) Hapus mind lama:
Data di mind lama hilang kecuali Anda dapat menemukan Mind Key-nya.
Panggilan API mengembalikan 401
Gejala
- Semua panggilan API mengembalikan 401 Unauthorized
- "Mind Key fehlt oder ungültig"
Solusi
1. Verifikasi format header:
2. Periksa Mind Key dimulai dengan (bukan yang merupakan JWT)
3. Tes langsung:
[CODE BLOCK]
4. Mind Key mungkin dicabut — buat mind baru
Lihat Autentikasi.
Panggilan API mengembalikan 404
Gejala
- 404 Not Found
- "Route not found"
Solusi
> [!CRITICAL]
> Jangan menebak path endpoint. Hanya path di yang ada.
1. Periksa endpoint valid:
2. Bandingkan URL persis — case sensitive, tanpa trailing slash
3. Periksa metode HTTP — vs berbeda
Panggilan API mengembalikan 429
Gejala
- 429 Too Many Requests
- "Rate limit exceeded"
Solusi
1. Beralih ke autentikasi header (tanpa rate limit):
[CODE BLOCK]
2. Tunggu detik jika Anda harus menggunakan
Lihat Rate Limits.
Pencarian memori tidak mengembalikan hasil
Gejala
- mengembalikan kosong
- Tahu memori ada
Solusi
1. Verifikasi memori ada:
2. Periksa sintaks pencarian — FTS5 memiliki sintaks spesifik
3. Coba kueri lebih sederhana — alih-alih
4. Gunakan pencarian semantik untuk kueri konseptual:
Lihat Pencarian FTS5.
Memori tidak bertahan
Gejala
- POST /memory mengembalikan sukses
- GET /memory/recall tidak menampilkannya
Solusi
1. Verifikasi Mind Key yang sama — key berbeda = mind berbeda
2. Periksa respons — POST mengembalikan
3. Coba GET /memory (daftar JSON) alih-alih /memory/recall (teks)
4. Periksa filter — atau mungkin menyembunyikannya
Alat tidak muncul di Claude Desktop
Gejala
- Claude Desktop menunjukkan 0 alat
- Tidak ada ikon 🔌
Solusi
1. Mulai ulang Claude Desktop sepenuhnya (Cmd+Q)
2. Verifikasi file konfigurasi adalah JSON yang valid
3. Periksa Node.js 18+ terpasang
4. Jalankan MCP secara manual:
5. Periksa log:
Lihat MCP Troubleshooting.
Synapse offline
Gejala
- Tidak dapat mencapai synapse.schaefer.zone
- curl timeout
Solusi
1. Periksa internet Anda — coba situs lain
2. Periksa health Synapse:
3. Tunggu — mungkin pemadaman sementara atau deployment
4. Periksa halaman status (jika tersedia)
Untuk self-hosted: periksa status container Docker, koneksi database.
Error database
Gejala
- 500 Internal Server Error
- "Database connection failed"
Solusi
Untuk self-hosted:
1. Periksa PostgreSQL berjalan:
2. Periksa DATABASEURL di env
3. Periksa migrasi:
4. Periksa ruang disk:
Untuk hosted: laporkan ke support.
Webhook tidak aktif
Gejala
- Mendaftarkan webhook tetapi tidak menerima callback
- Tidak ada POST ke URL Anda
Solusi
1. Verifikasi URL dapat dijangkau:
2. Periksa filter event — cocok dengan semua event memori
3. Tes webhook:
4. Periksa webhook diaktifkan:
5. Verifikasi SSL — Synapse memerlukan HTTPS yang valid untuk URL webhook
Lihat Webhooks API.
Cron job tidak berjalan
Gejala
- Membuat cron job tetapi tidak aktif
- tidak diperbarui
Solusi
1. Periksa sintaks jadwal — harus cron 5-field yang valid ATAU detik bilangan bulat
2. Verifikasi endpoint diizinkan — harus http(s), tanpa IP privat
3. Periksa job diaktifkan:
4. Tunggu waktu terjadwal berikutnya — cron tidak instan
Lihat Cron & Scheduler.
Butuh Bantuan Lebih Lanjut?
1. Periksa dokumentasi yang ada:
2. Cari dokumentasi:
3. Buka issue:
4. Kontak: lihat halaman
Langkah Berikutnya
- Errors & Error Handling
- FAQ API
- MCP Troubleshooting