# ДОКУМЕНТАЦІЯ SYNAPSE — Повний довідник
# Згенеровано: 2026-07-18T06:14:48.670Z
# Усього статей: 47
Цей документ містить повну документацію API Synapse.
Base URL: https://synapse.schaefer.zone
Language: uk
========================================================================
## КАТЕГОРІЯ: ПОЧАТОК РОБОТИ
Усе, що потрібно для початку роботи з Synapse.
────────────────────────────────────────────────────────────
# Автентифікація та Mind Keys
SUMMARY: Як працює автентифікація Synapse: Mind Keys для агентів, JWT для людей, ?key= для URL-only інструментів.
KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.
Автентифікація та Mind Keys
Synapse використовує два методи автентифікації, кожен оптимізований під свій
варіант використання. Розуміння різниці є необхідним для побудови надійних
інтеграцій.
Два методи автентифікації
| Метод | Варіант використання | Обмеження частоти | Термін дії |
|--------|----------|------------|--------|
| Mind Key | LLM-агенти, інструменти автоматизації | Немає (заголовок) / 60 хв (запит) | Ніколи |
| JWT | Людський інтерфейс, операції облікового запису | Немає | 7 днів |
Mind Key (для агентів)
Mind Key — це API-токен, прив'язаний до тенанта. Він автентифікує дані одного
mind-у (спогади, завдання, чат, скрипти тощо). Використовуйте для:
- LLM-агентів, що викликають API
- Фонових скриптів автоматизації
- Конфігурації MCP-сервера
- Будь-якої довготривалої інтеграції
Автентифікація через заголовок (рекомендовано)
[CODE BLOCK]
Параметр запиту (для URL-only інструментів)
[CODE BLOCK]
> [!WARNING]
> Параметр запиту обмежено до 60 запитів на хвилину.
> Заголовок Bearer не має обмеження. Використовуйте заголовок, коли ваш клієнт
> підтримує власні заголовки.
Створення Mind Key
[CODE BLOCK]
Відповідь містить — збережіть його негайно, воно показується лише раз.
Список ваших mind-ів
[CODE BLOCK]
Видалення mind-у (незворотно!)
[CODE BLOCK]
JWT (для людей)
JWT автентифікує обліковий запис користувача, а не конкретний mind. Використовуйте для:
- Реєстрації та входу в обліковий запис
- Створення / перегляду / видалення mind-ів
- Спільного доступу до mind-ів з іншими користувачами
- Керування підписками Web Push
Реєстрація
[CODE BLOCK]
Повертає:
Вхід
[CODE BLOCK]
Повертає:
Термін дії JWT
JWT закінчуються через 7 днів. Коли JWT закінчується, просто викличте
знову, щоб отримати новий. Mind Key ніколи не закінчується, тому наявні інтеграції
агентів продовжують працювати.
Найкращі практики безпеки
> [!CRITICAL]
> - Ніколи не комітьте Mind Keys у git. Використовуйте змінні середовища.
> - Ніколи не логуйте Mind Keys. Маскуйте їх у логах ().
> - Ротуйте ключі у разі підозри на витік (видаліть mind, створіть новий).
> - Один mind на проєкт, щоб обмежити масштаб шкоди при витоку ключа.
Шаблон змінних середовища
[CODE BLOCK]
[CODE BLOCK]
Конфігурація MCP-сервера
[CODE BLOCK]
Шаблон кількох mind-ів
Кожен користувач може мати кілька mind-ів. Поширені шаблони:
| Назва mind-у | Призначення |
|-----------|---------|
| | Робочі спогади |
| | Особисті уподобання, сім'я |
| | Контекст конкретного проєкту |
| | Прогрес навчання |
| | Універсальний fallback |
Використовуйте різні Mind Keys для різних сесій LLM, щоб ізолювати контексти.
Обмеження частоти
| Метод автентифікації | Ліміт | Область |
|-------------|-------|-------|
| Mind Key (заголовок) | Немає | На mind |
| Mind Key (?key=) | 60/хв | На IP |
| JWT (заголовок) | Немає | На користувача |
| Публічні кінцеві точки | Немає | Глобально |
Заголовки обмеження частоти (, ,
) включаються у відповіді за потреби.
Наступні кроки
- Mind Key проти JWT — коли що використовувати
- Memory API — що можна робити з Mind Key
- API користувачів — керування обліковим записом з JWT
────────────────────────────────────────────────────────────
# Mind Key проти JWT — що коли?
SUMMARY: Посібник з вибору: Mind Key для доступу агентів до даних, JWT для керування обліковим записом.
KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).
Mind Key проти JWT — що коли?
У Synapse два токени автентифікації. Вибір неправильного призводить до помилок 401.
Цей посібник дає чітку систему прийняття рішень.
Швидка таблиця рішень
| Ви хочете... | Використовуйте |
|----------------|-----|
| Зберігати / відкликати спогади | Mind Key |
| Надсилати / опитувати повідомлення чату | Mind Key |
| Керувати завданнями | Mind Key |
| Зберігати скрипти | Mind Key |
| Реєструвати webhooks | Mind Key |
| Керувати комп'ютерами | Mind Key (на боці користувача) / Computer Token (на боці агента) |
| Зареєструвати обліковий запис | Немає (публічне) |
| Увійти | Немає (публічне) |
| Створити / переглянути / видалити mind-и | JWT |
| Поділитися mind-ом з іншим користувачем | JWT |
| Підписатися на web push-сповіщення | JWT |
| Переглянути журнал аудиту | Mind Key |
Просте правило
> [!TIP]
> Якщо це стосується даних одного mind-у → Mind Key.
> Якщо це керує обліковим записом або метаданими mind-у → JWT.
Mind Key — токен доступу до даних
Mind Key надає доступ до даних одного mind-у. Це довготривалий токен, що
ніколи не закінчується (поки mind не видалено). Ідеально для:
- LLM-агентів, що зберігають спогади між сесіями
- Фонових cron-завдань
- Конфігурації MCP-сервера
- Інтеграцій webhook-ів
- Мобільних додатків, що читають пам'ять
Що може Mind Key
- — читати всі спогади в цьому mind-і
- — зберігати/оновлювати спогади
- — читати повідомлення чату
- — надсилати повідомлення чату
- — список завдань
- — створювати завдання
- — зберігати скрипти
- — реєструвати webhooks
- — ставити команди комп'ютера в чергу
Що Mind Key НЕ може
- Створювати / переглядати / видаляти mind-и (потрібен JWT)
- Ділитися mind-ом з іншим користувачем (потрібен JWT)
- Переглядати інформацію облікового запису (потрібен JWT)
- Підписуватися на web push (потрібен JWT)
JWT — токен керування обліковим записом
JWT автентифікує обліковий запис користувача. Він закінчується через 7 днів
і використовується для операцій на рівні облікового запису, що охоплюють кілька
mind-ів або залучають інших користувачів.
Що може JWT
- — створити новий mind (повертає новий Mind Key)
- — список усіх mind-ів цього користувача
- — видалити mind
- — поділитися mind-ом з іншим користувачем
- — підписатися на web push-сповіщення
- — список спільних mind-ів
Що JWT НЕ може
- Читати / писати спогади (потрібен Mind Key)
- Надсилати повідомлення чату (потрібен Mind Key)
- Керувати завданнями (потрібен Mind Key)
- Реєструвати webhooks (потрібен Mind Key)
Особливий випадок: Computer Token
Кінцеві точки (на боці агента, для screen-remote-agent)
використовують третій тип токена: Computer Token. Цей токен повертається
при активації коду встановлення та прив'язаний до
одного зареєстрованого комп'ютера.
| Кінцева точка | Auth |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key або JWT |
| | Mind Key або JWT |
Поширені шаблони
Шаблон 1: Один LLM-агент
1. Зареєструйтеся один раз → отримайте JWT
2. Створіть один mind → отримайте Mind Key
3. LLM використовує Mind Key для всього
Шаблон 2: Багатопроєктний агент
1. Зареєструйтеся один раз → отримайте JWT
2. Створіть кілька mind-ів (work, personal, project-x) → отримайте кілька Mind Keys
3. LLM завантажує різний Mind Key залежно від контексту
Шаблон 3: Командний доступ
1. Користувач A створює mind → отримує Mind Key A
2. Користувач A ділиться з Користувачем B через JWT ()
3. Користувач B тепер може доступатися через свій JWT
4. Для LLM-доступу Користувачу B потрібно створити власний Mind Key (або використати A)
Шаблон 4: MCP-сервер
MCP-сервери завжди використовують Mind Key (через змінну середовища ).
Один екземпляр MCP-сервера = один mind. Для багато-mind доступу запустіть кілька
екземплярів MCP або реалізуйте перемикання mind-ів на боці клієнта.
Шпаргалка форматів токенів
| Токен | Формат | Приклад |
|-------|--------|---------|
| Mind Key | + 36 символів | |
| JWT | + base64 | |
| Computer Token | + 36 символів | |
Наступні кроки
- Автентифікація — повний посібник з автентифікації
- API користувачів та mind-ів — кінцеві точки, захищені JWT
- Memory API — кінцеві точки, захищені Mind Key
────────────────────────────────────────────────────────────
# Швидкий старт для LLM-агентів
SUMMARY: За 3 API-виклики: відкликання всіх спогадів, збереження нового, пошук. Основний робочий процес LLM.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query)
ALWAYS call /memory/recall at the start of every session.
Wichtigste Befehle: GET /memory/recall, POST /memory, GET /memory/search?q=...
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
FTS5 search: multiple words = AND, "phrases" in quotes, prefix* for prefix search
Швидкий старт для LLM-агентів
Ви втрачаєте всю пам'ять між сесіями. Synapse — ваш зовнішній мозок. Цей посібник
показує три основні API-виклики, які має знати кожен LLM-агент.
> [!CRITICAL]
> Викликайте НА ПОЧАТКУ КОЖНОЇ сесії.
> Без цього виклику ви не маєте пам'яті про те, хто користувач, що ви обіцяли,
> або над чим працювали минулого разу.
Крок 1: Відкликання всіх спогадів (ЗАВЖДИ ПЕРШИМ)
[CODE BLOCK]
Повертає структуроване текстове резюме всіх збережених спогадів. Розберіть це,
щоб відновити свою ментальну модель користувача, його проєктів та минулих
взаємодій.
Приклад відповіді:
[CODE BLOCK]
Крок 2: Збереження нового спогаду
Коли ви дізнаєтесь щось, що варто запам'ятати:
[CODE BLOCK]
Категорії: , , , , , , , ,
Пріоритети: , , ,
> [!TIP]
> Завжди включайте поле — короткий ідентифікатор спогаду. Це дозволяє
> оновлювати той самий спогад пізніше, повторно POST-нувши з тим самим ключем.
Крок 3: Пошук конкретного спогаду
[CODE BLOCK]
> [!TIP]
> Синтаксис FTS5: кілька слів = пошук AND. Фрази в лапках: .
> Пошук за префіксом: . Булеві операції: .
Відкриті інструменти (без auth-заголовків)
Якщо ваш інструмент може лише відкривати URL (без власних заголовків), використовуйте параметр :
[CODE BLOCK]
> [!WARNING]
> обмежено до 60 запитів/хв. Заголовок Bearer не має обмеження.
> Використовуйте заголовок Bearer, коли можливо.
Повний робочий процес сесії
1. Початок сесії: — завантажити всі спогади
2. Під час роботи: — знайти конкретні факти
3. При новій інформації: — зберегти її (з category, key, tags, priority)
4. Періодично: — перевірити повідомлення від людини
5. Кінець сесії: зберегти будь-які фінальні висновки через
Поширені шаблони
Оновлення наявного спогаду
POST з тією ж та — наявний спогад оновлюється, а не
дублюється.
Збереження статусу проєкту
[CODE BLOCK]
Запис помилки (щоб не повторювати)
[CODE BLOCK]
Перевірка повідомлень від людини
[CODE BLOCK]
Повертає непрочитані повідомлення від людини. Відповідайте через:
[CODE BLOCK]
Наступні кроки
- Автентифікація — Mind Key проти JWT
- Довідник Memory API — усі 22 кінцеві точки пам'яті
- Chat API — асинхронне спілкування з людьми
- Куховарська книга LLM — практичні шаблони
────────────────────────────────────────────────────────────
# Швидкий старт (людина)
SUMMARY: Зареєструйте обліковий запис, створіть свій перший mind, збережіть спогад — усе за 5 хвилин.
Швидкий старт (людина)
Цей посібник проведе вас через отримання облікового запису Synapse, вашого
першого Mind Key та збереження першого спогаду. Загальний час: 5 хвилин.
Крок 1: Зареєструйте обліковий запис
Відкрийте API Synapse та створіть обліковий запис:
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
> [!TIP]
> Збережіть JWT у безпечному місці — він потрібен для створення mind-ів. JWT
> закінчується через 7 днів; повторно увійдіть через ту саму кінцеву точку для
> оновлення.
Крок 2: Створіть свій перший mind
«Mind» — це ізольована область пам'яті. Більшість користувачів починають з одного
mind-у, але ви можете мати кілька (напр. «work», «personal», «project-x»). Кожен
mind має власний унікальний Mind Key.
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
> [!CRITICAL]
> Збережіть негайно. Воно показується лише один раз і не може
> бути отримане пізніше. Якщо втратите, доведеться створити новий mind.
Крок 3: Збережіть свій перший спогад
Тепер використовуйте Mind Key для збереження спогаду:
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
Крок 4: Відкличайте всі спогади
Щоб отримати все, що ви зберегли:
[CODE BLOCK]
Відповідь (звичайний текст, оптимізований для споживання LLM):
[CODE BLOCK]
Крок 5: Пошук спогадів
Знайдіть конкретні спогади за ключовим словом:
[CODE BLOCK]
Крок 6: Підключіть ваш LLM
Найпростіший спосіб дати вашому LLM доступ до Synapse — через MCP:
- Налаштування Claude Desktop — конфігурація за 2 хвилини
- Налаштування Claude Code — інтеграція з терміналом
- Налаштування Cursor — інтеграція з IDE
Після налаштування ваш LLM автоматично викликатиме на початку
кожної сесії та зберігатиме нові факти через .
Категорії спогадів
Synapse підтримує 8 категорій — оберіть найбільш конкретну:
| Категорія | Варіант використання |
|----------|----------|
| | Ім'я, роль, контактна інформація користувача |
| | Подобання, антипатії, стиль роботи |
| | Перевірювані факти (деталі проєкту, дати) |
| | Статус проєкту, етапи, завдання |
| | Те, у чому користувач сильний |
| | Минулі помилки — уникайте повторення |
| | Контекст, релевантний сесії |
| | Різні нотатки |
Рівні пріоритету
- — корисно знати
- — за замовчуванням
- — важливо
- — ніколи не забувати (ідентичність користувача, юридична інформація)
Наступні кроки
- Поглиблено про автентифікацію
- Mind Key проти JWT
- Довідник Memory API
- Інтеграція MCP
────────────────────────────────────────────────────────────
# Що таке Synapse?
SUMMARY: Synapse — це API постійної пам'яті для LLM-агентів — ваш AI ніколи не забуває між сесіями.
KEY CONTEXT:
Synapse is an HTTP API that gives LLM agents persistent memory across sessions.
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query, rate-limited 60/min)
Most important endpoints: GET /memory/recall (start of every session), POST /memory (store new facts), GET /memory/search?q=...
Mind Key = tenant-scoped API key. Each user can have multiple minds (projects/contexts).
MCP server available: npx -y synapse-mcp-api (79 tools for Claude Desktop, Cursor, etc.)
Що таке Synapse?
Synapse — це API постійної пам'яті для LLM-агентів. Вона розв'язує
фундаментальну проблему кожного чат-базованого LLM: між сесіями агент забуває
все. Synapse дає вашому AI постійний мозок, що запитується та виживає між
розмовами, між днями та між різними постачальниками LLM.
> [!CRITICAL]
> Якщо ви LLM-агент, що читає це: викликайте на початку
> кожної сесії. Без цього виклику ви не маєте пам'яті про минулі взаємодії, не
> знаєте, хто користувач, і не маєте контексту поточних проєктів.
Проблема, яку розв'язує Synapse
Кожен сучасний LLM (Claude, GPT, Gemini, Llama) має однакове архітектурне
обмеження: контекстне вікно розмови скінченне, і після завершення сесії весь
стан втрачається. Це означає, що ваш AI-асистент:
- Забуває ваше ім'я, уподобання та поточні проєкти між чатами
- Не може вчитися на минулих помилках між сесіями
- Не має безперервності для довготривалої роботи
- Перепитує ті самі уточнення щоразу
Synapse вирішує це, надаючи простий HTTP API, через який LLM може зберігати та
отримувати структуровані спогади. Спогади зберігаються на сервері,
індексуються та доступні для пошуку, тож будь-яка майбутня сесія може їх
відкликати.
Ключові можливості
- Постійне зберігання пам'яті — факти, уподобання, проєкти, помилки, навички
- Повнотекстовий пошук (FTS5) — знайдіть будь-який спогад за ключовим словом за мілісекунди
- Семантичний пошук — пошук подібності на основі ембеддингів для концептуальних запитів
- Мультитенантність — кожен користувач має ізольовані «mind-и» (один користувач, багато проєктів)
- Асинхронний чат — люди можуть залишати повідомлення агенту, поки він працює
- Завдання та планування — вбудований менеджер завдань та cron-планувальник
- Інтеграція MCP — 79 інструментів, викритих як Model Context Protocol для Claude, Cursor, Continue
- Керування браузером та комп'ютером — інструменти віддаленої автоматизації
- Webhooks — отримуйте HTTP-зворотні виклики при змінах пам'яті/чату/завдань
Як це працює
[CODE BLOCK]
1. LLM викликає на початку сесії
2. Synapse повертає структуроване текстове резюме всіх збережених спогадів
3. LLM працює, періодично викликаючи для збереження нових фактів
4. Коли користувач ставить запитання, LLM може викликати
5. Наприкінці сесії важливий новий контекст зберігається для наступної сесії
Для кого це?
- Розробники LLM-агентів, яким потрібен постійний стан
- Просунуті користувачі, що запускають локальні LLM (Ollama, LM Studio) зі власними агентами
- Команди, що створюють AI-асистентів зі спільною пам'яттю
- Інженери автоматизації, що об'єднують виклики LLM між сесіями
Швидке порівняння
| Функція | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| Місце зберігання | Сервери OpenAI | Ваш сервер |
| API-доступ | Ні (закритий) | Так (REST + MCP) |
| Мультитенантність | Ні | Так (mind-и) |
| Власні категорії | Ні | Так (8 категорій) |
| Пошук | Обмежено | FTS5 + семантичний |
| Self-hostable | Ні | Так (Docker) |
Наступні кроки
- Швидкий старт для людей — отримайте Mind Key за 5 хвилин
- Швидкий старт для LLM — перші API-виклики
- Автентифікація — Mind Keys проти JWT
- Огляд архітектури — як побудовано Synapse
## КАТЕГОРІЯ: ДОВІДНИК З API
Повний довідник усіх кінцевих точок API.
────────────────────────────────────────────────────────────
# Браузерний проксі
SUMMARY: Служба автоматизації браузера — окремий Docker-контейнер на порту 13000 для керування браузером без графічного інтерфейсу.
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.)
Браузерний проксі
Браузерний проксі — це окрема Docker-служба, яка забезпечує автоматизацію
браузера без графічного інтерфейсу через Playwright. Вона НЕ є частиною API
Synapse безпосередньо — кінцеві точки Synapse не включають шляхи .
Архітектура
[CODE BLOCK]
Методи доступу
Метод 1: Через Synapse MCP Server (рекомендовано)
Сервер Synapse MCP надає браузерні інструменти як MCP-інструменти. Використовуйте
цей метод для автоматизації браузера під керуванням LLM:
[CODE BLOCK]
Доступні MCP-інструменти браузера:
- — відкрити нову вкладку браузера
- — перейти до URL
- — клацнути на елемент
- — ввести текст у поле
- — зробити знімок екрана
- — закрити вкладку
- (та інші — дивіться інтеграцію MCP)
Метод 2: Прямий доступ до браузерного проксі
Для не-MCP інтеграцій підключайтеся безпосередньо до служби browser-proxy:
[CODE BLOCK]
Типові варіанти використання
Веб-скрапінг
[CODE BLOCK]
Автоматизація форм
[CODE BLOCK]
Захоплення знімків екрана
[CODE BLOCK]
Пов'язані служби
| Служба | Порт | Призначення |
|---------|------|---------|
| Synapse API | 12800 | Пам'ять, чат, завдання |
| Synapse MCP | 13100 | MCP-сервер (79 інструментів) |
| Browser Proxy | 13000 | Автоматизація браузера без графічного інтерфейсу |
| SSH Proxy | 12900 | SSH-доступ до віддалених машин |
Наступні кроки
- Інтеграція MCP — як використовувати браузерні інструменти через MCP
- API керування комп'ютерами — для автоматизації GUI на зареєстрованих машинах
────────────────────────────────────────────────────────────
# Chat API
SUMMARY: Асинхронний чат між людьми та LLM-агентами — опитування, відповіді, історія, лічильник непрочитаного, завантаження файлів.
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 забезпечує асинхронне спілкування між людьми та LLM-агентами.
На відміну від синхронного чату (як у ChatGPT), людина може залишати повідомлення,
поки агент працює — агент опитує сервер між викликами інструментів.
Як це працює
[CODE BLOCK]
1. Людина надсилає повідомлення через веб-інтерфейс (використовує JWT)
2. Повідомлення зберігається, позначається як непрочитане
3. Агент опитує між викликами інструментів
4. Опитування повертає всі непрочитані повідомлення та позначає їх як прочитані
5. Агент обробляє повідомлення та за потреби відповідає через
Кінцеві точки
GET /chat/poll
Опитування нових повідомлень від людини. Повертає непрочитані повідомлення та
позначає їх як прочитані. Використовуйте між викликами інструментів.
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
POST /chat/reply
Надіслати повідомлення від імені агента.
[CODE BLOCK]
POST /chat/send
Надіслати повідомлення від імені людини (потребує JWT, а не Mind Key).
[CODE BLOCK]
GET /chat/history
Отримати нещодавню історію чату (обидві ролі).
[CODE BLOCK]
GET /chat/unread
Отримати кількість непрочитаних повідомлень.
[CODE BLOCK]
GET /chat/status
Отримати статус сесії чату (мітки часу останніх повідомлень, кількість непрочитаних).
[CODE BLOCK]
POST /chat/upload
Завантажити вкладений файл для конкретного повідомлення (multipart-форма).
[CODE BLOCK]
GET /chat/files/:messageid
Список вкладених файлів для повідомлення.
[CODE BLOCK]
GET /chat/file/:fileid
Завантажити вкладений файл.
[CODE BLOCK]
Шаблон опитування
> [!TIP]
> Опитуйте кожні 30–60 секунд між викликами інструментів. Не опитуйте частіше —
> це витрачає квоту API та не дає жодної користі.
[CODE BLOCK]
Наступні кроки
- Tasks API
- Шаблон опитування чату
────────────────────────────────────────────────────────────
# API керування комп'ютерами
SUMMARY: Віддалене керування зареєстрованими комп'ютерами — постановка команд у чергу, знімки екрана, запуск скриптів на віддалених машинах.
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
API керування комп'ютерами
API керування комп'ютерами дозволяє віддалено керувати зареєстрованими комп'ютерами.
Невеликий агент () працює на цільовій машині, опитує сервер
щодо команд, виконує їх та надсилає результати назад. Це забезпечує автоматизацію
GUI під керуванням LLM.
Архітектура
[CODE BLOCK]
Кінцеві точки для користувача (Mind Key або JWT)
GET /computers/list
Список усіх зареєстрованих комп'ютерів.
[CODE BLOCK]
GET /computers/:id
Отримати деталі конкретного комп'ютера.
[CODE BLOCK]
POST /computers/install-code
Згенерувати код встановлення для реєстрації нового комп'ютера.
[CODE BLOCK]
Відповідь:
POST /computers/:id/commands
Поставити команду в чергу для виконання віддаленим агентом.
[CODE BLOCK]
Відповідь:
GET /computers/:id/command (через запит)
Поставити команду в чергу через GET (для простих випадків).
[CODE BLOCK]
GET /computers/:id/commands
Список нещодавніх команд для комп'ютера.
[CODE BLOCK]
GET /computers/:id/commands/:cid
Отримати статус + результат конкретної команди.
[CODE BLOCK]
GET /computers/:id/screenshot
Одноразове виконання: поставити команду знімка екрана в чергу та чекати до 30 с на результат.
[CODE BLOCK]
POST /computers/:id/disable
Вимкнути комп'ютер (відкликає його токен, зберігає запис для аудиту).
[CODE BLOCK]
DELETE /computers/:id
Видалити комп'ютер назавжди.
[CODE BLOCK]
Кінцеві точки для агента (Computer Token)
Ці кінцеві точки використовує , що працює на цільовій
машині. Вони використовують Computer Token (повертається ), а
не Mind Key.
POST /computers/register
Активувати код встановлення та отримати Computer Token.
[CODE BLOCK]
Відповідь:
> [!CRITICAL]
> Збережіть — він показується лише один раз і потрібен для всіх
> кінцевих точок на боці агента.
GET /computers/me/poll
Довге опитування нових команд. Агент викликає це в циклі.
[CODE BLOCK]
Повертає негайно, якщо команди очікують, або через секунд, якщо ні.
POST /computers/me/commands/:cid/result
Надіслати результат виконання команди.
[CODE BLOCK]
Типи команд
| Тип | Payload | Опис |
|------|---------|-------------|
| | | Захоплення екрана як PNG (base64) |
| | | Клацання за координатами |
| | | Переміщення миші за координатами |
| | | Введення тексту в позиції курсора |
| | | Натискання комбінації клавіш |
| | | Прокручування колеса |
| | | Перетягування |
Типовий шаблон: автоматизація GUI під керуванням LLM
[CODE BLOCK]
Наступні кроки
- Браузерний проксі — окрема служба для автоматизації браузера
- Посібник із self-hosted агентів
────────────────────────────────────────────────────────────
# Cron та планувальник
SUMMARY: Планування регулярних викликів API — cron-завдання, що запускаються за розкладом, ідеально для періодичної синхронізації та нагадувань.
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 та планувальник
Cron API дозволяє планувати регулярні HTTP-виклики до кінцевих точок Synapse
(або зовнішніх HTTPS-кінцевих точок). Ідеально підходить для періодичної
синхронізації, нагадувань та завдань з обслуговування.
Кінцеві точки
POST /cron
Створити заплановане завдання.
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
GET /cron
Список усіх запланованих завдань.
[CODE BLOCK]
DELETE /cron/:id
Видалити заплановане завдання.
[CODE BLOCK]
PUT /cron/:id/toggle
Увімкнути або вимкнути завдання без видалення.
[CODE BLOCK]
Синтаксис розкладу
Стандартний cron (5 полів)
[CODE BLOCK]
Приклади:
| Розклад | Значення |
|----------|---------|
| | Щогодини |
| | Кожні 15 хвилин |
| | Будні о 9:00 |
| | Кожної неділі опівночі |
| | Першого числа кожного місяця опівночі |
Цілочисельний інтервал (секунди)
Для простих інтервалів передайте ціле число:
[CODE BLOCK]
Обмеження кінцевих точок
> [!WARNING]
> Кінцеві точки мають бути URL-адресами або , що вказують на:
> - Туж саму інсталяцію Synapse (напр. )
> - Публічні HTTPS-URL (без приватних IP, без localhost, без метаданихних IP)
Це запобігає SSRF-атакам, коли скомпрометований mind міг би планувати запити
до внутрішніх служб.
Типові шаблони
Щогодинне відкликання пам'яті (для LLM-агентів)
[CODE BLOCK]
Щоденне резервне копіювання
[CODE BLOCK]
Періодичне опитування чату (кожні 5 хвилин)
[CODE BLOCK]
Тригер щотижневого звіту
[CODE BLOCK]
Наступні кроки
- Variables API
- Webhooks API
────────────────────────────────────────────────────────────
# Помилки та обробка помилок
SUMMARY: Коди стану HTTP, формат відповідей з помилками та способи відновлення після поширених помилок.
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.
Помилки та обробка помилок
Synapse використовує стандартні коди стану HTTP із послідовним форматом
відповідей з помилками. Ця сторінка пояснює, як інтерпретувати та відновлюватися
після помилок.
Формат відповіді з помилкою
Усі помилки повертають JSON такої структури:
[CODE BLOCK]
| Поле | Опис |
|-------|-------------|
| | Код стану HTTP |
| | Назва статусу HTTP |
| | Зрозумілий для людини опис помилки |
| | URL-адреса відповідної документації (за наявності) |
Коди стану HTTP
200 OK
Успіх. Запит оброблено коректно.
201 Created
Успіх. Створено новий ресурс (напр. ).
204 No Content
Успіх. Тіло відповіді не повертається (напр. ).
400 Bad Request
Запит є malformed. Поширені причини:
- Відсутні обов'язкові JSON-поля
- Некоректний синтаксис JSON
- Недійсне значення enum (напр. неправильна категорія)
[CODE BLOCK]
Виправлення: Перевірте тіло запиту за документацією API. Переконайтеся, що
усі обов'язкові поля присутні та мають коректні значення.
401 Unauthorized
Помилка автентифікації. Поширені причини:
- Відсутній заголовок
- Недійсний Mind Key або JWT
- Використання Mind Key там, де потрібен JWT (або навпаки)
[CODE BLOCK]
Виправлення: Перевірте ваш токен. Дивіться Автентифікацію.
403 Forbidden
Ви автентифіковані, але не маєте права виконувати цю дію. Поширені причини:
- Спроба видалити чужий mind
- Спроба верифікувати спогад за допомогою Mind Key (потрібен JWT)
- Mind вимкнено
Виправлення: Перевірте, чи використовуєте правильний тип токена для цієї кінцевої точки.
404 Not Found
Запитаний шлях або ресурс не існує.
> [!CRITICAL]
> НЕ вгадуйте шляхи кінцевих точок. Існують лише шляхи зі списку .
> Якщо отримали 404 — ви використали неправильний шлях.
[CODE BLOCK]
Виправлення: Викличте , щоб побачити список дійсних кінцевих
точок. Порівняйте ваш URL зі списком символ за символом.
409 Conflict
Запит конфліктує з наявним станом. Поширені причини:
- Спроба зареєструватися з email, що вже існує
- Дублікат URL webhook
Виправлення: Використайте інше значення або скористайтеся для оновлення наявного ресурсу.
429 Too Many Requests
Ви досягли ліміту частоти. Стосується лише автентифікації через параметр запиту
(60/хв).
[CODE BLOCK]
Заголовки відповіді:
[CODE BLOCK]
Виправлення: Перейдіть на заголовок (без обмеження
частоти) або зачекайте секунд.
500 Internal Server Error
Помилка сервера. Це не повинно траплятися — якщо трапилося, це баг.
Виправлення:
1. Повторіть із експоненційною затримкою (1с, 2с, 4с, 8с)
2. Перевірте , щоб переконатися, що сервер працює
3. Якщо помилка стійка, повідомте про неї
503 Service Unavailable
Сервер тимчасово недоступний (напр. під час розгортання, міграції БД).
Виправлення: Зачекайте та повторіть спробу. Перевірте .
Шаблони відновлення
Повтор із експоненційною затримкою
[CODE BLOCK]
Обробка помилок автентифікації
[CODE BLOCK]
Поширені сценарії помилок
"Mind Key fehlt oder ungültig"
- Ви забули заголовок
- Ви використали , але ключ неправильний
- Ви використовуєте JWT там, де потрібен Mind Key
"Route not found"
- Ви вгадали шлях, якого не існує
- Ви неправильно використали метод (напр. замість )
- Перевірте для дійсних шляхів
"Rate limit exceeded"
- Ви використовуєте та перевищили 60 запитів/хв
- Перейдіть на заголовок
Наступні кроки
- Автентифікація
- Огляд API
- Обмеження частоти
────────────────────────────────────────────────────────────
# Memory API
SUMMARY: Повний довідник із 22 кінцевих точок пам'яті: збереження, відкликання, пошук, семантичний пошук, синхронізація, аудит та інше.
KEY CONTEXT:
Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)
ALWAYS call GET /memory/recall at session start.
POST /memory with same category+key updates the existing memory.
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
Search: GET /memory/search?q=... (FTS5 syntax: AND, OR, "phrases", prefix*)
Semantic: GET /memory/semantic-search?q=... (slower, conceptual)
Sync: GET /memory/diff?since=TIMESTAMP (incremental sync)
Export: GET /memory/mind-export (full JSON dump)
Memory API
Memory API — це серце Synapse. Вона надає 22 кінцеві точки для збереження,
отримання, пошуку та керування структурованими спогадами. Усі кінцеві точки
потребують Mind Key для автентифікації.
> [!CRITICAL]
> Завжди викликайте на початку кожної сесії. Це
> єдиний спосіб відновити контекст із попередніх сесій.
Категорії
Спогади організовано у 8 категорій:
| Категорія | Варіант використання |
|----------|----------|
| | Ім'я користувача, роль, контактна інформація, налаштування щодо себе |
| | Подобання, антипатії, стиль роботи, комунікаційні уподобання |
| | Перевірювані факти (деталі проєктів, дати, URL-адреси) |
| | Статус проєкту, етапи, архітектура |
| | Те, у чому користувач сильний |
| | Минулі помилки — уникайте повторення |
| | Контекст, релевантний сесії |
| | Різні нотатки |
Пріоритети
- — корисно знати
- — за замовчуванням
- — важливо
- — ніколи не забувати (ідентичність користувача, юридична інформація)
Основні кінцеві точки
GET /memory/recall
Повертає ВСІ спогади у вигляді звичайного тексту, оптимізованого для LLM. Викликайте на початку кожної сесії.
[CODE BLOCK]
Відповідь (text/plain):
[CODE BLOCK]
POST /memory
Зберігає новий спогад або оновлює наявний (та сама категорія + ключ = оновлення).
[CODE BLOCK]
Відповідь:
GET /memory
Список спогадів із необов'язковими фільтрами.
[CODE BLOCK]
PUT /memory/:id
Оновлення конкретного спогаду за ID.
[CODE BLOCK]
DELETE /memory/:id
Видалення одного спогаду.
[CODE BLOCK]
Кінцеві точки пошуку
GET /memory/search
Повнотекстовий пошук з використанням FTS5.
[CODE BLOCK]
Синтаксис FTS5:
- Кілька слів = AND:
- Фраза:
- Префікс:
- Булеві операції:
- Виключення:
GET /memory/semantic-search
Концептуальний пошук за ембеддингами (повільніший за FTS5, але розуміє зміст).
[CODE BLOCK]
Повертає спогади, семантично подібні до запиту, навіть якщо ключові слова
не збігаються. Корисно для «знайти спогади про X», де X описано інакше.
GET /memory/by-tag
Список спогадів за тегом.
[CODE BLOCK]
GET /memory/related/:id
Пошук спогадів, пов'язаних із конкретним спогадом (через спільні теги).
[CODE BLOCK]
Синхронізація та Diff
GET /memory/diff
Інкрементальна синхронізація — повертає спогади, що змінилися з певної мітки часу.
[CODE BLOCK]
Відповідь:
POST /memory/sync
Застосувати diff з іншої інсталяції (для синхронізації self-hosted).
[CODE BLOCK]
Масові операції
POST /memory/bulk-delete
Видалення кількох спогадів за ID.
[CODE BLOCK]
POST /memory/embed-batch
Генерування ембеддингів для спогадів, які їх ще не мають (для семантичного пошуку).
[CODE BLOCK]
GET /memory/embed-batch-status
Перевірка прогресу генерації ембеддингів.
[CODE BLOCK]
Верифікація
Спогади мають прапорець . Спогади, збережені агентом, за замовчуванням
неперевірені (); спогади, збережені людиною, — перевірені ().
POST /memory/verify
Позначити спогад як перевірений (потребує JWT, а не Mind Key).
[CODE BLOCK]
POST /memory/unverify
Позначити спогад як неперевірений (потребує JWT).
[CODE BLOCK]
GET /memory/unverified
Список спогадів, що очікують на перевірку людиною.
[CODE BLOCK]
Статистика та аудит
GET /memory/stats
Зведена статистика для поточного mind-у.
[CODE BLOCK]
Повертає:
GET /memory/audit
Журнал аудиту всіх операцій, що змінюють стан.
[CODE BLOCK]
GET /memory/contradictions
Виявлення потенційних суперечностей у збережених спогадах.
[CODE BLOCK]
GET /memory/expiring
Список спогадів, термін дії яких наближається.
[CODE BLOCK]
Стан та експорт
GET /memory/health
Швидка перевірка стану системи пам'яті.
[CODE BLOCK]
GET /memory/mind-export
Повний JSON-експорт усіх спогадів (для резервного копіювання).
[CODE BLOCK]
POST /memory/compact
Ущільнення подібних спогадів (автосумаризація).
[CODE BLOCK]
Наступні кроки
- Швидкий старт для LLM
- Найкращі практики роботи з пам'яттю
- Пошук FTS5
- Семантичний пошук
────────────────────────────────────────────────────────────
# Огляд API та базовий URL
SUMMARY: Усі кінцеві точки API Synapse, базовий URL, шаблони автентифікації та формати відповідей у стислому вигляді.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.
Огляд API та базовий URL
API Synapse — це RESTful HTTP API. Усі кінцеві точки повертають JSON (окрім
випадків, де зазначено інше). Ця сторінка охоплює основи, які потрібно знати
перед вивченням конкретних кінцевих точок.
Базовий URL
[CODE BLOCK]
Усі шляхи у цій документації вказуються відносно цього базового URL. Для
власних інсталяцій замініть на ваш URL.
Автентифікація
Два методи, обидва передаються через заголовок :
[CODE BLOCK]
Або через параметр запиту (з обмеженням частоти 60/хв):
[CODE BLOCK]
Докладніше дивіться у Автентифікації.
Групи кінцевих точок
| Група | Автентифікація | Опис |
|-------|------|-------------|
| Public | Немає | Головна сторінка, перевірка стану, OpenAPI, документація |
| Memory | Mind Key | CRUD, пошук, синхронізація, ембеддинги |
| Chat | Mind Key / JWT | Асинхронне спілкування між людиною та агентом |
| Tasks | Mind Key | Керування завданнями |
| Scripts | Mind Key / JWT | Постійне сховище скриптів |
| Scheduler | Mind Key | Cron-завдання + змінні |
| Webhooks | Mind Key | HTTP-зворотні виклики подій |
| Computers | Mind Key / JWT | Віддалене керування комп'ютерами |
| User/Minds | JWT | Обліковий запис + керування mind-ами |
| Sharing | JWT | Спільний доступ до mind-ів між користувачами |
| Push | JWT | Підписки Web Push |
| Tools | Немає | Час, калькулятор, випадкові значення (публічні утиліти) |
Формати відповідей
- JSON (за замовчуванням):
- Звичайний текст: повертає текст, оптимізований для LLM
- HTML: , , , ,
Стандартна обгортка відповіді
Успішні відповіді повертають дані безпосередньо:
[CODE BLOCK]
Відповіді з помилками використовують такий формат:
[CODE BLOCK]
> [!NOTE]
> Поле містить посилання на відповідну документацію для поширених помилок.
Коди стану HTTP
| Код | Значення |
|------|---------|
| 200 | Успіх (GET, PUT) |
| 201 | Створено (POST) |
| 204 | Немає вмісту (DELETE) |
| 400 | Некоректний запит (помилка валідації) |
| 401 | Не автентифіковано (відсутній/недійсний токен) |
| 403 | Заборонено (неправильний тип токена) |
| 404 | Не знайдено (шлях не існує) |
| 409 | Конфлікт (дублікат) |
| 429 | Забагато запитів (обмеження частоти) |
| 500 | Помилка сервера |
Кінцеві точки для виявлення
| Кінцева точка | Призначення |
|----------|---------|
| | Головна сторінка (оптимізована для LLM) |
| | Машиночитний список усіх кінцевих точок |
| | Список кінцевих точок у вигляді звичайного тексту |
| | Специфікація OpenAPI 3.0 |
| | Повна документація API (HTML) |
| | Документація API у форматі JSON |
| | Система документації (HTML) |
| | Індекс документації (JSON) |
| | Уся документація одним текстовим блоком |
| | Інтерактивний playground API |
Обмеження частоти
| Метод автентифікації | Ліміт |
|-------------|-------|
| Mind Key (заголовок) | Немає |
| Mind Key (?key=) | 60/хв на IP |
| JWT (заголовок) | Немає |
| Публічні кінцеві точки | Немає |
Відповіді з обмеженням частоти містять:
[CODE BLOCK]
Пагінація
Кінцеві точки списків підтримують та :
[CODE BLOCK]
Ліміт за замовчуванням: 100. Максимальний ліміт: 500.
CORS
Усі кінцеві точки підтримують CORS для браузерних клієнтів:
[CODE BLOCK]
SDK та клієнти
- Node.js SDK: (репозиторій)
- MCP Server: (репозиторій)
- HTTP-клієнт: будь-яка HTTP-бібліотека (curl, fetch, axios тощо)
Наступні кроки
- Memory API — найважливіші кінцеві точки
- Chat API — асинхронне спілкування людина-агент
- Помилки та обробка помилок
────────────────────────────────────────────────────────────
# Обмеження частоти та квоти
SUMMARY: Політика обмеження частоти для API Synapse — заголовок Bearer (без обмежень), ?key= (60/хв), публічні кінцеві точки.
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.
Обмеження частоти та квоти
Synapse має просту та передбачувану політику обмеження частоти, розроблену для
запобігання зловживанням, не заважаючи легітимному використанню.
Політика обмеження частоти
| Метод автентифікації | Ліміт | Область |
|-------------|-------|-------|
| Mind Key () | Немає | На mind |
| Mind Key () | 60 запитів/хв | На IP |
| JWT () | Немає | На користувача |
| Публічні кінцеві точки | Немає | Глобально |
> [!TIP]
> Завжди використовуйте заголовок , коли це можливо.
> Він не має обмеження частоти. Використовуйте лише для інструментів, які
> не можуть встановлювати власні заголовки.
Заголовки обмеження частоти
Коли ви використовуєте автентифікацію , відповіді містять заголовки обмеження:
[CODE BLOCK]
Коли ви перевищуєте ліміт:
[CODE BLOCK]
Коли ви досягли обмеження частоти
Якщо отримали 429:
1. Перейдіть на заголовок Authorization (рекомендовано):
[CODE BLOCK]
2. Або зачекайте секунд та повторіть спробу.
Чому існує ліміт ?key=
Параметр запиту зручний для URL-only інструментів (браузери, команди
), але має наслідки для безпеки та продуктивності:
- Безпека: Параметри запиту фіксуються в журналах доступу сервера, історії
браузера та заголовках Referer. Обмеження використання зменшує ризик викриття.
- Продуктивність: Автентифікація через параметр запиту потребує обмежувача
частоти на основі IP (пошук у Redis на кожен запит), що додає затримку.
Автентифікація через заголовок пропускає це.
- Запобігання зловживанням: Виточена URL-адреса може бути поширена та
піддата масовому використанню. Ліміт на IP обмежує масштаб шкоди.
Рекомендовані шаблони
LLM-агенти
[CODE BLOCK]
Браузерні інструменти
Якщо ваш інструмент може лише відкривати URL:
[CODE BLOCK]
MCP-сервер
MCP-сервери завжди використовують автентифікацію через заголовок за допомогою
змінної середовища — обмеження частоти не застосовується.
Масовий імпорт
Для масових операцій (напр. імпорт 1000 спогадів) завжди використовуйте
автентифікацію через заголовок. Масовий імпорт через досягне ліміту
протягом 1 хвилини.
Квоти (на рівні mind)
Наразі немає квот на розмір сховища або кількість спогадів для окремого mind-у.
Усі обмеження діють на рівні автентифікації/IP, а не даних. Це може змінитися
в майбутньому для справедливості в мультитенантному середовищі.
Моніторинг вашого використання
[CODE BLOCK]
Наступні кроки
- Автентифікація
- Помилки та обробка помилок
────────────────────────────────────────────────────────────
# Scripts API
SUMMARY: Постійне сховище скриптів — зберігайте багаторазові shell-, Python- або Node-скрипти та отримуйте їх через 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 забезпечує постійне сховище для багаторазових скриптів. Скрипти
іменуються та версіонуються в межах mind-у, і їх можна отримувати у вигляді
звичайного тексту — ідеально для шаблонів .
Кінцеві точки
POST /script
Зберегти або оновити скрипт.
[CODE BLOCK]
GET /script/:name
Отримати вміст скрипта як . Ідеально для передавання в bash.
[CODE BLOCK]
GET /script/:name/info
Отримати метадані скрипта без вмісту.
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
GET /scripts
Список усіх скриптів у поточному mind-і.
[CODE BLOCK]
DELETE /script/:name
Видалити скрипт.
[CODE BLOCK]
Типові варіанти використання
Скрипти розгортання
Зберігайте стандартні процедури розгортання, щоб LLM міг їх запускати без
повторного виведення кроків щоразу:
[CODE BLOCK]
Діагностичні сніпети
Зберігайте діагностичні команди для поширених проблем:
[CODE BLOCK]
Генератори конфігурації
Зберігайте скрипти, що генерують конфігурації:
[CODE BLOCK]
Наступні кроки
- Variables API
- Cron та планувальник
────────────────────────────────────────────────────────────
# Tasks API
SUMMARY: Керування завданнями для LLM-агентів — створення, список, оновлення, завершення, видалення завдань із пріоритетами.
KEY CONTEXT:
Auth: Mind Key
List: GET /mind/tasks?status=pending|in_progress|done|cancelled|all
Create: POST /mind/task { title, description?, priority?, due_at? }
Update: PUT /mind/task/:id { title?, description?, priority?, status?, due_at? }
Complete: GET /mind/task/:id/complete
Delete: GET /mind/task/:id/delete
Priorities: low, normal, high, critical
Statuses: pending, in_progress, done, cancelled
Pattern: create tasks for multi-step work, update status as you progress
Tasks API
Tasks API надає LLM-агентам структурований спосіб відстеження багатокрокової
роботи. Завдання прив'язані до поточного mind-у та зберігаються між сесіями, тож
агент може продовжити роботу з того місця, де зупинився.
Кінцеві точки
GET /mind/tasks
Список усіх завдань для поточного mind-у.
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
POST /mind/task
Створити нове завдання.
[CODE BLOCK]
GET /mind/task (параметри запиту)
Створити завдання через GET (для URL-only інструментів).
[CODE BLOCK]
PUT /mind/task/:id
Оновити наявне завдання.
[CODE BLOCK]
GET /mind/task/:id/complete
Позначити завдання як виконане.
[CODE BLOCK]
GET /mind/task/:id/delete
Видалити завдання назавжди.
[CODE BLOCK]
Пріоритети
- — невідкладно
- — за замовчуванням
- — важливо
- — виконати негайно
Статуси
- — створено, не розпочато
- — зараз виконується
- — завершено
- — скасовано
Шаблон: робочий процес на основі завдань
[CODE BLOCK]
Наступні кроки
- Робочий процес на основі завдань
- Cron та планувальник
────────────────────────────────────────────────────────────
# Службові інструменти (час, калькулятор, випадкові значення)
SUMMARY: Публічні службові кінцеві точки — час сервера, безпечний калькулятор, генератор випадкових значень. Автентифікація не потрібна.
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.
Службові інструменти
Кінцеві точки — це публічні утиліти, автентифікація не потрібна. Вони
корисні для LLM-агентів, яким потрібен серверний час, безпечні обчислення або
випадкові значення.
GET /tools/time
Отримати поточний час сервера, часовий пояс та зсув UTC.
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
Варіант використання: LLM-агенти, яким потрібно знати «котра година зараз» для
планування, міток часу чи обчислення відносних дат.
GET /tools/calc
Безпечний калькулятор — лише арифметика, без . Підтримує , , ,
, , , та числа.
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
> [!TIP]
> Використовуйте це замість спроб рахувати в умі або через розбір рядків.
> Це безпечно (неможлива ін'єкція коду) та точно.
Підтримувані оператори
- додавання
- віднімання
- множення
- ділення
- остача від ділення
- дужки
- Числа (цілі та десяткові)
Приклади
[CODE BLOCK]
GET /tools/random
Генерування випадкових значень.
[CODE BLOCK]
Параметри типу
| Тип | Параметри | Виведення |
|------|-----------|--------|
| | немає | Рядок UUID v4 |
| | , (за замовчуванням 0-100) | Ціле число |
| | , (за замовчуванням 0-100) | Дробове число |
| | , (діапазон довжини, за замовчуванням 8-16) | Hex-рядок |
| | , (діапазон довжини, за замовчуванням 8-16) | Алфавітний рядок |
Варіанти використання для LLM-агентів
Генерування унікальних ID
[CODE BLOCK]
Обчислення відсотків
[CODE BLOCK]
Отримання поточної мітки часу
[CODE BLOCK]
Генерування тестових даних
[CODE BLOCK]
Наступні кроки
- Огляд API — усі групи кінцевих точок
- Помилки та обробка помилок
────────────────────────────────────────────────────────────
# API користувачів та mind-ів
SUMMARY: Керування обліковим записом — реєстрація, вхід, створення mind-ів, список mind-ів, видалення mind-ів. Захищено JWT.
KEY CONTEXT:
Auth: JWT (from /register or /login)
Register: POST /register { email, password, display_name? } → returns JWT
Login: POST /login { email, password } → returns JWT
Create mind: POST /minds { name, description? } → returns mind_key (shown once!)
List minds: GET /minds
Delete mind: DELETE /minds/:id (irreversible — deletes all memories!)
JWT expires after 7 days. Mind Key never expires.
Mind Key is shown only once at creation — save it permanently.
API користувачів та mind-ів
API користувачів та mind-ів обробляє керування обліковим записом. Ці кінцеві
точки використовують JWT-автентифікацію (а не Mind Keys), оскільки працюють на
рівні облікового запису, а не на рівні mind-у.
Кінцеві точки автентифікації
POST /register
Створити новий обліковий запис користувача.
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
POST /login
Увійти до наявного облікового запису.
[CODE BLOCK]
Відповідь: як у .
Кінцеві точки mind-ів
POST /minds
Створити новий mind. Повертає Mind Key — збережіть його негайно, він
показується лише один раз.
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
> [!CRITICAL]
> показується лише один раз. Якщо ви його втратите, відновити його
> неможливо — доведеться видалити mind і створити новий (що знищить усі збережені
> спогади).
GET /minds
Список усіх mind-ів для поточного користувача.
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
DELETE /minds/:id
Видалити mind назавжди.
[CODE BLOCK]
> [!WARNING]
> Видалення mind незворотне. Усі спогади, завдання, історія чату та скрипти
> в цьому mind-і будуть безповоротно втрачені. Спочатку експортуйте через
> , якщо потрібна резервна копія.
Шаблон кількох mind-ів
Більшості користувачів корисно мати кілька mind-ів для ізоляції контекстів:
[CODE BLOCK]
Використовуйте різні Mind Keys у різних сесіях LLM, щоб ізолювати контексти.
Безпека облікового запису
Вимоги до пароля
- Мінімум 6 символів
- Без максимуму (використовуйте менеджер паролів)
- Зберігається як bcrypt-хеш (ніколи у відкритому вигляді)
Термін дії JWT
JWT-токени закінчуються через 7 днів. Коли термін дії закінчується, просто
викличте знову.
Безпека Mind Key
Mind Keys ніколи не закінчуються. Якщо Mind Key скомпрометовано:
1. Створіть новий mind через
2. Оновіть конфігурацію LLM новим Mind Key
3. Видаліть скомпрометований mind через
Наступні кроки
- Автентифікація — повний посібник з автентифікації
- Mind Key проти JWT — посібник з вибору
- API спільного доступу — надання іншим користувачам доступу до mind-ів
────────────────────────────────────────────────────────────
# Variables API
SUMMARY: Швидке сховище ключ-значення для стану LLM — лічильники, прапорці, мітки часу останнього бачення, частковий прогрес.
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 — це швидке сховище ключ-значення для ефемерного стану. На відміну
від спогадів (які індексуються, доступні для пошуку та структуровані), змінні
оптимізовані для швидкого читання/запису — ідеально для лічильників, прапорців та
стану сесії.
Кінцеві точки
POST /var
Встановити або оновити змінну.
[CODE BLOCK]
GET /var/:key
Отримати одну змінну.
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
GET /var
Список усіх змінних.
[CODE BLOCK]
DELETE /var/:key
Видалити змінну.
[CODE BLOCK]
Коли використовувати змінні, а коли пам'ять
| Варіант використання | Використовувати |
|----------|-----|
| Ім'я користувача, уподобання | Memory (доступно для пошуку, структуровано) |
| Мітка часу останньої сесії | Variable (ефемерний стан) |
| Лічильник (напр. надіслані повідомлення) | Variable (часті оновлення) |
| Стан робочого процесу («крок 3 з 5 виконано») | Variable (перехідний) |
| Розгорнуті нотатки про проєкт | Memory (повнотекстовий індекс) |
| Багаторазові скрипти | Script store (іменовані, версіоновані) |
Типові шаблони
Відстеження останньої сесії
[CODE BLOCK]
Шаблон лічильника
[CODE BLOCK]
Прапорці функцій
[CODE BLOCK]
Наступні кроки
- Memory API — для структурованих даних, придатних для пошуку
- Cron та планувальник
────────────────────────────────────────────────────────────
# Webhooks API
SUMMARY: Реєстрація HTTP-зворотних викликів для подій пам'яті, чату та завдань — отримуйте сповіщення при зміні даних.
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 дозволяють отримувати HTTP-зворотні виклики, коли в Synapse відбуваються
події. Ідеально підходить для запуску зовнішньої автоматизації, надсилання
сповіщень або синхронізації з іншими системами.
Кінцеві точки
POST /webhooks
Зареєструвати новий webhook.
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
GET /webhooks
Список усіх webhook-ів для поточного mind-у.
[CODE BLOCK]
GET /webhooks/:id
Отримати один webhook.
[CODE BLOCK]
PUT /webhooks/:id
Оновити webhook (URL, події, секрет або прапорець enabled).
[CODE BLOCK]
DELETE /webhooks/:id
Видалити webhook.
[CODE BLOCK]
Типи подій
| Шаблон | Спрацьовує коли |
|---------|------------|
| | Будь-яка подія пам'яті |
| | Збережено новий спогад |
| | Спогад оновлено |
| | Спогад видалено |
| | Будь-яка подія чату |
| | Нове повідомлення від людини |
| | Будь-яка подія завдання |
| | Створено нове завдання |
| | Завдання позначено як виконане |
| | Усі події |
Корисне навантаження webhook
Коли подія спрацьовує, Synapse надсилає POST на ваш URL:
[CODE BLOCK]
Перевірка підпису
Якщо ви встановили , Synapse підписує кожне корисне навантаження через HMAC-SHA256:
[CODE BLOCK]
Перевірка у вашому обробнику:
[CODE BLOCK]
Шаблон: синхронізація в реальному часі
[CODE BLOCK]
Наступні кроки
- Cron та планувальник
- Посібник з автоматизації webhook-ів
## КАТЕГОРІЯ: ІНТЕГРАЦІЯ MCP
Інтеграція з Claude, Cursor та іншими MCP-клієнтами.
────────────────────────────────────────────────────────────
# MCP у Claude Code
SUMMARY: Використовуйте інструменти Synapse з термінальним агентом Claude Code — постійна пам'ять для сесій програмування.
KEY CONTEXT:
Claude Code config: ~/.claude/config.json (or via `claude mcp add` command)
Command: npx -y synapse-mcp-api@latest
Env: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional)
Alternative: `claude mcp add synapse -- npx -y synapse-mcp-api@latest`
Then: set SYNAPSE_MIND_KEY env var in your shell
Test: in claude code, type "recall all my memories"
MCP у Claude Code
Claude Code — це термінальний агент програмування від Anthropic. Із Synapse MCP
Claude Code отримує постійну пам'ять між сесіями програмування — він пам'ятає
контекст вашого проєкту, минулі рішення та шаблони кодової бази.
Налаштування
Метод 1: CLI-команда (рекомендовано)
[CODE BLOCK]
Метод 2: редагування конфігураційного файлу
Відредагуйте :
[CODE BLOCK]
Перевірка роботи
Запустіть Claude Code:
[CODE BLOCK]
У промпті Claude Code введіть:
[CODE BLOCK]
Claude має викликати і відповісти вашими збереженими спогадами.
Типові шаблони
Постійність контексту проєкту
На початку сесії програмування:
[CODE BLOCK]
Claude викликає , бачить ваш список проєктів і продовжує роботу
з того місця, де ви зупинилися.
Рішення щодо кодової бази
Коли ви приймаєте архітектурне рішення:
[CODE BLOCK]
Claude викликає із категорією та пріоритетом .
Уникнення минулих помилок
[CODE BLOCK]
Claude шукає спогади з категорією та нагадує вам про минулі помилки.
Відстеження завдань
[CODE BLOCK]
Claude викликає , і завдання зберігається між сесіями.
Профілі інструментів
Для сесій програмування, коли вам не потрібні всі 119 інструментів:
[CODE BLOCK]
Вирішення проблем
MCP-сервер не запускається
[CODE BLOCK]
Mind Key не розпізнається
[CODE BLOCK]
Claude Code не бачить інструментів
- Перезапустіть Claude Code після змін конфігурації
- Перевірте , щоб упевнитися, що Synapse зареєстрований
- Див. Вирішення проблем MCP
Наступні кроки
- Налаштування Claude Desktop
- Налаштування Cursor
- Посібник зі створення постійного LLM-агента
────────────────────────────────────────────────────────────
# MCP у Claude Desktop
SUMMARY: Підключіть Synapse до Claude Desktop за 2 хвилини. Claude отримує 79 інструментів Synapse нативно.
KEY CONTEXT:
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\Claude\claude_desktop_config.json (Windows)
MCP server command: npx -y synapse-mcp-api@latest
Env vars: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional, default https://synapse.schaefer.zone)
After config: restart Claude Desktop, check for 🔌 icon with "79 tools"
Test: type "memory_recall aufrufen" in a new chat
Troubleshooting: Node.js ≥ 18, check Mind Key, see /docs/mcp/troubleshooting
MCP у Claude Desktop
Claude Desktop — це десктоп-додаток Anthropic для macOS та Windows. Із
налаштованим MCP-сервером Synapse Claude отримує нативний доступ до всіх 79
інструментів Synapse — він може зберігати спогади, відкликати їх, керувати
завданнями, спілкуватися з вами через чат та багато іншого.
Передумови
- Додаток Claude Desktop (macOS або Windows)
- Node.js 18+ встановлено ()
- Ваш Synapse Mind Key
Крок 1: відкрийте конфігураційний файл
- macOS:
- Windows:
Якщо файл не існує, створіть його.
Крок 2: додайте MCP-сервер Synapse
[CODE BLOCK]
> [!TIP]
> Якщо у вас вже налаштовано інші MCP-сервери, просто додайте блок
> усередину наявного об'єкта .
Крок 3: перезапустіть Claude Desktop
1. Повністю закрийте Claude Desktop (Cmd+Q на macOS, а не просто закрийте вікно)
2. Знову відкрийте Claude Desktop
3. Почніть новий чат
4. Знайдіть значок роз'єму 🔌 у нижньому лівому куті — має писати «79 tools»
Крок 4: перевірте
У новому чаті введіть:
[CODE BLOCK]
Claude має викликати інструмент і відповісти резюме ваших
збережених спогадів (або «No memories yet», якщо ваш mind порожній).
Доступні інструменти (вибірка)
| Інструмент | Опис |
|------|-------------|
| | Відкликати всі спогади |
| | Зберегти новий спогад |
| | Шукати спогади |
| | Вивести список завдань |
| | Створити завдання |
| | Перевірити нові повідомлення |
| | Відповісти на повідомлення |
| | Відкрити вкладку браузера |
| | Вивести список зареєстрованих комп'ютерів |
Повний список: Що таке MCP?
Вирішення проблем
Інструменти не з'являються в Claude Desktop
1. Перевірте версію Node.js: (має бути ≥ 18)
2. Перевірте, що конфігураційний файл є коректним JSON (без кінцевих ком)
3. Повністю перезапустіть Claude Desktop (Cmd+Q, а не просто закрити)
4. Перевірте логи Claude Desktop: (macOS)
Помилка «Mind Key invalid»
- Перевірте, що починається з
- Отримайте свіжий ключ через (потребує JWT з )
- Без лапок навколо ключа в JSON
npx не знайдено
- Встановіть Node.js 18+:
- Перезапустіть термінал після встановлення
- На macOS з Homebrew:
Інструменти відображаються, але виклики зазнають невдачі
- Перевірте, що доступний:
- Перевірте, що ваш Mind Key працює:
- Див. Вирішення проблем MCP
Профілі інструментів (економія токенів)
Якщо ви використовуєте менший LLM або хочете зберегти контекстні токени, установіть профіль інструментів:
[CODE BLOCK]
Профілі: (8 інструментів), (25), (119, за замовчуванням).
Наступні кроки
- Налаштування Claude Code
- Налаштування Cursor
- Вирішення проблем MCP
────────────────────────────────────────────────────────────
# MCP у Continue.dev
SUMMARY: Підключіть Synapse до Continue.dev — AI-асистента програмування з відкритим кодом для VS Code та JetBrains.
MCP у Continue.dev
Continue.dev — це AI-асистент програмування з відкритим кодом для VS Code та
IDE JetBrains. Із Synapse MCP Continue отримує постійну пам'ять між сесіями.
Передумови
- VS Code або IDE JetBrains
- Встановлено розширення Continue.dev
- Node.js 18+
- Ваш Synapse Mind Key
Налаштування
Крок 1: відкрийте конфігурацію Continue
У VS Code або JetBrains:
1. Відкрийте бічну панель розширення Continue
2. Натисніть значок шестірні → «Open config.json»
Або редагуйте безпосередньо.
Крок 2: додайте MCP-сервер Synapse
[CODE BLOCK]
Крок 3: перезавантажте Continue
Перезавантажте вікно VS Code (Cmd+Shift+P → «Reload Window») або перезапустіть IDE.
Перевірка роботи
У чаті Continue:
[CODE BLOCK]
Continue має викликати і відповісти вашими збереженими спогадами.
Типові шаблони
Контекст проєкту
[CODE BLOCK]
Continue викликає , бачить ваші спогади проєкту та продовжує
роботу з того місця, де ви зупинилися.
Шаблони рецензування коду
[CODE BLOCK]
Continue знаходить ваші збережені шаблони рецензування коду та застосовує їх.
Пам'ять парного програмування
[CODE BLOCK]
Continue зберігає це як спогад типу .
Вирішення проблем
MCP-сервер не підключається
1. Перевірте, що є коректним JSON
2. Перевірте Node.js:
3. Перевірте панель виводу Continue (View → Output → Continue)
4. Перезапустіть IDE
Інструменти не з'являються
- Перевірте, що версія Continue підтримує MCP (≥ 0.9.x)
- Перевірте, що змінну середовища установлено в конфігурації
- Шукайте помилки MCP у логах Continue
Наступні кроки
- Налаштування Claude Desktop
- Власний MCP-клієнт
────────────────────────────────────────────────────────────
# MCP у Cursor
SUMMARY: Підключіть Synapse до IDE Cursor для постійної пам'яті проєкту між сесіями програмування.
MCP у Cursor
Cursor — це IDE на основі AI, створена на базі VS Code. Із Synapse MCP Cursor
отримує постійну пам'ять між сесіями — він пам'ятає ваші проєктні рішення,
шаблони кодової бази та минулі сесії зневадження.
Передумови
- Встановлено IDE Cursor ()
- Node.js 18+
- Ваш Synapse Mind Key
Налаштування
Крок 1: відкрийте налаштування Cursor
У Cursor:
1. Відкрийте Налаштування (Cmd+, на macOS, Ctrl+, на Windows/Linux)
2. Знайдіть «MCP» або перейдіть до
Крок 2: додайте MCP-сервер Synapse
Натисніть «Add MCP Server» і налаштуйте:
| Поле | Значення |
|-------|-------|
| Name | |
| Type | |
| Command | |
| Env | |
Крок 3: редагуйте config.json безпосередньо (альтернатива)
Cursor зберігає конфігурацію MCP у :
[CODE BLOCK]
Крок 4: перезапустіть Cursor
Повністю перезапустіть Cursor (Cmd+Q і відкрийте знову на macOS).
Перевірка роботи
У панелі чату Cursor (Cmd+L):
[CODE BLOCK]
Cursor має викликати і відповісти вашими збереженими спогадами.
Типові шаблони
Онбординг проєкту
Під час відкриття нового проєкту:
[CODE BLOCK]
Cursor викликає і продовжує роботу з того місця, де ви зупинилися.
Архітектурні рішення
[CODE BLOCK]
Cursor зберігає це як спогад із пріоритетом .
Історія зневадження
[CODE BLOCK]
Cursor шукає спогади та нагадує вам про минулі виправлення.
Шаблони коду між сесіями
[CODE BLOCK]
Cursor знаходить спогади про реалізації автентифікації, які ви робили раніше.
Вирішення проблем
MCP-сервер не підключається
1. Перевірте Node.js: (≥ 18)
2. Перевірте MCP-сервер: (має запуститися без помилок)
3. Перевірте логи MCP Cursor (View → Output → MCP)
4. Повністю перезапустіть Cursor
Інструменти не з'являються
- Перевірте, що є коректним JSON
- Перевірте, що змінну середовища установлено
- Перевірте, що версія Cursor підтримує MCP (≥ 0.42)
Mind Key недійсний
[CODE BLOCK]
Наступні кроки
- Налаштування Claude Desktop
- Налаштування Continue.dev
- Посібник зі створення постійного LLM-агента
────────────────────────────────────────────────────────────
# Створення власного MCP-клієнта
SUMMARY: Підключіться до MCP-сервера Synapse з власного застосунку за допомогою MCP SDK.
Створення власного MCP-клієнта
Якщо ви створюєте власний LLM-застосунок, ви можете підключитися до MCP-сервера
Synapse безпосередньо, використовуючи офіційний MCP SDK. Це дає вашому застосунку
доступ до всіх 79 інструментів Synapse.
SDK
| Мова | Пакет |
|----------|---------|
| TypeScript/JavaScript | |
| Python | |
Приклад на TypeScript
Встановлення
[CODE BLOCK]
Підключення через stdio
[CODE BLOCK]
Підключення через HTTP/SSE (віддалене)
[CODE BLOCK]
Приклад на Python
Встановлення
[CODE BLOCK]
Підключення через stdio
[CODE BLOCK]
Профілі інструментів
Під час підключення ви можете запросити конкретний профіль інструментів через
заголовок (HTTP/SSE) або змінну середовища (stdio):
[CODE BLOCK]
Обробка помилок
[CODE BLOCK]
Варіанти використання
- Власні AI-асистенти — створіть свого агента з постійною пам'яттю
- Автоматизація робочих процесів — об'єднуйте інструменти Synapse у власні робочі процеси
- Конвеєри даних — видобувайте спогади, трансформуйте, завантажуйте в інше місце
- Інформаційні панелі моніторингу — відображайте статистику пам'яті, історію чату, завдання
Наступні кроки
- Специфікація MCP
- Репозиторій Synapse MCP
- Огляд API
────────────────────────────────────────────────────────────
# Вирішення проблем MCP
SUMMARY: Вирішення типових проблем інтеграції MCP — сервер не запускається, інструменти не з'являються, помилки автентифікації.
KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/
Вирішення проблем MCP
Типові проблеми та рішення під час інтеграції Synapse MCP із вашим LLM-клієнтом.
Швидкий діагностичний чек-лист
1. ✅ Node.js 18+ встановлено? ()
2. ✅ Mind Key починається з ? (не JWT )
3. ✅ Synapse API доступний? ()
4. ✅ Mind Key працює? ()
5. ✅ Конфігураційний файл є коректним JSON? (без кінцевих ком, без коментарів)
6. ✅ Клієнт перезапущено після зміни конфігурації?
7. ✅ MCP-сервер запускається вручну? ()
Проблема: інструменти не з'являються в клієнті
Симптоми
- Claude Desktop / Cursor / Continue показує 0 інструментів
- Немає значка 🔌 або запису «synapse» у списку MCP-серверів
Рішення
1. Повністю перезапустіть клієнт — Cmd+Q на macOS (не просто закрийте вікно)
2. Перевірте розташування конфігураційного файлу:
- Claude Desktop macOS:
- Claude Desktop Windows:
- Cursor:
- Continue:
3. Валідуйте JSON — вставте конфігурацію у
4. Перевірте логи клієнта на помилки MCP:
- Claude Desktop: (macOS)
- Cursor: View → Output → MCP
5. Запустіть MCP-сервер вручну, щоб побачити помилки запуску:
[CODE BLOCK]
Проблема: помилка «Mind Key invalid»
Симптоми
- Інструменти з'являються, але виклики зазнають невдачі з «401 Unauthorized»
- Помилка: «Mind Key fehlt oder ungültig»
Рішення
1. Перевірте формат Mind Key — починається з , 40 символів
2. Протестуйте безпосередньо:
[CODE BLOCK]
3. Перевірте, що змінну середовища встановлено — для транспорту stdio змінна середовища має бути в конфігурації MCP-сервера, а не у вашій оболонці
4. Отримайте свіжий Mind Key:
[CODE BLOCK]
Проблема: npx не знайдено
Симптоми
- Помилка: «npx: command not found»
- MCP-сервер не запускається
Рішення
1. Встановіть Node.js 18+:
- macOS: або завантажте з
- Linux:
- Windows: завантажте з
2. Перезапустіть термінал після встановлення
3. Перевірте:
Проблема: SYNAPSEURL недоступний
Симптоми
- MCP-сервер запускається, але виклики інструментів завершуються на тайм-ауті
- Помилка: «fetch failed» або «ECONNREFUSED»
Рішення
1. Перевірте з'єднання:
[CODE BLOCK]
2. Перевірте корпоративний фаєрвол — може блокувати вихідний HTTPS
3. Спробуйте альтернативний URL:
- Production:
- MCP-сервер:
4. Для самостійно розгорнутих: переконайтеся, що ваш екземпляр Synapse працює та доступний
Проблема: MCP-сервер аварійно завершується
Симптоми
- MCP-сервер завершується одразу після запуску
- Логи клієнта показують «MCP server disconnected»
Рішення
1. Запустіть вручну, щоб побачити помилку:
[CODE BLOCK]
2. Перевірте конфлікти портів — MCP-сервер використовує порт 13100 за замовчуванням
3. Очистіть кеш npx:
[CODE BLOCK]
4. Оновіть до останньої версії:
[CODE BLOCK]
Проблема: виклики інструментів повертають 429
Симптоми
- Помилка: «Rate limit exceeded»
Рішення
Цього не повинно траплятися з MCP (використовується автентифікація через заголовок, без обмеження частоти). Якщо все ж трапилось:
1. Перевірте, чи використовуєте десь — перейдіть на автентифікацію через заголовок
2. Перевірте — упевніться, що він вказує на правильний екземпляр
3. Зверніться до підтримки, якщо проблема не зникає
Проблема: інструменти з'являються, але не працюють
Симптоми
- Інструменти в списку клієнта
- Виклик інструменту повертає помилку або без результату
Рішення
1. Перевірте назву інструменту — має бути точною (наприклад, , а не )
2. Перевірте аргументи — звірьте зі схемою вводу інструменту
3. Протестуйте через прямий API:
[CODE BLOCK]
4. Перевірте стан Synapse:
[CODE BLOCK]
Отримання допомоги
Якщо жодне з вищезазначеного не вирішило вашу проблему:
1. Перевірте наявні issues:
2. Відкрийте нове issue із:
- Версією MCP-сервера ()
- Назвою та версією клієнта
- Операційною системою
- Відповідними уривками логів
- Кроками для відтворення
Наступні кроки
- Налаштування Claude Desktop
- Налаштування Claude Code
- Помилки API
────────────────────────────────────────────────────────────
# Що таке MCP?
SUMMARY: Model Context Protocol дозволяє LLM викликати зовнішні інструменти. Synapse викриває 79 інструментів через офіційний MCP-сервер.
KEY CONTEXT:
MCP = Model Context Protocol (Anthropic, 2024). Open standard for LLM-tool integration.
Synapse has official MCP server: synapse-mcp-api (npm package, npx -y synapse-mcp-api@latest)
79 tools exposed: 22 memory, 7 chat, 8 scheduler, 4 tasks, 5 scripts, 9 computers, 4 push, 5 user, 3 utility
3 transports: stdio (local), HTTP/SSE (remote), WebSocket (mobile)
Supported clients: Claude Desktop, Claude Code, Cursor, Continue, Cline, any MCP-compatible client
Tool Profiles (v1.4.0): minimal (8 tools), standard (25), full (119) — controlled via MCP_PROFILE env or Mcp-Tool-Profile header
Що таке MCP?
Model Context Protocol (MCP) — це відкритий стандарт від Anthropic (2024),
який дозволяє LLM викликати зовнішні інструменти структурованим чином. Замість
вставлення API-документації у промпт, ви реєструєте інструменти на MCP-сервері,
а LLM викликає їх за потреби — як function calling, але стандартизовано та
незалежно від клієнта.
MCP-сервер Synapse
Synapse постачається з офіційним MCP-сервером ( на npm), що викриває
79 інструментів, які покривають усі можливості Synapse:
| Категорія | Інструменти | Кількість |
|----------|-------|-------|
| Memory | recall, list, store, search, semantic-search, update, delete, bulk-delete, stats, unverified, contradictions, audit, related, by-tag, diff, expiring, health, sync, embed-batch, verify, unverify, mind-export | 22 |
| Chat | poll, reply, status, history, unread, send, upload | 7 |
| Scheduler | cronlist, croncreate, crondelete, crontoggle, varlist, varget, varset, vardelete | 8 |
| Tasks | tasklist, taskget, taskcreate, taskupdate | 4 |
| Scripts | scriptlist, scriptget, scriptinfo, scriptstore, scriptdelete | 5 |
| Computers | computerlist, computerget, installcode, screenshot, commandqueue, commandstatus, commandslist, disable, delete | 9 |
| Push | vapidpublickey, subscribe, unsubscribe, test | 4 |
| User/Mind | register, login, mindslist, mindcreate, minddelete | 5 |
| Utility | time, calc, random | 3 |
| Visualization | graph, tags, compact | 3 |
| Sharing | share, list, revoke | 3 |
| Webhooks | register, list, get, update, delete | 5 |
| Browser | new, navigate, click, type, screenshot, close | 6 |
| Усього | | 79+ |
Як це працює
[CODE BLOCK]
1. Ви налаштовуєте ваш LLM-клієнт (Claude Desktop, Cursor тощо) на використання MCP-сервера Synapse
2. Клієнт запускає MCP-сервер (через )
3. MCP-сервер підключається до Synapse API за допомогою вашого Mind Key
4. LLM бачить усі 79 інструментів як нативні функції, які він може викликати
5. Коли LLM має щось запам'ятати, він викликає — MCP-сервер транслює це у на Synapse
Транспорти
MCP-сервер Synapse підтримує три транспорти:
stdio (локально, рекомендовано для десктопа)
[CODE BLOCK]
HTTP/SSE (віддалено, мультитенантно)
Підключіть ваш MCP-клієнт до:
[CODE BLOCK]
WebSocket (мобільні, великий обсяг)
[CODE BLOCK]
Профілі інструментів (v1.4.0)
Щоб зменшити витрату токенів для менших LLM, MCP-сервер підтримує три
профілі інструментів:
| Профіль | Інструменти | Токени | Найкраще для |
|---------|-------|--------|----------|
| | 8 (композитна диспетчеризація) | 500 | Самохостовані LLM із контекстом ≤8k |
| | 25 (іменовані) | 2,500 | Середні LLM (Claude Haiku, GPT-3.5) |
| | 119 (усі) | 8,250 | Великі LLM (Claude Sonnet/Opus, GPT-4) — за замовчуванням |
Керування через:
- Змінну середовища:
- Заголовок:
Підтримувані клієнти
- Claude Desktop — десктоп-додаток Anthropic
- Claude Code — термінальний агент програмування
- Cursor — IDE на основі AI
- Continue.dev — AI-асистент програмування з відкритим кодом
- Cline — розширення VS Code
- Будь-який MCP-сумісний клієнт
Чому варто використовувати MCP замість прямого API?
| Підхід | Плюси | Мінуси |
|----------|------|------|
| Прямий API | Простий, без зайвого шару | LLM має знати URL, заголовки, автентифікацію |
| MCP | LLM бачить нативні інструменти, не треба запам'ятовувати URL | Додатковий процес MCP-сервера |
Для більшості сценаріїв використання LLM-агентів MCP — кращий вибір, адже LLM
не повинен запам'ятовувати API-шляхи чи шаблони автентифікації.
Наступні кроки
- Налаштування Claude Desktop — конфігурація за 2 хвилини
- Налаштування Claude Code — термінальна інтеграція
- Власний MCP-клієнт — створіть свій
## КАТЕГОРІЯ: ПОСІБНИКИ ТА ІНСТРУКЦІЇ
Покрокові посібники для конкретних сценаріїв.
────────────────────────────────────────────────────────────
# Автоматизоване тестування iOS-додатків
SUMMARY: Використовуйте Synapse + Computer Control API для автоматизації тестування iOS-додатків через Simulator.
Автоматизоване тестування iOS-додатків
Поєднайте систему пам'яті Synapse з Computer Control API для побудови тестів
iOS-додатків під керуванням LLM. LLM запам'ятовує тестові сценарії, вчиться з
минулих невдач та адаптується до змін UI.
Архітектура
[CODE BLOCK]
Передумови
- Обліковий запис Synapse + Mind Key
- MCP-сервер Synapse налаштовано у Claude Desktop
- iOS Simulator із встановленим
- Комп'ютер зареєстровано в Synapse (дивіться Computer Control API)
Крок 1: Зареєструйте комп'ютер Simulator
На Mac, де запущено iOS Simulator:
[CODE BLOCK]
Крок 2: Збережіть тестові сценарії в пам'яті
Зберігайте багаторазові тестові сценарії як спогади:
[CODE BLOCK]
Крок 3: Виконання тестів під керуванням LLM
У Claude Desktop (із налаштованим Synapse MCP):
[CODE BLOCK]
Claude:
1. Викличе , щоб знайти спогад
2. Викличе , щоб побачити поточний стан
3. Виконає кожен крок через (click, type)
4. Перевірить результати через знімки екрана
5. Збереже будь-які невдачі як спогади
Крок 4: Тести з самовідновленням
Коли тест провалюється, збережіть невдачу та відновлення:
[CODE BLOCK]
Наступного разу, коли LLM запускає тест, він відкликає невдачу та застосовує
відновлення автоматично.
Крок 5: Відстеження результатів тестів
Відстежуйте запуск тестів як завдання:
[CODE BLOCK]
Поширені команди
| Дія | Команда |
|--------|---------|
| Запуск Simulator | |
| Знімок екрана | (через Synapse MCP) |
| Тап у (x,y) | |
| Введення тексту | |
| Натиснути Home | |
Найкращі практики
> [!TIP]
> - Зберігайте координати UI як спогади — UI змінюється, але LLM може перенавчатись
> - Використовуйте мітки доступності — стабільніші за координати
> - Зберігайте тестові дані окремо — використовуйте змінні для імен користувачів, паролів
> - Запускайте тести в чистому стані — скидайте Simulator між запусками
> - Логуйте знімки для невдач — корисно для налагодження
Наступні кроки
- Тести з самовідновленням
- Computer Control API
- Найкращі практики роботи з пам'яттю
────────────────────────────────────────────────────────────
# Резервне копіювання та відновлення
SUMMARY: Експортуйте спогади для резервного копіювання, міграції між mind-ами, відновлення після втрати даних.
Резервне копіювання та відновлення
Synapse забезпечує повний експорт/імпорт для резервного копіювання пам'яті,
міграції та відновлення після збоїв. Цей посібник охоплює основні операції.
Експорт
Повний експорт mind-у
Експорт усіх спогадів у mind-і як JSON:
[CODE BLOCK]
Формат відповіді:
[CODE BLOCK]
Інкрементальний експорт (Diff)
Експорт лише спогадів, що змінилися з мітки часу:
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
Автоматизоване резервне копіювання
Плануйте щоденне резервне копіювання через cron:
[CODE BLOCK]
> [!NOTE]
> Cron-кінцева точка отримує відповідь, але не зберігає її. Для реального
> резервного копіювання вкажіть cron на ваш власний резервний сервер, що
> зберігає відповідь.
Краще: зовнішній скрипт резервного копіювання
[CODE BLOCK]
Додайте у crontab:
[CODE BLOCK]
Відновлення
Відновлення в той самий mind
[CODE BLOCK]
Відновлення в новий mind
[CODE BLOCK]
Скрипт відновлення на Python
[CODE BLOCK]
Міграція між mind-ами
[CODE BLOCK]
Резервне копіювання інших даних
Не забудьте робити резервні копії:
| Тип даних | Кінцева точка |
|-----------|----------|
| Memories | |
| Tasks | |
| Scripts | |
| Webhooks | |
| Cron jobs | |
| Variables | |
| Chat history | |
Перевірка
Після відновлення перевірте:
[CODE BLOCK]
Найкращі практики
> [!TIP]
> - Резервне копіювання щодня — автоматизуйте через cron
> - Тестуйте відновлення — резервна копія, яку не можна відновити, марна
> - Зберігайте кілька версій — щонайменше 30 днів
> - Зберігайте поза сайтом — S3, Backblaze B2 тощо
> - Шифруйте чутливі резервні копії — спогади можуть містити PII
> - Документуйте процес відновлення — ви забудете його до моменту, коли він знадобиться
Наступні кроки
- Memory API
- Cron та планувальник — для автоматизованого резервного копіювання
────────────────────────────────────────────────────────────
# Найкращі практики роботи з пам'яттю
SUMMARY: Як структурувати спогади для ефективного відкликання — категорії, ключі, теги, пріоритети.
Найкращі практики роботи з пам'яттю
Те, як ви структуруєте спогади, визначає їхню корисність. Цей посібник охоплює
шаблони категоризації, тегування та пріоритизації спогадів, щоб LLM міг
відкликати правильну інформацію в потрібний момент.
Категорії: обирайте найбільш конкретну
| Категорія | Для чого | Приклад |
|----------|---------|---------|
| | Ім'я, роль, контактна інформація | |
| | Подобання, антипатії, стиль роботи | |
| | Перевірювані факти | |
| | Статус проєкту, рішення | |
| | Навички користувача | |
| | Минулі помилки для уникнення | |
| | Контекст, релевантний сесії | |
| | Різні нотатки | |
> [!TIP]
> У разі сумніву використовуйте для перевірюваної інформації та
> для всього іншого. Не надмірно категоризуйте — краще мати чіткий , ніж
> заплутаний .
Ключі: змістовні ідентифікатори
Поле — це ідентифікатор спогаду. Використовуйте змістовні, стабільні ключі:
Хороші ключі:
-
-
-
-
Погані ключі:
- (не змістовний)
- (не описовий)
- (дата не допомагає відкликанню)
Угоди іменування ключів
- (нижній регістр із підкресленнями)
- Префіксуйте категорією: , ,
- Використовуйте описові іменники, а не дієслова
- До 50 символів
Теги: для пошуку та фільтрації
Теги забезпечують швидку фільтрацію та пошук. Додавайте 2-5 тегів на спогад:
[CODE BLOCK]
Шаблони тегів
- Назви проєктів: , ,
- Тем: , , ,
- Статусу: , ,
- Індикатори пріоритету: ,
> [!NOTE]
> Теги нечутливі до регістру. Використовуйте нижній регістр для узгодженості.
Пріоритети: будьте реалістичними
| Пріоритет | Для чого | % спогадів |
|----------|---------|---------------|
| | Ідентичність користувача, юридична інформація, незворотні рішення | 5% |
| | Активні проєкти, важливі уподобання | 20% |
| | Більшість фактів, нотаток, контексту | 65% |
| | Ефемерне, корисно знати | 10% |
> [!WARNING]
> Не позначайте все . Якщо все критичне, то нічого не критичне.
> Залишайте для речей, що спричинять реальну шкоду при забуванні.
Коли зберігати, а коли ні
Завжди зберігайте
- Ідентичність користувача (ім'я, email, роль)
- Довготривалі уподобання
- Рішення про проєкт та їх обґрунтування
- Минулі помилки та отримані уроки
- Зобов'язання перед користувачем
Не зберігайте
- Перехідний стан (використовуйте змінні)
- Історію розмов дослівно (це обробляє система чату)
- Чутливі дані (паролі, API-ключі)
- Факти, що легко вивести (поточна дата, вміст файлів)
- Ефемерний контекст (використовуйте категорію із низьким пріоритетом)
Оновлення спогадів
POST з тією ж + оновлює наявний спогад:
[CODE BLOCK]
> [!TIP]
> Використовуйте стабільні ключі, щоб оновлювати без створення дублікатів. LLM
> має повторно POST-нути той самий ключ при зміні інформації, а не створювати
> нові спогади.
Життєвий цикл спогаду
[CODE BLOCK]
- Create: POST /memory з повним контекстом
- Active: Часто відкликати, оновлювати за потреби
- Stale: Ще релевантні, але не активно використовуються (знизити пріоритет?)
- Archive: Встановити пріоритет , зберігати для історичного довідника
- Delete: DELETE /memory/:id, коли більше не релевантний
Періодичне очищення
[CODE BLOCK]
Шаблон: успадкування спогадів
Для ієрархічного контексту (проєкт → підпроєкт → завдання):
[CODE BLOCK]
Потім LLM може шукати , щоб знайти всі пов'язані спогади.
Шаблон: журнал рішень
Зберігайте рішення з обґрунтуванням, щоб LLM не переробляв їх:
[CODE BLOCK]
Шаблон: уникнення помилок
Зберігайте помилки зі специфічними інструкціями уникнення:
[CODE BLOCK]
Антишаблони для уникнення
> [!WARNING]
> - Зберігання логів розмов — це обробляє система чату
> - Зберігання цілих файлів — використовуйте сховище скриптів або зовнішнє сховище
> - Зберігання ефемерного стану — використовуйте змінні
> - Зберігання секретів — використовуйте змінні середовища
> - Дублювання спогадів — використовуйте стабільні ключі
> - Надмірне тегування — 2-5 тегів на спогад ідеально
> - Усе критичне — будьте реалістичними з пріоритетами
Наступні кроки
- Memory API
- Постійний LLM-агент
- Стратегія тегування пам'яті
────────────────────────────────────────────────────────────
# Координація кількох агентів
SUMMARY: Координуйте кількох LLM-агентів зі спільними mind-ами, завданнями та чатом Synapse.
Координація кількох агентів
Коли у вас кілька LLM-агентів, що працюють над пов'язаними завданнями, Synapse
забезпечує шар координації — спільну пам'ять, призначення завдань та асинхронний чат.
Шаблони
Шаблон 1: Спільний mind (єдине джерело істини)
Усі агенти поділяють один Mind Key. Вони читають/пишиуть у одне сховище пам'яті.
[CODE BLOCK]
Варіант використання: Невелика команда агентів над одним проєктом.
Налаштування:
[CODE BLOCK]
Координація через завдання:
[CODE BLOCK]
Шаблон 2: Спеціалізовані mind-и (ізольовані контексти)
Кожен агент має власний mind. Вони спілкуються через спільний «координаційний» mind.
[CODE BLOCK]
Варіант використання: Агенти з різними спеціальностями (кодування, рев'ю, розгортання).
Налаштування:
[CODE BLOCK]
Координація через спільний mind:
[CODE BLOCK]
Шаблон 3: Хаб-і-спиці (оркестратор)
Центральний агент-оркестратор призначає завдання робочим агентам.
[CODE BLOCK]
Варіант використання: Складні робочі процеси з паралельною роботою.
Реалізація:
[CODE BLOCK]
Координація через чат
Агенти можуть спілкуватися через систему чату:
[CODE BLOCK]
> [!NOTE]
> Повідомлення чату позначаються роллю. Встановлюйте role=agent для повідомлень
> між агентами, role=human для повідомлень людина-агент.
Координація через змінні
Використовуйте змінні для легкої координації (блокування, прапорці):
[CODE BLOCK]
Найкращі практики
> [!TIP]
> - Окремі mind-и для окремих завдань — не змішуйте пам'ять кодера та рев'юера
> - Тегуйте агентів у чаті — для чіткої адресації
> - Використовуйте завдання для призначення роботи — а не чат (чат для обговорення)
> - Реалізуйте ідемпотентність — агенти можуть повторювати невдалі операції
> - Логуйте все — зберігайте рішення в пам'яті для перевірочності
Наступні кроки
- Постійний LLM-агент
- Куховарська книга LLM
- Автоматизація webhook-ів
────────────────────────────────────────────────────────────
# Створення постійного LLM-агента
SUMMARY: Покроковий посібник зі створення LLM-агента, що пам'ятає між сесіями за допомогою Synapse.
Огляд
Цей посібник проведе вас через побудову LLM-агента, що зберігає контекст між
сесіями за допомогою Synapse. Наприкінці ваш агент зможе:
- Відкликати минулий контекст на початку сесії
- Зберігати нові висновки в міру їхньої появи
- Відстежувати багатокрокові завдання між сесіями
- Спілкуватися з людьми через асинхронний чат
Архітектура
[CODE BLOCK]
Крок 1: Налаштуйте Mind Key
[CODE BLOCK]
Крок 2: Протокол початку сесії
На початку кожної сесії відкличайте всі спогади:
[CODE BLOCK]
Крок 3: Зберігання нових висновків
Щоразу, коли агент дізнається щось варте запам'ятовування:
[CODE BLOCK]
Крок 4: Керування завданнями
Відстежуйте багатокрокову роботу між сесіями:
[CODE BLOCK]
Крок 5: Асинхронний чат з людьми
Опитуйте повідомлення між викликами інструментів:
[CODE BLOCK]
Крок 6: Протокол кінця сесії
Наприкінці сесії зберігайте фінальний контекст:
[CODE BLOCK]
Повний шаблон
[CODE BLOCK]
Найкращі практики
> [!TIP]
>
> - Завжди відкликати спочатку — ніколи не починайте роботу без завантаження контексту
> - Зберігайте проактивно — не чекайте до кінця сесії
> - Використовуйте змістовні ключі — , , а не
> - Тегуйте все — теги забезпечують пошук та фільтрацію
> - Встановлюйте реалістичні пріоритети — не все
Наступні кроки
- Куховарська книга LLM — практичні шаблони
- Найкращі практики роботи з пам'яттю
- Координація кількох агентів
────────────────────────────────────────────────────────────
# Конвеєри тестів із самовідновленням
SUMMARY: Створюйте конвеєри тестів, що вчаться з невдач та адаптуються автоматично за допомогою пам'яті Synapse.
Конвеєри тестів із самовідновленням
Традиційні набори тестів ламаються при зміні UI. Тести з самовідновленням
використовують пам'ять Synapse, щоб вчитися з минулих невдач та адаптуватися —
це зменшує flaky-тести та витрати на обслуговування.
Концепція
[CODE BLOCK]
1. Тест запускається
2. Якщо він провалюється, зберегти невдачу (що пішло не так, чому, як виправити)
3. Наступний запуск: відкликати відповідні невдачі перед виконанням
4. Застосувати відомі виправлення автоматично
Реалізація
Крок 1: Обгортка тесту
Обгорніть кожен тест відкликанням/збереженням пам'яті:
[CODE BLOCK]
Крок 2: Адаптивна логіка тесту
Усередині тесту перевіряйте відомі невдачі та застосовуйте виправлення:
[CODE BLOCK]
Крок 3: Стратегії відновлення
Зберігайте стратегії відновлення як спогади:
[CODE BLOCK]
Крок 4: Інтеграція з CI
[CODE BLOCK]
Крок 5: Інформаційна панель аналізу невдач
[CODE BLOCK]
Найкращі практики
> [!TIP]
> - Зберігайте tracebacks — вони містять точний рядок, що дав збій
> - Тегуйте за назвою тесту — забезпечує швидку фільтрацію
> - Використовуйте категорію — відокремлює від звичайних спогадів
> - Встановлюйте пріоритет — невдачі не повинні забуватися
> - Періодичне очищення — видаляйте спогади для вирішених проблем
> - Не зберігайте чутливі дані — облікові дані, PII
Поширені шаблони невдач для збереження
| Тип невдачі | Що зберігати |
|--------------|---------------|
| Елемент не знайдено | Спробований селектор, стан сторінки, знімок екрана |
| Тайм-аут | Час очікування, чого чекали |
| Помилка твердження | Очікуване проти фактичного значення |
| Мережева помилка | URL, код статусу, тіло відповіді |
| Доступ заборонено | Потрібний дозвіл, поточна роль користувача |
Наступні кроки
- Автоматизоване тестування iOS
- Найкращі практики роботи з пам'яттю
- Куховарська книга відновлення помилок
────────────────────────────────────────────────────────────
# Автоматизація webhook-ів
SUMMARY: Запускайте зовнішні системи при зміні спогадів — синхронізація, сповіщення, автоматизація.
Автоматизація webhook-ів
Webhooks дозволяють запускати зовнішні системи, коли спрацьовують події Synapse.
Цей посібник охоплює поширені шаблони автоматизації.
Поширені шаблони
Шаблон 1: Сповіщення про критичний спогад
Надсилайте повідомлення в Slack, коли зберігається критичний спогад:
[CODE BLOCK]
Зареєструйте webhook:
[CODE BLOCK]
Шаблон 2: Синхронізація із зовнішньою системою
Синхронізуйте спогади з Notion, Obsidian або будь-якою зовнішньою KB:
[CODE BLOCK]
Шаблон 3: Запуск CI/CD
Запускайте розгортання, коли зберігається спогад «release»:
[CODE BLOCK]
Шаблон 4: Пробудження агента при повідомленні людини
Запускайте виконання LLM-агента, коли людина надсилає повідомлення чату:
[CODE BLOCK]
Шаблон 5: Агреговані метрики
Відстежуйте зростання пам'яті, активність чату, завершення завдань:
[CODE BLOCK]
Перевірка підпису
Завжди перевіряйте підписи webhook, щоб запобігти підробці:
[CODE BLOCK]
Логіка повторних спроб
Synapse повторює невдалі webhook-и з експоненційною затримкою. Ваш обробник має:
1. Повернути 200 швидко — не робіть важку роботу синхронно
2. Ставити роботу в чергу — використовуйте фонову систему завдань
3. Бути ідемпотентним — та сама подія може доставлятися двічі
[CODE BLOCK]
Налагодження webhook-ів
Перевірка історії доставок
Доставки webhook-ів логуються. Перевірте недавні доставки вашого webhook-а:
[CODE BLOCK]
Тест webhook вручну
[CODE BLOCK]
Поширені проблеми
| Проблема | Виправлення |
|-------|-----|
| 4xx відповіді | Перевірте, що обробник повертає 200 |
| 5xx відповіді | Помилка сервера — перевірте логи додатку |
| Тайм-аут | Повертайте 200 швидко, ставте роботу в чергу асинхронно |
| Дубльовані доставки | Зробіть обробник ідемпотентним |
| Невідповідність підпису | Перевірте, що секрет правильний |
Найкращі практики
> [!TIP]
> - Завжди перевіряйте підписи — ніколи не пропускайте це
> - Повертайте 200 швидко — не блокуйте Synapse
> - Будьте ідемпотентними — обробляйте дубльовані доставки
> - Використовуйте специфічні події — , а не
> - Моніторте збої доставки — налаштуйте сповіщення
Наступні кроки
- Webhooks API
- Cron та планувальник
- Постійний LLM-агент
## КАТЕГОРІЯ: КОНЦЕПЦІЇ
Архітектура та концепції Synapse.
────────────────────────────────────────────────────────────
# Архітектура Synapse
SUMMARY: Як побудовано Synapse — Fastify, PostgreSQL, FTS5, ембеддинги, MCP-сервер.
Архітектура Synapse
Synapse — це мультитенантний API пам'яті, побудований на Fastify, PostgreSQL із
FTS5 та опціональній службі ембеддингів для семантичного пошуку.
Архітектура високого рівня
[CODE BLOCK]
Основні компоненти
1. Synapse API (Fastify)
Головний HTTP-сервер. Обробляє:
- REST-кінцеві точки (, , тощо)
- Автентифікацію (Mind Key для агентів, JWT для людей)
- Обмеження частоти (лише для автентифікації )
- Віддачу статичних файлів (веб-інтерфейс на , тощо)
- Диспетчеризацію webhook-ів
Побудовано на Fastify 5 для високої продуктивності. У продакшені працює на
порту 12800.
2. PostgreSQL з FTS5
Основне сховище даних. Використовує PostgreSQL із розширенням FTS5 для
повнотекстового пошуку.
Основні таблиці:
| Таблиця | Призначення |
|-------|---------|
| | Облікові записи користувачів |
| | Області mind-ів (кожен має Mind Key) |
| | Записи спогадів із віртуальною таблицею FTS5 |
| | Керування завданнями |
| | Історія чату |
| | Постійні скрипти |
| | Реєстрації webhook-ів |
| | Заплановані завдання |
| | Сховище ключ-значення |
| | Журнал аудиту |
FTS5 забезпечує повнотекстовий пошук за всіма спогадами з затримкою менше
мілісекунди. Докладніше дивіться у пошуку FTS5.
3. Служба ембеддингів (опціональна)
Для семантичного пошуку Synapse генерує векторні ембеддинги вмісту спогадів.
Вони зберігаються разом зі спогадами та використовуються для пошуку за подібністю.
- Постачальник: настроюваний (OpenAI, локальна модель тощо)
- Зберігається у колонці у таблиці
- Використовується кінцевою точкою
- Дивіться Семантичний пошук
4. MCP-сервер (окрема служба)
MCP-сервер Synapse працює як окремий процес (порт 13100). Він:
- Надає 79 інструментів через Model Context Protocol
- Підтримує транспорти stdio, HTTP/SSE та WebSocket
- Перетворює виклики MCP-інструментів у виклики API Synapse
- Мультитенантний: один Mind Key на сесію
5. Браузерний проксі (окрема служба)
Для автоматизації браузера окрема служба на основі Playwright працює на порту
13000. MCP-сервер може викликати її для інструментів .
6. SSH-проксі (окрема служба)
Для віддалених команд через SSH окрема служба працює на порту 12900.
Модель мультитенантності
[CODE BLOCK]
Кожен mind повністю ізольований. Mind Keys надають доступ лише до одного mind-у.
JWT надають доступ до облікового запису користувача (для керування mind-ами).
Докладніше дивіться у Мультитенантності.
Потік запитів
Запит на збереження спогаду
[CODE BLOCK]
Запит на пошук спогадів
[CODE BLOCK]
Розгортання
Synapse розгортається як Docker-контейнер. Дивіться :
[CODE BLOCK]
Характеристики продуктивності
| Операція | Затримка | Пропускна здатність |
|-----------|---------|------------|
| Збереження спогаду | 5мс | 1000+ запитів/с |
| Відкликання спогадів | 20мс | 500 запитів/с |
| Пошук FTS5 | 10мс | 800 запитів/с |
| Семантичний пошук | 50мс | 200 запитів/с |
| Опитування чату | 5мс | 2000 запитів/с |
Наступні кроки
- Модель пам'яті
- Мультитенантність
- Пошук FTS5
────────────────────────────────────────────────────────────
# Повнотекстовий пошук FTS5
SUMMARY: Як Synapse використовує SQLite FTS5 для повнотекстового пошуку спогадів із затримкою менше мілісекунди.
Повнотекстовий пошук FTS5
Synapse використовує FTS5 (Full-Text Search 5) для швидкого та гнучкого пошуку
спогадів. Ця сторінка пояснює, як це працює та як ефективно ним користуватися.
Що таке FTS5?
FTS5 — це розширення SQLite (також доступне в PostgreSQL через розширення), що
забезпечує можливості повнотекстового пошуку. Воно:
- Індексує текстовий вміст для швидкого пошуку за ключовими словами
- Підтримує булеві оператори (AND, OR, NOT)
- Підтримує пошук фраз у лапках
- Підтримує пошук за префіксом з
- Ранжує результати за релевантністю
Synapse використовує FTS5 для індексування всього вмісту спогадів, забезпечуючи
пошук із затримкою менше мілісекунди серед тисяч спогадів.
Як Synapse використовує FTS5
Коли ви викликаєте :
1. Вміст спогаду зберігається в таблиці
2. Вміст також вставляється у віртуальну таблицю FTS5
3. FTS5 автоматично токенізує та індексує вміст
Коли ви викликаєте :
1. Synapse розбирає запит із використанням синтаксису FTS5
2. Виконує проти індексу FTS5
3. Фільтрує за (ізоляція тенантів)
4. Повертає ранжовані результати
Синтаксис запитів
Простий пошук за ключовим словом
[CODE BLOCK]
Повертає спогади, що містять «docker».
Кілька ключових слів (неявний AND)
[CODE BLOCK]
Повертає спогади, що містять ОБИДВА слова «docker» та «swarm».
Пошук фраз
[CODE BLOCK]
Повертає спогади, що містять точну фразу «docker swarm».
Пошук за префіксом
[CODE BLOCK]
Повертає спогади зі словами, що починаються на «docker» (напр. «dockers»,
«dockerfile», «dockerize»).
Булеве OR
[CODE BLOCK]
Повертає спогади, що містять «docker» АБО «kubernetes».
Булеве NOT
[CODE BLOCK]
Повертає спогади, що містять «docker», але НЕ «swarm».
Групування
[CODE BLOCK]
Повертає спогади, що містять «docker» або «kubernetes», але не «test».
Практичні приклади
Пошук спогадів про проєкт
[CODE BLOCK]
Пошук точної фрази
[CODE BLOCK]
Виключення тестових спогадів
[CODE BLOCK]
Пошук за технологією
[CODE BLOCK]
Ранжування
FTS5 ранжує результати за релевантністю за алгоритмом BM25. Фактори:
- Частота терміна (як часто термін зустрічається)
- Зворотна частота документа (рідкісні терміни ранжуються вище)
- Довжина документа (коротші документи з терміном ранжуються вище)
- Вага колонки (title > content)
Результати повертаються в порядку ранжування (найрелевантніші першими).
Продуктивність
| Операція | Затримка |
|-----------|---------|
| Пошук у 100 спогадах | < 5мс |
| Пошук у 1 000 спогадах | < 10мс |
| Пошук у 10 000 спогадах | < 25мс |
| Пошук у 100 000 спогадах | < 100мс |
FTS5 добре оптимізований для навантажень з переважанням читання.
Обмеження
Стемінг
FTS5 за замовчуванням не робить стемінг. «running» та «run» — різні терміни.
Обхідний шлях: Використовуйте пошук за префіксом:
Толерантність до опечаток
FTS5 не підтримує нечіткий пошук. Опечатка не поверне результатів.
Обхідний шлях: Використовуйте семантичний пошук
() для концептуального зіставлення.
Стоп-слова
Поширені слова (the, a, an, is) індексуються, але можуть бути не корисними для
пошуку. FTS5 обробляє це автоматично.
FTS5 проти семантичного пошуку
| Аспект | FTS5 | Семантичний пошук |
|--------|------|-----------------|
| Швидкість | Менше мілісекунди | 50-100мс |
| Зіставлення | Точні ключові слова | Концептуальне |
| Толерантність до опечаток | Немає | Деяка |
| Стемінг | Немає | Неявний |
| Потребує ембеддингів | Ні | Так |
| Найкраще для | Конкретних термінів | Концепцій |
Використовуйте FTS5, коли знаєте ключові слова. Використовуйте семантичний пошук,
коли потрібні «спогади про X», де X описано інакше.
Найкращі практики
> [!TIP]
> - Використовуйте конкретні терміни — «docker swarm» краще за «container orchestration»
> - Лапки для фраз — гарантує пошук фраз
> - Префікс для варіацій — ловить «deploy», «deployment», «deploying»
> - Виключайте шум — фільтрує тестові спогади
> - Комбінуйте з тегами — звужує результати
Наступні кроки
- Семантичний пошук
- Memory API
- Найкращі практики роботи з пам'яттю
────────────────────────────────────────────────────────────
# Модель пам'яті
SUMMARY: Як структуровані спогади — категорії, ключі, теги, пріоритети, джерела, верифікація.
Модель пам'яті
Модель пам'яті Synapse розроблена для LLM-агентів — достатньо структурована для
надійного відкликання, достатньо гнучка для будь-якої предметної області.
Анатомія спогаду
[CODE BLOCK]
Поля
| Поле | Тип | Обов'язкове | Опис |
|-------|------|----------|-------------|
| | string | авто | Унікальний ID (memxxx) |
| | enum | ✅ | Одна з 8 категорій |
| | string | ✅ | Стабільний ідентифікатор (для оновлень) |
| | string | ✅ | Вміст спогаду (будь-який текст) |
| | string[] | – | Для пошуку та фільтрації |
| | enum | – | low, normal, high, critical (за замовчуванням: normal) |
| | enum | авто | user, agent (хто зберіг) |
| | bool | авто | Чи верифікувала це людина? |
| | float | – | 0.0 до 1.0 (за замовчуванням: 1.0 для user, 0.7 для agent) |
| | timestamp | – | Коли забути цей спогад |
| | string | авто | Якому mind-у належить |
| | timestamp | авто | Перше збереження |
| | timestamp | авто | Остання зміна |
Категорії
Вісім категорій охоплюють типові варіанти використання LLM-агентів:
| Категорія | Призначення | Приклад вмісту |
|----------|---------|-----------------|
| | Ким є користувач | "User is Michael Schäfer, software engineer in Berlin" |
| | Уподобання користувача | "Prefers concise technical responses" |
| | Перевірювані факти | "Office is in Berlin, timezone Europe/Berlin" |
| | Статус проєкту | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| | Навички користувача | "Advanced Python, 10+ years" |
| | Минулі помилки | "Forgot to bump npm version — CI failed" |
| | Контекст сесії | "Currently reviewing PR #42" |
| | Різні нотатки | "Try Redis for caching next sprint" |
Ключі: стабільні ідентифікатори
Поле є критичним — воно дозволяє оновлювати спогади без створення
дублікатів.
[CODE BLOCK]
Правила ключів:
- Має бути унікальним у межах (category, mind)
- Використовуйте
- Префіксуйте категорією для ясності: ,
- Тримайте стабільними — не змінюйте ключі після створення
Теги: для пошуку
Теги забезпечують швидку фільтрацію та пошук:
[CODE BLOCK]
Найкращі практики тегів:
- 2-5 тегів на спогад (не перетегуйте)
- Нижній регістр для узгодженості
- Використовуйте назви проєктів, тем, технологій
- Теги нечутливі до регістру
Рівні пріоритету
| Пріоритет | Коли використовувати | Поведінка відкликання |
|----------|-------------|-----------------|
| | Ідентичність, юридична інформація, незворотне | Завжди на початку відкликання |
| | Активні проєкти, ключові уподобання | Помітне у відкликанні |
| | Більшість спогадів (за замовчуванням) | Стандартний порядок відкликання |
| | Ефемерне, корисно знати | Може бути сумаризовано |
сортує за пріоритетом (critical першими), потім за новизною.
Джерело: користувач проти агента
Спогади позначаються :
- — збережено людиною (через JWT або людський інтерфейс)
- — збережено LLM-агентом (через Mind Key)
Це впливає на:
- Верифікацію: спогади авто-верифікуються, — ні
- Впевненість: за замовчуванням 1.0, — 0.7
- Відкликання: позначає неперевірені спогади як «(unverified)»
> [!NOTE]
> Ставтеся до спогадів із джерелом зі здоровим скептицизмом. Вони можуть
> бути виведені або припущені, а не прямо заявлені користувачем.
Верифікація
Прапорець вказує, що людина підтвердила спогад:
- Спогади : авто-верифіковані ()
- Спогади : за замовчуванням неперевірені ()
Верифікуйте спогади через:
[CODE BLOCK]
> [!NOTE]
> Верифікація потребує JWT (автентифікація людини), а не Mind Key (автентифікація
> агента). Це гарантує, що лише люди можуть позначати спогади як перевірені.
Впевненість
Поле (0.0 до 1.0) вказує, наскільки надійним є спогад:
- 1.0 — прямо заявлено користувачем
- 0.7 — виведено агентом
- 0.5 — невпевнено, потребує верифікації
- 0.0 — прямо сумнівно
Встановлюйте впевненість при збереженні:
[CODE BLOCK]
Термін дії
Встановлюйте для спогадів, чутливих до часу:
[CODE BLOCK]
Спогади з минулим терміном не повертаються (але все ще
існують у БД). Використовуйте , щоб побачити
спогади, термін яких скоро закінчується.
Життєвий цикл спогаду
[CODE BLOCK]
Поведінка відкликання
повертає текстове резюме, оптимізоване для контексту LLM:
[CODE BLOCK]
- Сортовано за пріоритетом (critical → low), потім за новизною
- Неперевірені спогади позначено
- Теги включено для контексту
- Звичайний текст (не потрібен розбір JSON)
Наступні кроки
- Memory API
- Найкращі практики роботи з пам'яттю
- Пошук FTS5
────────────────────────────────────────────────────────────
# Мультитенантність та ізоляція
SUMMARY: Як Synapse ізолює дані між користувачами та mind-ами — пояснення меж безпеки.
Мультитенантність та ізоляція
Synapse є мультитенантним: кілька користувачів, кожен із кількома mind-ами, повністю
ізольованими один від одного. Ця сторінка пояснює модель ізоляції.
Ієрархія тенантів
[CODE BLOCK]
Рівні ізоляції
Рівень 1: Ізоляція користувачів
Кожен обліковий запис користувача ізольований. Аліса не може:
- Бачити mind-и Боба
- Доступатися до спогадів Боба (навіть зі своїм JWT)
- Переглядати інформацію про обліковий запис Боба
Забезпечено: колонка у всіх таблицях, JWT містить , усі
запити фільтруються за .
Рівень 2: Ізоляція mind-ів
У межах користувача кожен mind ізольований. Mind A не може:
- Бачити спогади Mind B
- Доступатися до завдань, чату, скриптів Mind B
Забезпечено: колонка у всіх таблицях даних, Mind Key містить ,
усі запити фільтруються за .
> [!CRITICAL]
> Ізоляція Mind Key — це основна межа безпеки. Виточений Mind Key надає повний
> доступ до даних цього mind-у — але ТІЛЬКИ цього mind-у.
Токени автентифікації
| Токен | Область | Що може доступати |
|-------|-------|-------------------|
| Mind Key | Один mind | Лише дані цього mind-у |
| JWT | Обліковий запис користувача | Керування обліковим записом (створення/список/видалення mind-ів) |
| Computer Token | Один комп'ютер | Команди цього комп'ютера |
Між-mind доступ
У межах одного користувача
Користувач може доступатися до всіх своїх mind-ів через JWT (напр.
виводить усі). Але для читання/запису даних пам'яті потрібен конкретний Mind Key.
Між користувачами
Користувачі не можуть доступатися до даних одне одного — ЯКЩО тільки явно не
поділяться mind-ом через Sharing API:
[CODE BLOCK]
Після цього Боб може доступатися до Mind A через свій JWT (лише читання, якщо
).
Межі безпеки
[CODE BLOCK]
Типові шаблони мультитенантності
Шаблон 1: Один користувач, один mind
Найпоширеніший для індивідуальних користувачів LLM-агентів.
- 1 обліковий запис користувача
- 1 mind
- 1 Mind Key
- Усі спогади в одній області
Шаблон 2: Один користувач, кілька mind-ів
Для користувачів із кількома контекстами (робота, особисте, проєкти).
- 1 обліковий запис користувача
- N mind-ів (напр. «work», «personal», «project-x»)
- N Mind Keys
- Кожна сесія LLM використовує один Mind Key
Шаблон 3: Командний спільний mind
Для команд, що співпрацюють над проєктом.
- 1 користувач створює mind (отримує Mind Key)
- Творець ділиться з членами команди через JWT
- Усі члени команди доступаються через JWT (або спільний Mind Key)
> [!WARNING]
> Поширення Mind Key дає повний доступ на читання/запис. Для командної
> співпраці віддавайте перевагу Sharing API (на основі JWT), а не прямому
> поширенню Mind Keys.
Шаблон 4: SaaS-провайдер
Для додатків, що вбудовують Synapse як шар пам'яті.
- Кожен клієнт = 1 обліковий запис користувача
- Кожен проєкт клієнта = 1 mind
- Додаток зберігає Mind Keys для кожного клієнта/проєкту
- Повна ізоляція між клієнтами
Перевірка ізоляції
Тест: Mind Key не може доступатися до інших mind-ів
[CODE BLOCK]
Тест: JWT не може читати дані пам'яті напряму
[CODE BLOCK]
Найкращі практики
> [!TIP]
> - Один mind на проєкт/контекст — ізоляція — ваш друг
> - Ніколи не поширюйте Mind Keys — використовуйте Sharing API
> - Ротуйте Mind Keys у разі компрометації (видаліть mind, створіть новий)
> - Аудитуйте спільні mind-и — періодично переглядайте
> - Використовуйте JWT для людського UI — ніколи не викривайте Mind Keys кінцевим користувачам
Наступні кроки
- Автентифікація
- Mind Key проти JWT
- Архітектура
────────────────────────────────────────────────────────────
# Семантичний пошук (ембеддинги)
SUMMARY: Концептуальний пошук спогадів із використанням векторних ембеддингів — пошук за змістом, а не лише за ключовими словами.
Семантичний пошук (ембеддинги)
Synapse підтримує семантичний пошук за допомогою векторних ембеддингів. На відміну
від FTS5 (зіставлення ключових слів), семантичний пошук знаходить спогади за
змістом — навіть якщо ключові слова не збігаються.
Як це працює
[CODE BLOCK]
Що таке ембеддинги?
Ембеддинги — це числові векторні представлення тексту. Текст зі схожим змістом
має схожі вектори. Synapse генерує вектор (напр. 1536 вимірів) для вмісту
кожного спогаду.
Косинусна подібність
Для пошуку семантично схожих спогадів Synapse обчислює косинусну подібність
між вектором запиту та вектором кожного спогаду. Більша подібність = більша
релевантність.
Коли використовувати семантичний пошук
Використовуйте семантичний пошук, коли:
- Потрібні «спогади про X», де X описано інакше, ніж збережено
- FTS5 не повертає результатів (немає збігу ключових слів)
- Потрібне концептуальне групування (напр. усі спогади про «deployment», навіть якщо деякі кажуть «release»)
- Запит є питанням: «як ми обробляємо автентифікацію?»
Використовуйте FTS5, коли:
- Знаєте точні ключові слова
- Потрібна булева логіка (AND, OR, NOT)
- Потрібна затримка менше мілісекунди
- Потрібен пошук фраз
Кінцева точка
GET /memory/semantic-search
[CODE BLOCK]
Відповідь:
[CODE BLOCK]
Приклади
Пошук спогадів про розгортання
[CODE BLOCK]
Повертає спогади про «deployment», «release», «publishing», «rolling out» тощо.
Пошук шаблонів автентифікації
[CODE BLOCK]
Повертає спогади про login, auth, JWT, session management, OAuth тощо.
Пошук подібних спогадів
[CODE BLOCK]
Використовує семантичну подібність (через спільні теги ТА вектори ембеддингів).
Генерування ембеддингів
Коли генеруються ембеддинги?
- При збереженні спогаду — якщо службу ембеддингів налаштовано, ембеддинг генерується синхронно
- Пакетна генерація — генерує ембеддинги для спогадів, що їх не мають
- Асинхронні оновлення — при оновленні вмісту ембеддинг регенерується
Постачальники ембеддингів
Synapse підтримує настроюваних постачальників ембеддингів:
- OpenAI (, )
- Локальні моделі (через Ollama або подібні)
- Користувацькі (реалізуйте інтерфейс ембеддингів)
Налаштування через змінні середовища:
[CODE BLOCK]
Пакетна генерація
Для mind-ів із багатьма спогадами без ембеддингів:
[CODE BLOCK]
Продуктивність
| Операція | Затримка |
|-----------|---------|
| Генерування ембеддингу (OpenAI) | 100-200мс |
| Семантичний пошук (1к спогадів) | 50-100мс |
| Семантичний пошук (10к спогадів) | 200-500мс |
| Пакетна генерація (100 спогадів) | 10-20с |
> [!NOTE]
> Семантичний пошук повільніший за FTS5 через обчислення векторів. Використовуйте
> FTS5 для відомих ключових слів, семантичний — для концептуальних запитів.
Обмеження
Вартість ембеддингів
Якщо використовуєте OpenAI, генерування ембеддингів коштує гроші ($0.02 за 1М
токенів для text-embedding-3-small). Для 10 000 спогадів у середньому по 100
токенів кожен — це $0.02, що несуттєво.
Холодний старт
Спогади, збережені до налаштування ембеддингів, не матимуть ембеддингів. Запустіть
для заповнення.
Залежність від постачальника
Якщо постачальник ембеддингів недоступний, семантичний пошук м'яко завершується
помилкою (повертає порожні результати або помилку). FTS5 продовжує працювати.
Коли ембеддинги недоступні
Якщо службу ембеддингів не налаштовано:
- повертає 503 Service Unavailable
- продовжує працювати (просто ембеддинг не генерується)
- Пошук FTS5 продовжує працювати
Найкращі практики
> [!TIP]
> - Семантичний для концептуальних запитів — «як ми обробляємо X?»
> - FTS5 для конкретних термінів — «docker swarm»
> - Регулярно заповнюйте ембеддинги —
> - Моніторте стан постачальника — від нього залежить семантичний пошук
> - Комбінуйте з тегами — семантичний + фільтр тегів звужує результати
Наступні кроки
- Пошук FTS5
- Memory API
- Архітектура
## КАТЕГОРІЯ: КНИГА РЕЦЕПТІВ LLM
Рецепти та шаблони для LLM-агентів.
────────────────────────────────────────────────────────────
# Шаблон опитування чату
SUMMARY: Як опитувати чат про повідомлення від людини між викликами інструментів без блокування робочого процесу.
Шаблон опитування чату
Система чату є асинхронною — люди можуть залишати повідомлення, поки ви працюєте.
Цей шаблон показує, як опитувати чат про повідомлення без блокування вашого робочого процесу.
Сам шаблон
[CODE BLOCK]
Опитуйте між викликами інструментів, а не у щільному циклі.
Чому опитувати між викликами інструментів?
- Не блокуйте — опитування у щільному циклі витрачає API-виклики
- Не пропускайте повідомлення — занадто рідкісне опитування означає повільні відповіді
- Золота середина — опитуйте кожні 30–60 секунд або після кожного виклику інструменту
Реалізація
Базове опитування
[CODE BLOCK]
Шаблон 1: опитування після кожного виклику інструменту
[CODE BLOCK]
Шаблон 2: опитування на основі часу
[CODE BLOCK]
Шаблон 3: подієва модель (з вебхуками)
Для сповіщень у реальному часі зареєструйте вебхук:
[CODE BLOCK]
Тоді ваш обробник вебхука може розбудити агента:
[CODE BLOCK]
Шаблони обробки повідомлень
Шаблон: підтвердити, потім обробити
[CODE BLOCK]
Шаблон: черга для пакетної обробки
[CODE BLOCK]
Шаблон: маршрутизація за пріоритетом
[CODE BLOCK]
Частота опитування
| Сценарій | Частота |
|----------|-----------|
| Інтерактивний агент (людина очікує) | Кожні 5–10 секунд |
| Фоновий агент | Кожні 30–60 секунд |
| Пакетна обробка | Кожні 5 хвилин |
| Подієва модель через вебхуки | Не опитуйте — використовуйте вебхуки |
> [!WARNING]
> Опитування частіше, ніж раз на 5 секунд, витрачає API-виклики. Ендпоінт
> повертає результат негайно, якщо є повідомлення в черзі, тому
> швидше опитування не дає жодної користі.
Чат між агентами
Для комунікації між агентами:
[CODE BLOCK]
Найкращі практики
> [!TIP]
> - Опитуйте між викликами інструментів — а не у щільному циклі
> - Підтвердьте негайно — людина знає, що ви отримали повідомлення
> - Обробляйте асинхронно — не блокуйте тривалу роботу
> - Використовуйте вебхуки для реального часу — опитування має затримку
> - Не опитуйте частіше, ніж раз на 5 секунд — це витрачає API-виклики
Типові проблеми
Повідомлення зникають
- автоматично позначає повідомлення як прочитані
- Якщо ви їх не обробите, вони зникнуть
- Вирішення: Завжди обробляйте повідомлення до повернення
Дубльовані відповіді
- Якщо ваш обробник аварійно завершується, ви можете відповісти двічі
- Вирішення: Зробіть обробник ідемпотентним (перевіряйте, чи вже відповідали)
Повільні відповіді
- Опитування кожні 60 секунд означає затримку до 60 секунд
- Вирішення: Опитуйте кожні 10–30 секунд або використовуйте вебхуки
Наступні кроки
- Chat API
- Шаблон початку сесії
- Відновлення після помилок
────────────────────────────────────────────────────────────
# Відновлення після помилок для агентів
SUMMARY: Як LLM-агентам слід обробляти та відновлюватися після помилок — повтор, збереження, навчання.
Відновлення після помилок для агентів
Помилки трапляються. Мережі дають збій, API повертають 500, Mind Keys завершуються. Цей посібник
показує, як LLM-агентам слід елегантно обробляти помилки та вчитися на них.
Принципи обробки помилок
1. Повтор із бекофом — тимчасові помилки часто вирішуються самі
2. Зберігайте помилку — навчайтеся на шаблонах
3. Деградуйте елегантно — не аварійно завершуйте всю сесію
4. Сповіщайте людину — про помилки, які ви не можете вирішити
Обробка HTTP-помилок
Повтор із експоненційним бекофом
[CODE BLOCK]
Обробка помилок автентифікації
[CODE BLOCK]
Збереження помилок як спогадів
Коли виникають помилки, зберігайте їх, щоб майбутні сесії могли вчитися:
[CODE BLOCK]
Типові сценарії помилок
Сценарій 1: Mind Key недійсний
[CODE BLOCK]
Сценарій 2: Мережева помилка
[CODE BLOCK]
Сценарій 3: Обмеження частоти запитів
[CODE BLOCK]
Сценарій 4: Помилка сервера (5xx)
[CODE BLOCK]
Сценарій 5: Збій виклику інструменту
[CODE BLOCK]
Шаблон: автоматичний вимикач
Для повторюваних збоїв тимчасово припиніть спроби:
[CODE BLOCK]
Найкращі практики
> [!TIP]
> - Завжди повторюйте тимчасові помилки — мережі дають збій, сервери «гикають»
> - Не повторюйте клієнтські помилки (4xx) — вони не виправляться самі
> - Зберігайте помилки як спогади — навчайтеся на шаблонах
> - Сповіщайте людей про критичні помилки — вони мають знати
> - Деградуйте елегантно — часткова робота краща за аварійне завершення
> - Використовуйте автоматичні вимикачі — не «дубі́те» сервіс, що дає збій
Наступні кроки
- Довідник API помилок
- Шаблон початку сесії
- Самовідновлювальні тести
────────────────────────────────────────────────────────────
# Стратегія тегування пам'яті
SUMMARY: Як тегувати спогади для ефективного пошуку та фільтрації — система тегування, що масштабується.
Стратегія тегування пам'яті
Теги — це секрет масштабованого отримання спогадів. Цей посібник показує, як
тегувати спогади, щоб потрібні поверталися у потрібний момент.
Чому теги важливі
Без тегів ви маєте плаский повнотекстовий пошук. Із тегами ви маєте структуровану
навігацію:
[CODE BLOCK]
Теги дають змогу:
- Швидко фільтрувати —
- Обмежувати пошук —
- Групувати — знайти всі спогади типу «mistake» для проєкту
- Перехресно посилатися — спогади зі спільними тегами пов'язані
Схема тегування
Теги проєктів
Використовуйте назви проєктів як теги:
[CODE BLOCK]
Теги технологій
Використовуйте назви технологій:
[CODE BLOCK]
Теги тем
Використовуйте тематичні категорії:
[CODE BLOCK]
Теги статусу
Використовуйте індикатори стану:
[CODE BLOCK]
Теги типу
Використовуйте індикатори типу:
[CODE BLOCK]
Правила тегування
Правило 1: 2–5 тегів на спогад
Замало тегів = слабка виявляємість. Забагато = шум.
[CODE BLOCK]
Правило 2: нижній регістр, через дефіс
[CODE BLOCK]
Правило 3: використовуйте послідовний словник
Установіть словник тегів і дотримуйтесь його:
[CODE BLOCK]
Правило 4: тегуйте з наміром пошуку
Запитайте себе: «Як я шукатиму цей спогад?»
[CODE BLOCK]
Шаблони
Шаблон 1: проєкт + тема
[CODE BLOCK]
Пошук: (усі спогади проєкту Synapse)
Пошук: (спогади про розгортання в Synapse)
Шаблон 2: тип + домен
[CODE BLOCK]
Пошук: (усі помилки)
Пошук: (помилки розгортання)
Шаблон 3: ієрархічний
Для підпроєктів у межах проєкту:
[CODE BLOCK]
Пошук: (увесь Synapse)
Пошук: (лише підпроєкт docs)
Шаблон 4: відстеження статусу
[CODE BLOCK]
Типові випадки використання
Знайти всі рішення щодо проєкту
[CODE BLOCK]
Знайти всі помилки в домені
[CODE BLOCK]
Знайти активну роботу
[CODE BLOCK]
Знайти спогади про технологію
[CODE BLOCK]
Супровід тегів
Періодичний перегляд
[CODE BLOCK]
Об'єднання тегів
Якщо у вас непослідовні теги ( і ), об'єднайте їх:
[CODE BLOCK]
Найкращі практики
> [!TIP]
> - Установіть словник якомога раніше — послідовні теги з першого дня
> - Тегуйте з наміром пошуку — як ви знайдете це пізніше?
> - 2–5 тегів — золота середина — замало чи забагато — погано
> - Нижній регістр + дефіси — , а не
> - Переглядайте періодично — об'єднуйте дублікати, видаляйте невикористані
Наступні кроки
- Найкращі практики для пам'яті
- Пошук FTS5
- Робочий процес на основі завдань
────────────────────────────────────────────────────────────
# Шаблон початку сесії
SUMMARY: Канонічна послідовність початку сесії, яку має дотримуватись кожен 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.
Шаблон початку сесії
Кожна сесія LLM-агента має дотримуватись цієї канонічної послідовності запуску.
Пропуск кроків призводить до втрати контексту, пропущених повідомлень та
забутих завдань.
Сам шаблон
[CODE BLOCK]
Реалізація
Крок 1: відкликати всі спогади
> [!CRITICAL]
> Це найважливіший виклик. Без нього ви не маєте пам'яті про минулі
> сесії.
[CODE BLOCK]
Повертає текстове резюме всіх спогадів, відсортованих за пріоритетом.
Крок 2: опитати чат про непрочитані повідомлення
[CODE BLOCK]
Повертає непрочитані повідомлення від людини. Автоматично позначає їх як прочитані.
Крок 3: перевірити завдання в процесі виконання
[CODE BLOCK]
Повертає завдання, над якими ви працювали в минулій сесії.
Крок 4: побудувати контекст
Об'єднайте три відповіді у ваш системний промпт:
[CODE BLOCK]
Крок 5: обробити невиконані елементи
[CODE BLOCK]
Повний приклад
[CODE BLOCK]
Типові помилки
> [!WARNING]
> - Пропуск recall — ви починаєте без контексту та повторюєте минулі помилки
> - Забуте опитування чату — повідомлення людини залишаються без відповіді
> - Ігнорування активних завдань — робота забувається на півдорозі
> - Нічого не зберігається — сесія не створює постійної цінності
Варіації
Мінімальний шаблон (LLM із малим контекстом)
Для LLM із невеликим контекстним вікном пропустіть повний recall:
[CODE BLOCK]
Потім шукайте конкретні теми за потребою:
[CODE BLOCK]
Агресивний шаблон (тривалі агенти)
Для агентів, що працюють годинами, додайте періодичний повтор recall:
[CODE BLOCK]
Наступні кроки
- Стратегія тегування пам'яті
- Робочий процес на основі завдань
- Шаблон опитування чату
────────────────────────────────────────────────────────────
# Робочий процес на основі завдань
SUMMARY: Використовуйте завдання Synapse для керування багатокроковими LLM-робочими процесами, що зберігаються між сесіями.
Робочий процес на основі завдань
Завдання — це не просто списки справ, це основа постійних LLM-робочих процесів.
Створюючи завдання для багатокрокової роботи, ви гарантуєте безперервність
між сесіями та забезпечуєте аудит-журнали виконаного.
Чому на основі завдань?
Без завдань:
- LLM починає кожну сесію невпевненим, що робити
- Багатокрокова робота забувається на півдорозі
- Немає запису про те, що було зроблено
Із завданнями:
- LLM негайно відновлює завдання в процесі виконання
- Багатокрокова робота зберігається між сесіями
- Вбудований аудит-журнал усієї роботи
Сам шаблон
[CODE BLOCK]
Реалізація
Крок 1: створити завдання для багатокрокової роботи
[CODE BLOCK]
Крок 2: відстежувати прогрес в описі завдання
[CODE BLOCK]
Крок 3: відновлення між сесіями
[CODE BLOCK]
Крок 4: завершити та заархівувати
[CODE BLOCK]
Повний приклад: робочий процес розгортання
[CODE BLOCK]
Ієрархія завдань
Для складної роботи використовуйте зв'язки «батько-нащадок»:
[CODE BLOCK]
Пошук підзавдань:
[CODE BLOCK]
Робочий процес статусів
[CODE BLOCK]
Pending (очікує)
Завдання створене, але не розпочате. Використовуйте для запланованої роботи.
In Progress (у процесі)
Виконується зараз. Оновлюйте опис із прогресом.
Done (завершене)
Успішно завершене. Опис має містити підсумок.
Cancelled (скасоване)
Покинуте. Опис має містити причину.
Найкращі практики
> [!TIP]
> - Створюйте завдання для багатокрокової роботи — однокрокова робота не потребує завдання
> - Оновлюйте опис із прогресом — це уможливлює відновлення
> - Використовуйте високий пріоритет для активної роботи — спливає в recall
> - Завершуйте завдання після виконання — не залишайте їх у стані inprogress
> - Зберігайте підсумки завершення як спогади — для довгострокового посилання
Типові шаблони
Шаблон: робочий процес виправлення помилки
[CODE BLOCK]
Шаблон: робочий процес дослідження
[CODE BLOCK]
Наступні кроки
- Шаблон початку сесії
- Шаблон опитування чату
- Відновлення після помилок
## КАТЕГОРІЯ: ЧАСТІ ЗАПИТАННЯ
Часті запитання та поширені проблеми.
────────────────────────────────────────────────────────────
# API FAQ
SUMMARY: Поширені питання про API — автентифікація, обмеження частоти, обробка помилок, виявлення кінцевих точок.
API FAQ
Поширені запитання щодо API Synapse.
Як автентифікуватися?
Два методи:
1. Mind Key (для кінцевих точок даних):
2. JWT (для кінцевих точок облікового запису):
Або через параметр запиту (ліміт 60 запитів/хв):
Дивіться Автентифікацію.
У чому різниця між Mind Key та JWT?
- Mind Key: прив'язаний до mind-у, ніколи не закінчується, для даних memory/chat/tasks
- JWT: прив'язаний до користувача, термін дії 7 днів, для керування обліковим записом/mind-ами
Дивіться Mind Key проти JWT.
Чому я отримую 401 Unauthorized?
Поширені причини:
1. Відсутній заголовок
2. Недійсний Mind Key (перевірте, що починається з )
3. Використання JWT там, де потрібен Mind Key (або навпаки)
4. Mind Key відкликано
Виправлення: Перевірте ваш токен. Дивіться Автентифікацію.
Чому я отримую 404 Not Found?
Ви використали неправильний шлях кінцевої точки. У Synapse є лише шляхи зі списку
.
Виправлення: Викличте , щоб побачити всі дійсні шляхи. Не вгадуйте.
Чому я отримую 429 Too Many Requests?
Ви використовуєте автентифікацію через параметр запиту , що обмежена до 60/хв.
Виправлення: Перейдіть на заголовок (без обмеження).
Дивіться Обмеження частоти.
Як вивести список усіх кінцевих точок?
[CODE BLOCK]
Як знайти потрібну кінцеву точку?
1. Перевірте для машиночитного списку
2. Перевірте для повної документації API
3. Перегляньте для системи документації
4. Використовуйте для специфікації OpenAPI 3.0
Чи можна використовувати GET замість POST?
Деякі POST-кінцеві точки мають GET-аналоги для URL-only інструментів:
- ↔
- ↔
- ↔
Перевірте для доступних GET-варіантів.
Як обробляти помилки?
Усі помилки повертають JSON:
[CODE BLOCK]
Дивіться Помилки та обробка помилок.
Який ліміт розміру тіла запиту?
10 МБ. Для більших корисних навантажень (напр. завантаження файлів) використовуйте
multipart-кінцеві точки.
Чи підтримує API CORS?
Так. Усі кінцеві точки повертають:
[CODE BLOCK]
Чи є SDK?
Так:
- Node.js:
- MCP:
Дивіться Огляд API для деталей.
Як робити пагінацію?
Використовуйте та :
[CODE BLOCK]
Ліміт за замовчуванням: 100. Макс: 500.
Чи можна фільтрувати спогади за категорією або тегом?
Так:
[CODE BLOCK]
Як шукати спогади?
Двома способами:
1. Пошук ключових слів FTS5:
2. Семантичний пошук:
Дивіться Пошук FTS5 та Семантичний пошук.
Як оновити спогад?
POST з тією ж + — наявний спогад оновлюється, а не
дублюється.
[CODE BLOCK]
Як видалити спогад?
[CODE BLOCK]
Чи можна масово видаляти?
Так:
[CODE BLOCK]
Наступні кроки
- Огляд API
- Помилки та обробка помилок
- Автентифікація
────────────────────────────────────────────────────────────
# Загальне FAQ
SUMMARY: Поширені запитання про Synapse — що це, як працює, для кого.
Загальне FAQ
Поширені запитання про Synapse.
Що таке Synapse?
Synapse — це API постійної пам'яті для LLM-агентів. Вона дає вашому AI-асистенту
постійний мозок, що запитується та виживає між сесіями. Замість того, щоб
забувати все при закритті чату, LLM зберігає та отримує спогади через простий
HTTP API.
Докладніше: Що таке Synapse?
Для кого Synapse?
- Розробники LLM-агентів, яким потрібен постійний стан
- Просунуті користувачі, що запускають локальні LLM зі власними агентами
- Команди, що створюють AI-асистентів зі спільною пам'яттю
- Інженери автоматизації, що об'єднують виклики LLM між сесіями
Synapse безкоштовна?
Synapse розміщено на та безкоштовна для особистого
використання. Для self-hosting дивіться репозиторій.
Чим Synapse відрізняється від ChatGPT Memory?
| Функція | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| Сховище | Сервери OpenAI | Ваш сервер |
| API-доступ | Ні | Так (REST + MCP) |
| Мультитенантність | Ні | Так (mind-и) |
| Власні категорії | Ні | Так (8 категорій) |
| Повнотекстовий пошук | Обмежено | FTS5 + семантичний |
| Self-hostable | Ні | Так |
Які LLM працюють із Synapse?
Будь-який LLM, що може робити HTTP-виклики або використовувати MCP:
- Claude (Anthropic) — через MCP або прямий API
- GPT-4 / GPT-3.5 (OpenAI) — через function calling + API
- Gemini (Google) — через function calling + API
- Llama / Mistral (локальні) — через власну інтеграцію
- Будь-який LLM через MCP-сервер Synapse
Чи потрібно розгортати Synapse самостійно?
Ні. Хостинг-версія на доступна для публічного
використання. Self-hosting є опціональним (для конфіденційності, кастомізації або
ізольованих середовищ).
Скільки даних можна зберігати?
На хостинг-версії немає жорстких лімітів. Типове використання:
- 100-1000 спогадів на mind
- 1-10 КБ на спогад (поле content)
- Загалом: 10 МБ на mind
Для більшого масштабу — self-hosting.
Чи мої дані конфіденційні?
Так. Кожен mind ізольований (дивіться Мультитенантність).
Інші користувачі не можуть бачити ваші дані. Постачальник хостингу (Schäfer Services)
має доступ, але не переглядає дані користувачів.
Для максимальної конфіденційності — self-hosting.
Чи можу я експортувати свої дані?
Так. Використовуйте для експорту всіх спогадів у JSON.
Дивіться Резервне копіювання та відновлення.
Що станеться, якщо я втрачу Mind Key?
Mind Keys показуються лише один раз при створенні. Якщо втрачено:
1. Увійдіть з email/password, щоб отримати JWT
2. Створіть новий mind через
3. Збережіть новий Mind Key
4. (Опціонально) Видаліть старий mind через
Відновити спогади з mind-у, чий ключ втрачено, неможливо.
Чи можуть кілька LLM-агентів ділитися mind-ом?
Так. Усі агенти, що використовують однаковий Mind Key, поділяють дані цього mind-у.
Для координованої багатоагентної роботи дивіться Координацію кількох агентів.
Чи працює Synapse офлайн?
Ні, Synapse потребує інтернет-з'єднання з сервером (хостованим або власним). Для
офлайн LLM запускайте Synapse локально.
Наскільки швидкий пошук спогадів?
- Пошук ключових слів FTS5: < 10мс для 1000 спогадів
- Семантичний пошук: 50-100мс для 1000 спогадів
- Повне відкликання: < 50мс для 1000 спогадів
Дивіться Пошук FTS5 для деталей.
Чи можна використовувати Synapse без LLM?
Так. Synapse — це універсальний API пам'яті. Можна використовувати з будь-яким
додатком, що виграє від постійного, придатного для пошуку сховища ключ-значення з
категоріями та тегами.
Наступні кроки
- Що таке Synapse?
- Швидкий старт
- API FAQ
────────────────────────────────────────────────────────────
# MCP FAQ
SUMMARY: Поширені запитання про інтеграцію MCP — інструменти, транспорти, усунення несправностей.
MCP FAQ
Поширені запитання щодо MCP-сервера Synapse.
Що таке MCP?
MCP (Model Context Protocol) — відкритий стандарт від Anthropic для інтеграції
LLM з інструментами. Замість вставки документації API в промпти, ви реєструєте
інструменти на MCP-сервері, і LLM викликає їх як нативні функції.
Дивіться Що таке MCP?.
Скільки інструментів надає Synapse MCP?
79 інструментів у 12 категоріях: memory, chat, scheduler, tasks, scripts,
computers, push, user, utility, visualization, sharing, webhooks, browser.
Дивіться повний список у Що таке MCP?.
Які MCP-клієнти підтримуються?
- Claude Desktop (macOS, Windows)
- Claude Code (термінал)
- Cursor (IDE)
- Continue.dev (VS Code, JetBrains)
- Cline (VS Code)
- Будь-який MCP-сумісний клієнт
Дивіться Налаштування Claude Desktop для прикладів конфігурації.
Які транспорти підтримуються?
1. stdio (локальний, рекомендовано для десктопа)
2. HTTP/SSE (віддалений, мультитенантний)
3. WebSocket (мобільний, високий обсяг)
Як налаштувати Claude Desktop?
Відредагуйте :
[CODE BLOCK]
Дивіться Налаштування Claude Desktop.
Чому інструменти не з'являються в Claude Desktop?
1. Повністю перезапустіть Claude Desktop (Cmd+Q на macOS)
2. Перевірте, що файл конфігурації є коректним JSON
3. Перевірте Node.js 18+ встановлено
4. Перевірте MCP-логи:
Дивіться Усунення несправностей MCP.
Як використовувати інший mind?
Змініть у вашій MCP-конфігурації та перезапустіть клієнт.
Для кількох mind-ів запустіть кілька екземплярів MCP-сервера з різними Mind Keys.
Чи можна обмежити, які інструменти викриваються?
Так, використовуйте Профілі інструментів:
- : 8 композитних інструментів (500 токенів)
- : 25 інструментів (2 500 токенів)
- : 119 інструментів (8 250 токенів, за замовчуванням)
Встановлюється через змінну середовища або заголовок .
Як налагодити проблеми MCP?
1. Запустіть MCP-сервер вручну:
2. Перевірте логи клієнта (залежить від клієнта)
3. Перевірте, що Mind Key працює:
4. Перевірте стан Synapse:
Дивіться Усунення несправностей MCP.
MCP-сервер безкоштовний?
Так. npm-пакет є open source. Хостований MCP-сервер на
безкоштовний для публічного використання.
Чи можу я самостійно розгорнути MCP-сервер?
Так:
[CODE BLOCK]
Чим MCP відрізняється від прямих API-викликів?
| Аспект | Прямий API | MCP |
|--------|-----------|-----|
| LLM повинен знати | URL, заголовки, auth | Лише назви інструментів |
| Обробка auth | Вручну | Автоматично (змінна середовища) |
| Виявлення інструментів | Читання /endpoints | Автоматично через MCP-протокол |
| Обробка помилок | Вручну | Стандартизовано |
| Найкраще для | Власних інтеграцій | LLM-агентів |
Чи можу я створити власний MCP-клієнт?
Так. Використовуйте офіційний MCP SDK:
- TypeScript:
- Python:
Дивіться Власний MCP-клієнт.
Як повідомити про баг MCP?
Відкрийте issue:
Включіть:
- Версію MCP-сервера
- Назву та версію клієнта
- Операційну систему
- Відповідні логи
- Кроки відтворення
Наступні кроки
- Що таке MCP?
- Налаштування Claude Desktop
- Усунення несправностей MCP
────────────────────────────────────────────────────────────
# FAQ з усунення несправностей
SUMMARY: Рішення поширених проблем Synapse — автентифікація, мережа, дані, розгортання.
FAQ з усунення несправностей
Рішення поширених проблем Synapse.
Не можу увійти
Симптоми
- повертає 401
- «Invalid email or password»
Рішення
1. Перевірте, що email правильний — чутливий до регістру
2. Перевірте пароль — мінімум 6 символів
3. Спочатку зареєструйтесь, якщо немає облікового запису:
4. Скиньте пароль (якщо налаштовано SMTP) через веб-інтерфейс
Я втратив Mind Key
Симптоми
- Не можу доступатися до спогадів
- Mind Key видалено/втрачено
Рішення
Mind Keys неможливо відновити. Вам потрібно:
1. Увійти, щоб отримати JWT:
2. Вивести список mind-ів: (з JWT)
3. Створити новий mind:
4. Зберегти новий Mind Key
5. (Опціонально) Видалити старий mind:
Дані у старому mind-і втрачено, якщо ви не зможете знайти Mind Key.
API-виклики повертають 401
Симптоми
- Усі API-виклики повертають 401 Unauthorized
- «Mind Key fehlt oder ungültig»
Рішення
1. Перевірте формат заголовка:
2. Перевірте, що Mind Key починається з (не , що є JWT)
3. Протестуйте напряму:
[CODE BLOCK]
4. Mind Key може бути відкликано — створіть новий mind
Дивіться Автентифікацію.
API-виклики повертають 404
Симптоми
- 404 Not Found
- «Route not found»
Рішення
> [!CRITICAL]
> Не вгадуйте шляхи кінцевих точок. Існують лише шляхи зі списку .
1. Перевірте дійсні кінцеві точки:
2. Порівняйте URL точно — чутливий до регістру, без кінцевих слешів
3. Перевірте HTTP-метод — та різні
API-виклики повертають 429
Симптоми
- 429 Too Many Requests
- «Rate limit exceeded»
Рішення
1. Перейдіть на автентифікацію через заголовок (без обмеження):
[CODE BLOCK]
2. Зачекайте секунд, якщо доводиться використовувати
Дивіться Обмеження частоти.
Пошук спогадів не повертає результатів
Симптоми
- повертає порожньо
- Знаєте, що спогади існують
Рішення
1. Перевірте, що спогади існують:
2. Перевірте синтаксис пошуку — у FTS5 специфічний синтаксис
3. Спробуйте простіший запит — замість
4. Використовуйте семантичний пошук для концептуальних запитів:
Дивіться Пошук FTS5.
Спогади не зберігаються
Симптоми
- POST /memory повертає успіх
- GET /memory/recall не показує їх
Рішення
1. Перевірте, що той самий Mind Key — різні ключі = різні mind-и
2. Перевірте відповідь — POST повертає
3. Спробуйте GET /memory (JSON-список) замість /memory/recall (текст)
4. Перевірте фільтр — або можуть ховати їх
Інструменти не з'являються в Claude Desktop
Симптоми
- Claude Desktop показує 0 інструментів
- Немає іконки 🔌
Рішення
1. Повністю перезапустіть Claude Desktop (Cmd+Q)
2. Перевірте, що файл конфігурації є коректним JSON
3. Перевірте Node.js 18+ встановлено
4. Запустіть MCP вручну:
5. Перевірте логи:
Дивіться Усунення несправностей MCP.
Synapse офлайн
Симптоми
- Не можна досягти synapse.schaefer.zone
- curl тайм-аутиться
Рішення
1. Перевірте інтернет — спробуйте інший сайт
2. Перевірте стан Synapse:
3. Зачекайте — можливо, тимчасовий збій або розгортання
4. Перевірте сторінку статусу (якщо є)
Для self-hosted: перевірте статус Docker-контейнера, підключення до БД.
Помилки бази даних
Симптоми
- 500 Internal Server Error
- «Database connection failed»
Рішення
Для self-hosted:
1. Перевірте, що PostgreSQL працює:
2. Перевірте DATABASEURL у середовищі
3. Перевірте міграції:
4. Перевірте місце на диску:
Для хостингу: зверніться до підтримки.
Webhook не спрацьовує
Симптоми
- Зареєстровано webhook, але не отримуєте зворотних викликів
- Немає POST на ваш URL
Рішення
1. Перевірте, що URL доступний:
2. Перевірте фільтр подій — ловить усі події пам'яті
3. Протестуйте webhook:
4. Перевірте, що webhook увімкнено:
5. Перевірте SSL — Synapse потребує дійсний HTTPS для URL webhook-ів
Дивіться Webhooks API.
Cron-завдання не запускається
Симптоми
- Створено cron-завдання, але воно не спрацьовує
- не оновлюється
Рішення
1. Перевірте синтаксис розкладу — має бути коректний 5-польовий cron АБО ціле число секунд
2. Перевірте, що кінцева точка дозволена — має бути http(s), без приватних IP
3. Перевірте, що завдання увімкнено:
4. Зачекайте на наступний запланований час — cron не миттєвий
Дивіться Cron та планувальник.
Потрібна додаткова допомога?
1. Перевірте наявну документацію:
2. Шукайте в документах:
3. Відкрийте issue:
4. Контакт: дивіться сторінку
Наступні кроки
- Помилки та обробка помилок
- API FAQ
- Усунення несправностей MCP