# DOKUMENTACJA SYNAPSE — Pełna referencja
# Wygenerowano: 2026-07-18T04:12:22.646Z
# Łączna liczba artykułów: 47
Ten dokument zawiera pełną dokumentację API Synapse.
Base URL: https://synapse.schaefer.zone
Language: pl
========================================================================
## KATEGORIA: PIERWSZE KROKI
Wszystko, czego potrzebujesz, aby zacząć z Synapse.
────────────────────────────────────────────────────────────
# Autoryzacja i Mind Key
SUMMARY: Jak działa autoryzacja w Synapse: Mind Key dla agentów, JWT dla ludzi, ?key= dla narzędzi obsługujących tylko 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.
Autoryzacja i Mind Key
Synapse używa dwóch metod autoryzacji, każda zoptymalizowana pod inny przypadek.
Zrozumienie różnicy jest kluczowe dla budowy niezawodnych integracji.
Dwie metody autoryzacji
| Metoda | Przypadek użycia | Limit żądań | Wygasanie |
|--------|----------|------------|--------|
| Mind Key | Agenty LLM, narzędzia zautomatyzowane | Brak (nagłówek) / 60 min (zapytanie) | Nigdy |
| JWT | Interfejs dla człowieka, operacje na koncie | Brak | 7 dni |
Mind Key (dla agentów)
Mind Key to token API o zakresie dzierżawcy. Uwierzytelnia dane pojedynczego
umysłu (wspomnienia, zadania, czat, skrypty itp.). Stosować do:
- Agentów LLM wywołujących API
- Skryptów automatyzacji w tle
- Konfiguracji serwera MCP
- Dowolnej długotrwałej integracji
Autoryzacja nagłówkiem (zalecane)
[CODE BLOCK]
Parametr zapytania (dla narzędzi obsługujących tylko URL)
[CODE BLOCK]
> [!WARNING]
> Parametr zapytania jest ograniczony do 60 żądań na minutę. Nagłówek
> Bearer nie ma limitu. Należy używać nagłówka zawsze, gdy klient obsługuje
> własne nagłówki.
Tworzenie Mind Key
[CODE BLOCK]
Odpowiedź zawiera — należy go natychmiast zapisać, jest
wyświetlany tylko raz.
Wylistowanie umysłów
[CODE BLOCK]
Usuwanie umysłu (nieodwracalne!)
[CODE BLOCK]
JWT (dla ludzi)
JWT uwierzytelnia konto użytkownika, a nie konkretny umysł. Stosować do:
- Rejestracji konta i logowania
- Tworzenia / listowania / usuwania umysłów
- Współdzielenia umysłów z innymi użytkownikami
- Zarządzania subskrypcjami Web Push
Rejestracja
[CODE BLOCK]
Zwraca:
Logowanie
[CODE BLOCK]
Zwraca:
Wygasanie JWT
JWT wygasają po 7 dniach. Po wygaśnięciu należy po prostu ponownie wywołać
, aby uzyskać nowy. Mind Key nigdy nie wygasa, więc istniejące integracje
agentów nadal działają.
Najlepsze praktyki bezpieczeństwa
> [!CRITICAL]
> - Nigdy nie commitować Mind Key do gita. Używać zmiennych środowiskowych.
> - Nigdy nie logować Mind Key. Maskować je w logach ().
> - Rotować klucze w razie podejrzenia wycieku (usunąć umysł, utworzyć nowy).
> - Używać jednego umysłu na projekt, aby ograniczyć obszar rażenia przy wycieku klucza.
Wzorzec zmiennych środowiskowych
[CODE BLOCK]
[CODE BLOCK]
Konfiguracja serwera MCP
[CODE BLOCK]
Wzorzec wielu umysłów
Każdy użytkownik może mieć wiele umysłów. Typowe wzorce:
| Nazwa umysłu | Przeznaczenie |
|-----------|---------|
| | Wspomnienia związane z pracą |
| | Preferencje osobiste, rodzina |
| | Kontekst konkretnego projektu |
| | Postęp w nauce |
| | Ogólnego przeznaczenia, zapasowy |
Należy używać różnych Mind Key dla różnych sesji LLM, aby utrzymać konteksty
oddzielone.
Limity żądań
| Metoda autoryzacji | Limit | Zakres |
|-------------|-------|-------|
| Mind Key (nagłówek) | Brak | Na umysł |
| Mind Key (?key=) | 60/min | Na IP |
| JWT (nagłówek) | Brak | Na użytkownika |
| Endpointy publiczne | Brak | Globalny |
Nagłówki limitu żądań (, , )
są dołączane do odpowiedzi, gdy ma to zastosowanie.
Następne kroki
- Mind Key vs JWT — kiedy którego używać
- Memory API — co można robić z Mind Key
- User API — zarządzanie kontem z JWT
────────────────────────────────────────────────────────────
# Mind Key vs JWT — co i kiedy?
SUMMARY: Przewodnik decyzyjny: Mind Key do dostępu do danych agenta, JWT do zarządzania kontem.
KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).
Mind Key vs JWT — co i kiedy?
Synapse ma dwa tokeny autoryzacyjne. Wybór niewłaściwego prowadzi do błędów 401.
Ten przewodnik dostarcza jasnej ramy decyzyjnej.
Szybka tabela decyzyjna
| Cel | Użyć |
|----------------|-----|
| Zapis / recall wspomnień | Mind Key |
| Wysyłanie / odpytywanie wiadomości czatu | Mind Key |
| Zarządzanie zadaniami | Mind Key |
| Zapis skryptów | Mind Key |
| Rejestracja webhooków | Mind Key |
| Sterowanie komputerami | Mind Key (po stronie użytkownika) / Computer Token (po stronie agenta) |
| Rejestracja konta użytkownika | Brak (publiczne) |
| Logowanie | Brak (publiczne) |
| Tworzenie / listowanie / usuwanie umysłów | JWT |
| Współdzielenie umysłu z innym użytkownikiem | JWT |
| Subskrypcja powiadomień Web Push | JWT |
| Przegląd dziennika audytu | Mind Key |
Prosta reguła
> [!TIP]
> Jeśli operacja dotyka danych pojedynczego umysłu → Mind Key.
> Jeśli zarządza kontem lub metadanymi umysłów → JWT.
Mind Key — token dostępu do danych
Mind Key daje dostęp do danych jednego umysłu. Jest długowiecznym tokenem,
który nigdy nie wygasa (dopóki umysł nie zostanie usunięty). Idealny do:
- Agentów LLM utrwalających wspomnienia między sesjami
- Zadań cron w tle
- Konfiguracji serwera MCP
- Integracji webhooków
- Aplikacji mobilnych odczytujących pamięć
Co Mind Key może
- — odczyt wszystkich wspomnień w tym umyśle
- — zapis/aktualizacja wspomnień
- — odczyt wiadomości czatu
- — wysyłanie wiadomości czatu
- — lista zadań
- — tworzenie zadań
- — zapis skryptów
- — rejestracja webhooków
- — kolejkowanie poleceń komputera
Czego Mind Key NIE może
- Tworzyć / listować / usuwać umysłów (wymagany JWT)
- Współdzielić umysłu z innym użytkownikiem (wymagany JWT)
- Wyświetlać informacji o koncie użytkownika (wymagany JWT)
- Subskrybować Web Push (wymagany JWT)
JWT — token zarządzania kontem
JWT uwierzytelnia konto użytkownika. Wygasa po 7 dniach i jest używany do
operacji na poziomie konta, które obejmują wiele umysłów lub innych użytkowników.
Co JWT może
- — utworzenie nowego umysłu (zwraca nowy Mind Key)
- — lista wszystkich umysłów tego użytkownika
- — usunięcie umysłu
- — udostępnienie umysłu innemu użytkownikowi
- — subskrypcja powiadomień Web Push
- — lista udostępnień umysłu
Czego JWT NIE może
- Odczytywać / zapisywać wspomnień (wymagany Mind Key)
- Wysyłać wiadomości czatu (wymagany Mind Key)
- Zarządzać zadaniami (wymagany Mind Key)
- Rejestrować webhooków (wymagany Mind Key)
Przypadek specjalny: Computer Token
Endpointy (po stronie agenta, dla screen-remote-agent) używają
trzeciego typu tokena: Computer Token. Jest on zwracany przez
przy realizacji kodu instalacyjnego i jest specyficzny
dla jednego zarejestrowanego komputera.
| Endpoint | Autoryzacja |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key lub JWT |
| | Mind Key lub JWT |
Typowe wzorce
Wzorzec 1: pojedynczy agent LLM
1. Jedna rejestracja → uzyskanie JWT
2. Utworzenie jednego umysłu → uzyskanie Mind Key
3. LLM używa Mind Key do wszystkiego
Wzorzec 2: agent wieloprojektowy
1. Jedna rejestracja → uzyskanie JWT
2. Utworzenie wielu umysłów (work, personal, project-x) → uzyskanie wielu Mind Key
3. LLM ładuje różne Mind Key w zależności od kontekstu
Wzorzec 3: współdzielenie zespołu
1. Użytkownik A tworzy umysł → uzyskuje Mind Key A
2. Użytkownik A udostępnia użytkownikowi B przez JWT ()
3. Użytkownik B ma teraz dostęp przez własny JWT
4. Do dostępu przez LLM użytkownik B musi utworzyć własny Mind Key (lub użyć A)
Wzorzec 4: serwer MCP
Serwery MCP zawsze używają Mind Key (ustawionego przez zmienną środowiskową
). Jedna instancja serwera MCP = jeden umysł. Dla dostępu do
wielu umysłów należy uruchomić wiele instancji MCP lub zaimplementować
przełączanie umysłów po stronie klienta.
Ściąga formatów tokenów
| Token | Format | Przykład |
|-------|--------|---------|
| Mind Key | + 36 znaków | |
| JWT | + base64 | |
| Computer Token | + 36 znaków | |
Następne kroki
- Autoryzacja — pełny przewodnik autoryzacji
- User & Minds API — endpointy chronione JWT
- Memory API — endpointy chronione Mind Key
────────────────────────────────────────────────────────────
# Szybki start dla agentów LLM
SUMMARY: W 3 wywołaniach API: recall wszystkich wspomnień, zapis nowego, wyszukiwanie. Niezbędny przepływ 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
Szybki start dla agentów LLM
Między sesjami tracisz całą pamięć. Synapse jest twoim zewnętrznym mózgiem. Ten
przewodnik pokazuje trzy niezbędne wywołania API, które musi znać każdy agent LLM.
> [!CRITICAL]
> Należy wywołać na POCZĄTKU KAŻDEJ sesji.
> Bez tego wywołania agent nie ma pamięci o tym, kim jest użytkownik, co obiecał
> ani nad czym pracował ostatnio.
Krok 1: Recall wszystkich wspomnień (ZAWSZE NAJPIERW)
[CODE BLOCK]
Zwraca ustrukturyzowane, tekstowe podsumowanie wszystkich zapisanych wspomnień.
Należy je przeanalizować, aby odbudować model mentalny użytkownika, jego projektów
i przeszłych interakcji.
Przykładowa odpowiedź:
[CODE BLOCK]
Krok 2: Zapis nowego wspomnienia
Gdy poznasz coś warte zapamiętania:
[CODE BLOCK]
Kategorie: , , , , , , , ,
Priorytety: , , ,
> [!TIP]
> Zawsze należy dołączyć pole — krótki identyfikator wspomnienia. Pozwala to
> zaktualizować to samo wspomnienie później przez ponowne POST z tym samym kluczem.
Krok 3: Wyszukiwanie konkretnego wspomnienia
[CODE BLOCK]
> [!TIP]
> Składnia FTS5: wiele słów = wyszukiwanie AND. Frazy w cudzysłowach: .
> Wyszukiwanie prefiksem: . Wartość logiczna: .
Narzędzia otwarte (bez nagłówków autoryzacji)
Jeśli narzędzie potrafi tylko otwierać URL-e (bez własnych nagłówków), użyć
parametru :
[CODE BLOCK]
> [!WARNING]
> jest ograniczone do 60 żądań/minutę. Nagłówek Bearer nie ma limitu.
> Należy używać nagłówka Bearer zawsze, gdy to możliwe.
Pełny przepływ sesji
1. Początek sesji: — załadowanie wszystkich wspomnień
2. Podczas pracy: — znalezienie konkretnych faktów
3. Przy nowej informacji: — zapis (z kategorią, kluczem, tagami, priorytetem)
4. Okresowo: — sprawdzenie wiadomości od człowieka
5. Koniec sesji: Zapis końcowych ustaleń przez
Typowe wzorce
Aktualizacja istniejącego wspomnienia
Wykonać POST z tym samym i — istniejące wspomnienie
jest aktualizowane, a nie duplikowane.
Zapis statusu projektu
[CODE BLOCK]
Zapis błędu (aby go nie powtórzyć)
[CODE BLOCK]
Sprawdzanie wiadomości od człowieka
[CODE BLOCK]
Zwraca nieprzeczytane wiadomości od człowieka. Odpowiedź przez:
[CODE BLOCK]
Następne kroki
- Autoryzacja — Mind Key vs JWT
- Dokumentacja Memory API — wszystkie 22 endpointy pamięci
- Chat API — asynchroniczna komunikacja z ludźmi
- Książka kucharska LLM — praktyczne wzorce
────────────────────────────────────────────────────────────
# Szybki start (człowiek)
SUMMARY: Zarejestruj konto, utwórz pierwszy umysł, zapisz wspomnienie — wszystko w 5 minut.
Szybki start (człowiek)
Ten przewodnik przeprowadzi przez zakładanie konta Synapse, uzyskanie pierwszego
Mind Key i zapisanie pierwszego wspomnienia. Łączny czas: około 5 minut.
Krok 1: Rejestracja konta
Otworzyć API Synapse i utworzyć konto:
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
> [!TIP]
> Należy zapisać JWT w bezpiecznym miejscu — będzie potrzebny do tworzenia umysłów.
> JWT wygasa po 7 dniach; ponowne logowanie tym samym endpointem go odświeża.
Krok 2: Utworzenie pierwszego umysłu
„Umysł" to izolowany zakres pamięci. Większość użytkowników zaczyna od jednego
umysłu, ale można mieć wiele (np. „work", „personal", „project-x"). Każdy umysł
ma swój unikalny Mind Key.
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
> [!CRITICAL]
> Należy natychmiast zapisać . Jest wyświetlany tylko raz i nie
> można go później odzyskać. W razie utraty trzeba utworzyć nowy umysł.
Krok 3: Zapis pierwszego wspomnienia
Teraz użyj Mind Key, aby zapisać wspomnienie:
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
Krok 4: Recall wszystkich wspomnień
Aby pobrać wszystko, co zapisano:
[CODE BLOCK]
Odpowiedź (zwykły tekst, zoptymalizowany pod kątem konsumpcji przez LLM):
[CODE BLOCK]
Krok 5: Wyszukiwanie wspomnień
Znajdowanie konkretnych wspomnień po słowie kluczowym:
[CODE BLOCK]
Krok 6: Podłączenie LLM
Najprostszym sposobem nadania LLM-owi dostępu do Synapse jest MCP:
- Konfiguracja Claude Desktop — konfiguracja w 2 minuty
- Konfiguracja Claude Code — integracja z terminalem
- Konfiguracja Cursor — integracja z IDE
Po konfiguracji LLM automatycznie wywoła na początku każdej sesji
i utrwali nowe fakty przez .
Kategorie wspomnień
Synapse obsługuje 8 kategorii — wybrać najbardziej konkretną:
| Kategoria | Przypadek użycia |
|----------|----------|
| | Imię użytkownika, rola, dane kontaktowe |
| | Sympatie, antypatie, styl pracy |
| | Weryfikowalne fakty (szczegóły projektu, daty) |
| | Status projektu, kamienie milowe, todo |
| | Rzeczy, w których użytkownik jest dobry |
| | Błędy z przeszłości — unikać powtarzania |
| | Kontekst istotny dla sesji |
| | Różne notatki |
Poziomy priorytetu
- — warto wiedzieć
- — domyślny
- — ważne
- — nigdy nie wolno zapominać (tożsamość użytkownika, informacje prawne)
Następne kroki
- Dogłębna autoryzacja
- Mind Key vs JWT
- Dokumentacja Memory API
- Integracja MCP
────────────────────────────────────────────────────────────
# Czym jest Synapse?
SUMMARY: Synapse to API trwałej pamięci dla agentów LLM — AI nigdy nie zapomina między sesjami.
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.)
Czym jest Synapse?
Synapse to API trwałej pamięci dla agentów LLM. Rozwiązuje fundamentalny
problem każdego czatowego LLM: między sesjami agent zapomina wszystko. Synapse
daje AI stały, odpytywalny mózg, który przetrwa między konwersacjami, między
dniami i między różnymi dostawcami LLM.
> [!CRITICAL]
> Jeśli jesteś agentem LLM czytającym to: wywołaj na
> początku każdej sesji. Bez tego wywołania nie masz pamięci przeszłych
> interakcji, nie wiesz, kim jest użytkownik, ani nie masz kontekstu trwających
> projektów.
Problem, który rozwiązuje Synapse
Każdy współczesny LLM (Claude, GPT, Gemini, Llama) ma to samo ograniczenie
architektoniczne: okno kontekstu konwersacji jest skończone, a po zakończeniu
sesji cały stan jest tracony. Oznacza to, że asystent AI:
- Zapomina imię, preferencje i trwające projekty między czatami
- Nie potrafi uczyć się na przeszłych błędach między sesjami
- Nie ma ciągłości dla długotrwałej pracy
- Za każdym razem zadaje te same pytania doprecyzowujące
Synapse rozwiązuje to, dostarczając proste API HTTP, w którym LLM może zapisywać
i pobierać ustrukturyzowane wspomnienia. Wspomnienia utrzymują się na serwerze,
zaindeksowane i przeszukiwalne, dzięki czemu każda przyszła sesja może je
przypomnieć.
Najważniejsze funkcje
- Trwały magazyn pamięci — fakty, preferencje, projekty, błędy, umiejętności
- Wyszukiwanie pełnotekstowe (FTS5) — znalezienie każdego wspomnienia po słowie kluczowym w milisekundach
- Wyszukiwanie semantyczne — wyszukiwanie podobieństw oparte na osadzeniach dla zapytań koncepcyjnych
- Wielodostępność — każdy użytkownik ma izolowane „umysły" (jeden użytkownik, wiele projektów)
- Asynchroniczny czat — ludzie mogą zostawiać wiadomości dla agenta, gdy pracuje
- Zadania i harmonogram — wbudowany menedżer zadań i harmonogram cron
- Integracja MCP — 79 narzędzi udostępnionych jako Model Context Protocol dla Claude, Cursor, Continue
- Sterowanie przeglądarką i komputerem — narzędzia zdalnej automatyzacji
- Webhooki — wywołania zwrotne HTTP przy zmianach pamięci/czatu/zadań
Jak to działa
[CODE BLOCK]
1. LLM wywołuje na początku sesji
2. Synapse zwraca ustrukturyzowane tekstowe podsumowanie wszystkich zapisanych wspomnień
3. LLM pracuje, okresowo wywołując , aby zapisywać nowe fakty
4. Gdy użytkownik zadaje pytanie, LLM może wywołać
5. Na końcu sesji istotny nowy kontekst jest utrwalany na następną sesję
Dla kogo to jest?
- Twórcy agentów LLM, którzy potrzebują trwałego stanu
- Zaawansowani użytkownicy uruchamiający lokalne LLM (Ollama, LM Studio) z własnymi agentami
- Zespoły budujące asystenty AI wymagające współdzielonej pamięci
- Inżynierowie automatyzacji łączący wywołania LLM między sesjami
Szybkie porównanie
| Cecha | Pamięć ChatGPT | Synapse |
|---------|---------------|---------|
| Lokalizacja magazynu | Serwery OpenAI | Własny serwer |
| Dostęp przez API | Nie (zamknięte) | Tak (REST + MCP) |
| Wielodostępność | Nie | Tak (umysły) |
| Własne kategorie | Nie | Tak (8 kategorii) |
| Wyszukiwanie | Ograniczone | FTS5 + semantyczne |
| Self-hosting | Nie | Tak (Docker) |
Następne kroki
- Szybki start dla ludzi — Mind Key w 5 minut
- Szybki start dla LLM — pierwsze wywołania API
- Autoryzacja — Mind Key vs JWT
- Przegląd architektury — jak zbudowany jest Synapse
## KATEGORIA: DOKUMENTACJA API
Pełna dokumentacja każdego punktu końcowego API.
────────────────────────────────────────────────────────────
# Proxy przeglądarki
SUMMARY: Usługa automatyzacji przeglądarki — osobny kontener Docker na porcie 13000 do sterowania przeglądarką 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.)
Proxy przeglądarki
Proxy przeglądarki to osobna usługa Docker, która udostępnia automatyzację
przeglądarki headless przez Playwright. Nie jest częścią API Synapse — endpointy
Synapse nie zawierają ścieżek .
Architektura
[CODE BLOCK]
Metody dostępu
Metoda 1: przez serwer MCP Synapse (zalecane)
Serwer MCP Synapse udostępnia narzędzia przeglądarki jako narzędzia MCP. Należy
tego używać do automatyzacji przeglądarki sterowanej przez LLM:
[CODE BLOCK]
Dostępne narzędzia MCP przeglądarki:
- — otwiera nową kartę przeglądarki
- — przechodzi pod podany URL
- — klika element
- — wpisuje tekst w pole
- — wykonuje zrzut ekranu
- — zamyka kartę
- (i więcej — patrz Integracja MCP)
Metoda 2: bezpośredni dostęp do Browser Proxy
W integracjach niewymagających MCP należy połączyć się bezpośrednio z usługą
browser-proxy:
[CODE BLOCK]
Typowe przypadki użycia
Web scraping
[CODE BLOCK]
Automatyzacja formularzy
[CODE BLOCK]
Przechwytywanie zrzutów ekranu
[CODE BLOCK]
Powiązane usługi
| Usługa | Port | Przeznaczenie |
|---------|------|----------------|
| Synapse API | 12800 | Memory, chat, tasks |
| Synapse MCP | 13100 | Serwer MCP (79 narzędzi) |
| Browser Proxy | 13000 | Automatyzacja przeglądarki headless |
| SSH Proxy | 12900 | Dostęp SSH do zdalnych maszyn |
Następne kroki
- Integracja MCP — jak używać narzędzi przeglądarki przez MCP
- Computer Control API — automatyzacja GUI na zarejestrowanych maszynach
────────────────────────────────────────────────────────────
# Chat API
SUMMARY: Asynchroniczny czat między człowiekiem a agentami LLM — odpytywanie, odpowiedzi, historia, liczba nieprzeczytanych, przesyłanie plików.
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 umożliwia asynchroniczną komunikację między człowiekiem a agentami LLM.
W przeciwieństwie do czatu synchronicznego (w stylu ChatGPT), człowiek może
zostawiać wiadomości, gdy agent pracuje — agent odpytuje API między wywołaniami
narzędzi.
Jak to działa
[CODE BLOCK]
1. Człowiek wysyła wiadomość przez interfejs WWW (używa JWT)
2. Wiadomość jest zapisywana i oznaczana jako nieprzeczytana
3. Agent odpytuje między wywołaniami narzędzi
4. Poll zwraca wszystkie nieprzeczytane wiadomości i oznacza je jako przeczytane
5. Agent przetwarza wiadomość i opcjonalnie odpowiada przez
Endpointy
GET /chat/poll
Odpytuje o nowe wiadomości od człowieka. Zwraca nieprzeczytane wiadomości i
oznacza je jako przeczytane. Należy używać między wywołaniami narzędzi.
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
POST /chat/reply
Wysyła wiadomość jako agent.
[CODE BLOCK]
POST /chat/send
Wysyła wiadomość jako człowiek (wymaga JWT, nie Mind Key).
[CODE BLOCK]
GET /chat/history
Pobiera najnowszą historię czatu (obie role).
[CODE BLOCK]
GET /chat/unread
Zwraca liczbę nieprzeczytanych wiadomości.
[CODE BLOCK]
GET /chat/status
Zwraca status sesji czatu (znaczniki czasu ostatnich wiadomości, liczby nieprzeczytanych).
[CODE BLOCK]
POST /chat/upload
Przesyła załącznik do pliku dla konkretnej wiadomości (formularz multipart).
[CODE BLOCK]
GET /chat/files/:messageid
Lista załączników dla wiadomości.
[CODE BLOCK]
GET /chat/file/:fileid
Pobiera załącznik.
[CODE BLOCK]
Wzorzec odpytywania
> [!TIP]
> Należy odpytywać co 30-60 sekund między wywołaniami narzędzi. Częstsze
> odpytywanie zużywa przydział API bez żadnych korzyści.
[CODE BLOCK]
Następne kroki
- Tasks API
- Wzorzec odpytywania czatu
────────────────────────────────────────────────────────────
# Computer Control API
SUMMARY: Zdalne sterowanie zarejestrowanymi komputerami — kolejkowanie poleceń, zrzuty ekranu, uruchamianie skryptów na maszynach zdalnych.
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 umożliwia zdalne sterowanie zarejestrowanymi komputerami.
Na maszynie docelowej działa niewielki agent (), który
odpytuje o polecenia, wykonuje je i odsyła wyniki. Umożliwia to automatyzację
GUI sterowaną przez LLM.
Architektura
[CODE BLOCK]
Endpointy użytkownika (Mind Key lub JWT)
GET /computers/list
Lista wszystkich zarejestrowanych komputerów.
[CODE BLOCK]
GET /computers/:id
Szczegóły pojedynczego komputera.
[CODE BLOCK]
POST /computers/install-code
Generuje kod instalacyjny do rejestracji nowego komputera.
[CODE BLOCK]
Odpowiedź:
POST /computers/:id/commands
Kolejkuje polecenie do wykonania przez agenta zdalnego.
[CODE BLOCK]
Odpowiedź:
GET /computers/:id/command (przez zapytanie)
Kolejkuje polecenie przez GET (dla prostych przypadków).
[CODE BLOCK]
GET /computers/:id/commands
Lista ostatnich poleceń dla komputera.
[CODE BLOCK]
GET /computers/:id/commands/:cid
Zwraca status i wynik konkretnego polecenia.
[CODE BLOCK]
GET /computers/:id/screenshot
Pojedyncze działanie: kolejkuje polecenie zrzutu ekranu i czeka do 30 s na wynik.
[CODE BLOCK]
POST /computers/:id/disable
Wyłącza komputer (cofa jego token, zachowuje rekord w celach audytowych).
[CODE BLOCK]
DELETE /computers/:id
Trwale usuwa komputer.
[CODE BLOCK]
Endpointy agenta (Computer Token)
Z tych endpointów korzysta uruchomiony na maszynie
docelowej. Używają Computer Token (zwracanego przez ), a nie
Mind Key.
POST /computers/register
Realizuje kod instalacyjny i zwraca Computer Token.
[CODE BLOCK]
Odpowiedź:
> [!CRITICAL]
> Należy zapisać — jest wyświetlany tylko raz i wymagany przez
> wszystkie endpointy po stronie agenta.
GET /computers/me/poll
Long-poll dla nowych poleceń. Agent wywołuje to w pętli.
[CODE BLOCK]
Powraca natychmiast, gdy są oczekujące polecenia, lub po sekundach, jeśli
ich nie ma.
POST /computers/me/commands/:cid/result
Publikuje wynik wykonania polecenia.
[CODE BLOCK]
Typy poleceń
| Typ | Payload | Opis |
|------|---------|------|
| | | Przechwyć ekran jako PNG (base64) |
| | | Kliknięcie we współrzędnych |
| | | Przesunięcie myszy we współrzędne |
| | | Wpisanie tekstu w pozycji kursora |
| | | Wciśnięcie kombinacji klawiszy |
| | | Przewinięcie kółkiem |
| | | Przeciągnięcie i upuszczenie |
Typowy wzorzec: automatyzacja GUI sterowana przez LLM
[CODE BLOCK]
Następne kroki
- Proxy przeglądarki — osobna usługa do automatyzacji przeglądarki
- Przewodnik po agentach self-hosted
────────────────────────────────────────────────────────────
# Cron i Scheduler
SUMMARY: Planowanie cyklicznych wywołań API — zadania cron uruchamiane wg harmonogramu, idealne do okresowej synchronizacji i przypomnień.
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 i Scheduler
Cron API umożliwia planowanie cyklicznych wywołań HTTP do endpointów Synapse
(lub zewnętrznych endpointów HTTPS). Idealne do okresowej synchronizacji,
przypomnień i zadań porządkowych.
Endpointy
POST /cron
Tworzy zaplanowane zadanie.
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
GET /cron
Lista wszystkich zaplanowanych zadań.
[CODE BLOCK]
DELETE /cron/:id
Usuwa zaplanowane zadanie.
[CODE BLOCK]
PUT /cron/:id/toggle
Włącza lub wyłącza zadanie bez jego usuwania.
[CODE BLOCK]
Składnia harmonogramu
Standardowy cron (5 pól)
[CODE BLOCK]
Przykłady:
| Harmonogram | Znaczenie |
|----------|---------|
| | Co godzinę |
| | Co 15 minut |
| | Dni robocze o 9:00 |
| | Co niedzielę o północy |
| | Pierwszego dnia każdego miesiąca o północy |
Przedział całkowitoliczbowy (sekundy)
Dla prostych interwałów należy podać liczbę całkowitą:
[CODE BLOCK]
Ograniczenia endpointów
> [!WARNING]
> Endpointy muszą być adresami URL lub wskazującymi na:
> - tę samą instancję Synapse (np. )
> - publiczne adresy URL HTTPS (bez prywatnych IP, bez localhost, bez IP metadanych)
Zabezpiecza to przed atakami SSRF, w których przejęty umysł mógłby planować
żądania do usług wewnętrznych.
Typowe wzorce
Godzinowe recall pamięci (dla agentów LLM)
[CODE BLOCK]
Codzienna kopia zapasowa
[CODE BLOCK]
Okresowe odpytywanie czatu (co 5 minut)
[CODE BLOCK]
Wyzwalacz raportu tygodniowego
[CODE BLOCK]
Następne kroki
- Variables API
- Webhooks API
────────────────────────────────────────────────────────────
# Błędy i ich obsługa
SUMMARY: Kody stanu HTTP, format odpowiedzi błędu i sposoby odzyskiwania po typowych błędach.
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.
Błędy i ich obsługa
Synapse używa standardowych kodów stanu HTTP wraz ze spójnym formatem odpowiedzi
błędu. Ta strona wyjaśnia, jak interpretować i obsługiwać błędy.
Format odpowiedzi błędu
Wszystkie błędy zwracają JSON o następującej strukturze:
[CODE BLOCK]
| Pole | Opis |
|-------|-------------|
| | Kod stanu HTTP |
| | Nazwa stanu HTTP |
| | Czytelny dla człowieka opis błędu |
| | URL do istotnej dokumentacji (gdy dostępny) |
Kody stanu HTTP
200 OK
Sukces. Żądanie zostało poprawnie przetworzone.
201 Created
Sukces. Utworzono nowy zasób (np. ).
204 No Content
Sukces. Brak treści w odpowiedzi (np. ).
400 Bad Request
Żądanie było nieprawidłowo sformułowane. Typowe przyczyny:
- Brak wymaganych pól JSON
- Nieprawidłowa składnia JSON
- Nieprawidłowa wartość enum (np. zła kategoria)
[CODE BLOCK]
Rozwiązanie: Należy sprawdzić treść żądania względem dokumentacji API i
upewnić się, że wszystkie wymagane pola są obecne i mają prawidłowe wartości.
401 Unauthorized
Autoryzacja nie powiodła się. Typowe przyczyny:
- Brak nagłówka
- Nieprawidłowy Mind Key lub JWT
- Użycie Mind Key tam, gdzie wymagany jest JWT (lub odwrotnie)
[CODE BLOCK]
Rozwiązanie: Zweryfikować token. Patrz Autoryzacja.
403 Forbidden
Użytkownik jest uwierzytelniony, ale nie może wykonać tej akcji. Typowe przyczyny:
- Próba usunięcia cudzego umysłu
- Próba weryfikacji pamięci przy użyciu Mind Key (wymagany JWT)
- Umysł jest wyłączony
Rozwiązanie: Należy sprawdzić, czy używa się poprawnego typu tokena dla tego
endpointu.
404 Not Found
Żądana ścieżka lub zasób nie istnieje.
> [!CRITICAL]
> Nie wolno zgadywać ścieżek endpointów. Istnieją tylko ścieżki wymienione
> w . W przypadku otrzymania 404 użyto błędnej ścieżki.
[CODE BLOCK]
Rozwiązanie: Wywołać , aby zobaczyć listę poprawnych
endpointów, i porównać swój URL z listą znak po znaku.
409 Conflict
Żądanie stoi w konflikcie z istniejącym stanem. Typowe przyczyny:
- Próba rejestracji z adresem e-mail, który już istnieje
- Duplikat URL webhooka
Rozwiązanie: Użyć innej wartości lub użyć , aby zaktualizować istniejący
zasób.
429 Too Many Requests
Osiągnięto limit żądań. Dotyczy tylko autoryzacji parametrem (60/min).
[CODE BLOCK]
Nagłówki odpowiedzi:
[CODE BLOCK]
Rozwiązanie: Przełączyć się na nagłówek (bez limitu)
lub odczekać sekund.
500 Internal Server Error
Błąd serwera. Nie powinien się zdarzyć — jeśli wystąpi, jest to błąd.
Rozwiązanie:
1. Ponowić z wykładniczym wycofywaniem (1 s, 2 s, 4 s, 8 s)
2. Sprawdzić , aby upewnić się, że serwer działa
3. Jeśli błąd utrzymuje się, zgłosić go
503 Service Unavailable
Serwer jest tymczasowo niedostępny (np. podczas wdrażania, migracji bazy danych).
Rozwiązanie: Odczekać i ponowić żądanie. Sprawdzić .
Wzorce odzyskiwania
Ponowienie z wykładniczym wycofywaniem
[CODE BLOCK]
Obsługa błędów autoryzacji
[CODE BLOCK]
Typowe scenariusze błędów
„Mind Key fehlt oder ungültig"
- Pominięto nagłówek
- Użyto , ale klucz jest błędny
- Użyto JWT tam, gdzie wymagany jest Mind Key
„Route not found"
- Zgadnięto ścieżkę, która nie istnieje
- Użyto nieprawidłowo czasownika (np. zamiast )
- Należy sprawdzić pod kątem poprawnych ścieżek
„Rate limit exceeded"
- Używane i przekroczono 60 żądań/min
- Należy przełączyć się na nagłówek
Następne kroki
- Autoryzacja
- Przegląd API
- Limity żądań
────────────────────────────────────────────────────────────
# Memory API
SUMMARY: Pełna dokumentacja 22 endpointów pamięci: zapis, recall, wyszukiwanie, wyszukiwanie semantyczne, synchronizacja, audyt i więcej.
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 stanowi serce Synapse. Zapewnia 22 endpointy do zapisywania,
pobierania, wyszukiwania i zarządzania ustrukturyzowanymi wspomnieniami. Wszystkie
endpointy wymagają Mind Key do autoryzacji.
> [!CRITICAL]
> Należy zawsze wywoływać na początku każdej sesji. To
> jedyny sposób odbudowy kontekstu z poprzednich sesji.
Kategorie
Wspomnienia są zorganizowane w 8 kategoriach:
| Kategoria | Przypadek użycia |
|----------|----------|
| | Imię użytkownika, rola, dane kontaktowe, preferencje dotyczące samego siebie |
| | Sympatie, antypatie, styl pracy, preferencje komunikacyjne |
| | Weryfikowalne fakty (szczegóły projektu, daty, URL-e) |
| | Status projektu, kamienie milowe, architektura |
| | Rzeczy, w których użytkownik jest dobry |
| | Błędy z przeszłości — unikać ich powtarzania |
| | Kontekst istotny dla sesji |
| | Różne notatki |
Priorytety
- — warto wiedzieć
- — domyślny
- — ważne
- — nigdy nie wolno zapominać (tożsamość użytkownika, informacje prawne)
Podstawowe endpointy
GET /memory/recall
Zwraca WSZYSTKIE wspomnienia jako zwykły tekst zoptymalizowany dla LLM. Należy
wywoływać na początku każdej sesji.
[CODE BLOCK]
Odpowiedź (text/plain):
[CODE BLOCK]
POST /memory
Zapisuje nowe wspomnienie lub aktualizuje istniejące (ta sama kategoria + klucz
= aktualizacja).
[CODE BLOCK]
Odpowiedź:
GET /memory
Lista wspomnień z opcjonalnymi filtrami.
[CODE BLOCK]
PUT /memory/:id
Aktualizuje konkretne wspomnienie po ID.
[CODE BLOCK]
DELETE /memory/:id
Usuwa pojedyncze wspomnienie.
[CODE BLOCK]
Endpointy wyszukiwania
GET /memory/search
Wyszukiwanie pełnotekstowe z użyciem FTS5.
[CODE BLOCK]
Składnia FTS5:
- Wiele słów = AND:
- Fraza:
- Prefiks:
- Wartość logiczna:
- Wykluczenie:
GET /memory/semantic-search
Wyszukiwanie semantyczne z użyciem osadzeń (wolniejsze niż FTS5, ale rozumie znaczenie).
[CODE BLOCK]
Zwraca wspomnienia semantycznie podobne do zapytania, nawet jeśli nie ma dopasowań
słów kluczowych. Przydatne do „znajdź wspomnienia o X", gdy X jest opisane inaczej.
GET /memory/by-tag
Lista wspomnień wg tagu.
[CODE BLOCK]
GET /memory/related/:id
Znajduje wspomnienia powiązane z konkretnym (przez wspólne tagi).
[CODE BLOCK]
Synchronizacja i diff
GET /memory/diff
Synchronizacja przyrostowa — zwraca wspomnienia zmienione od podanego
znacznika czasu.
[CODE BLOCK]
Odpowiedź:
POST /memory/sync
Stosuje diff z innej instancji (do synchronizacji self-hosted).
[CODE BLOCK]
Operacje masowe
POST /memory/bulk-delete
Usuwa wiele wspomnień po ID.
[CODE BLOCK]
POST /memory/embed-batch
Generuje osadzenia dla wspomnień, które ich jeszcze nie mają (do wyszukiwania
semantycznego).
[CODE BLOCK]
GET /memory/embed-batch-status
Sprawdza postęp generowania osadzeń.
[CODE BLOCK]
Weryfikacja
Wspomnienia mają flagę . Wspomnienia zapisane przez agenta są domyślnie
niezweryfikowane (); zapisane przez człowieka są zweryfikowane
().
POST /memory/verify
Oznacza wspomnienie jako zweryfikowane (wymaga JWT, nie Mind Key).
[CODE BLOCK]
POST /memory/unverify
Oznacza wspomnienie jako niezweryfikowane (wymaga JWT).
[CODE BLOCK]
GET /memory/unverified
Lista wspomnień oczekujących na weryfikację przez człowieka.
[CODE BLOCK]
Statystyki i audyt
GET /memory/stats
Statystyki agregowane dla bieżącego umysłu.
[CODE BLOCK]
Zwraca:
GET /memory/audit
Dziennik audytu wszystkich operacji zmieniających stan.
[CODE BLOCK]
GET /memory/contradictions
Wykrywa potencjalne sprzeczności w zapisanych wspomnieniach.
[CODE BLOCK]
GET /memory/expiring
Lista wspomnień z zbliżającą się datą wygaśnięcia.
[CODE BLOCK]
Kondycja i eksport
GET /memory/health
Szybkie sprawdzenie kondycji systemu pamięci.
[CODE BLOCK]
GET /memory/mind-export
Pełny eksport JSON wszystkich wspomnień (do kopii zapasowej).
[CODE BLOCK]
POST /memory/compact
Kompaktuje podobne wspomnienia (automatyczne streszczanie).
[CODE BLOCK]
Następne kroki
- Szybki start dla LLM
- Najlepsze praktyki pamięci
- Wyszukiwanie FTS5
- Wyszzukiwanie semantyczne
────────────────────────────────────────────────────────────
# Przegląd API i bazowy URL
SUMMARY: Wszystkie endpointy API Synapse, bazowy URL, wzorce autoryzacji i formaty odpowiedzi w jednym miejscu.
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.
Przegląd API i bazowy URL
API Synapse jest RESTfulowym interfejsem HTTP. Wszystkie endpointy zwracają JSON
(z wyjątkiem miejsc, w których zaznaczono inaczej). Niniejsza strona zawiera
podstawowe informacje potrzebne przed przejściem do szczegółowych endpointów.
Bazowy URL
[CODE BLOCK]
Wszystkie ścieżki w niniejszej dokumentacji są względne wobec tego bazowego URL-a.
W przypadku instancji self-hosted należy użyć własnego adresu URL.
Autoryzacja
Dwie metody, obie wysyłane nagłówkiem :
[CODE BLOCK]
Lub przez parametr zapytania (ograniczony do 60/min):
[CODE BLOCK]
Szczegóły znajdują się w sekcji Autoryzacja.
Grupy endpointów
| Grupa | Autoryzacja | Opis |
|-------|-------------|------|
| Publiczne | Brak | Strona główna, health, OpenAPI, dokumentacja |
| Memory | Mind Key | CRUD, wyszukiwanie, synchronizacja, osadzenia |
| Chat | Mind Key / JWT | Asynchroniczne wiadomości między człowiekiem a agentem |
| Tasks | Mind Key | Zarządzanie zadaniami |
| Scripts | Mind Key / JWT | Trwały magazyn skryptów |
| Scheduler | Mind Key | Zadania cron i zmienne |
| Webhooks | Mind Key | Wywołania zwrotne HTTP przy zdarzeniach |
| Computers | Mind Key / JWT | Zdalne sterowanie komputerami |
| User/Minds | JWT | Konto i zarządzanie umysłami |
| Sharing | JWT | Współdzielenie umysłów między użytkownikami |
| Push | JWT | Subskrypcje Web Push |
| Tools | Brak | Czas, kalkulator, losowość (narzędzia publiczne) |
Formaty odpowiedzi
- JSON (domyślnie):
- Zwykły tekst: zwraca tekst zoptymalizowany dla LLM
- HTML: , , , ,
Standardowa koperta odpowiedzi
Odpowiedzi pomyślne zwracają dane bezpośrednio:
[CODE BLOCK]
Odpowiedzi błędne używają następującego formatu:
[CODE BLOCK]
> [!NOTE]
> Pole zawiera link do dokumentacji istotnej dla częstych błędów.
Kody stanu HTTP
| Kod | Znaczenie |
|------|-----------|
| 200 | Sukces (GET, PUT) |
| 201 | Utworzono (POST) |
| 204 | Brak treści (DELETE) |
| 400 | Nieprawidłowe żądanie (błąd walidacji) |
| 401 | Brak autoryzacji (brak/nieprawidłowy token) |
| 403 | Zabronione (nieprawidłowy typ tokena) |
| 404 | Nie znaleziono (ścieżka nie istnieje) |
| 409 | Konflikt (duplikat) |
| 429 | Zbyt wiele żądań (limit) |
| 500 | Błąd serwera |
Endpointy wykrywalności
| Endpoint | Przeznaczenie |
|----------|---------------|
| | Strona główna (zoptymalizowana dla LLM) |
| | Czytelna maszynowo lista wszystkich endpointów |
| | Lista endpointów w postaci zwykłego tekstu |
| | Specyfikacja OpenAPI 3.0 |
| | Pełna dokumentacja API (HTML) |
| | Dokumentacja API jako JSON |
| | System dokumentacji (HTML) |
| | Indeks dokumentacji (JSON) |
| | Cała dokumentacja jako jeden blok tekstowy |
| | Interaktywny playground API |
Limity żądań
| Metoda autoryzacji | Limit |
|-------------|-------|
| Mind Key (nagłówek) | Brak |
| Mind Key (?key=) | 60/min na IP |
| JWT (nagłówek) | Brak |
| Endpointy publiczne | Brak |
Odpowiedzi objęte limitem zawierają:
[CODE BLOCK]
Paginacja
Endpointy list obsługują oraz :
[CODE BLOCK]
Domyślny limit: 100. Maksymalny limit: 500.
CORS
Wszystkie endpointy obsługują CORS dla klientów opartych na przeglądarce:
[CODE BLOCK]
SDK i klienci
- Node.js SDK: (repozytorium)
- MCP Server: (repozytorium)
- Klient HTTP: dowolna biblioteka HTTP (curl, fetch, axios itp.)
Następne kroki
- Memory API — najważniejsze endpointy
- Chat API — asynchroniczna komunikacja człowiek-agent
- Błędy i ich obsługa
────────────────────────────────────────────────────────────
# Limity żądań i przydziały
SUMMARY: Polityka limitów żądań dla API Synapse — nagłówek Bearer (bez limitu), ?key= (60/min), endpointy publiczne.
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.
Limity żądań i przydziały
Synapse posiada prostą i przewidywalną politykę limitów żądań, zaprojektowaną w
celu zapobiegania nadużyciom, nie blokując jednocześnie prawidłowego użytku.
Polityka limitów żądań
| Metoda autoryzacji | Limit | Zakres |
|-------------|-------|-------|
| Mind Key () | Brak | Na umysł |
| Mind Key () | 60 żądań/min | Na IP |
| JWT () | Brak | Na użytkownika |
| Endpointy publiczne | Brak | Globalny |
> [!TIP]
> Należy zawsze używać nagłówka , gdy to możliwe. Nie
> ma on limitu żądań. należy stosować tylko w narzędziach, które nie
> potrafią ustawiać własnych nagłówków.
Nagłówki limitu żądań
Gdy używana jest autoryzacja , odpowiedzi zawierają nagłówki limitu:
[CODE BLOCK]
Po przekroczeniu limitu:
[CODE BLOCK]
Po osiągnięciu limitu żądań
W przypadku otrzymania 429:
1. Przełączyć się na nagłówek Authorization (zalecane):
[CODE BLOCK]
2. Lub odczekać sekund i ponowić żądanie.
Dlaczego istnieje limit dla
Parametr zapytania jest wygodny dla narzędzi opartych wyłącznie na URL
(przeglądarki, polecenia ), ale niesie ze sobą implikacje bezpieczeństwa i
wydajności:
- Bezpieczeństwo: Parametry zapytania są rejestrowane w logach dostępu
serwera, historii przeglądarki i nagłówkach Referer. Ograniczenie użycia
zmniejsza ekspozycję.
- Wydajność: Autoryzacja parametrem zapytania wymaga ogranicznika opartego na
IP (odpytanie Redis przy każdym żądaniu), co dodaje opóźnienie. Autoryzacja
nagłówkiem pomija ten krok.
- Zapobieganie nadużyciom: Wyciekły URL mógłby zostać udostępniony i
masowo wywoływany. Limit IP ogranicza obszar rażenia.
Zalecane wzorce
Agenci LLM
[CODE BLOCK]
Narzędzia oparte na przeglądarce
Jeśli narzędzie potrafi tylko otwierać URL-e:
[CODE BLOCK]
Serwer MCP
Serwery MCP zawsze korzystają z autoryzacji nagłówkiem przez zmienną środowiskową
— limit nie ma zastosowania.
Importy masowe
W przypadku operacji masowych (np. import 1000 wspomnień) zawsze należy używać
autoryzacji nagłówkiem. Importy przez osiągną limit w ciągu minuty.
Przydziały (poziom umysłu)
Obecnie nie ma przydziałów na poziomie umysłu dotyczących rozmiaru pamięci lub
liczby wspomnień. Wszystkie limity znajdują się na poziomie autoryzacji/IP, a nie
danych. Może się to zmienić w przyszłości w celu sprawiedliwego współdzielenia
w środowisku wielodostępnym.
Monitorowanie użycia
[CODE BLOCK]
Następne kroki
- Autoryzacja
- Błędy i ich obsługa
────────────────────────────────────────────────────────────
# Scripts API
SUMMARY: Trwały magazyn skryptów — zapisuj wielokrotnego użytku skrypty shell, Python lub Node i pobieraj je przez 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 zapewnia trwały magazyn dla skryptów wielokrotnego użytku. Skrypty są
nazywane i wersjonowane w obrębie umysłu oraz mogą być pobierane jako zwykły
tekst — idealne dla wzorców .
Endpointy
POST /script
Zapisuje lub aktualizuje skrypt.
[CODE BLOCK]
GET /script/:name
Pobiera treść skryptu jako . Idealne do potokowania do basha.
[CODE BLOCK]
GET /script/:name/info
Zwraca metadane skryptu bez treści.
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
GET /scripts
Lista wszystkich skryptów w bieżącym umyśle.
[CODE BLOCK]
DELETE /script/:name
Usuwa skrypt.
[CODE BLOCK]
Typowe przypadki użycia
Skrypty wdrożeniowe
Zapisuje standardowe procedury wdrożeniowe, aby LLM mógł je uruchomić bez
ponownego wyprowadzania kroków za każdym razem:
[CODE BLOCK]
Snippety diagnostyczne
Zapisuje polecenia diagnostyczne dla częstych problemów:
[CODE BLOCK]
Generatory konfiguracji
Zapisuje skrypty generujące konfiguracje:
[CODE BLOCK]
Następne kroki
- Variables API
- Cron i Scheduler
────────────────────────────────────────────────────────────
# Tasks API
SUMMARY: Zarządzanie zadaniami dla agentów LLM — tworzenie, lista, aktualizacja, ukończenie, usuwanie zadań z priorytetami.
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 zapewnia agentom LLM ustrukturyzowany sposób śledzenia wieloetapowych
prac. Zadania są ograniczone do bieżącego umysłu i utrzymują się między sesjami,
dzięki czemu agent może wznowić pracę tam, gdzie ją przerwał.
Endpointy
GET /mind/tasks
Lista wszystkich zadań dla bieżącego umysłu.
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
POST /mind/task
Tworzy nowe zadanie.
[CODE BLOCK]
GET /mind/task (parametry zapytania)
Tworzy zadanie przez GET (dla narzędzi obsługujących tylko URL-e).
[CODE BLOCK]
PUT /mind/task/:id
Aktualizuje istniejące zadanie.
[CODE BLOCK]
GET /mind/task/:id/complete
Oznacza zadanie jako ukończone.
[CODE BLOCK]
GET /mind/task/:id/delete
Trwale usuwa zadanie.
[CODE BLOCK]
Priorytety
- — nienaglące
- — domyślny
- — ważne
- — zrobić natychmiast
Statusy
- — utworzone, nierozpoczęte
- — obecnie realizowane
- — ukończone
- — porzucone
Wzorzec: przepływ oparty na zadaniach
[CODE BLOCK]
Następne kroki
- Przepływ oparty na zadaniach
- Cron i Scheduler
────────────────────────────────────────────────────────────
# Narzędzia pomocnicze (czas, kalkulator, losowość)
SUMMARY: Publiczne endpointy narzędziowe — czas serwera, bezpieczny kalkulator, generator wartości losowych. Bez autoryzacji.
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.
Narzędzia pomocnicze
Endpointy to publiczne narzędzia — nie wymagają autoryzacji. Są
przydatne dla agentów LLM, które potrzebują czasu po stronie serwera,
bezpiecznych obliczeń matematycznych lub wartości losowych.
GET /tools/time
Zwraca aktualny czas serwera, strefę czasową i przesunięcie UTC.
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
Przypadek użycia: agenty LLM, które muszą wiedzieć „która jest teraz godzina" do
planowania, znaczników czasu lub obliczeń dat względnych.
GET /tools/calc
Bezpieczny kalkulator — wyłącznie arytmetyka, bez . Obsługuje , ,
, , , , oraz liczby.
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
> [!TIP]
> Należy używać tego zamiast liczenia w pamięci lub parsowania ciągów. Jest
> bezpieczne (bez możliwości wstrzykiwania kodu) i dokładne.
Obsługiwane operatory
- dodawanie
- odejmowanie
- mnożenie
- dzielenie
- modulo
- nawiasy
- Liczby (całkowite i dziesiętne)
Przykłady
[CODE BLOCK]
GET /tools/random
Generuje wartości losowe.
[CODE BLOCK]
Parametry typu
| Typ | Parametry | Wynik |
|------|-----------|--------|
| | brak | Ciąg UUID v4 |
| | , (domyślnie 0-100) | Liczba całkowita |
| | , (domyślnie 0-100) | Liczba zmiennoprzecinkowa |
| | , (zakres długości, domyślnie 8-16) | Ciąg szesnastkowy |
| | , (zakres długości, domyślnie 8-16) | Ciąg alfabetyczny |
Przypadki użycia dla agentów LLM
Generowanie unikalnych ID
[CODE BLOCK]
Obliczanie procentów
[CODE BLOCK]
Pobieranie aktualnego znacznika czasu
[CODE BLOCK]
Generowanie danych testowych
[CODE BLOCK]
Następne kroki
- Przegląd API — wszystkie grupy endpointów
- Błędy i ich obsługa
────────────────────────────────────────────────────────────
# User & Minds API
SUMMARY: Zarządzanie kontem — rejestracja, logowanie, tworzenie umysłów, lista umysłów, usuwanie umysłów. Chronione 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 obsługuje zarządzanie kontem. Te endpointy używają
autoryzacji JWT (nie Mind Key), ponieważ operują na poziomie konta, a nie umysłu.
Endpointy autoryzacji
POST /register
Tworzy nowe konto użytkownika.
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
POST /login
Logowanie do istniejącego konta.
[CODE BLOCK]
Odpowiedź: taka sama jak dla .
Endpointy umysłów
POST /minds
Tworzy nowy umysł. Zwraca Mind Key — należy go natychmiast zapisać, jest
wyświetlany tylko raz.
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
> [!CRITICAL]
> jest wyświetlany tylko raz. W przypadku jego utraty nie można go
> odzyskać — należy usunąć umysł i utworzyć nowy (co powoduje utratę wszystkich
> zapisanych wspomnień).
GET /minds
Lista wszystkich umysłów bieżącego użytkownika.
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
DELETE /minds/:id
Trwale usuwa umysł.
[CODE BLOCK]
> [!WARNING]
> Usunięcie umysłu jest nieodwracalne. Wszystkie wspomnienia, zadania,
> historia czatu i skrypty w tym umyśle zostają trwale utracone. Należy najpierw
> wykonać eksport przez , jeśli kopia zapasowa jest
> potrzebna.
Wzorzec wielu umysłów
Większości użytkowników pomaga posiadanie wielu umysłów, aby utrzymać konteksty
oddzielone:
[CODE BLOCK]
Należy używać różnych Mind Key w różnych sesjach LLM, aby utrzymać konteksty
oddzielone.
Bezpieczeństwo konta
Wymagania dotyczące hasła
- Minimum 6 znaków
- Brak maksimum (zaleca się menedżer haseł)
- Przechowywane jako hasz bcrypt (nigdy w postaci jawnej)
Wygasanie JWT
JWT wygasają po 7 dniach. Po wygaśnięciu należy ponownie wywołać .
Bezpieczeństwo Mind Key
Mind Key nigdy nie wygasa. W przypadku skompromitowania Mind Key:
1. Utworzyć nowy umysł przez
2. Zaktualizować konfigurację LLM o nowy Mind Key
3. Usunąć skompromitowany umysł przez
Następne kroki
- Autoryzacja — pełny przewodnik autoryzacji
- Mind Key vs JWT — przewodnik decyzyjny
- Sharing API — współdzielenie umysłów z innymi użytkownikami
────────────────────────────────────────────────────────────
# Variables API
SUMMARY: Szybki magazyn klucz-wartość dla stanu LLM — liczniki, flagi, znaczniki ostatniego wyświetlenia, częściowe postępy.
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 jest szybkim magazynem klucz-wartość dla stanu efemerycznego. W
przeciwieństwie do wspomnień (które są indeksowane, przeszukiwalne i
ustrukturyzowane), zmienne są zoptymalizowane pod kątem szybkiego odczytu i
zapisu — idealne dla liczników, flag i stanu sesji.
Endpointy
POST /var
Ustawia lub aktualizuje zmienną.
[CODE BLOCK]
GET /var/:key
Pobiera pojedynczą zmienną.
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
GET /var
Lista wszystkich zmiennych.
[CODE BLOCK]
DELETE /var/:key
Usuwa zmienną.
[CODE BLOCK]
Kiedy używać zmiennych, a kiedy pamięci
| Przypadek użycia | Wybór |
|----------|-----|
| Imię użytkownika, preferencje | Pamięć (przeszukiwalne, ustrukturyzowane) |
| Znacznik czasu ostatniej sesji | Zmienna (stan efemeryczny) |
| Licznik (np. wysłane wiadomości) | Zmienna (częste aktualizacje) |
| Stan przepływu pracy („krok 3 z 5 ukończony") | Zmienna (przejściowy) |
| Długie notatki projektowe | Pamięć (indeksowane pełnotekstowo) |
| Skrypty wielokrotnego użytku | Magazyn skryptów (nazywane, wersjonowane) |
Typowe wzorce
Śledzenie ostatniej sesji
[CODE BLOCK]
Wzorzec licznika
[CODE BLOCK]
Flagi funkcji
[CODE BLOCK]
Następne kroki
- Memory API — dla ustrukturyzowanych, przeszukiwalnych danych
- Cron i Scheduler
────────────────────────────────────────────────────────────
# Webhooks API
SUMMARY: Rejestrowanie wywołań zwrotnych HTTP dla zdarzeń pamięci, czatu i zadań — powiadomienia o zmianach danych.
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
Webhooki pozwalają otrzymywać wywołania zwrotne HTTP, gdy w Synapse mają miejsce
zdarzenia. Idealne do wyzwalania zewnętrznej automatyzacji, wysyłania powiadomień
lub synchronizacji z innymi systemami.
Endpointy
POST /webhooks
Rejestruje nowy webhook.
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
GET /webhooks
Lista wszystkich webhooków dla bieżącego umysłu.
[CODE BLOCK]
GET /webhooks/:id
Zwraca pojedynczy webhook.
[CODE BLOCK]
PUT /webhooks/:id
Aktualizuje webhook (URL, zdarzenia, sekret lub flagę enabled).
[CODE BLOCK]
DELETE /webhooks/:id
Usuwa webhook.
[CODE BLOCK]
Typy zdarzeń
| Wzorzec | Uruchamiane, gdy |
|---------|------------|
| | Dowolne zdarzenie pamięci |
| | Zapisano nowe wspomnienie |
| | Zaktualizowano wspomnienie |
| | Usunięto wspomnienie |
| | Dowolne zdarzenie czatu |
| | Nowa wiadomość od człowieka |
| | Dowolne zdarzenie zadania |
| | Utworzono nowe zadanie |
| | Zadanie oznaczono jako ukończone |
| | Wszystkie zdarzenia |
Payload webhooka
Gdy wystąpi zdarzenie, Synapse wysyła POST pod podany URL:
[CODE BLOCK]
Weryfikacja podpisu
Jeśli ustawiono , Synapse podpisuje każdy payload algorytmem HMAC-SHA256:
[CODE BLOCK]
Weryfikacja w obsłudze:
[CODE BLOCK]
Wzorzec: synchronizacja w czasie rzeczywistym
[CODE BLOCK]
Następne kroki
- Cron i Scheduler
- Przewodnik automatyzacji webhookami
## KATEGORIA: INTEGRACJA MCP
Integracja z Claude, Cursor i innymi klientami MCP.
────────────────────────────────────────────────────────────
# MCP w Claude Code
SUMMARY: Używanie narzędzi Synapse z agenta terminalowego Claude Code — trwała pamięć dla sesji kodowania.
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 w Claude Code
Claude Code to terminalowy agent kodowania od Anthropic. Dzięki Synapse MCP
Claude Code zyskuje trwałą pamięć między sesjami kodowania — pamięta kontekst
projektu, przeszłe decyzje i wzorce w bazie kodu.
Konfiguracja
Metoda 1: polecenie CLI (zalecane)
[CODE BLOCK]
Metoda 2: edycja pliku konfiguracyjnego
Edytować :
[CODE BLOCK]
Weryfikacja działania
Uruchomić Claude Code:
[CODE BLOCK]
W promptcie Claude Code wpisać:
[CODE BLOCK]
Claude powinien wywołać i odpowiedzieć zapisanymi wspomnieniami.
Typowe wzorce
Trwałość kontekstu projektu
Na początku sesji kodowania:
[CODE BLOCK]
Claude wywołuje , widzi listę projektów i kontynuuje pracę tam,
gdzie ją przerwano.
Decyzje w bazie kodu
Gdy podejmowana jest decyzja architektoniczna:
[CODE BLOCK]
Claude wywołuje z kategorią , priorytetem .
Unikanie przeszłych błędów
[CODE BLOCK]
Claude wyszukuje wspomnienia z kategorią i przypomina przeszłe błędy.
Śledzenie zadań
[CODE BLOCK]
Claude wywołuje , a zadanie utrzymuje się między sesjami.
Profile narzędzi
Dla sesji kodowania, gdy nie potrzeba wszystkich 119 narzędzi:
[CODE BLOCK]
Rozwiązywanie problemów
Serwer MCP się nie uruchamia
[CODE BLOCK]
Mind Key nierozpoznany
[CODE BLOCK]
Claude Code nie widzi narzędzi
- Zrestartować Claude Code po zmianach konfiguracji
- Sprawdzić , aby zweryfikować rejestrację Synapse
- Patrz Rozwiązywanie problemów MCP
Następne kroki
- Konfiguracja Claude Desktop
- Konfiguracja Cursor
- Przewodnik trwałego agenta LLM
────────────────────────────────────────────────────────────
# MCP w Claude Desktop
SUMMARY: Podłączenie Synapse do Claude Desktop w 2 minuty. Claude zyskuje 79 narzędzi Synapse natywnie.
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 w Claude Desktop
Claude Desktop to aplikacja biurkowa Anthropic dla macOS i Windows. Po
skonfigurowaniu serwera Synapse MCP Claude zyskuje natywny dostęp do wszystkich
79 narzędzi Synapse — może zapisywać wspomnienia, przypominać je, zarządzać
zadaniami, czatować i więcej.
Wymagania wstępne
- Aplikacja Claude Desktop (macOS lub Windows)
- Node.js 18+ zainstalowany ()
- Twój Mind Key Synapse
Krok 1: otwarcie pliku konfiguracyjnego
- macOS:
- Windows:
Jeśli plik nie istnieje, utworzyć go.
Krok 2: dodanie serwera Synapse MCP
[CODE BLOCK]
> [!TIP]
> Jeśli skonfigurowano już inne serwery MCP, wystarczy dodać blok
> wewnątrz istniejącego obiektu .
Krok 3: restart Claude Desktop
1. W pełni zamknąć Claude Desktop (Cmd+Q na macOS, nie tylko zamknąć okno)
2. Ponownie otworzyć Claude Desktop
3. Rozpocząć nowy czat
4. Poszukać ikony wtyczki 🔌 w lewym dolnym rogu — powinna wskazywać „79 tools"
Krok 4: test
W nowym czacie wpisać:
[CODE BLOCK]
Claude powinien wywołać narzędzie i odpowiedzieć z podsumowaniem
zapisanych wspomnień (lub „No memories yet", jeśli umysł jest pusty).
Dostępne narzędzia (wybór)
| Narzędzie | Opis |
|------|-------------|
| | Przypomnienie wszystkich wspomnień |
| | Zapis nowego wspomnienia |
| | Wyszukiwanie wspomnień |
| | Lista zadań |
| | Utworzenie zadania |
| | Sprawdzenie nowych wiadomości |
| | Odpowiedź na wiadomość |
| | Otwarcie karty przeglądarki |
| | Lista zarejestrowanych komputerów |
Pełna lista: Czym jest MCP?
Rozwiązywanie problemów
Brak narzędzi w Claude Desktop
1. Zweryfikować wersję Node.js: (musi być ≥ 18)
2. Sprawdzić, czy plik konfiguracyjny jest poprawnym JSON-em (bez końcowych przecinków)
3. W pełni zrestartować Claude Desktop (Cmd+Q, nie tylko zamknąć)
4. Sprawdzić logi Claude Desktop: (macOS)
Błąd „Mind Key invalid"
- Zweryfikować, że zaczyna się od
- Uzyskać nowy klucz przez (wymaga JWT z )
- Brak cudzysłowów wokół klucza w JSON
npx nie znalezione
- Zainstalować Node.js 18+:
- Zrestartować terminal po instalacji
- Na macOS z Homebrew:
Narzędzia się wyświetlają, ale wywołania zawodzą
- Sprawdzić, czy jest osiągalny:
- Zweryfikować działanie Mind Key:
- Patrz Rozwiązywanie problemów MCP
Profile narzędzi (oszczędność tokenów)
Jeśli używany jest mniejszy LLM lub zachodzi potrzeba oszczędności tokenów
kontekstu, ustawić profil narzędzi:
[CODE BLOCK]
Profile: (8 narzędzi), (25), (119, domyślnie).
Następne kroki
- Konfiguracja Claude Code
- Konfiguracja Cursor
- Rozwiązywanie problemów MCP
────────────────────────────────────────────────────────────
# MCP w Continue.dev
SUMMARY: Podłączenie Synapse do Continue.dev — open-source'owego asystenta kodowania AI dla VS Code i JetBrains.
MCP w Continue.dev
Continue.dev to open-source'owy asystent kodowania AI dla VS Code i środowisk
JetBrains. Dzięki Synapse MCP Continue zyskuje trwałą pamięć między sesjami.
Wymagania wstępne
- VS Code lub IDE JetBrains
- Zainstalowane rozszerzenie Continue.dev
- Node.js 18+
- Twój Mind Key Synapse
Konfiguracja
Krok 1: otwarcie konfiguracji Continue
W VS Code lub JetBrains:
1. Otworzyć pasek boczny rozszerzenia Continue
2. Kliknąć ikonę koła zębatego → „Open config.json"
Lub edytować bezpośrednio .
Krok 2: dodanie serwera Synapse MCP
[CODE BLOCK]
Krok 3: przeładowanie Continue
Przeładować okno VS Code (Cmd+Shift+P → „Reload Window") lub zrestartować IDE.
Weryfikacja działania
W czacie Continue:
[CODE BLOCK]
Continue powinien wywołać i odpowiedzieć zapisanymi wspomnieniami.
Typowe wzorce
Kontekst projektu
[CODE BLOCK]
Continue wywołuje , widzi wspomnienia projektu i kontynuuje pracę
tam, gdzie ją przerwano.
Wzorce przeglądu kodu
[CODE BLOCK]
Continue znajduje zapisane wzorce przeglądu kodu i je stosuje.
Pamięć programowania w parze
[CODE BLOCK]
Continue zapisuje to jako wspomnienie .
Rozwiązywanie problemów
Serwer MCP się nie łączy
1. Sprawdzić, czy jest poprawnym JSON-em
2. Zweryfikować Node.js:
3. Sprawdzić panel wyjścia Continue (View → Output → Continue)
4. Zrestartować IDE
Narzędzia się nie pojawiają
- Zweryfikować, że wersja Continue obsługuje MCP (≥ 0.9.x)
- Sprawdzić, czy zmienna środowiskowa jest ustawiona w konfiguracji
- Poszukać błędów MCP w logach Continue
Następne kroki
- Konfiguracja Claude Desktop
- Niestandardowy klient MCP
────────────────────────────────────────────────────────────
# MCP w Cursor
SUMMARY: Podłączenie Synapse do IDE Cursor dla trwałej pamięci projektu między sesjami kodowania.
MCP w Cursor
Cursor to IDE oparte na sztucznej inteligencji, bazujące na VS Code. Dzięki
Synapse MCP Cursor zyskuje trwałą pamięć między sesjami — pamięta decyzje
projektowe, wzorce bazy kodu i przeszłe sesje debugowania.
Wymagania wstępne
- Zainstalowane IDE Cursor ()
- Node.js 18+
- Twój Mind Key Synapse
Konfiguracja
Krok 1: otwarcie ustawień Cursor
W Cursor:
1. Otworzyć Settings (Cmd+, na macOS, Ctrl+, na Windows/Linux)
2. Wyszukać „MCP" lub przejść do
Krok 2: dodanie serwera Synapse MCP
Kliknąć „Add MCP Server" i skonfigurować:
| Pole | Wartość |
|-------|-------|
| Name | |
| Type | |
| Command | |
| Env | |
Krok 3: edycja config.json bezpośrednio (alternatywa)
Cursor przechowuje konfigurację MCP w :
[CODE BLOCK]
Krok 4: restart Cursor
W pełni zrestartować Cursor (Cmd+Q i ponownie otworzyć na macOS).
Weryfikacja działania
W panelu czatu Cursor (Cmd+L):
[CODE BLOCK]
Cursor powinien wywołać i odpowiedzieć zapisanymi wspomnieniami.
Typowe wzorce
Onboarding projektu
Podczas otwierania nowego projektu:
[CODE BLOCK]
Cursor wywołuje i kontynuuje pracę tam, gdzie ją przerwano.
Decyzje architektoniczne
[CODE BLOCK]
Cursor zapisuje to jako wspomnienie z priorytetem .
Historia debugowania
[CODE BLOCK]
Cursor wyszukuje wspomnienia i przypomina przeszłe poprawki.
Wzorce kodu między sesjami
[CODE BLOCK]
Cursor znajduje wspomnienia o implementacjach autoryzacji, które wcześniej
wykonano.
Rozwiązywanie problemów
Serwer MCP się nie łączy
1. Zweryfikować Node.js: (≥ 18)
2. Przetestować serwer MCP: (powinien wystartować bez błędów)
3. Sprawdzić logi MCP Cursor (View → Output → MCP)
4. W pełni zrestartować Cursor
Narzędzia się nie pojawiają
- Sprawdzić, czy jest poprawnym JSON-em
- Zweryfikować, że zmienna środowiskowa jest ustawiona
- Sprawdzić, czy wersja Cursor obsługuje MCP (≥ 0.42)
Mind Key nieprawidłowy
[CODE BLOCK]
Następne kroki
- Konfiguracja Claude Desktop
- Konfiguracja Continue.dev
- Przewodnik trwałego agenta LLM
────────────────────────────────────────────────────────────
# Budowa niestandardowego klienta MCP
SUMMARY: Połączenie z serwerem Synapse MCP z własnej aplikacji przy użyciu SDK MCP.
Budowa niestandardowego klienta MCP
Jeśli buduje się własną aplikację LLM, można połączyć się z serwerem Synapse MCP
bezpośrednio, używając oficjalnego SDK MCP. Daje to aplikacji dostęp do wszystkich
79 narzędzi Synapse.
SDK
| Język | Pakiet |
|----------|---------|
| TypeScript/JavaScript | |
| Python | |
Przykład w TypeScript
Instalacja
[CODE BLOCK]
Połączenie przez stdio
[CODE BLOCK]
Połączenie przez HTTP/SSE (zdalne)
[CODE BLOCK]
Przykład w Pythonie
Instalacja
[CODE BLOCK]
Połączenie przez stdio
[CODE BLOCK]
Profile narzędzi
Podczas łączenia można zażądać konkretnego profilu narzędzi przez nagłówek
(HTTP/SSE) lub zmienną środowiskową (stdio):
[CODE BLOCK]
Obsługa błędów
[CODE BLOCK]
Przypadki użycia
- Niestandardowi asystenci AI — budowa własnego agenta z trwałą pamięcią
- Automatyzacja przepływu pracy — łańcuch narzędzi Synapse w własnych przepływach
- Potoki danych — ekstrakcja wspomnień, transformacja, ładowanie gdzie indziej
- Panele monitoringu — wyświetlanie statystyk pamięci, historii czatu, zadań
Następne kroki
- Specyfikacja MCP
- Repozytorium Synapse MCP
- Przegląd API
────────────────────────────────────────────────────────────
# Rozwiązywanie problemów MCP
SUMMARY: Rozwiązania częstych problemów integracji MCP — serwer się nie uruchamia, narzędzia się nie pojawiają, błędy autoryzacji.
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/
Rozwiązywanie problemów MCP
Częste problemy i rozwiązania przy integracji Synapse MCP z klientem LLM.
Szybka lista kontrolna diagnostyki
1. ✅ Node.js 18+ zainstalowany? ()
2. ✅ Mind Key zaczyna się od ? (nie JWT )
3. ✅ API Synapse osiągalne? ()
4. ✅ Mind Key działa? ()
5. ✅ Plik konfiguracyjny jest poprawnym JSON-em? (bez końcowych przecinków, bez komentarzy)
6. ✅ Klient zrestartowany po zmianie konfiguracji?
7. ✅ Serwer MCP uruchamia się ręcznie? ()
Problem: brak narzędzi w kliencie
Symptomy
- Claude Desktop / Cursor / Continue pokazuje 0 narzędzi
- Brak ikony 🔌 lub wpisu „synapse" w liście serwerów MCP
Rozwiązania
1. W pełni zrestartować klienta — Cmd+Q na macOS (nie tylko zamknąć okno)
2. Sprawdzić lokalizację pliku konfiguracyjnego:
- Claude Desktop macOS:
- Claude Desktop Windows:
- Cursor:
- Continue:
3. Zwalidować JSON — wkleić konfigurację do
4. Sprawdzić logi klienta pod kątem błędów MCP:
- Claude Desktop: (macOS)
- Cursor: View → Output → MCP
5. Uruchomić serwer MCP ręcznie, aby zobaczyć błędy startu:
[CODE BLOCK]
Problem: błąd „Mind Key invalid"
Symptomy
- Narzędzia się wyświetlają, ale wywołania zawodzą z „401 Unauthorized"
- Błąd: „Mind Key fehlt oder ungültig"
Rozwiązania
1. Zweryfikować format Mind Key — zaczyna się od , około 40 znaków
2. Przetestować bezpośrednio:
[CODE BLOCK]
3. Sprawdzić, czy zmienna środowiskowa jest ustawiona — dla transportu stdio
zmienna musi być w konfiguracji serwera MCP, a nie w powłoce
4. Uzyskać nowy Mind Key:
[CODE BLOCK]
Problem: npx nie znalezione
Symptomy
- Błąd: „npx: command not found"
- Serwer MCP nie może się uruchomić
Rozwiązania
1. Zainstalować Node.js 18+:
- macOS: lub pobrać z
- Linux:
- Windows: pobrać z
2. Zrestartować terminal po instalacji
3. Zweryfikować:
Problem: SYNAPSEURL nieosiągalne
Symptomy
- Serwer MCP się uruchamia, ale wywołania narzędzi przekraczają czas oczekiwania
- Błąd: „fetch failed" lub „ECONNREFUSED"
Rozwiązania
1. Przetestować łączność:
[CODE BLOCK]
2. Sprawdzić firmowy firewall — może blokować wychodzący HTTPS
3. Wypróbować alternatywny URL:
- Produkcja:
- Serwer MCP:
4. Dla self-hosted: upewnić się, że instancja Synapse działa i jest dostępna
Problem: serwer MCP się zawiesza
Symptomy
- Serwer MCP wychodzi natychmiast po starcie
- Logi klienta pokazują „MCP server disconnected"
Rozwiązania
1. Uruchomić ręcznie, aby zobaczyć błąd:
[CODE BLOCK]
2. Sprawdzić konflikty portów — serwer MCP używa domyślnie portu 13100
3. Wyczyścić pamięć podręczną npx:
[CODE BLOCK]
4. Zaktualizować do najnowszej wersji:
[CODE BLOCK]
Problem: wywołania narzędzi zwracają 429
Symptomy
- Błąd: „Rate limit exceeded"
Rozwiązania
To nie powinno się zdarzyć z MCP (używa autoryzacji nagłówkiem, bez limitu). Jeśli
tak:
1. Sprawdzić, czy gdzieś używane jest — przełączyć na autoryzację nagłówkiem
2. Zweryfikować — upewnić się, że wskazuje właściwą instancję
3. Skontaktować się ze wsparciem, jeśli problem utrzymuje się
Problem: narzędzia się wyświetlają, ale nie działają
Symptomy
- Narzędzia wymienione w kliencie
- Wywołanie narzędzia zwraca błąd lub brak wyniku
Rozwiązania
1. Sprawdzić nazwę narzędzia — musi być dokładna (np. , nie )
2. Zweryfikować argumenty — sprawdzić schemat wejściowy narzędzia
3. Przetestować przez bezpośrednie API:
[CODE BLOCK]
4. Sprawdzić kondycję Synapse:
[CODE BLOCK]
Uzyskiwanie pomocy
Jeśli żadne z powyższych nie rozwiąże problemu:
1. Sprawdzić istniejące zgłoszenia:
2. Otworzyć nowe zgłoszenie z:
- Wersją serwera MCP ()
- Nazwą i wersją klienta
- Systemem operacyjnym
- Istotnymi fragmentami logów
- Krokami reprodukcji
Następne kroki
- Konfiguracja Claude Desktop
- Konfiguracja Claude Code
- Błędy API
────────────────────────────────────────────────────────────
# Czym jest MCP?
SUMMARY: Model Context Protocol pozwala LLM wywoływać zewnętrzne narzędzia. Synapse udostępnia 79 narzędzi przez oficjalny serwer 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
Czym jest MCP?
Model Context Protocol (MCP) to otwarty standard Anthropic (2024), który
pozwala LLM wywoływać zewnętrzne narzędzia w ustrukturyzowany sposób. Zamiast
wklejać dokumentację API do promptu, rejestruje się narzędzia w serwerze MCP, a
LLM wywołuje je w razie potrzeby — jak function calling, ale ustandaryzowane i
niezależne od klienta.
Serwer Synapse MCP
Synapse dostarcza oficjalny serwer MCP ( na npm), który
udostępnia 79 narzędzi obejmujących wszystkie funkcje Synapse:
| Kategoria | Narzędzia | Liczba |
|----------|-------|-------|
| 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 |
| Łącznie | | 79+ |
Jak to działa
[CODE BLOCK]
1. Konfiguruje się klienta LLM (Claude Desktop, Cursor itp.) do używania serwera Synapse MCP
2. Klient uruchamia serwer MCP (przez )
3. Serwer MCP łączy się z API Synapse przy użyciu Mind Key
4. LLM widzi wszystkie 79 narzędzi jako natywne funkcje, które może wywoływać
5. Gdy LLM musi coś zapamiętać, wywołuje — serwer MCP tłumaczy to na w Synapse
Transporty
Serwer Synapse MCP obsługuje trzy transporty:
stdio (lokalny, zalecany dla komputerów biurkowych)
[CODE BLOCK]
HTTP/SSE (zdalny, wielodostępny)
Podłączyć klienta MCP do:
[CODE BLOCK]
WebSocket (mobilny, duży ruch)
[CODE BLOCK]
Profile narzędzi (v1.4.0)
Aby zmniejszyć narzut tokenów dla mniejszych LLM, serwer MCP obsługuje trzy
profile narzędzi:
| Profil | Narzędzia | Tokeny | Najlepsze dla |
|---------|-------|--------|----------|
| | 8 (kompozytowe dyspozytor) | około 500 | Self-hostowane LLM z kontekstem ≤8k |
| | 25 (nazwane) | około 2 500 | Średnie LLM (Claude Haiku, GPT-3.5) |
| | 119 (wszystkie) | około 8 250 | Duże LLM (Claude Sonnet/Opus, GPT-4) — domyślnie |
Kontrola przez:
- Zmienna środowiskowa:
- Nagłówek:
Obsługiwani klienci
- Claude Desktop — aplikacja biurkowa Anthropic
- Claude Code — terminalowy agent kodowania
- Cursor — IDE oparte na AI
- Continue.dev — open-source'owy asystent kodowania AI
- Cline — rozszerzenie VS Code
- Dowolny klient zgodny z MCP
Dlaczego używać MCP zamiast bezpośredniego API?
| Podejście | Zalety | Wady |
|----------|------|------|
| Bezpośrednie API | Proste, bez dodatkowej warstwy | LLM musi znać URL-e, nagłówki, autoryzację |
| MCP | LLM widzi natywne narzędzia, bez zapamiętywania URL-i | Dodatkowy proces serwera MCP |
Dla większości przypadków użycia agentów LLM MCP jest lepszym wyborem — LLM nie
musi pamiętać ścieżek API ani wzorców autoryzacji.
Następne kroki
- Konfiguracja Claude Desktop — konfiguracja w 2 minuty
- Konfiguracja Claude Code — integracja z terminalem
- Niestandardowy klient MCP — budowa własnego
## KATEGORIA: PRZEWODNIKI I TUTORIALE
Przewodniki krok po kroku dla konkretnych scenariuszy.
────────────────────────────────────────────────────────────
# Zautomatyzowane testowanie aplikacji iOS
SUMMARY: Wykorzystanie Synapse i Computer Control API do automatyzacji testów aplikacji iOS przez Simulator.
Zautomatyzowane testowanie aplikacji iOS
Połączenie systemu pamięci Synapse z Computer Control API pozwala budować testy
aplikacji iOS sterowane przez LLM. LLM pamięta scenariusze testowe, uczy się na
przeszłych błędach i dostosowuje się do zmian UI.
Architektura
[CODE BLOCK]
Wymagania wstępne
- Konto Synapse i Mind Key
- Serwer MCP Synapse skonfigurowany w Claude Desktop
- iOS Simulator z zainstalowanym
- Komputer zarejestrowany w Synapse (patrz Computer Control API)
Krok 1: Rejestracja komputera-symulatora
Na Macu z uruchomionym iOS Simulator:
[CODE BLOCK]
Krok 2: Zapis scenariuszy testowych w pamięci
Zapisanie wielokrotnego użytku scenariuszy testowych jako wspomnień:
[CODE BLOCK]
Krok 3: Wykonanie testu sterowane przez LLM
W Claude Desktop (z skonfigurowanym MCP Synapse):
[CODE BLOCK]
Claude wykona:
1. Wywoła , aby znaleźć wspomnienie
2. Wywoła , aby zobaczyć aktualny stan
3. Wykona każdy krok przez (kliknięcie, wpisanie)
4. Zweryfikuje wyniki przez zrzuty ekranu
5. Zapisze błędy jako wspomnienia
Krok 4: Testy samonaprawiające
Gdy test się nie powiedzie, zapisać błąd i sposób odzyskiwania:
[CODE BLOCK]
Przy następnym uruchomieniu testu LLM przypomni sobie błąd i automatycznie
zastosuje odzyskiwanie.
Krok 5: Śledzenie wyników testów
Śledzenie uruchomień testów jako zadań:
[CODE BLOCK]
Typowe polecenia
| Akcja | Polecenie |
|--------|---------|
| Uruchomienie Simulator | |
| Zrzut ekranu | (przez MCP Synapse) |
| Stuknięcie w (x,y) | |
| Wpisanie tekstu | |
| Wciśnięcie Home | |
Najlepsze praktyki
> [!TIP]
> - Zapisywać współrzędne UI jako wspomnienia — UI się zmienia, ale LLM może się ponownie nauczyć
> - Używać etykiet dostępności — stabilniejsze niż współrzędne
> - Przechowywać dane testowe osobno — używać zmiennych dla nazw użytkowników, haseł
> - Uruchamiać testy w czystym stanie — resetować Simulator między uruchomieniami
> - Logować zrzuty ekranu dla błędów — przydatne do debugowania
Następne kroki
- Testy samonaprawiające
- Computer Control API
- Najlepsze praktyki pamięci
────────────────────────────────────────────────────────────
# Kopia zapasowa i przywracanie
SUMMARY: Eksportuj wspomnienia do kopii zapasowej, migruj między umysłami, przywracaj po utracie danych.
Kopia zapasowa i przywracanie
Synapse zapewnia pełny eksport/import do kopii zapasowej pamięci, migracji i
odzyskiwania po awarii. Ten przewodnik obejmuje podstawowe operacje.
Eksport
Pełny eksport umysłu
Eksport wszystkich wspomnień w umyśle jako JSON:
[CODE BLOCK]
Format odpowiedzi:
[CODE BLOCK]
Eksport przyrostowy (diff)
Eksport tylko wspomnień zmienionych od znacznika czasu:
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
Zautomatyzowane kopie zapasowe
Planowanie codziennych kopii przez cron:
[CODE BLOCK]
> [!NOTE]
> Endpoint cron odbiera odpowiedź, ale jej nie przechowuje. Do rzeczywistych
> kopii zapasowych należy wskazać cronem własny serwer kopii, który zapisze
> odpowiedź.
Lepiej: zewnętrzny skrypt kopii zapasowej
[CODE BLOCK]
Dodać do crontab:
[CODE BLOCK]
Przywracanie
Przywracanie do tego samego umysłu
[CODE BLOCK]
Przywracanie do nowego umysłu
[CODE BLOCK]
Skrypt przywracania w Pythonie
[CODE BLOCK]
Migracja między umysłami
[CODE BLOCK]
Kopia zapasowa innych danych
Nie zapomnij zrobić kopii zapasowej:
| Typ danych | Endpoint |
|-----------|----------|
| Wspomnienia | |
| Zadania | |
| Skrypty | |
| Webhooki | |
| Zadania cron | |
| Zmienne | |
| Historia czatu | |
Weryfikacja
Po przywróceniu zweryfikować:
[CODE BLOCK]
Najlepsze praktyki
> [!TIP]
> - Codzienna kopia zapasowa — zautomatyzować przez cron
> - Testować przywracanie — kopia, której nie da się przywrócić, jest bezużyteczna
> - Przechowywać wiele wersji — co najmniej 30 dni
> - Przechowywać poza siedzibą — S3, Backblaze B2 itp.
> - Szyfrować wrażliwe kopie — wspomnienia mogą zawierać dane osobowe
> - Dokumentować proces przywracania — zapomni się go, gdy będzie potrzebny
Następne kroki
- Memory API
- Cron i Scheduler — do zautomatyzowanych kopii
────────────────────────────────────────────────────────────
# Najlepsze praktyki pamięci
SUMMARY: Jak ustrukturyzować wspomnienia do skutecznego recall — kategorie, klucze, tagi, priorytety.
Najlepsze praktyki pamięci
Sposób ustrukturyzowania wspomnień determinuje ich użyteczność. Ten przewodnik
obejmuje wzorce kategoryzowania, tagowania i priorytetyzowania wspomnień, aby
LLM mógł przypomnieć właściwą informację we właściwym czasie.
Kategorie: wybierać najbardziej konkretną
| Kategoria | Użyć dla | Przykład |
|----------|---------|---------|
| | Imię użytkownika, rola, dane kontaktowe | |
| | Sympatie, antypatie, styl pracy | |
| | Weryfikowalne fakty | |
| | Status projektu, decyzje | |
| | Umiejętności użytkownika | |
| | Błędy z przeszłości do uniknięcia | |
| | Kontekst istotny dla sesji | |
| | Różne notatki | |
> [!TIP]
> W razie wątpliwości używać dla weryfikowalnych informacji i dla
> reszty. Nie nadużywać kategoryzacji — lepszy jasny niż mylący .
Klucze: znaczące identyfikatory
Pole jest identyfikatorem wspomnienia. Używać znaczących, stabilnych kluczy:
Dobre klucze:
-
-
-
-
Złe klucze:
- (nie znaczący)
- (nie opisowy)
- (data nie pomaga w recall)
Konwencje nazewnictwa kluczy
- (małe litery z podkreśleniami)
- Prefiksować kategorią: , ,
- Używać opisowych rzeczowników, nie czasowników
- Utrzymywać poniżej 50 znaków
Tagi: do wyszukiwania i filtrowania
Tagi umożliwiają szybkie filtrowanie i wyszukiwanie. Dodać 2-5 tagów na
wspomnienie:
[CODE BLOCK]
Wzorce tagów
- Nazwy projektów: , ,
- Tematy: , , ,
- Status: , ,
- Wskaźniki priorytetu: ,
> [!NOTE]
> Tagi są niewrażliwe na wielkość liter. Używać małych liter dla spójności.
Priorytety: być realistycznym
| Priorytet | Użyć dla | % wspomnień |
|----------|---------|---------------|
| | Tożsamość użytkownika, informacje prawne, decyzje nieodwracalne | około 5% |
| | Aktywne projekty, ważne preferencje | około 20% |
| | Większość faktów, notatek, kontekstu | około 65% |
| | Efemeryczne, warto wiedzieć | około 10% |
> [!WARNING]
> Nie oznaczać wszystkiego jako . Jeśli wszystko jest krytyczne, nic
> nie jest. Zarezerwować dla rzeczy, których zapomnienie wyrządziłoby
> realną szkodę.
Kiedy zapisywać, a kiedy nie
Zawsze zapisywać
- Tożsamość użytkownika (imię, e-mail, rola)
- Długoterminowe preferencje
- Decyzje projektowe i ich uzasadnienie
- Przeszłe błędy i wyciągnięte lekcje
- Zobowiązania względem użytkownika
Nie zapisywać
- Stan przejściowy (użyć zmiennych)
- Historię konwersacji dosłownie (system czatu to obsługuje)
- Dane wrażliwe (hasła, klucze API)
- Faktory łatwo wyprowadzalne (aktualna data, zawartość plików)
- Kontekst efemeryczny (użyć kategorii z niskim priorytetem)
Aktualizacja wspomnień
POST z tym samym + aktualizuje istniejące wspomnienie:
[CODE BLOCK]
> [!TIP]
> Używać stabilnych kluczy, aby aktualizować bez tworzenia duplikatów. LLM
> powinien ponownie POSTować ten sam klucz przy zmianie informacji, a nie
> tworzyć nowe wspomnienia.
Cykl życia wspomnienia
[CODE BLOCK]
- Create: POST /memory z pełnym kontekstem
- Active: Częsty recall, aktualizacja w razie potrzeby
- Stale: Nadal istotne, ale nieaktywnie używane (obniżyć priorytet?)
- Archive: Ustawić priorytet na , zachować dla odniesienia historycznego
- Delete: DELETE /memory/:id, gdy już nieistotne
Okresowe czyszczenie
[CODE BLOCK]
Wzorzec: dziedziczenie pamięci
Dla hierarchicznego kontekstu (projekt → podprojekt → zadanie):
[CODE BLOCK]
LLM może wtedy wyszukać , aby znaleźć wszystkie powiązane
wspomnienia.
Wzorzec: dziennik decyzji
Zapisywać decyzje z uzasadnieniem, aby LLM nie kwestionował ich ponownie:
[CODE BLOCK]
Wzorzec: unikanie błędów
Zapisywać błędy z konkretnymi instrukcjami unikania:
[CODE BLOCK]
Antywzorce do unikania
> [!WARNING]
> - Zapisywanie logów konwersacji — system czatu to obsługuje
> - Zapisywanie całych plików — użyć magazynu skryptów lub zewnętrznego magazynu
> - Zapisywanie stanu efemerycznego — użyć zmiennych
> - Zapisywanie sekretów — użyć zmiennych środowiskowych
> - Duplikowanie wspomnień — używać stabilnych kluczy
> - Nadmiarowe tagowanie — 2-5 tagów na wspomnienie jest optymalne
> - Wszystko jest krytyczne — być realistycznym z priorytetami
Następne kroki
- Memory API
- Trwały agent LLM
- Strategia tagowania pamięci
────────────────────────────────────────────────────────────
# Koordynacja wielu agentów
SUMMARY: Koordynacja wielu agentów LLM z użyciem współdzielonych umysłów Synapse, zadań i czatu.
Koordynacja wielu agentów
Gdy wiele agentów LLM pracuje nad powiązanymi zadaniami, Synapse zapewnia warstwę
koordynacji — współdzieloną pamięć, przydzielanie zadań i asynchroniczny czat.
Wzorce
Wzorzec 1: współdzielony umysł (pojedyncze źródło prawdy)
Wszyscy agenci współdzielą jeden Mind Key. Odczytują/zapisują ten sam magazyn
pamięci.
[CODE BLOCK]
Przypadek użycia: Mały zespół agentów pracujący nad jednym projektem.
Konfiguracja:
[CODE BLOCK]
Koordynacja przez zadania:
[CODE BLOCK]
Wzorzec 2: wyspecjalizowane umysły (izolowane konteksty)
Każdy agent ma własny umysł. Komunikują się przez współdzielony umysł
„koordynacyjny".
[CODE BLOCK]
Przypadek użycia: Agenci z różnymi specjalnościami (kodowanie, przegląd, wdrażanie).
Konfiguracja:
[CODE BLOCK]
Koordynacja przez współdzielony umysł:
[CODE BLOCK]
Wzorzec 3: hub-and-spoke (orkiestrator)
Centralny agent orkiestrujący przydziela zadania agentom wykonawczym.
[CODE BLOCK]
Przypadek użycia: Złożone przepływy z pracą równoległą.
Implementacja:
[CODE BLOCK]
Koordynacja przez czat
Agenci mogą komunikować się przez system czatu:
[CODE BLOCK]
> [!NOTE]
> Wiadomości czatu są oznaczane rolą. Ustawić role=agent dla wiadomości
> agent-agent, role=human dla człowiek-agent.
Koordynacja przez zmienne
Używać zmiennych do lekkiej koordynacji (blokady, flagi):
[CODE BLOCK]
Najlepsze praktyki
> [!TIP]
> - Używać osobnych umysłów dla osobnych zagadnień — nie mieszać pamięci kodera i recenzenta
> - Oznaczać agentów w czacie — dla jasnego adresowania
> - Używać zadań do przydzielania pracy — nie czatu (czat jest do dyskusji)
> - Implementować idempotentność — agenci mogą ponawiać nieudane operacje
> - Logować wszystko — zapisywać decyzje w pamięci dla audytowalności
Następne kroki
- Trwały agent LLM
- Książka kucharska LLM
- Automatyzacja webhookami
────────────────────────────────────────────────────────────
# Budowa trwałego agenta LLM
SUMMARY: Przewodnik krok po kroku budowy agenta LLM, który pamięta między sesjami z użyciem Synapse.
Przegląd
Ten przewodnik przeprowadza przez budowę agenta LLM, który utrwala kontekst
między sesjami z użyciem Synapse. Na końcu agent będzie:
- Przypominał przeszły kontekst na początku sesji
- Zapisywał nowe informacje na bieżąco
- Śledził wieloetapowe zadania między sesjami
- Komunikował się z ludźmi przez asynchroniczny czat
Architektura
[CODE BLOCK]
Krok 1: konfiguracja Mind Key
[CODE BLOCK]
Krok 2: protokół początku sesji
Na początku każdej sesji przypomnieć wszystkie wspomnienia:
[CODE BLOCK]
Krok 3: zapis nowych informacji
Gdy agent poznaje coś warte zapamiętania:
[CODE BLOCK]
Krok 4: zarządzanie zadaniami
Śledzenie wieloetapowej pracy między sesjami:
[CODE BLOCK]
Krok 5: asynchroniczny czat z ludźmi
Odpytywanie o wiadomości między wywołaniami narzędzi:
[CODE BLOCK]
Krok 6: protokół końca sesji
Na końcu sesji zapisać końcowy kontekst:
[CODE BLOCK]
Pełny wzorzec
[CODE BLOCK]
Najlepsze praktyki
> [!TIP]
>
> - Zawsze najpierw recall — nigdy nie zaczynać pracy bez załadowania kontekstu
> - Zapis proaktywny — nie czekać do końca sesji
> - Używać znaczących kluczy — , , nie
> - Tagować wszystko — tagi napędzają wyszukiwanie i filtrowanie
> - Ustawiać realistyczne priorytety — nie wszystko jest
Następne kroki
- Książka kucharska LLM — praktyczne wzorce
- Najlepsze praktyki pamięci
- Koordynacja wielu agentów
────────────────────────────────────────────────────────────
# Samonaprawiające się potoki testowe
SUMMARY: Budowa potoków testowych, które uczą się na błędach i adaptują automatycznie z użyciem pamięci Synapse.
Samonaprawiające się potoki testowe
Tradycyjne zestawy testów psują się, gdy zmienia się UI. Testy samonaprawiające
używają pamięci Synapse, aby uczyć się na przeszłych błędach i adaptować — co
zmniejsza flaky tests i obciążenie utrzymaniem.
Koncepcja
[CODE BLOCK]
1. Uruchomienie testu
2. W razie niepowodzenia zapisanie błędu (co poszło nie tak, dlaczego, jak naprawić)
3. Następne uruchomienie: recall istotnych błędów przed wykonaniem
4. Automatyczne zastosowanie znanych poprawek
Implementacja
Krok 1: opakowanie testu
Opakowanie każdego testu recall/zapisem pamięci:
[CODE BLOCK]
Krok 2: adaptacyjna logika testu
Wewnątrz testu sprawdzać znane błędy i stosować poprawki:
[CODE BLOCK]
Krok 3: strategie odzyskiwania
Zapis strategii odzyskiwania jako wspomnień:
[CODE BLOCK]
Krok 4: integracja CI
[CODE BLOCK]
Krok 5: panel analizy błędów
[CODE BLOCK]
Najlepsze praktyki
> [!TIP]
> - Zapisywać tracebacki — zawierają dokładną linię, która zawiodła
> - Tagować po nazwie testu — umożliwia szybkie filtrowanie
> - Używać kategorii — oddziela od zwykłych wspomnień
> - Ustawiać priorytet — błędy nigdy nie powinny być zapomniane
> - Okresowe czyszczenie — usuwanie wspomnień dla rozwiązanych problemów
> - Nie zapisywać danych wrażliwych — poświadczenia, dane osobowe
Częste wzorce błędów do zapisu
| Typ błędu | Co zapisać |
|--------------|---------------|
| Element nie znaleziony | Próbowany selektor, stan strony, zrzut ekranu |
| Timeout | Czas oczekiwania, na co czekano |
| Asercja nie powiodła się | Oczekiwana vs rzeczywista wartość |
| Błąd sieci | URL, kod statusu, treść odpowiedzi |
| Odmowa uprawnień | Wymagane uprawnienie, bieżąca rola użytkownika |
Następne kroki
- Zautomatyzowane testowanie iOS
- Najlepsze praktyki pamięci
- Książka kucharska odzyskiwania po błędach
────────────────────────────────────────────────────────────
# Automatyzacja webhookami
SUMMARY: Wyzwalanie systemów zewnętrznych, gdy zmieniają się wspomnienia — synchronizacja, powiadomienia, automatyzacja.
Automatyzacja webhookami
Webhooki pozwalają wyzwalać systemy zewnętrzne, gdy uruchamiają się zdarzenia
Synapse. Ten przewodnik obejmuje typowe wzorce automatyzacji.
Typowe wzorce
Wzorzec 1: powiadomienie o krytycznym wspomnieniu
Wysłanie wiadomości Slack, gdy zapisywane jest krytyczne wspomnienie:
[CODE BLOCK]
Rejestracja webhooka:
[CODE BLOCK]
Wzorzec 2: synchronizacja z systemem zewnętrznym
Synchronizacja wspomnień z Notion, Obsidian lub dowolną zewnętrzną bazą wiedzy:
[CODE BLOCK]
Wzorzec 3: wyzwalanie CI/CD
Wyzwalanie wdrożenia, gdy zapisywane jest wspomnienie „release":
[CODE BLOCK]
Wzorzec 4: przebudzenie agenta przy wiadomości człowieka
Wyzwolenie uruchomienia agenta LLM, gdy człowiek wysyła wiadomość czatu:
[CODE BLOCK]
Wzorzec 5: agregacja metryk
Śledzenie wzrostu pamięci, aktywności czatu, ukończenia zadań:
[CODE BLOCK]
Weryfikacja podpisu
Zawsze weryfikować podpisy webhooków, aby zapobiec fałszerstwu:
[CODE BLOCK]
Logika ponowień
Synapse ponawia nieudane webhooki z wykładniczym wycofywaniem. Obsługa powinna:
1. Szybko zwracać 200 — nie wykonywać ciężkiej pracy synchronicznie
2. Kolejkować pracę — użyć systemu zadań w tle
3. Być idempotentna — to samo zdarzenie może być dostarczone dwa razy
[CODE BLOCK]
Debugowanie webhooków
Sprawdzenie historii dostarczeń
Dostarczenia webhooków są logowane. Sprawdzić ostatnie dostarczenia webhooka:
[CODE BLOCK]
Ręczne testowanie webhooka
[CODE BLOCK]
Częste problemy
| Problem | Rozwiązanie |
|-------|-----|
| Odpowiedzi 4xx | Sprawdzić, czy obsługa zwraca 200 |
| Odpowiedzi 5xx | Błąd serwera — sprawdzić logi aplikacji |
| Timeout | Szybko zwrócić 200, kolejkować pracę asynchronicznie |
| Duplikaty dostaw | Uczynić obsługę idempotentną |
| Niedopasowanie podpisu | Zweryfikować poprawność sekretu |
Najlepsze praktyki
> [!TIP]
> - Zawsze weryfikować podpisy — nigdy tego nie pomijać
> - Szybko zwracać 200 — nie blokować Synapse
> - Być idempotentnym — obsługiwać duplikaty dostaw
> - Używać konkretnych zdarzeń — , nie
> - Monitorować błędy dostaw — skonfigurować alertowanie
Następne kroki
- Webhooks API
- Cron i Scheduler
- Trwały agent LLM
## KATEGORIA: POJĘCIA
Architektura i koncepcje stojące za Synapse.
────────────────────────────────────────────────────────────
# Architektura Synapse
SUMMARY: Jak zbudowany jest Synapse — Fastify, PostgreSQL, FTS5, osadzenia, serwer MCP.
Architektura Synapse
Synapse to wielodostępne API pamięci zbudowane na Fastify, PostgreSQL z FTS5
oraz opcjonalnej usłudze osadzeń do wyszukiwania semantycznego.
Architektura wysokiego poziomu
[CODE BLOCK]
Główne komponenty
1. Synapse API (Fastify)
Główny serwer HTTP. Obsługuje:
- Endpointy REST (, , itp.)
- Autoryzację (Mind Key dla agentów, JWT dla ludzi)
- Limity żądań (tylko autoryzacja )
- Serwowanie plików statycznych (interfejs WWW pod , itp.)
- Wysyłanie webhooków
Zbudowany na Fastify 5 dla wydajności. W środowisku produkcyjnym działa na
porcie 12800.
2. PostgreSQL z FTS5
Główny magazyn danych. Wykorzystuje PostgreSQL z rozszerzeniem FTS5 do
wyszukiwania pełnotekstowego.
Kluczowe tabele:
| Tabela | Przeznaczenie |
|-------|---------|
| | Konta użytkowników |
| | Zakresy umysłów (każdy ma Mind Key) |
| | Rekordy wspomnień z tabelą wirtualną FTS5 |
| | Zarządzanie zadaniami |
| | Historia czatu |
| | Trwałe skrypty |
| | Rejestracje webhooków |
| | Zaplanowane zadania |
| | Magazyn klucz-wartość |
| | Ścieżka audytu |
FTS5 umożliwia wyszukiwanie pełnotekstowe poniżej milisekundy w całej treści
wspomnień. Szczegóły w sekcji Wyszukiwanie FTS5.
3. Usługa osadzeń (opcjonalna)
Do wyszukiwania semantycznego Synapse generuje wektorowe osadzenia treści
wspomnień. Są one przechowywane razem ze wspomnieniami i używane do wyszukiwania
podobieństwa.
- Dostawca: konfigurowalny (OpenAI, model lokalny itp.)
- Przechowywane jako kolumna w tabeli
- Używane przez endpoint
- Patrz Wyszukiwanie semantyczne
4. Serwer MCP (osobna usługa)
Serwer MCP Synapse działa jako osobny proces (port 13100). Spełnia funkcje:
- Udostępnia 79 narzędzi przez Model Context Protocol
- Obsługuje transporty stdio, HTTP/SSE oraz WebSocket
- Tłumaczy wywołania narzędzi MCP na wywołania API Synapse
- Wielodostępność: jeden Mind Key na sesję
5. Proxy przeglądarki (osobna usługa)
Do automatyzacji przeglądarki działa osobna usługa oparta na Playwright na
porcie 13000. Serwer MCP może ją wywoływać dla narzędzi .
6. Proxy SSH (osobna usługa)
Do zdalnych poleceń opartych na SSH działa osobna usługa na porcie 12900.
Model wielodostępności
[CODE BLOCK]
Każdy umysł jest w pełni izolowany. Mind Key daje dostęp dokładnie do jednego
umysłu. JWT dają dostęp do konta użytkownika (do zarządzania umysłami).
Szczegóły w sekcji Wielodostępność.
Przepływ żądania
Żądanie zapisu wspomnienia
[CODE BLOCK]
Żądanie wyszukiwania wspomnień
[CODE BLOCK]
Wdrożenie
Synapse jest wdrażany jako kontener Docker. Patrz :
[CODE BLOCK]
Charakterystyka wydajności
| Operacja | Opóźnienie | Przepustowość |
|-----------|---------|------------|
| Zapis wspomnienia | 5 ms | 1000+ żądań/s |
| Recall wspomnień | 20 ms | 500 żądań/s |
| Wyszukiwanie FTS5 | 10 ms | 800 żądań/s |
| Wyszukiwanie semantyczne | 50 ms | 200 żądań/s |
| Odpytywanie czatu | 5 ms | 2000 żądań/s |
Następne kroki
- Model pamięci
- Wielodostępność
- Wyszukiwanie FTS5
────────────────────────────────────────────────────────────
# Wyszukiwanie pełnotekstowe FTS5
SUMMARY: Jak Synapse wykorzystuje SQLite FTS5 do wyszukiwania wspomnień poniżej milisekundy.
Wyszukiwanie pełnotekstowe FTS5
Synapse używa FTS5 (Full-Text Search 5) do szybkiego i elastycznego wyszukiwania
wspomnień. Ta strona wyjaśnia, jak to działa i jak efektywnie tego używać.
Czym jest FTS5?
FTS5 to rozszerzenie SQLite (dostępne również w PostgreSQL przez rozszerzenia),
które zapewnia możliwości wyszukiwania pełnotekstowego. Spełnia funkcje:
- Indeksuje treść tekstową pod kątem szybkiego wyszukiwania słów kluczowych
- Obsługuje operatory logiczne (AND, OR, NOT)
- Obsługuje dopasowywanie fraz z cudzysłowami
- Obsługuje dopasowywanie prefiksów z
- Ranguje wyniki według trafności
Synapse używa FTS5 do indeksowania całej treści wspomnień, co umożliwia
wyszukiwanie poniżej milisekundy w tysiącach wspomnień.
Jak Synapse używa FTS5
Gdy wykonywane jest :
1. Treść wspomnienia jest zapisywana w tabeli
2. Treść jest również wstawiana do tabeli wirtualnej FTS5
3. FTS5 automatycznie tokenizuje i indeksuje treść
Gdy wykonywane jest :
1. Synapse parsuje zapytanie składnią FTS5
2. Wykonuje wobec indeksu FTS5
3. Filtruje po (izolacja dzierżawcy)
4. Zwraca wyniki z rankingiem
Składnia zapytania
Proste wyszukiwanie słów kluczowych
[CODE BLOCK]
Zwraca wspomnienia zawierające „docker".
Wiele słów kluczowych (domyślnie AND)
[CODE BLOCK]
Zwraca wspomnienia zawierające ZARÓWNO „docker", JAK i „swarm".
Dopasowywanie fraz
[CODE BLOCK]
Zwraca wspomnienia zawierające dokładną frazę „docker swarm".
Dopasowywanie prefiksów
[CODE BLOCK]
Zwraca wspomnienia zawierające słowa zaczynające się od „docker" (np. „dockers",
„dockerfile", „dockerize").
Operator logiczny OR
[CODE BLOCK]
Zwraca wspomnienia zawierające „docker" LUB „kubernetes".
Operator logiczny NOT
[CODE BLOCK]
Zwraca wspomnienia zawierające „docker", ale NIE „swarm".
Grupowanie
[CODE BLOCK]
Zwraca wspomnienia zawierające „docker" lub „kubernetes", ale nie „test".
Praktyczne przykłady
Znajdowanie wspomnień o projekcie
[CODE BLOCK]
Znajdowanie dokładnej frazy
[CODE BLOCK]
Wykluczanie wspomnień testowych
[CODE BLOCK]
Wyszukiwanie po technologii
[CODE BLOCK]
Ranking
FTS5 ranguje wyniki pod kątem trafności algorytmem BM25. Czynniki:
- Częstotliwość terminu (jak często występuje)
- Odwrotna częstotliwość dokumentu (rzadsze terminy mają wyższy ranking)
- Długość dokumentu (krótsze dokumenty z terminem mają wyższy ranking)
- Waga kolumny (tytuł > treść)
Wyniki są zwracane w kolejności rangi (najbardziej trafne najpierw).
Wydajność
| Operacja | Opóźnienie |
|-----------|---------|
| Wyszukiwanie 100 wspomnień | < 5 ms |
| Wyszukiwanie 1 000 wspomnień | < 10 ms |
| Wyszukiwanie 10 000 wspomnień | < 25 ms |
| Wyszukiwanie 100 000 wspomnień | < 100 ms |
FTS5 jest wysoce zoptymalizowany dla obciążeń odczytu.
Ograniczenia
Stemming
FTS5 domyślnie nie wykonuje stemmingu. „Running" i „run" to różne terminy.
Obejście: Użyć dopasowania prefiksu:
Tolerancja literówek
FTS5 nie obsługuje dopasowywania rozmytego. Literówka zwróci brak wyników.
Obejście: Użyć wyszukiwania semantycznego () do
dopasowywania koncepcyjnego.
Słowa stop
Popularne słowa (the, a, an, is) są indeksowane, ale mogą nie być użyteczne w
wyszukiwaniu. FTS5 obsługuje to automatycznie.
FTS5 a wyszukiwanie semantyczne
| Aspekt | FTS5 | Wyszukiwanie semantyczne |
|--------|------|-----------------|
| Prędkość | Poniżej milisekundy | 50-100 ms |
| Dopasowywanie | Dokładne słowa kluczowe | Koncepcyjne |
| Tolerancja literówek | Brak | Pewna |
| Stemming | Brak | Domniemany |
| Wymaga osadzeń | Nie | Tak |
| Najlepsze do | Konkretnych terminów | Koncepcji |
Należy używać FTS5, gdy znane są słowa kluczowe. Wyszukiwanie semantyczne należy
stosować, gdy potrzebne są „wspomnienia o X", gdzie X jest opisane inaczej.
Najlepsze praktyki
> [!TIP]
> - Używać konkretnych terminów — „docker swarm" jest lepsze niż „container orchestration"
> - Cytować frazy — zapewnia dopasowanie frazy
> - Używać prefiksu dla wariantów — wyłapuje „deploy", „deployment", „deploying"
> - Wykluczać szum — odfiltrowuje wspomnienia testowe
> - Łączyć z tagami — zawęża wyniki
Następne kroki
- Wyszukiwanie semantyczne
- Memory API
- Najlepsze praktyki pamięci
────────────────────────────────────────────────────────────
# Model pamięci
SUMMARY: Jak ustrukturyzowane są wspomnienia — kategorie, klucze, tagi, priorytety, źródła, weryfikacja.
Model pamięci
Model pamięci Synapse jest zaprojektowany dla agentów LLM — na tyle
ustrukturyzowany, by zapewnić niezawodne przypominanie, na tyle elastyczny, by
pasował do każdej domeny.
Anatomia wspomnienia
[CODE BLOCK]
Pola
| Pole | Typ | Wymagane | Opis |
|-------|------|----------|-------------|
| | string | auto | Unikalny identyfikator (memxxx) |
| | enum | ✅ | Jedna z 8 kategorii |
| | string | ✅ | Stabilny identyfikator (używany do aktualizacji) |
| | string | ✅ | Treść wspomnienia (dowolny tekst) |
| | string[] | – | Do wyszukiwania i filtrowania |
| | enum | – | low, normal, high, critical (domyślnie: normal) |
| | enum | auto | user, agent (kto zapisał) |
| | bool | auto | Czy człowiek to zweryfikował? |
| | float | – | 0.0-1.0 (domyślnie: 1.0 dla użytkownika, 0.7 dla agenta) |
| | timestamp | – | Kiedy zapomnieć to wspomnienie |
| | string | auto | Do którego umysłu należy |
| | timestamp | auto | Pierwszy zapis |
| | timestamp | auto | Ostatnia modyfikacja |
Kategorie
Osiem kategorii pokrywa typowe przypadki użycia agentów LLM:
| Kategoria | Przeznaczenie | Przykładowa treść |
|----------|---------|-----------------|
| | Kim jest użytkownik | „User is Michael Schäfer, software engineer in Berlin" |
| | Preferencje użytkownika | „Prefers concise technical responses" |
| | Weryfikowalne fakty | „Office is in Berlin, timezone Europe/Berlin" |
| | Status projektu | „Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| | Umiejętności użytkownika | „Advanced Python, 10+ years" |
| | Błędy z przeszłości | „Forgot to bump npm version — CI failed" |
| | Kontekst sesji | „Currently reviewing PR #42" |
| | Różne notatki | „Try Redis for caching next sprint" |
Klucze: stabilne identyfikatory
Pole jest kluczowe — to sposób aktualizacji wspomnień bez tworzenia
duplikatów.
[CODE BLOCK]
Zasady kluczy:
- Musi być unikalny w obrębie (kategoria, umysł)
- Używać
- Prefiksować kategorią dla jasności: ,
- Utrzymywać stabilność — nie zmieniać kluczy po utworzeniu
Tagi: do wyszukiwania
Tagi umożliwiają szybkie filtrowanie i wyszukiwanie:
[CODE BLOCK]
Najlepsze praktyki tagowania:
- 2-5 tagów na wspomnienie (bez przesady)
- Małe litery dla spójności
- Używać nazw projektów, tematów, technologii
- Tagi są niewrażliwe na wielkość liter
Poziomy priorytetu
| Priorytet | Kiedy stosować | Zachowanie recall |
|----------|-------------|-----------------|
| | Tożsamość, kwestie prawne, nieodwracalne | Zawsze na górze recall |
| | Aktywne projekty, kluczowe preferencje | Wyeksponowane w recall |
| | Większość wspomnień (domyślny) | Standardowa kolejność recall |
| | Efemeryczne, warto wiedzieć | Mogą zostać podsumowane |
sortuje po priorytecie (krytyczne najpierw), a następnie po
aktualności.
Źródło: użytkownik czy agent
Wspomnienia są oznaczane :
- — zapisane przez człowieka (przez JWT lub interfejs ludzki)
- — zapisane przez agenta LLM (przez Mind Key)
To wpływa na:
- Weryfikację: wspomnienia są automatycznie weryfikowane, — nie
- Pewność: domyślnie 1.0, 0.7
- Recall: oznacza niezweryfikowane wspomnienia jako „(unverified)"
> [!NOTE]
> Należy podchodzić do wspomnień ze źródła z odpowiednim sceptycyzmem. Mogą
> być wnioskowane lub zakładane, a nie bezpośrednio zadeklarowane przez użytkownika.
Weryfikacja
Flaga wskazuje, że człowiek potwierdził wspomnienie:
- Wspomnienia : automatycznie zweryfikowane ()
- Wspomnienia : domyślnie niezweryfikowane ()
Weryfikacja wspomnień:
[CODE BLOCK]
> [!NOTE]
> Weryfikacja wymaga JWT (autoryzacja człowieka), a nie Mind Key (autoryzacja
> agenta). Zapewnia to, że tylko ludzie mogą oznaczać wspomnienia jako zweryfikowane.
Pewność
Pole (0.0-1.0) wskazuje, jak wiarygodne jest wspomnienie:
- 1.0 — bezpośrednio zadeklarowane przez użytkownika
- 0.7 — wnioskowane przez agenta
- 0.5 — niepewne, wymaga weryfikacji
- 0.0 — wprost wątpliwe
Ustawianie pewności przy zapisie:
[CODE BLOCK]
Wygaśnięcie
Dla wspomnień wrażliwych czasowo należy ustawić :
[CODE BLOCK]
Wygasłe wspomnienia nie są zwracane przez (ale nadal istnieją w
bazie). Należy użyć , aby zobaczyć wspomnienia
wygasające wkrótce.
Cykl życia wspomnienia
[CODE BLOCK]
Zachowanie recall
zwraca podsumowanie w postaci zwykłego tekstu, zoptymalizowane
dla kontekstu LLM:
[CODE BLOCK]
- Posortowane po priorytecie (critical → low), a następnie po aktualności
- Niezweryfikowane wspomnienia oznaczone
- Tagi dołączone dla kontekstu
- Zwykły tekst (bez parsowania JSON)
Następne kroki
- Memory API
- Najlepsze praktyki pamięci
- Wyszukiwanie FTS5
────────────────────────────────────────────────────────────
# Wielodostępność i izolacja
SUMMARY: Jak Synapse izoluje dane między użytkownikami i umysłami — wyjaśnione granice bezpieczeństwa.
Wielodostępność i izolacja
Synapse jest wielodostępny: wielu użytkowników, każdy z wieloma umysłami, w pełni
odizolowanych od siebie. Ta strona wyjaśnia model izolacji.
Hierarchia dzierżawców
[CODE BLOCK]
Poziomy izolacji
Poziom 1: Izolacja użytkownika
Każde konto użytkownika jest izolowane. Alice nie może:
- Widzieć umysłów Boba
- Dostać się do wspomnień Boba (nawet ze swoim JWT)
- Wylistować informacji o koncie Boba
Wymuszane przez: kolumna we wszystkich tabelach, JWT zawiera
, wszystkie zapytania filtrują po .
Poziom 2: Izolacja umysłu
W obrębie użytkownika każdy umysł jest izolowany. Umysł A nie może:
- Widzieć wspomnień umysłu B
- Dostać się do zadań, czatu, skryptów umysłu B
Wymuszane przez: kolumna we wszystkich tabelach danych, Mind Key
zawiera , wszystkie zapytania filtrują po .
> [!CRITICAL]
> Izolacja Mind Key jest główną granicą bezpieczeństwa. Wyciekły Mind Key daje
> pełny dostęp do danych tego umysłu — ale TYLKO tego umysłu.
Tokeny autoryzacyjne
| Token | Zakres | Do czego ma dostęp |
|-------|-------|-------------------|
| Mind Key | Pojedynczy umysł | Tylko dane tego umysłu |
| JWT | Konto użytkownika | Zarządzanie kontem (tworzenie/lista/usuwanie umysłów) |
| Computer Token | Pojedynczy komputer | Polecenia tego komputera |
Dostęp między umysłami
W obrębie tego samego użytkownika
Użytkownik ma dostęp do wszystkich swoich umysłów przez JWT (np.
wylistowuje wszystkie). Aby jednak odczytać/zapisać dane pamięci, potrzebny jest
konkretny Mind Key.
Między użytkownikami
Użytkownicy nie mają dostępu do danych innych — CHYBA że jawnie udostępnią umysł
przez Sharing API:
[CODE BLOCK]
Po udostępnieniu Bob ma dostęp do umysłu A przez swój JWT (tylko do odczytu, jeśli
).
Granice bezpieczeństwa
[CODE BLOCK]
Typowe wzorce wielodostępności
Wzorzec 1: pojedynczy użytkownik, pojedynczy umysł
Najczęstszy dla indywidualnych użytkowników agentów LLM.
- 1 konto użytkownika
- 1 umysł
- 1 Mind Key
- Wszystkie wspomnienia w jednym zakresie
Wzorzec 2: pojedynczy użytkownik, wiele umysłów
Dla użytkowników z wieloma kontekstami (praca, życie prywatne, projekty).
- 1 konto użytkownika
- N umysłów (np. „work", „personal", „project-x")
- N Mind Key
- Każda sesja LLM używa jednego Mind Key
Wzorzec 3: współdzielony umysł zespołu
Dla zespołów współpracujących nad projektem.
- Jeden użytkownik tworzy umysł (otrzymuje Mind Key)
- Twórca udostępnia członkom zespołu przez JWT
- Wszyscy członkowie zespołu mają dostęp przez JWT (lub współdzielony Mind Key)
> [!WARNING]
> Współdzielenie Mind Key daje pełny dostęp do odczytu i zapisu. Do współpracy
> zespołu preferować Sharing API (oparte na JWT) zamiast bezpośredniego
> współdzielenia Mind Key.
Wzoczec 4: dostawca SaaS
Dla aplikacji osadzających Synapse jako warstwę pamięci.
- Każdy klient = 1 konto użytkownika
- Każdy projekt klienta = 1 umysł
- Aplikacja przechowuje Mind Key per klient/projekt
- Pełna izolacja między klientami
Weryfikacja izolacji
Test: Mind Key nie ma dostępu do innych umysłów
[CODE BLOCK]
Test: JWT nie może odczytać danych pamięci bezpośrednio
[CODE BLOCK]
Najlepsze praktyki
> [!TIP]
> - Używać jednego umysłu na projekt/kontekst — izolacja jest sojusznikiem
> - Nigdy nie współdzielić Mind Key — zamiast tego używać Sharing API
> - Rotować Mind Key w razie kompromitacji (usunąć umysł, utworzyć nowy)
> - Audytować współdzielone umysły — okresowo przeglądać
> - Używać JWT dla interfejsu ludzkiego — nigdy nie udostępniać Mind Key użytkownikom końcowym
Następne kroki
- Autoryzacja
- Mind Key vs JWT
- Architektura
────────────────────────────────────────────────────────────
# Wyszukiwanie semantyczne (osadzenia)
SUMMARY: Koncepcyjne wyszukiwanie wspomnień z użyciem osadzeń wektorowych — znajdowanie po znaczeniu, nie tylko słowach kluczowych.
Wyszukiwanie semantyczne (osadzenia)
Synapse obsługuje wyszukiwanie semantyczne z użyciem osadzeń wektorowych. W
przeciwieństwie do FTS5 (dopasowywanie słów kluczowych), wyszukiwanie semantyczne
znajduje wspomnienia po znaczeniu — nawet gdy nie ma dopasowania słów
kluczowych.
Jak to działa
[CODE BLOCK]
Czym są osadzenia?
Osadzenia to liczbowe reprezentacje wektorowe tekstu. Tekst o podobnym znaczeniu
ma podobne wektory. Synapse generuje wektor (np. 1536 wymiarów) dla treści
każdego wspomnienia.
Podobieństwo cosinusowe
Aby znaleźć semantycznie podobne wspomnienia, Synapse oblicza podobieństwo
cosinusowe między wektorem zapytania a każdym wektorem wspomnienia. Wyższe
podobieństwo = większa trafność.
Kiedy używać wyszukiwania semantycznego
Użyć wyszukiwania semantycznego, gdy:
- Potrzebne są „wspomnienia o X", gdzie X jest opisane inaczej niż zapisane
- FTS5 nie zwraca wyników (brak dopasowania słów kluczowych)
- Wymagane grupowanie koncepcyjne (np. wszystkie wspomnienia o „wdrożeniu", nawet jeśli niektóre mówią „release")
- Zapytanie jest pytaniem: „jak obsługujemy autoryzację?"
Użyć FTS5, gdy:
- Znane są dokładne słowa kluczowe
- Wymagana logika boolowska (AND, OR, NOT)
- Wymagana odpowiedź poniżej milisekundy
- Wymagane dopasowanie frazy
Endpoint
GET /memory/semantic-search
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
Przykłady
Znajdowanie wspomnień o wdrożeniu
[CODE BLOCK]
Zwraca wspomnienia o „deployment", „release", „publishing", „rolling out" itp.
Znajdowanie wzorców autoryzacji
[CODE BLOCK]
Zwraca wspomnienia o logowaniu, autoryzacji, JWT, zarządzaniu sesjami, OAuth itp.
Znajdowanie podobnych wspomnień
[CODE BLOCK]
Używa podobieństwa semantycznego (przez współdzielone tagi i wektory osadzeń).
Generowanie osadzeń
Kiedy generowane są osadzenia?
- Przy zapisie wspomnienia — jeśli skonfigurowano usługę osadzeń, są one generowane synchronicznie
- Generowanie wsadowe — generuje osadzenia dla wspomnień, które ich nie mają
- Aktualizacje asynchroniczne — gdy treść jest aktualizowana, osadzenie jest regenerowane
Dostawcy osadzeń
Synapse obsługuje konfigurowalnych dostawców osadzeń:
- OpenAI (, )
- Modele lokalne (przez Ollama lub podobne)
- Własne (implementacja interfejsu osadzeń)
Konfiguracja przez zmienne środowiskowe:
[CODE BLOCK]
Generowanie wsadowe
Dla umysłów z wieloma wspomnieniami bez osadzeń:
[CODE BLOCK]
Wydajność
| Operacja | Opóźnienie |
|-----------|---------|
| Generowanie osadzenia (OpenAI) | 100-200 ms |
| Wyszukiwanie semantyczne (1k wspomnień) | 50-100 ms |
| Wyszukiwanie semantyczne (10k wspomnień) | 200-500 ms |
| Generowanie wsadowe (100 wspomnień) | 10-20 s |
> [!NOTE]
> Wyszukiwanie semantyczne jest wolniejsze niż FTS5 z powodu obliczeń wektorowych.
> FTS5 należy stosować dla znanych słów kluczowych, semantyczne — do zapytań
> koncepcyjnych.
Ograniczenia
Koszt osadzeń
W przypadku użycia OpenAI generowanie osadzeń kosztuje (około 0,02 USD za 1M
tokenów dla text-embedding-3-small). Dla 10 000 wspomnień średnio po 100 tokenów
każde — około 0,02 USD — zaniedbywalne.
Zimny start
Wspomnienia zapisane przed skonfigurowaniem osadzeń nie będą ich miały. Należy
uruchomić , aby wykonać backfill.
Zależność od dostawcy
Jeśli dostawca osadzeń jest niedostępny, wyszukiwanie semantyczne kończy się
łagodnie (zwraca puste wyniki lub błąd). FTS5 nadal działa.
Gdy osadzenia nie są dostępne
Jeśli usługa osadzeń nie jest skonfigurowana:
- zwraca 503 Service Unavailable
- nadal działa (tylko bez generowania osadzenia)
- Wyszukiwanie FTS5 nadal działa
Najlepsze praktyki
> [!TIP]
> - Semantyczne do zapytań koncepcyjnych — „jak obsługujemy X?"
> - FTS5 dla konkretnych terminów — „docker swarm"
> - Regularnie wykonywać backfill osadzeń —
> - Monitorować kondycję dostawcy — wyszukiwanie semantyczne od niego zależy
> - Łączyć z tagami — semantyczne + filtr tagów zawęża wyniki
Następne kroki
- Wyszukiwanie FTS5
- Memory API
- Architektura
## KATEGORIA: KSIĘGA PRZEPISÓW LLM
Przepisy i wzorce dla agentów LLM.
────────────────────────────────────────────────────────────
# Wzorzec odpytywania czatu
SUMMARY: Jak odpytywać o wiadomości od człowieka między wywołaniami narzędzi bez blokowania przepływu pracy.
Wzorzec odpytywania czatu
System czatu jest asynchroniczny — ludzie mogą zostawiać wiadomości, gdy pracujesz.
Ten wzorzec pokazuje, jak odpytywać o wiadomości bez blokowania przepływu pracy.
Wzorzec
[CODE BLOCK]
Odpytywać między wywołaniami narzędzi, nie w ciasnej pętli.
Dlaczego odpytywać między wywołaniami narzędzi?
- Nie blokować — odpytywanie w ciasnej pętli marnuje wywołania API
- Nie przegapić wiadomości — zbyt rzadkie odpytywanie oznacza powolne odpowiedzi
- Złoty środek — odpytywać co 30-60 sekund lub po każdym wywołaniu narzędzia
Implementacja
Podstawowe odpytywanie
[CODE BLOCK]
Wzorzec 1: odpytywanie po każdym wywołaniu narzędzia
[CODE BLOCK]
Wzorzec 2: odpytywanie oparte na czasie
[CODE BLOCK]
Wzorzec 3: sterowanie zdarzeniami (z webhookami)
Do powiadomień w czasie rzeczywistym zarejestrować webhook:
[CODE BLOCK]
Następnie obsługa webhooka może przebudzić agenta:
[CODE BLOCK]
Wzorce obsługi wiadomości
Wzorzec: potwierdzenie, a następnie przetworzenie
[CODE BLOCK]
Wzorzec: kolejkowanie do przetwarzania wsadowego
[CODE BLOCK]
Wzorzec: rutowanie priorytetowe
[CODE BLOCK]
Częstotliwość odpytywania
| Przypadek użycia | Częstotliwość |
|----------|-----------|
| Agent interaktywny (człowiek czeka) | Co 5-10 sekund |
| Agent w tle | Co 30-60 sekund |
| Przetwarzanie wsadowe | Co 5 minut |
| Sterowany webhookiem | Nie odpytywać — używać webhooków |
> [!WARNING]
> Odpytywanie częściej niż raz na 5 sekund marnuje wywołania API. Endpoint
> zwraca natychmiast, gdy wiadomości oczekują, więc szybsze
> odpytywanie nie przynosi korzyści.
Czat wielu agentów
Do komunikacji agent-agent:
[CODE BLOCK]
Najlepsze praktyki
> [!TIP]
> - Odpytywać między wywołaniami narzędzi — nie w ciasnej pętli
> - Potwierdzać natychmiast — człowiek wie, że wiadomość dotarła
> - Przetwarzać asynchronicznie — nie blokować na długiej pracy
> - Używać webhooków dla czasu rzeczywistego — odpytywanie ma opóźnienie
> - Nie odpytywać częściej niż raz na 5 sekund — marnuje wywołania API
Częste problemy
Utrata wiadomości
- automatycznie oznacza wiadomości jako przeczytane
- Jeśli się ich nie przetworzy, są stracone
- Rozwiązanie: Zawsze przetwarzać wiadomości przed powrotem
Duplikaty odpowiedzi
- Jeśli obsługa się zawiesi, może odpowiedzieć dwa razy
- Rozwiązanie: Uczynić obsługę idempotentną (sprawdzać, czy już odpowiedziano)
Powolne odpowiedzi
- Odpytywanie co 60 s oznacza opóźnienie do 60 s
- Rozwiązanie: Odpytywać co 10-30 s lub używać webhooków
Następne kroki
- Chat API
- Wzorzec początku sesji
- Odzyskiwanie po błędach
────────────────────────────────────────────────────────────
# Odzyskiwanie po błędach dla agentów
SUMMARY: Jak agenty LLM powinny obsługiwać błędy i od nich odzyskiwać — ponowienie, zapis, nauka.
Odzyskiwanie po błędach dla agentów
Błędy się zdarzają. Sieci zawodzą, API zwracają 500, Mind Key wygasają. Ten
przewodnik pokazuje, jak agenty LLM powinny obsługiwać błędy z gracją i uczyć się
na nich.
Zasady obsługi błędów
1. Ponowienie z wycofywaniem — błędy przejściowe często ustępują
2. Zapisanie błędu — nauka z wzorców
3. Skradzona degradacja — nie zawieszać całej sesji
4. Powiadomienie człowieka — o błędach, których nie da się rozwiązać
Obsługa błędów HTTP
Ponowienie z wykładniczym wycofywaniem
[CODE BLOCK]
Obsługa błędów autoryzacji
[CODE BLOCK]
Zapisywanie błędów jako wspomnień
Gdy występują błędy, zapisywać je, aby przyszłe sesje mogły się uczyć:
[CODE BLOCK]
Typowe scenariusze błędów
Scenariusz 1: nieprawidłowy Mind Key
[CODE BLOCK]
Scenariusz 2: błąd sieci
[CODE BLOCK]
Scenariusz 3: limit żądań
[CODE BLOCK]
Scenariusz 4: błąd serwera (5xx)
[CODE BLOCK]
Scenariusz 5: wywołanie narzędzia nie udaje się
[CODE BLOCK]
Wzorzec: wyłącznik
Dla powtarzających się błędów tymczasowo przestać próbować:
[CODE BLOCK]
Najlepsze praktyki
> [!TIP]
> - Zawsze ponawiać błędy przejściowe — sieci zawodzą, serwery czkają
> - Nie ponawiać błędów klienta (4xx) — same się nie naprawią
> - Zapisywać błędy jako wspomnienia — uczyć się z wzorców
> - Powiadamiać ludzi o krytycznych błędach — muszą wiedzieć
> - Degradować z gracją — częściowa praca lepsza niż zawieszenie
> - Używać wyłączników — nie bombardować usługi, która zawodzi
Następne kroki
- Dokumentacja błędów API
- Wzorzec początku sesji
- Testy samonaprawiające
────────────────────────────────────────────────────────────
# Strategia tagowania pamięci
SUMMARY: Jak tagować wspomnienia do skutecznego wyszukiwania i filtrowania — system tagowania, który się skaluje.
Strategia tagowania pamięci
Tagi są sekretem skalowalnego pobierania wspomnień. Ten przewodnik pokazuje, jak
tagować wspomnienia, aby właściwe wracały we właściwym czasie.
Dlaczego tagi mają znaczenie
Bez tagów ma się płaskie wyszukiwanie pełnotekstowe. Z tagami ma się
ustrukturyzowaną nawigację:
[CODE BLOCK]
Tagi umożliwiają:
- Szybkie filtrowanie —
- Wyszukiwanie w zakresie —
- Grupowanie — znalezienie wszystkich wspomnień „mistake" dla projektu
- Odsyłanie krzyżowe — wspomnienia współdzielące tagi są powiązane
Schemat tagowania
Tagi projektów
Używać nazw projektów jako tagów:
[CODE BLOCK]
Tagi technologii
Używać nazw technologii:
[CODE BLOCK]
Tagi tematyczne
Używać kategorii tematycznych:
[CODE BLOCK]
Tagi statusu
Używać wskaźników statusu:
[CODE BLOCK]
Tagi typów
Używać wskaźników typów:
[CODE BLOCK]
Zasady tagowania
Zasada 1: 2-5 tagów na wspomnienie
Zbyt mało tagów = słaba wykrywalność. Zbyt wiele = szum.
[CODE BLOCK]
Zasada 2: małe litery, z myślnikami
[CODE BLOCK]
Zasada 3: używać spójnego słownictwa
Ustanowić słownik tagowania i się go trzymać:
[CODE BLOCK]
Zasada 4: tagować z intencją wyszukiwania
Zapytać: „Jak będę szukać tego wspomnienia?"
[CODE BLOCK]
Wzorce
Wzorzec 1: projekt + temat
[CODE BLOCK]
Wyszukiwanie: (wszystkie wspomnienia projektu Synapse)
Wyszukiwanie: (wspomnienia wdrożeniowe w Synapse)
Wzorzec 2: typ + domena
[CODE BLOCK]
Wyszukiwanie: (wszystkie błędy)
Wyszukiwanie: (błędy wdrożeniowe)
Wzorzec 3: hierarchiczny
Dla podprojektów w projekcie:
[CODE BLOCK]
Wyszukiwanie: (cały Synapse)
Wyszukiwanie: (tylko podprojekt dokumentów)
Wzorzec 4: śledzenie statusu
[CODE BLOCK]
Typowe przypadki użycia
Znalezienie wszystkich decyzji o projekcie
[CODE BLOCK]
Znalezienie wszystkich błędów w domenie
[CODE BLOCK]
Znalezienie aktywnej pracy
[CODE BLOCK]
Znalezienie wspomnień o technologii
[CODE BLOCK]
Utrzymanie tagów
Okresowy przegląd
[CODE BLOCK]
Scalanie tagów
Jeśli istnieją niespójne tagi ( i ), scalić je:
[CODE BLOCK]
Najlepsze praktyki
> [!TIP]
> - Ustanowić słownik wcześnie — spójne tagi od pierwszego dnia
> - Tagować z intencją wyszukiwania — jak to znajdziesz później?
> - 2-5 tagów to złoty środek — zbyt mało lub zbyt wiele jest złe
> - Małe litery + myślniki — , nie
> - Przeglądać okresowo — scalać duplikaty, usuwać nieużywane
Następne kroki
- Najlepsze praktyki pamięci
- Wyszukiwanie FTS5
- Przepływ oparty na zadaniach
────────────────────────────────────────────────────────────
# Wzorzec początku sesji
SUMMARY: Kanoniczna sekwencja początkowa, którą powinien stosować każdy agent 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.
Wzorzec początku sesji
Każda sesja agenta LLM powinna podążać za kanoniczną sekwencją startową. Pominięcie
kroków prowadzi do utraty kontekstu, przeoczenia wiadomości i zapomnienia zadań.
Wzorzec
[CODE BLOCK]
Implementacja
Krok 1: recall wszystkich wspomnień
> [!CRITICAL]
> To najważniejsze wywołanie. Bez niego agent nie ma pamięci przeszłych sesji.
[CODE BLOCK]
Zwraca tekstowe podsumowanie wszystkich wspomnień, posortowane po priorytecie.
Krok 2: odpytanie o nieprzeczytane wiadomości czatu
[CODE BLOCK]
Zwraca nieprzeczytane wiadomości od człowieka. Automatycznie oznacza je jako
przeczytane.
Krok 3: sprawdzenie zadań w toku
[CODE BLOCK]
Zwraca zadania, nad którymi pracowano w ostatniej sesji.
Krok 4: budowa kontekstu
Połączyć trzy odpowiedzi w system prompt:
[CODE BLOCK]
Krok 5: przetworzenie oczekujących elementów
[CODE BLOCK]
Pełny przykład
[CODE BLOCK]
Częste błędy
> [!WARNING]
> - Pomijanie recall — start bez kontekstu, powtarzanie przeszłych błędów
> - Zapominanie o odpytaniu czatu — wiadomości człowieka pozostają bez odpowiedzi
> - Ignorowanie aktywnych zadań — praca zostaje zapomniana w połowie wykonania
> - Brak zapisów — sesja nie tworzy trwałej wartości
Wariacje
Wzorzec minimalny (LLM z małym kontekstem)
Dla LLM z małymi oknami kontekstu pominąć pełny recall:
[CODE BLOCK]
Następnie wyszukiwać konkretne tematy w razie potrzeby:
[CODE BLOCK]
Wzorzec agresywny (agenty długotrwałe)
Dla agentów uruchomionych przez wiele godzin dodać okresowy ponowny recall:
[CODE BLOCK]
Następne kroki
- Strategia tagowania pamięci
- Przepływ oparty na zadaniach
- Wzorzec odpytywania czatu
────────────────────────────────────────────────────────────
# Przepływ oparty na zadaniach
SUMMARY: Wykorzystanie zadań Synapse do napędzania wieloetapowych przepływów LLM, które przetrwają między sesjami.
Przepływ oparty na zadaniach
Zadania to nie tylko todo — to kręgosłup trwałych przepływów LLM. Tworząc zadania
dla wieloetapowej pracy, zapewnia się ciągłość między sesjami i dostarcza ścieżki
audytowe tego, co zrobiono.
Dlaczego przepływ oparty na zadaniach?
Bez zadań:
- LLM zaczyna każdą sesję niepewny, co robić
- Wieloetapowa praca jest zapominana w połowie wykonania
- Brak zapisu tego, co zostało zrobione
Z zadaniami:
- LLM natychmiast wznawia zadania w toku
- Wieloetapowa praca przetrwa między sesjami
- Wbudowana ścieżka audytowa całej pracy
Wzorzec
[CODE BLOCK]
Implementacja
Krok 1: utworzenie zadania dla wieloetapowej pracy
[CODE BLOCK]
Krok 2: śledzenie postępu w opisie zadania
[CODE BLOCK]
Krok 3: wznawianie między sesjami
[CODE BLOCK]
Krok 4: ukończenie i archiwizacja
[CODE BLOCK]
Pełny przykład: przepływ wdrożenia
[CODE BLOCK]
Hierarchia zadań
Dla złożonej pracy używać relacji zadań nadrzędnych-podrzędnych:
[CODE BLOCK]
Wyszukiwanie podzadań:
[CODE BLOCK]
Przepływ statusu
[CODE BLOCK]
Pending
Zadanie utworzone, ale nierozpoczęte. Używać do planowanej pracy.
In Progress
Obecnie realizowane. Aktualizować opis o postęp.
Done
Ukończone pomyślnie. Opis powinien zawierać podsumowanie.
Cancelled
Porzucone. Opis powinien zawierać powód.
Najlepsze praktyki
> [!TIP]
> - Tworzyć zadania dla wieloetapowej pracy — jednoetapowa praca nie wymaga zadania
> - Aktualizować opis o postęp — umożliwia wznowienie
> - Używać wysokiego priorytetu dla aktywnej pracy — wyróżnia się w recall
> - Ukończyć zadania po zrobieniu — nie zostawiać ich w inprogress
> - Zapisywać podsumowania ukończenia jako wspomnienia — długoterminowe odniesienie
Typowe wzorce
Wzorzec: przepływ naprawy błędu
[CODE BLOCK]
Wzorzec: przepływ badawczy
[CODE BLOCK]
Następne kroki
- Wzorzec początku sesji
- Wzorzec odpytywania czatu
- Odzyskiwanie po błędach
## KATEGORIA: NAJCZĘSTSZE PYTANIA
Najczęstsze pytania i typowe problemy.
────────────────────────────────────────────────────────────
# FAQ API
SUMMARY: Częste pytania o API — autoryzacja, limity, obsługa błędów, wykrywanie endpointów.
FAQ API
Częste pytania dotyczące API Synapse.
Jak się autoryzować?
Dwie metody:
1. Mind Key (dla endpointów danych):
2. JWT (dla endpointów konta):
Lub przez parametr zapytania (limit 60 żądań/min):
Patrz Autoryzacja.
Jaka jest różnica między Mind Key a JWT?
- Mind Key: zakres dzierżawcy, nigdy nie wygasa, do danych memory/chat/tasks
- JWT: zakres użytkownika, wygasa po 7 dniach, do zarządzania kontem/umysłami
Patrz Mind Key vs JWT.
Dlaczego otrzymuję 401 Unauthorized?
Typowe przyczyny:
1. Brak nagłówka
2. Nieprawidłowy Mind Key (zweryfikować, czy zaczyna się od )
3. Użycie JWT tam, gdzie wymagany jest Mind Key (lub odwrotnie)
4. Mind Key został cofnięty
Rozwiązanie: Zweryfikować token. Patrz Autoryzacja.
Dlaczego otrzymuję 404 Not Found?
Użyto błędnej ścieżki endpointu. Synapse ma tylko ścieżki wymienione w
.
Rozwiązanie: Wywołać , aby zobaczyć wszystkie poprawne ścieżki.
Nie zgadywać.
Dlaczego otrzymuję 429 Too Many Requests?
Używana jest autoryzacja parametrem zapytania , która ma limit 60/min.
Rozwiązanie: Przełączyć się na nagłówek (bez limitu).
Patrz Limity żądań.
Jak wylistować wszystkie endpointy?
[CODE BLOCK]
Jak znaleźć właściwy endpoint?
1. Sprawdzić dla listy czytelnej maszynowo
2. Sprawdzić dla pełnej dokumentacji API
3. Przeglądać w systemie dokumentacji
4. Użyć dla specyfikacji OpenAPI 3.0
Czy mogę użyć GET zamiast POST?
Niektóre endpointy POST mają odpowiedniki GET dla narzędzi obsługujących tylko
URL-e:
- ↔
- ↔
- ↔
Sprawdzić , aby zobaczyć dostępne warianty GET.
Jak obsługiwać błędy?
Wszystkie błędy zwracają JSON:
[CODE BLOCK]
Patrz Błędy i ich obsługa.
Jaki jest limit treści żądania?
10 MB. Dla większych payloadów (np. przesyłanie plików) należy użyć endpointów
multipart.
Czy API obsługuje CORS?
Tak. Wszystkie endpointy zwracają:
[CODE BLOCK]
Czy istnieje SDK?
Tak:
- Node.js:
- MCP:
Szczegóły w sekcji Przegląd API.
Jak paginować?
Użyć i :
[CODE BLOCK]
Domyślny limit: 100. Maksymalny: 500.
Czy mogę filtrować wspomnienia po kategorii lub tagu?
Tak:
[CODE BLOCK]
Jak wyszukiwać wspomnienia?
Dwa sposoby:
1. Wyszukiwanie słów kluczowych FTS5:
2. Wyszukiwanie semantyczne:
Patrz Wyszukiwanie FTS5 i Wyszukiwanie semantyczne.
Jak zaktualizować wspomnienie?
Wykonać POST z tym samym + — istniejące wspomnienie
jest aktualizowane, a nie duplikowane.
[CODE BLOCK]
Jak usunąć wspomnienie?
[CODE BLOCK]
Czy mogę usuwać masowo?
Tak:
[CODE BLOCK]
Następne kroki
- Przegląd API
- Błędy i ich obsługa
- Autoryzacja
────────────────────────────────────────────────────────────
# FAQ ogólne
SUMMARY: Częste pytania o Synapse — czym jest, jak działa, dla kogo.
FAQ ogólne
Częste pytania dotyczące Synapse.
Czym jest Synapse?
Synapse to API trwałej pamięci dla agentów LLM. Zapewnia asystentowi AI
stały, odpytywalny mózg, który przetrwa między sesjami. Zamiast zapominać
wszystko po zamknięciu czatu, LLM zapisuje i pobiera wspomnienia przez proste
API HTTP.
Więcej: Czym jest Synapse?
Dla kogo jest Synapse?
- Twórcy agentów LLM, którzy potrzebują trwałego stanu
- Zaawansowani użytkownicy uruchamiający lokalne LLM z własnymi agentami
- Zespoły budujące asystenty AI ze współdzieloną pamięcią
- Inżynierowie automatyzacji łączący wywołania LLM między sesjami
Czy Synapse jest darmowy?
Synapse jest hostowany pod adresem i darmowy do
użytku osobistego. W przypadku self-hostingu patrz repozytorium.
Czym Synapse różni się od pamięci ChatGPT?
| Cecha | Pamięć ChatGPT | Synapse |
|---------|---------------|---------|
| Magazyn | Serwery OpenAI | Własny serwer |
| Dostęp przez API | Nie | Tak (REST + MCP) |
| Wielodostępność | Nie | Tak (umysły) |
| Własne kategorie | Nie | Tak (8 kategorii) |
| Wyszukiwanie pełnotekstowe | Ograniczone | FTS5 + semantyczne |
| Self-hosting | Nie | Tak |
Z jakimi LLM współpracuje Synapse?
Z każdym LLM, który potrafi wykonywać wywołania HTTP lub używać MCP:
- Claude (Anthropic) — przez MCP lub bezpośrednie API
- GPT-4 / GPT-3.5 (OpenAI) — przez function calling + API
- Gemini (Google) — przez function calling + API
- Llama / Mistral (lokalnie) — przez własną integrację
- Dowolny LLM przez serwer MCP Synapse
Czy muszę hostować Synapse samodzielnie?
Nie. Wersja hostowana pod adresem jest dostępna
do użytku publicznego. Self-hosting jest opcjonalny (dla prywatności,
dostosowywania lub środowisk odciętych od sieci).
Ile danych mogę przechowywać?
Nie ma twardych limitów w wersji hostowanej. Typowe użycie:
- 100-1000 wspomnień na umysł
- 1-10 KB na wspomnienie (pole content)
- Łącznie: około 10 MB na umysł
Większa skala — self-hosting.
Czy moje dane są prywatne?
Tak. Każdy umysł jest izolowany (patrz Wielodostępność).
Inni użytkownicy nie widzą danych. Dostawca hostingu (Schaefer Services) ma
dostęp, ale nie przegląda danych użytkowników.
Maksymalna prywatność — self-hosting.
Czy mogę eksportować swoje dane?
Tak. Użyć , aby wyeksportować wszystkie wspomnienia jako
JSON. Patrz Kopia zapasowa i przywracanie.
Co się stanie, jeśli zgubię Mind Key?
Mind Key jest wyświetlany tylko raz przy tworzeniu. W razie utraty:
1. Zalogować się adresem e-mail/hasłem, aby uzyskać JWT
2. Utworzyć nowy umysł przez
3. Zapisać nowy Mind Key
4. (Opcjonalnie) Usunąć stary umysł przez
Nie można odzyskać wspomnień z umysłu, którego klucz został utracony.
Czy wiele agentów LLM może współdzielić umysł?
Tak. Wszyscy agenci używający tego samego Mind Key współdzielą dane tego umysłu.
Do skoordynowanej pracy wielu agentów patrz Koordynacja wielu agentów.
Czy Synapse działa offline?
Nie, Synapse wymaga połączenia internetowego z serwerem (hostowanym lub
self-hosted). Dla offline'owych LLM należy uruchomić Synapse lokalnie.
Jak szybkie jest wyszukiwanie wspomnień?
- Wyszukiwanie słów kluczowych FTS5: < 10 ms dla 1000 wspomnień
- Wyszukiwanie semantyczne: 50-100 ms dla 1000 wspomnień
- Pełny recall: < 50 ms dla 1000 wspomnień
Patrz Wyszukiwanie FTS5.
Czy mogę używać Synapse bez LLM?
Tak. Synapse to ogólne API pamięci. Można z niego korzystać z dowolnej aplikacji,
która korzysta z trwałego, przeszukiwalnego magazynu klucz-wartość z kategoriami
i tagami.
Następne kroki
- Czym jest Synapse?
- Szybki start
- FAQ API
────────────────────────────────────────────────────────────
# FAQ MCP
SUMMARY: Częste pytania o integrację MCP — narzędzia, transporty, rozwiązywanie problemów.
FAQ MCP
Częste pytania dotyczące serwera MCP Synapse.
Czym jest MCP?
MCP (Model Context Protocol) to otwarty standard Anthropic dla integracji LLM z
narzędziami. Zamiast wklejać dokumentację API do promptów, rejestruje się
narzędzia w serwerze MCP, a LLM wywołuje je jako funkcje natywne.
Patrz Czym jest MCP?.
Ile narzędzi udostępnia Synapse MCP?
79 narzędzi w 12 kategoriach: memory, chat, scheduler, tasks, scripts,
computers, push, user, utility, visualization, sharing, webhooks, browser.
Pełna lista w sekcji Czym jest MCP?.
Które klienty MCP są obsługiwane?
- Claude Desktop (macOS, Windows)
- Claude Code (terminal)
- Cursor (IDE)
- Continue.dev (VS Code, JetBrains)
- Cline (VS Code)
- Dowolny klient zgodny z MCP
Przykłady konfiguracji w sekcji Konfiguracja Claude Desktop.
Jakie transporty są obsługiwane?
1. stdio (lokalny, zalecany dla komputerów biurkowych)
2. HTTP/SSE (zdalny, wielodostępny)
3. WebSocket (mobilny, duży ruch)
Jak skonfigurować Claude Desktop?
Edytować :
[CODE BLOCK]
Patrz Konfiguracja Claude Desktop.
Dlaczego narzędzia nie pojawiają się w Claude Desktop?
1. W pełni zrestartować Claude Desktop (Cmd+Q na macOS)
2. Sprawdzić, czy plik konfiguracyjny jest poprawnym JSON-em
3. Zweryfikować Node.js 18+ zainstalowany
4. Sprawdzić logi MCP:
Patrz Rozwiązywanie problemów MCP.
Jak używać innego umysłu?
Zmienić w konfiguracji MCP i zrestartować klienta.
Dla wielu umysłów uruchomić wiele instancji serwera MCP z różnymi Mind Key.
Czy mogę ograniczyć, które narzędzia są udostępniane?
Tak, użyć Profili narzędzi:
- : 8 narzędzi złożonych (około 500 tokenów)
- : 25 narzędzi (około 2 500 tokenów)
- : 119 narzędzi (około 8 250 tokenów, domyślnie)
Ustawić przez zmienną środowiskową lub nagłówek .
Jak debugować problemy MCP?
1. Uruchomić serwer MCP ręcznie:
2. Sprawdzić logi klienta (różne w zależności od klienta)
3. Zweryfikować działanie Mind Key:
4. Sprawdzić kondycję Synapse:
Patrz Rozwiązywanie problemów MCP.
Czy serwer MCP jest darmowy?
Tak. Pakiet npm jest open source. Hostowany serwer MCP pod
adresem jest darmowy do użytku publicznego.
Czy mogę hostować serwer MCP samodzielnie?
Tak:
[CODE BLOCK]
Czym MCP różni się od bezpośrednich wywołań API?
| Aspekt | Bezpośrednie API | MCP |
|--------|-----------|-----|
| LLM musi znać | URL-e, nagłówki, autoryzację | Tylko nazwy narzędzi |
| Obsługa autoryzacji | Ręczna | Automatyczna (zmienna środowiskowa) |
| Wykrywanie narzędzi | Czytanie /endpoints | Automatyczne przez protokół MCP |
| Obsługa błędów | Ręczna | Ustandaryzowana |
| Najlepsze do | Niestandardowych integracji | Agentów LLM |
Czy mogę zbudować własnego klienta MCP?
Tak. Użyć oficjalnego SDK MCP:
- TypeScript:
- Python:
Patrz Niestandardowy klient MCP.
Jak zgłaszać błędy MCP?
Otworzyć zgłoszenie:
Dołączyć:
- Wersję serwera MCP
- Nazwę i wersję klienta
- System operacyjny
- Istotne logi
- Kroki reprodukcji
Następne kroki
- Czym jest MCP?
- Konfiguracja Claude Desktop
- Rozwiązywanie problemów MCP
────────────────────────────────────────────────────────────
# FAQ — rozwiązywanie problemów
SUMMARY: Rozwiązania częstych problemów Synapse — autoryzacja, sieć, dane, wdrożenie.
FAQ — rozwiązywanie problemów
Rozwiązania częstych problemów Synapse.
Nie mogę się zalogować
Symptomy
- zwraca 401
- „Invalid email or password"
Rozwiązania
1. Zweryfikować poprawność e-maila — wielkość liter ma znaczenie
2. Sprawdzić hasło — minimum 6 znaków
3. Najpierw zarejestrować, jeśli nie ma konta:
4. Zresetować hasło (jeśli skonfigurowano SMTP) przez interfejs WWW
Zgubiłem Mind Key
Symptomy
- Brak dostępu do wspomnień
- Mind Key został usunięty/zgubiony
Rozwiązania
Mind Key nie można odzyskać. Należy:
1. Zalogować się, aby uzyskać JWT:
2. Wylistować umysły: (z JWT)
3. Utworzyć nowy umysł:
4. Zapisać nowy Mind Key
5. (Opcjonalnie) Usunąć stary umysł:
Dane w starym umyśle są utracone, chyba że Mind Key zostanie odnaleziony.
Wywołania API zwracają 401
Symptomy
- Wszystkie wywołania API zwracają 401 Unauthorized
- „Mind Key fehlt oder ungültig"
Rozwiązania
1. Zweryfikować format nagłówka:
2. Sprawdzić, czy Mind Key zaczyna się od (nie , które to JWT)
3. Przetestować bezpośrednio:
[CODE BLOCK]
4. Mind Key może być cofnięty — utworzyć nowy umysł
Patrz Autoryzacja.
Wywołania API zwracają 404
Symptomy
- 404 Not Found
- „Route not found"
Rozwiązania
> [!CRITICAL]
> Nie wolno zgadywać ścieżek endpointów. Istnieją tylko ścieżki w .
1. Sprawdzić poprawne endpointy:
2. Porównać URL dokładnie — wielkość liter ma znaczenie, bez końcowych ukośników
3. Sprawdzić metodę HTTP — i to różne endpointy
Wywołania API zwracają 429
Symptomy
- 429 Too Many Requests
- „Rate limit exceeded"
Rozwiązania
1. Przełączyć się na autoryzację nagłówkiem (bez limitu):
[CODE BLOCK]
2. Odczekać sekund, jeśli trzeba użyć
Patrz Limity żądań.
Wyszukiwanie wspomnień nie zwraca wyników
Symptomy
- zwraca puste
- Wspomnienia na pewno istnieją
Rozwiązania
1. Zweryfikować istnienie wspomnień:
2. Sprawdzić składnię wyszukiwania — FTS5 ma specyficzną składnię
3. Spróbować prostszego zapytania — zamiast
4. Użyć wyszukiwania semantycznego do zapytań koncepcyjnych:
Patrz Wyszukiwanie FTS5.
Wspomnienia nie utrwalają się
Symptomy
- POST /memory zwraca sukces
- GET /memory/recall nie pokazuje ich
Rozwiązania
1. Zweryfikować ten sam Mind Key — różne klucze = różne umysły
2. Sprawdzić odpowiedź — POST zwraca
3. Spróbować GET /memory (lista JSON) zamiast /memory/recall (tekst)
4. Sprawdzić filtr — lub mogą je ukrywać
Narzędzia nie pojawiają się w Claude Desktop
Symptomy
- Claude Desktop pokazuje 0 narzędzi
- Brak ikony 🔌
Rozwiązania
1. W pełni zrestartować Claude Desktop (Cmd+Q)
2. Zweryfikować, czy plik konfiguracyjny jest poprawnym JSON-em
3. Sprawdzić Node.js 18+ zainstalowany
4. Uruchomić MCP ręcznie:
5. Sprawdzić logi:
Patrz Rozwiązywanie problemów MCP.
Synapse jest offline
Symptomy
- Nie można dotrzeć do synapse.schaefer.zone
- curl przekracza czas oczekiwania
Rozwiązania
1. Sprawdzić połączenie internetowe — spróbować innej strony
2. Sprawdzić kondycję Synapse:
3. Poczekać — może to być tymczasowa awaria lub wdrożenie
4. Sprawdzić stronę statusu (jeśli dostępna)
Dla self-hosted: sprawdzić status kontenera Docker, połączenie z bazą danych.
Błędy bazy danych
Symptomy
- 500 Internal Server Error
- „Database connection failed"
Rozwiązania
Dla self-hosted:
1. Sprawdzić, czy PostgreSQL działa:
2. Sprawdzić DATABASEURL w środowisku
3. Sprawdzić migracje:
4. Sprawdzić miejsce na dysku:
Dla hostowanej wersji: zgłosić do wsparcia.
Webhook się nie wyzwala
Symptomy
- Zarejestrowany webhook, ale brak wywołań zwrotnych
- Brak POST pod podany URL
Rozwiązania
1. Zweryfikować osiągalność URL:
2. Sprawdzić filtr zdarzeń — pasuje do wszystkich zdarzeń pamięci
3. Przetestować webhook:
4. Sprawdzić, czy webhook jest włączony:
5. Zweryfikować SSL — Synapse wymaga ważnego HTTPS dla URL-i webhooków
Patrz Webhooks API.
Zadanie cron się nie uruchamia
Symptomy
- Utworzono zadanie cron, ale się nie wyzwala
- się nie aktualizuje
Rozwiązania
1. Sprawdzić składnię harmonogramu — musi być poprawny cron 5-polowy lub liczba całkowita sekund
2. Zweryfikować, czy endpoint jest dozwolony — musi być http(s), bez prywatnych IP
3. Sprawdzić, czy zadanie jest włączone:
4. Poczekać na następny zaplanowany czas — cron nie jest natychmiastowy
Patrz Cron i Scheduler.
Potrzebna dalsza pomoc?
1. Sprawdzić istniejącą dokumentację:
2. Przeszukać dokumentację:
3. Otworzyć zgłoszenie:
4. Kontakt: patrz strona
Następne kroki
- Błędy i ich obsługa
- FAQ API
- Rozwiązywanie problemów MCP