# ДОКУМЕНТАЦИЯ SYNAPSE — Полный справочник
# Сгенерировано: 2026-07-18T06:15:34.182Z
# Всего статей: 47
Этот документ содержит полную документацию к API Synapse.
Base URL: https://synapse.schaefer.zone
Language: ru
========================================================================
## КАТЕГОРИЯ: НАЧАЛО РАБОТЫ
Всё, что нужно для начала работы с Synapse.
────────────────────────────────────────────────────────────
# Аутентификация и Mind Key
SUMMARY: Как работает аутентификация в Synapse: Mind Key для агентов, JWT для людей, ?key= для инструментов, работающих только с URL.
KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.
Аутентификация и Mind Key
Synapse использует два способа аутентификации, каждый оптимизирован под свой
сценарий. Понимание различий необходимо для создания надёжных интеграций.
Два способа аутентификации
| Способ | Сценарий | Лимит запросов | Срок действия |
|--------|----------|------------|--------|
| Mind Key | LLM-агенты, автоматизированные инструменты | Нет (заголовок) / 60/мин (query) | Бессрочно |
| JWT | Человеко-ориентированный UI, операции с аккаунтом | Нет | 7 дней |
Mind Key (для агентов)
Mind Key — это токен API с областью действия на арендатора. Он аутентифицирует
данные одного mind (воспоминания, задачи, чат, скрипты и т. д.). Используйте его для:
- LLM-агентов, вызывающих API
- Фоновых скриптов автоматизации
- Конфигурации MCP-сервера
- Любой долгоживущей интеграции
Аутентификация через заголовок (рекомендуется)
[CODE BLOCK]
Через query-параметр (для инструментов, работающих только с URL)
[CODE BLOCK]
> [!WARNING]
> Query-параметр ограничен 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 дней. После истечения просто вызовите снова,
чтобы получить новый. Mind Key не истекает, поэтому существующие интеграции
агентов продолжают работать.
Лучшие практики безопасности
> [!CRITICAL]
> - Никогда не коммитьте Mind Key в git. Используйте переменные окружения.
> - Никогда не логируйте Mind Key. Маскируйте их в логах ().
> - Ротируйте ключи при подозрении на утечку (удалите mind, создайте новый).
> - Используйте один mind на проект, чтобы ограничить масштаб ущерба при утечке ключа.
Паттерн переменных окружения
[CODE BLOCK]
[CODE BLOCK]
Конфигурация MCP-сервера
[CODE BLOCK]
Паттерн нескольких mind
У каждого пользователя может быть несколько mind. Типовые паттерны:
| Имя mind | Назначение |
|-----------|---------|
| | Рабочие воспоминания |
| | Личные предпочтения, семья |
| | Контекст конкретного проекта |
| | Прогресс обучения |
| | Универсальный fallback |
Используйте разные Mind Key в разных LLM-сессиях, чтобы контексты были изолированы.
Лимиты запросов
| Способ аутентификации | Лимит | Область |
|-------------|-------|-------|
| Mind Key (заголовок) | Нет | На mind |
| Mind Key (?key=) | 60/мин | На IP |
| JWT (заголовок) | Нет | На пользователя |
| Публичные эндпоинты | Нет | Глобально |
Заголовки лимитов (, , )
включаются в ответы при применимости.
Следующие шаги
- Mind Key против JWT — когда что использовать
- Memory API — что можно делать с Mind Key
- User 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 |
| Регистрировать вебхуки | 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-сервера
- Интеграций через вебхуки
- Мобильных приложений, читающих память
Что может Mind Key
- — читать все воспоминания этого mind
- — сохранять/обновлять воспоминания
- — читать сообщения чата
- — отправлять сообщения чата
- — получать список задач
- — создавать задачи
- — хранить скрипты
- — регистрировать вебхуки
- — ставить команды в очередь
Что 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)
- Регистрировать вебхуки (нужен Mind Key)
Особый случай: Computer Token
Эндпоинты (для агентов, screen-remote-agent) используют
третий тип токена: Computer Token. Он возвращается
при активации установочного кода и привязан к конкретному зарегистрированному
компьютеру.
| Эндпоинт | Аутентификация |
|----------|------|
| | 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 Key
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 символов | |
Следующие шаги
- Аутентификация — полное руководство по аутентификации
- User & Minds API — эндпоинты под защитой 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-поиск. Фразы в кавычках: .
> Поиск по префиксу: . Булево: .
Открытые инструменты (без заголовков аутентификации)
Если ваш инструмент может только открывать 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 Cookbook — практические паттерны
────────────────────────────────────────────────────────────
# Быстрый старт (человек)
SUMMARY: Зарегистрируйте аккаунт, создайте первый mind, сохраните воспоминание — всего за 5 минут.
Быстрый старт (человек)
Это руководство проведёт вас через получение аккаунта Synapse, вашего первого
Mind Key и сохранение первого воспоминания. Общее время: 5 минут.
Шаг 1: зарегистрируйте аккаунт
Откройте Synapse API и создайте аккаунт:
[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) — найти любое воспоминание по ключевому слову за миллисекунды
- Семантический поиск — поиск по сходству на эмбеддингах для концептуальных запросов
- Multi-tenant — у каждого пользователя изолированные «mind» (один пользователь, много проектов)
- Асинхронный чат — люди могут оставлять сообщения для агента, пока он работает
- Задачи и планирование — встроенный менеджер задач и cron-планировщик
- Интеграция с MCP — 79 инструментов, предоставляемых как Model Context Protocol для Claude, Cursor, Continue
- Управление браузером и компьютером — инструменты удалённой автоматизации
- Вебхуки — HTTP-колбэки при изменении памяти/чата/задач
Как это работает
[CODE BLOCK]
1. LLM вызывает в начале сессии
2. Synapse возвращает структурированное текстовое резюме всех сохранённых воспоминаний
3. LLM работает, периодически вызывая для сохранения новых фактов
4. Когда пользователь задаёт вопрос, LLM может вызвать
5. В конце сессии важный новый контекст сохраняется для следующей сессии
Для кого это?
- Разработчики LLM-агентов, которым нужно постоянное состояние
- Продвинутые пользователи, запускающие локальные LLM (Ollama, LM Studio) с кастомными агентами
- Команды, создающие AI-ассистентов с общей памятью
- Инженеры автоматизации, связывающие LLM-вызовы между сессиями
Краткое сравнение
| Возможность | Память ChatGPT | Synapse |
|---------|---------------|---------|
| Расположение хранилища | Серверы OpenAI | Ваш сервер |
| Доступ через API | Нет (закрытый) | Да (REST + MCP) |
| Multi-tenant | Нет | Да (mind) |
| Кастомные категории | Нет | Да (8 категорий) |
| Поиск | Ограниченный | FTS5 + семантический |
| Self-hostable | Нет | Да (Docker) |
Следующие шаги
- Быстрый старт для людей — получите Mind Key за 5 минут
- Быстрый старт для LLM — первые вызовы API
- Аутентификация — Mind Key против JWT
- Обзор архитектуры — как устроен Synapse
## КАТЕГОРИЯ: СПРАВОЧНИК ПО API
Полный справочник по всем конечным точкам API.
────────────────────────────────────────────────────────────
# Браузерный прокси
SUMMARY: Сервис автоматизации браузера — отдельный Docker-контейнер на порту 13000 для управления headless-браузером.
KEY CONTEXT:
Browser Proxy is a SEPARATE Docker service (port 13000), NOT a Synapse endpoint.
Synapse endpoints do NOT include /browser/* paths.
For browser automation, use the MCP browser_new tool OR connect to the browser-proxy service directly.
Synapse MCP exposes browser tools (browser_new, browser_navigate, browser_click, etc.)
Браузерный прокси
Браузерный прокси — это отдельный Docker-сервис, обеспечивающий автоматизацию
headless-браузера через Playwright. Он не является частью Synapse API напрямую —
эндпоинты Synapse не включают пути .
Архитектура
[CODE BLOCK]
Способы доступа
Способ 1: через MCP-сервер Synapse (рекомендуется)
MCP-сервер Synapse предоставляет браузерные инструменты как MCP-инструменты.
Используйте этот способ для LLM-управляемой автоматизации браузера:
[CODE BLOCK]
Доступные MCP-инструменты для браузера:
- — открыть новую вкладку браузера
- — перейти по URL
- — кликнуть по элементу
- — ввести текст в поле
- — сделать снимок экрана
- — закрыть вкладку
- (и другие — см. интеграция с MCP)
Способ 2: прямой доступ к Browser Proxy
Для интеграций без MCP подключайтесь напрямую к сервису browser-proxy:
[CODE BLOCK]
Типовые сценарии использования
Веб-скрапинг
[CODE BLOCK]
Автоматизация форм
[CODE BLOCK]
Захват снимков экрана
[CODE BLOCK]
Связанные сервисы
| Сервис | Порт | Назначение |
|---------|------|---------|
| Synapse API | 12800 | Память, чат, задачи |
| Synapse MCP | 13100 | MCP-сервер (79 инструментов) |
| Browser Proxy | 13000 | Автоматизация headless-браузера |
| SSH Proxy | 12900 | SSH-доступ к удалённым машинам |
Следующие шаги
- Интеграция с MCP — как использовать браузерные инструменты через MCP
- Computer Control 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
- Паттерн опроса чата
────────────────────────────────────────────────────────────
# Computer Control 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
Computer Control API
Computer Control API позволяет удалённо управлять зарегистрированными компьютерами.
Небольшой агент () работает на целевой машине, опрашивает сервер,
выполняет команды и отправляет результаты обратно. Это обеспечивает LLM-управляемую
GUI-автоматизацию.
Архитектура
[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 (через query)
Поставить команду в очередь через 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
Long-poll для новых команд. Агент вызывает этот метод в цикле.
[CODE BLOCK]
Возвращает сразу, если есть ожидающие команды, или через секунд, если их нет.
POST /computers/me/commands/:cid/result
Отправить результат выполнения команды.
[CODE BLOCK]
Типы команд
| Тип | Payload | Описание |
|------|---------|-------------|
| | | Захват экрана в формате PNG (base64) |
| | | Клик по координатам |
| | | Перемещение мыши на координаты |
| | | Ввод текста в позиции курсора |
| | | Нажатие комбинации клавиш |
| | | Прокрутка колеса мыши |
| | | Перетаскивание |
Типовой паттерн: LLM-управляемая GUI-автоматизация
[CODE BLOCK]
Следующие шаги
- Browser Proxy — отдельный сервис для автоматизации браузера
- Руководство по Self-Hosted Agents
────────────────────────────────────────────────────────────
# 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, без metadata-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
Запрос сформирован некорректно. Типичные причины:
- Отсутствуют обязательные поля JSON
- Некорректный синтаксис JSON
- Недопустимое значение перечисления (например, неверная категория)
[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 вебхука
Исправление: Используйте другое значение или примените для обновления
существующего ресурса.
429 Too Many Requests
Вы превысили лимит запросов. Применяется только к аутентификации через query-параметр
(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"
- Вы угадали несуществующий путь
- Вы неправильно использовали HTTP-метод (например, вместо )
- Проверьте для списка допустимых путей
"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
Сохранить новое воспоминание или обновить существующее (та же категория + key = обновление).
[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: Все эндпоинты Synapse API, базовый 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
Synapse API — это RESTful HTTP API. Все эндпоинты возвращают JSON (кроме
отмеченных случаев). На этой странице описано всё необходимое перед переходом
к конкретным эндпоинтам.
Базовый URL
[CODE BLOCK]
Все пути в этой документации указаны относительно этого базового URL. Для
self-hosted экземпляров замените на ваш собственный URL.
Аутентификация
Два способа, оба передаются через заголовок :
[CODE BLOCK]
Или через query-параметр (с лимитом 60 запросов в минуту):
[CODE BLOCK]
Подробнее см. Аутентификация.
Группы эндпоинтов
| Группа | Аутентификация | Описание |
|-------|------|-------------|
| Public | Нет | Главная страница, health, 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) |
| | Вся документация одним текстовым блоком |
| | Интерактивная песочница API |
Лимиты запросов
| Способ аутентификации | Лимит |
|-------------|-------|
| Mind Key (заголовок) | Нет |
| Mind Key (?key=) | 60/мин на IP |
| JWT (заголовок) | Нет |
| Публичные эндпоинты | Нет |
Ответы с лимитом включают:
[CODE BLOCK]
Пагинация
Списочные эндпоинты поддерживают и :
[CODE BLOCK]
Лимит по умолчанию: 100. Максимальный лимит: 500.
CORS
Все эндпоинты поддерживают CORS для браузерных клиентов:
[CODE BLOCK]
SDK и клиенты
- Node.js SDK: (репозиторий)
- MCP-сервер: (репозиторий)
- HTTP-клиент: любая HTTP-библиотека (curl, fetch, axios и т. д.)
Следующие шаги
- Memory API — самые важные эндпоинты
- Chat API — асинхронное общение человека и агента
- Ошибки и обработка ошибок
────────────────────────────────────────────────────────────
# Лимиты запросов и квоты
SUMMARY: Политика лимитов запросов для Synapse API — заголовок 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. Или подождите секунд и повторите запрос.
Почему для существует лимит
Query-параметр удобен для инструментов, работающих только с URL (браузеры,
команда ), но имеет последствия для безопасности и производительности:
- Безопасность: Query-параметры попадают в журналы доступа сервера, историю
браузера и заголовки Referer. Ограничение использования снижает риски.
- Производительность: Аутентификация через query-параметр требует лимитера
по IP (Redis-запрос на каждый запрос), что добавляет задержку. Header-auth
обходит это.
- Предотвращение злоупотреблений: Утёкший URL с могут расшарить и
закидать запросами. Лимит по IP ограничивает масштаб ущерба.
Рекомендуемые паттерны
LLM-агенты
[CODE BLOCK]
Браузерные инструменты
Если ваш инструмент может только открывать URL:
[CODE BLOCK]
MCP-сервер
MCP-серверы всегда используют header-auth через переменную окружения
— лимит не применяется.
Массовый импорт
Для массовых операций (например, импорт 1000 воспоминаний) всегда используйте
header-auth. Массовый импорт через упрётся в лимит менее чем за минуту.
Квоты (на уровне mind)
В настоящее время квоты на размер хранилища или количество воспоминаний на mind
отсутствуют. Все лимиты применяются на уровне аутентификации/IP, а не данных.
Это может измениться в будущем для обеспечения справедливости в multi-tenant-среде.
Мониторинг использования
[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 (query-параметры)
Создать задачу через GET (для инструментов, работающих только с URL).
[CODE BLOCK]
PUT /mind/task/:id
Обновить существующую задачу.
[CODE BLOCK]
GET /mind/task/:id/complete
Пометить задачу как выполненную.
[CODE BLOCK]
GET /mind/task/:id/delete
Удалить задачу навсегда.
[CODE BLOCK]
Приоритеты
- — несрочно
- — по умолчанию
- — важно
- — сделать немедленно
Статусы
- — создано, не начато
- — в работе
- — завершено
- — отменено
Паттерн: задача-ориентированный рабочий процесс
[CODE BLOCK]
Следующие шаги
- Task-Driven Workflow
- 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 — все группы эндпоинтов
- Ошибки и обработка ошибок
────────────────────────────────────────────────────────────
# User & Minds API
SUMMARY: Управление аккаунтом — регистрация, вход, создание minds, получение списка, удаление minds. Защищено JWT.
KEY CONTEXT:
Auth: JWT (from /register or /login)
Register: POST /register { email, password, display_name? } → returns JWT
Login: POST /login { email, password } → returns JWT
Create mind: POST /minds { name, description? } → returns mind_key (shown once!)
List minds: GET /minds
Delete mind: DELETE /minds/:id (irreversible — deletes all memories!)
JWT expires after 7 days. Mind Key never expires.
Mind Key is shown only once at creation — save it permanently.
User & Minds API
User & Minds API управляет аккаунтами. Эти эндпоинты используют JWT-аутентификацию
(а не Mind Key), так как работают на уровне аккаунта, а не на уровне mind.
Эндпоинты аутентификации
POST /register
Создать новый аккаунт пользователя.
[CODE BLOCK]
Ответ:
[CODE BLOCK]
POST /login
Войти в существующий аккаунт.
[CODE BLOCK]
Ответ: такой же, как у .
Эндпоинты Minds
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 Key в разных LLM-сессиях, чтобы контексты были изолированы.
Безопасность аккаунта
Требования к паролю
- Минимум 6 символов
- Без максимума (используйте менеджер паролей)
- Хранится как bcrypt-хэш (никогда в открытом виде)
Срок действия JWT
JWT истекает через 7 дней. После истечения просто вызовите снова.
Безопасность Mind Key
Mind Key не имеет срока действия. Если Mind Key скомпрометирован:
1. Создайте новый mind через
2. Обновите конфигурацию LLM новым Mind Key
3. Удалите скомпрометированный mind через
Следующие шаги
- Аутентификация — полное руководство по аутентификации
- Mind Key против JWT — руководство по выбору
- Sharing API — обмен minds между пользователями
────────────────────────────────────────────────────────────
# Variables API
SUMMARY: Быстрое key-value хранилище для состояния 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 — это быстрое key-value хранилище для эфемерного состояния. В отличие
от воспоминаний (которые индексируются, доступны для поиска и структурированы),
переменные оптимизированы для быстрого чтения/записи — идеально для счётчиков,
флагов и состояния сессии.
Эндпоинты
POST /var
Установить или обновить переменную.
[CODE BLOCK]
GET /var/:key
Получить одну переменную.
[CODE BLOCK]
Ответ:
[CODE BLOCK]
GET /var
Получить список всех переменных.
[CODE BLOCK]
DELETE /var/:key
Удалить переменную.
[CODE BLOCK]
Когда использовать переменные, а когда — память
| Сценарий | Использовать |
|----------|-----|
| Имя пользователя, предпочтения | Память (поиск, структура) |
| Временная метка последней сессии | Переменная (эфемерное состояние) |
| Счётчик (например, отправлено сообщений) | Переменная (частые обновления) |
| Состояние рабочего процесса («выполнен шаг 3 из 5») | Переменная (переходящее) |
| Длинные заметки по проекту | Память (полнотекстовая индексация) |
| Повторно используемые скрипты | Хранилище скриптов (именованные, версии) |
Типовые паттерны
Отслеживание последней сессии
[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
Вебхуки позволяют получать HTTP-колбэки при наступлении событий в Synapse. Идеально
подходит для запуска внешней автоматизации, отправки уведомлений или синхронизации
с другими системами.
Эндпоинты
POST /webhooks
Зарегистрировать новый вебхук.
[CODE BLOCK]
Ответ:
[CODE BLOCK]
GET /webhooks
Получить список всех вебхуков текущего mind.
[CODE BLOCK]
GET /webhooks/:id
Получить один вебхук.
[CODE BLOCK]
PUT /webhooks/:id
Обновить вебхук (URL, события, секрет или флаг включения).
[CODE BLOCK]
DELETE /webhooks/:id
Удалить вебхук.
[CODE BLOCK]
Типы событий
| Шаблон | Срабатывает, когда |
|---------|------------|
| | Любое событие памяти |
| | Сохранено новое воспоминание |
| | Воспоминание обновлено |
| | Воспоминание удалено |
| | Любое событие чата |
| | Новое сообщение от человека |
| | Любое событие задачи |
| | Создана новая задача |
| | Задача помечена выполненной |
| | Все события |
Payload вебхука
При наступлении события Synapse выполняет POST на ваш URL:
[CODE BLOCK]
Проверка подписи
Если вы установили , Synapse подписывает каждый payload с помощью HMAC-SHA256:
[CODE BLOCK]
Проверка в обработчике:
[CODE BLOCK]
Паттерн: синхронизация в реальном времени
[CODE BLOCK]
Следующие шаги
- Cron и планировщик
- Руководство по автоматизации через вебхуки
## КАТЕГОРИЯ: ИНТЕГРАЦИЯ 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 вызывает , и задача сохраняется между сессиями.
Tool Profiles
Для сессий кодинга, где не нужны все 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 (без trailing-запятых)
3. Полностью перезапустите Claude Desktop (Cmd+Q, а не просто закрытие)
4. Проверьте логи Claude Desktop: (macOS)
Ошибка «Mind Key invalid»
- Проверьте, что начинается с
- Получите новый ключ через (требуется JWT из )
- Без кавычек вокруг ключа в JSON
npx не найден
- Установите Node.js 18+:
- Перезапустите терминал после установки
- На macOS через Homebrew:
Инструменты видны, но вызовы падают
- Проверьте доступность :
- Убедитесь, что ваш Mind Key работает:
- См. Устранение проблем MCP
Tool Profiles (экономия токенов)
Если вы используете меньший LLM или хотите сэкономить контекстные токены,
установите tool profile:
[CODE BLOCK]
Профили: (8 инструментов), (25), (119, по умолчанию).
Следующие шаги
- Настройка Claude Code
- Настройка Cursor
- Устранение проблем MCP
────────────────────────────────────────────────────────────
# MCP в Continue.dev
SUMMARY: Подключите Synapse к Continue.dev — open-source AI-кодинг-ассистенту для VS Code и JetBrains.
MCP в Continue.dev
Continue.dev — open-source AI-кодинг-ассистент для VS Code и JetBrains IDE.
С Synapse MCP Continue получает постоянную память между сессиями.
Предварительные требования
- VS Code или JetBrains IDE
- Установленное расширение 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 к Cursor IDE для постоянной памяти проекта между сессиями кодинга.
MCP в Cursor
Cursor — AI-ориентированная IDE на базе VS Code. С Synapse MCP Cursor получает
постоянную память между сессиями — он запоминает решения по проекту, паттерны
кодовой базы и прошлые сессии отладки.
Предварительные требования
- Установленная IDE Cursor ()
- Node.js 18+
- Ваш Synapse Mind Key
Настройка
Шаг 1: откройте настройки Cursor
В Cursor:
1. Откройте Settings (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]
Tool Profiles
При подключении можно запросить конкретный профиль инструментов через заголовок
(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? (без trailing-запятых, без комментариев)
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. Проверьте корпоративный firewall — может блокировать исходящий HTTPS
3. Попробуйте альтернативный URL:
- Продакшен:
- MCP-сервер:
4. Для self-hosted: убедитесь, что ваш экземпляр Synapse запущен и доступен
Проблема: MCP-сервер падает
Симптомы
- MCP-сервер завершается сразу после запуска
- Логи клиента показывают «MCP server disconnected»
Решения
1. Запустите вручную, чтобы увидеть ошибку:
[CODE BLOCK]
2. Проверьте конфликты портов — MCP-сервер использует порт 13100 по умолчанию
3. Очистите кэш npx:
[CODE BLOCK]
4. Обновите до последней версии:
[CODE BLOCK]
Проблема: вызовы инструментов возвращают 429
Симптомы
- Ошибка: «Rate limit exceeded»
Решения
С MCP этого не должно происходить (используется header-auth, без лимита). Если происходит:
1. Проверьте, не используете ли вы где-то — перейдите на header-auth
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 (локально, рекомендуется для desktop)
[CODE BLOCK]
HTTP/SSE (удалённо, multi-tenant)
Подключите ваш MCP-клиент к:
[CODE BLOCK]
WebSocket (мобильные, высокий объём)
[CODE BLOCK]
Tool Profiles (v1.4.0)
Для снижения нагрузки на токены для меньших LLM MCP-сервер поддерживает три
профиля инструментов:
| Профиль | Инструменты | Токены | Лучше всего для |
|---------|-------|--------|----------|
| | 8 (составная диспетчеризация) | 500 | Self-hosted 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 — AI-ориентированная IDE
- Continue.dev — open-source 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 для создания
LLM-управляемых тестов iOS-приложений. LLM запоминает тестовые сценарии,
учится на прошлых сбоях и адаптируется к изменениям UI.
Архитектура
[CODE BLOCK]
Предварительные требования
- Аккаунт Synapse + Mind Key
- MCP-сервер Synapse настроен в Claude Desktop
- iOS Simulator с установленным
- Компьютер зарегистрирован в Synapse (см. Computer Control API)
Шаг 1: регистрация компьютера-симулятора
На 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 может переучиваться
> - Используйте accessibility-метки — стабильнее координат
> - Храните тестовые данные отдельно — используйте переменные для имён пользователей, паролей
> - Запускайте тесты в чистом состоянии — сбрасывайте 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]
Резервное копирование других данных
Не забудьте создать резервные копии:
| Тип данных | Эндпоинт |
|-----------|----------|
| Воспоминания | |
| Задачи | |
| Скрипты | |
| Вебхуки | |
| Cron-задачи | |
| Переменные | |
| История чата | |
Проверка
После восстановления проверьте:
[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 Cookbook
- Автоматизация через вебхуки
────────────────────────────────────────────────────────────
# Создание постоянного 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 Cookbook — практические паттерны
- Лучшие практики работы с памятью
- Координация нескольких агентов
────────────────────────────────────────────────────────────
# Самовосстанавливающиеся тестовые пайплайны
SUMMARY: Создавайте тестовые пайплайны, которые учатся на сбоях и адаптируются автоматически, используя память Synapse.
Самовосстанавливающиеся тестовые пайплайны
Традиционные наборы тестов ломаются при изменении UI. Самовосстанавливающиеся
тесты используют память Synapse, чтобы учиться на прошлых сбоях и адаптироваться
— снижая количество «флакающих» тестов и нагрузку на поддержку.
Концепция
[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
- Лучшие практики работы с памятью
- Cookbook восстановления после ошибок
────────────────────────────────────────────────────────────
# Автоматизация через вебхуки
SUMMARY: Запускайте внешние системы при изменении памяти — синхронизация, уведомления, автоматизация.
Автоматизация через вебхуки
Вебхуки позволяют запускать внешние системы при наступлении событий Synapse.
Это руководство описывает типовые паттерны автоматизации.
Частые паттерны
Паттерн 1: уведомление о критичной памяти
Отправка Slack-сообщения при сохранении критичной памяти:
[CODE BLOCK]
Регистрация вебхука:
[CODE BLOCK]
Паттерн 2: синхронизация с внешней системой
Синхронизация памяти с Notion, Obsidian или любой внешней базой знаний:
[CODE BLOCK]
Паттерн 3: запуск CI/CD
Запуск развёртывания при сохранении памяти о «релизе»:
[CODE BLOCK]
Паттерн 4: пробуждение агента при сообщении человека
Запуск LLM-агента, когда человек отправляет сообщение в чат:
[CODE BLOCK]
Паттерн 5: агрегация метрик
Отслеживание роста памяти, активности чата, завершения задач:
[CODE BLOCK]
Проверка подписи
Всегда проверяйте подписи вебхуков для предотвращения подмены:
[CODE BLOCK]
Логика повторов
Synapse повторяет неудачные вебхуки с экспоненциальной задержкой. Ваш обработчик должен:
1. Быстро возвращать 200 — не делайте тяжёлую работу синхронно
2. Ставить работу в очередь — используйте фоновую систему задач
3. Быть идемпотентным — одно событие может быть доставлено дважды
[CODE BLOCK]
Отладка вебхуков
Проверка истории доставок
Доставки вебхуков логируются. Проверьте недавние доставки вашего вебхука:
[CODE BLOCK]
Ручное тестирование вебхука
[CODE BLOCK]
Частые проблемы
| Проблема | Решение |
|-------|-----|
| 4xx ответы | Проверьте, что обработчик возвращает 200 |
| 5xx ответы | Ошибка сервера — проверьте логи приложения |
| Тайм-аут | Возвращайте 200 быстро, ставьте работу в очередь асинхронно |
| Дублирующиеся доставки | Сделайте обработчик идемпотентным |
| Несовпадение подписи | Проверьте, что секрет корректен |
Лучшие практики
> [!TIP]
> - Всегда проверяйте подписи — никогда не пропускайте это
> - Возвращайте 200 быстро — не блокируйте Synapse
> - Будьте идемпотентны — обрабатывайте дублирующиеся доставки
> - Используйте конкретные события — , а не
> - Мониторьте неудачи доставки — настройте оповещения
Следующие шаги
- Webhooks API
- Cron и планировщик
- Постоянный LLM-агент
## КАТЕГОРИЯ: КОНЦЕПЦИИ
Архитектура и концепции Synapse.
────────────────────────────────────────────────────────────
# Архитектура Synapse
SUMMARY: Как устроен Synapse — Fastify, PostgreSQL, FTS5, эмбеддинги, MCP-сервер.
Архитектура Synapse
Synapse — это multi-tenant API памяти, построенный на Fastify, PostgreSQL с FTS5
и опциональном сервисе эмбеддингов для семантического поиска.
Высокоуровневая архитектура
[CODE BLOCK]
Основные компоненты
1. Synapse API (Fastify)
Главный HTTP-сервер. Обрабатывает:
- REST-эндпоинты (, , и т. д.)
- Аутентификацию (Mind Key для агентов, JWT для людей)
- Лимиты запросов (только при )
- Раздачу статических файлов (веб-интерфейс на , и т. д.)
- Диспетчеризацию вебхуков
Построен на Fastify 5 для производительности. В продакшене работает на порту 12800.
2. PostgreSQL с FTS5
Основное хранилище данных. Использует PostgreSQL с расширением FTS5 для
полнотекстового поиска.
Ключевые таблицы:
| Таблица | Назначение |
|-------|---------|
| | Аккаунты пользователей |
| | Области mind (у каждого есть Mind Key) |
| | Записи памяти с виртуальной таблицей FTS5 |
| | Управление задачами |
| | История чата |
| | Постоянные скрипты |
| | Регистрации вебхуков |
| | Запланированные задачи |
| | Key-value хранилище |
| | Журнал аудита |
FTS5 обеспечивает полнотекстовый поиск по всему содержимому памяти
с задержкой менее миллисекунды. Подробнее см. FTS5-поиск.
3. Сервис эмбеддингов (опционально)
Для семантического поиска Synapse генерирует векторные эмбеддинги содержимого
памяти. Они хранятся вместе с воспоминаниями и используются для поиска по
схожести.
- Провайдер: настраиваемый (OpenAI, локальная модель и т. д.)
- Хранится в колонке таблицы
- Используется эндпоинтом
- См. Семантический поиск
4. MCP-сервер (отдельный сервис)
MCP-сервер Synapse работает как отдельный процесс (порт 13100). Он:
- Предоставляет 79 инструментов через Model Context Protocol
- Поддерживает транспорты stdio, HTTP/SSE и WebSocket
- Транслирует вызовы MCP-инструментов в вызовы Synapse API
- Multi-tenant: один Mind Key на сессию
5. Браузерный прокси (отдельный сервис)
Для автоматизации браузера запускается отдельный сервис на базе Playwright
на порту 13000. MCP-сервер может вызывать его для инструментов .
6. SSH-прокси (отдельный сервис)
Для удалённых команд по SSH запускается отдельный сервис на порту 12900.
Модель multi-tenancy
[CODE BLOCK]
Каждый mind полностью изолирован. Mind Key даёт доступ ровно к одному mind.
JWT даёт доступ к аккаунту пользователя (для управления mind).
Подробнее см. Multi-tenancy.
Поток запросов
Запрос на сохранение памяти
[CODE BLOCK]
Запрос на поиск памяти
[CODE BLOCK]
Развёртывание
Synapse разворачивается как Docker-контейнер. См. :
[CODE BLOCK]
Характеристики производительности
| Операция | Задержка | Пропускная способность |
|-----------|---------|------------|
| Сохранение памяти | 5 мс | 1000+ запросов/с |
| Отзыв памяти | 20 мс | 500 запросов/с |
| FTS5-поиск | 10 мс | 800 запросов/с |
| Семантический поиск | 50 мс | 200 запросов/с |
| Опрос чата | 5 мс | 2000 запросов/с |
Следующие шаги
- Модель памяти
- Multi-tenancy
- FTS5-поиск
────────────────────────────────────────────────────────────
# Полнотекстовый поиск FTS5
SUMMARY: Как Synapse использует FTS5 SQLite для полнотекстового поиска по памяти с задержкой менее миллисекунды.
Полнотекстовый поиск 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. Факторы:
- Частота термина (как часто термин встречается)
- Обратная частота документа (более редкие термины ранжируются выше)
- Длина документа (более короткие документы с термином ранжируются выше)
- Вес колонки (заголовок > содержимое)
Результаты возвращаются в порядке ранжирования (наиболее релевантные — первыми).
Производительность
| Операция | Задержка |
|-----------|---------|
| Поиск по 100 воспоминаниям | < 5 мс |
| Поиск по 1000 воспоминаний | < 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), затем по свежести.
Источник: user против agent
У воспоминаний есть тег :
- — сохранено человеком (через JWT или человеко-ориентированный UI)
- — сохранено 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 — явно сомнительное
Устанавливайте confidence при сохранении:
[CODE BLOCK]
Истечение срока
Устанавливайте для чувствительных ко времени воспоминаний:
[CODE BLOCK]
Истёкшие воспоминания не возвращаются (но остаются в БД).
Используйте , чтобы увидеть воспоминания, истекающие скоро.
Жизненный цикл памяти
[CODE BLOCK]
Поведение отзыва
возвращает простое текстовое резюме, оптимизированное
для контекста LLM:
[CODE BLOCK]
- Сортировка по приоритету (critical → low), затем по свежести
- Неверифицированные воспоминания помечены
- Теги включены для контекста
- Простой текст (разбор JSON не требуется)
Следующие шаги
- Memory API
- Лучшие практики работы с памятью
- FTS5-поиск
────────────────────────────────────────────────────────────
# Multi-tenancy и изоляция
SUMMARY: Как Synapse изолирует данные между пользователями и minds — разбор границ безопасности.
Multi-tenancy и изоляция
Synapse — multi-tenant-система: несколько пользователей, у каждого — несколько
mind, полностью изолированных друг от друга. На этой странице описана модель
изоляции.
Иерархия арендаторов
[CODE BLOCK]
Уровни изоляции
Уровень 1: изоляция пользователей
Каждый аккаунт пользователя изолирован. Alice не может:
- Видеть mind пользователя Bob
- Получать доступ к воспоминаниям Bob (даже со своим JWT)
- Просматривать данные аккаунта Bob
Обеспечивается: колонкой во всех таблицах, 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]
После этого Bob может получить доступ к Mind A через свой JWT
(только для чтения, если ).
Границы безопасности
[CODE BLOCK]
Типовые паттерны multi-tenancy
Паттерн 1: один пользователь, один mind
Наиболее распространён у индивидуальных пользователей LLM-агентов.
- 1 аккаунт пользователя
- 1 mind
- 1 Mind Key
- Все воспоминания в одной области
Паттерн 2: один пользователь, несколько mind
Для пользователей с несколькими контекстами (работа, личное, проекты).
- 1 аккаунт пользователя
- N mind (например, «work», «personal», «project-x»)
- N Mind Key
- Каждая LLM-сессия использует один Mind Key
Паттерн 3: командный общий mind
Для команд, сотрудничающих над проектом.
- 1 пользователь создаёт mind (получает Mind Key)
- Создатель делится с участниками команды через JWT
- Все участники получают доступ через JWT (или общий Mind Key)
> [!WARNING]
> Передача Mind Key даёт полный доступ на чтение/запись. Для командной работы
> предпочтительнее Sharing API (на основе JWT), а не прямой обмен Mind Key.
Паттерн 4: SaaS-провайдер
Для приложений, встраивающих Synapse как слой памяти.
- Каждый клиент = 1 аккаунт пользователя
- Каждый проект клиента = 1 mind
- Приложение хранит Mind Key по каждому клиенту/проекту
- Полная изоляция между клиентами
Проверка изоляции
Тест: Mind Key не может получить доступ к другим mind
[CODE BLOCK]
Тест: JWT не может читать данные памяти напрямую
[CODE BLOCK]
Лучшие практики
> [!TIP]
> - Используйте один mind на проект/контекст — изоляция вам помогает
> - Никогда не передавайте Mind Key — используйте Sharing API
> - Ротируйте Mind Key при компрометации (удалите mind, создайте новый)
> - Аудит общих mind — периодически проверяйте
> - Используйте JWT для человеко-ориентированного UI — никогда не показывайте Mind Key конечным пользователям
Следующие шаги
- Аутентификация
- 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, управлении сессиями, 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 Key истекают. Это
руководство показывает, как 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-поиск
- Task-Driven Workflow
────────────────────────────────────────────────────────────
# Паттерн начала сессии
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]
> - Пропуск отзыва — вы начинаете без контекста, повторяете прошлые ошибки
> - Забываете опросить чат — сообщения человека остаются без ответа
> - Игнорирование активных задач — работа забывается на середине выполнения
> - Ничего не сохраняете — сессия не приносит постоянной ценности
Вариации
Минимальный паттерн (LLM с малым контекстом)
Для LLM с небольшим контекстным окном пропустите полный отзыв:
[CODE BLOCK]
Затем ищите конкретные темы по необходимости:
[CODE BLOCK]
Агрессивный паттерн (долгоживущие агенты)
Для агентов, работающих часами, добавьте периодический повторный отзыв:
[CODE BLOCK]
Следующие шаги
- Стратегия тегирования памяти
- Task-Driven Workflow
- Паттерн опроса чата
────────────────────────────────────────────────────────────
# Task-Driven Workflow
SUMMARY: Используйте задачи Synapse для управления многошаговыми LLM-рабочими процессами, которые сохраняются между сессиями.
Task-Driven Workflow
Задачи — это не просто todo, это основа постоянных 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]
> - Создавайте задачи для многошаговой работы — одношаговой задача не нужна
> - Обновляйте описание с прогрессом — обеспечивает возобновление
> - Используйте высокий приоритет для активной работы — поднимается в отзыве
> - Завершайте задачи после выполнения — не оставляйте в inprogress
> - Сохраняйте резюме завершения как воспоминания — для долгосрочной ссылки
Частые паттерны
Паттерн: рабочий процесс исправления бага
[CODE BLOCK]
Паттерн: рабочий процесс исследования
[CODE BLOCK]
Следующие шаги
- Паттерн начала сессии
- Паттерн опроса чата
- Восстановление после ошибок
## КАТЕГОРИЯ: ЧАСТО ЗАДАВАЕМЫЕ ВОПРОСЫ
Часто задаваемые вопросы и распространённые проблемы.
────────────────────────────────────────────────────────────
# FAQ по API
SUMMARY: Типовые вопросы по API — аутентификация, лимиты, обработка ошибок, обнаружение эндпоинтов.
FAQ по API
Типовые вопросы по Synapse API.
Как аутентифицироваться?
Два способа:
1. Mind Key (для данных):
2. JWT (для аккаунтов):
Или через query-параметр (лимит 60 запросов/мин):
См. Аутентификация.
В чём разница между Mind Key и JWT?
- Mind Key: область — арендатор, не истекает, для данных памяти/чата/задач
- 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?
Вы используете аутентификацию через query-параметр , лимит — 60 запросов/мин.
Решение: Перейдите на заголовок (без лимита).
См. Лимиты запросов.
Как получить список всех эндпоинтов?
[CODE BLOCK]
Как найти нужный эндпоинт?
1. Проверьте для машиночитаемого списка
2. Проверьте для полной документации API
3. Просмотрите — систему документации
4. Используйте для спецификации OpenAPI 3.0
Можно ли использовать GET вместо POST?
У некоторых POST-эндпоинтов есть GET-эквиваленты для инструментов, работающих только с URL:
- ↔
- ↔
- ↔
Проверьте на наличие GET-вариантов.
Как обрабатывать ошибки?
Все ошибки возвращают JSON:
[CODE BLOCK]
См. Ошибки и обработка ошибок.
Какой лимит размера тела запроса?
10 МБ. Для больших payloads (например, загрузка файлов) используйте 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?
| Возможность | Память ChatGPT | Synapse |
|---------|---------------|---------|
| Хранилище | Серверы OpenAI | Ваш сервер |
| Доступ через API | Нет | Да (REST + MCP) |
| Multi-tenant | Нет | Да (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-host.
Мои данные приватны?
Да. Каждый mind изолирован (см. Multi-tenancy).
Другие пользователи не могут видеть ваши данные. Хостинг-провайдер (Schäfer Services)
имеет доступ, но не просматривает данные пользователей.
Для максимальной приватности — self-host.
Можно ли экспортировать мои данные?
Да. Используйте для экспорта всех воспоминаний в JSON.
См. Резервное копирование и восстановление.
Что делать, если я потерял Mind Key?
Mind Key показывается только один раз при создании. Если потерян:
1. Войдите по email/паролю, чтобы получить JWT
2. Создайте новый mind через
3. Сохраните новый Mind Key
4. (Опционально) Удалите старый mind через
Восстановить воспоминания из mind, ключ к которому утерян, нельзя.
Могут ли несколько LLM-агентов делить mind?
Да. Все агенты, использующие один Mind Key, делят данные этого mind. Для
скоординированной multi-agent-работы см. Координация нескольких агентов.
Работает ли Synapse офлайн?
Нет, Synapse требует интернет-соединения с сервером (хостинговым или
собственным). Для офлайн LLM запускайте Synapse локально.
Насколько быстр поиск по памяти?
- Полнотекстовый поиск FTS5: < 10 мс для 1000 воспоминаний
- Семантический поиск: 50–100 мс для 1000 воспоминаний
- Полный отзыв: < 50 мс для 1000 воспоминаний
Подробнее см. FTS5-поиск.
Можно ли использовать Synapse без LLM?
Да. Synapse — это универсальный API памяти. Его можно использовать из любого
приложения, которому выгодно постоянное, доступное для поиска key-value-хранилище
с категориями и тегами.
Следующие шаги
- Что такое Synapse?
- Быстрый старт
- FAQ по API
────────────────────────────────────────────────────────────
# FAQ по MCP
SUMMARY: Типовые вопросы по интеграции MCP — инструменты, транспорты, устранение проблем.
FAQ по MCP
Типовые вопросы по 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 (локально, рекомендуется для desktop)
2. HTTP/SSE (удалённо, multi-tenant)
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 Key.
Можно ли ограничить набор инструментов?
Да, используйте Tool Profiles:
- : 8 составных инструментов (500 токенов)
- : 25 инструментов (2 500 токенов)
- : 119 инструментов (8 250 токенов, по умолчанию)
Задаётся через переменную окружения или заголовок .
Как отлаживать проблемы MCP?
1. Запустите MCP-сервер вручную:
2. Проверьте логи клиента (зависит от клиента)
3. Убедитесь, что Mind Key работает:
4. Проверьте здоровье Synapse:
См. Устранение проблем MCP.
MCP-сервер бесплатен?
Да. npm-пакет имеет открытый исходный код. Хостинговый
MCP-сервер на бесплатен для публичного использования.
Можно ли хостить MCP-сервер самому?
Да:
[CODE BLOCK]
Чем MCP отличается от прямых вызовов API?
| Аспект | Прямой API | MCP |
|--------|-----------|-----|
| Что нужно знать LLM | URL, заголовки, аутентификацию | Только имена инструментов |
| Аутентификация | Вручную | Автоматически (env var) |
| Обнаружение инструментов | Чтение /endpoints | Автоматически через протокол MCP |
| Обработка ошибок | Вручную | Стандартизированная |
| Лучше всего для | Кастомных интеграций | LLM-агентов |
Можно ли создать свой MCP-клиент?
Да. Используйте официальный SDK MCP:
- 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 Key нельзя восстановить. Необходимо:
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 точно — чувствителен к регистру, без trailing-слешей
3. Проверьте HTTP-метод — и различаются
API-вызовы возвращают 429
Симптомы
- 429 Too Many Requests
- «Rate limit exceeded»
Решения
1. Перейдите на header-auth (без лимита):
[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. Проверьте место на диске:
Для хостинга: сообщите в поддержку.
Вебхук не срабатывает
Симптомы
- Зарегистрировали вебхук, но колбэки не приходят
- Нет POST на ваш URL
Решения
1. Убедитесь, что URL доступен:
2. Проверьте фильтр событий — соответствует всем событиям памяти
3. Протестируйте вебхук:
4. Проверьте, что вебхук включён:
5. Проверьте SSL — Synapse требует валидный HTTPS для URL вебхуков
См. Webhooks API.
Cron-задача не запускается
Симптомы
- Создали cron-задачу, но она не срабатывает
- не обновляется
Решения
1. Проверьте синтаксис расписания — должен быть валидный 5-полейный cron ИЛИ целое число секунд
2. Убедитесь, что эндпоинт разрешён — должен быть http(s), без приватных IP
3. Проверьте, что задача включена:
4. Дождитесь следующего запланированного времени — cron не мгновенный
См. Cron и планировщик.
Нужно больше помощи?
1. Проверьте существующую документацию:
2. Поиск по документации:
3. Создайте issue:
4. Контакт: см. страницу
Следующие шаги
- Ошибки и обработка ошибок
- FAQ по API
- Устранение проблем MCP