# 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