# Memory API

Memory API adalah jantung Synapse. API ini menyediakan 22 endpoint untuk
menyimpan, mengambil, mencari, dan mengelola memori terstruktur. Semua endpoint
memerlukan Mind Key untuk autentikasi.

> [!CRITICAL]
> **Selalu panggil `GET /memory/recall` di awal setiap sesi.** Ini adalah
> satu-satunya cara untuk membangun kembali konteks dari sesi sebelumnya.

## Kategori

Memori diorganisasi ke dalam 8 kategori:

| Kategori | Kasus Penggunaan |
|----------|----------|
| `identity` | Nama pengguna, peran, info kontak, preferensi tentang diri sendiri |
| `preference` | Suka, tidak suka, gaya kerja, preferensi komunikasi |
| `fact` | Fakta yang dapat diverifikasi (detail proyek, tanggal, URL) |
| `project` | Status proyek, milestone, arsitektur |
| `skill` | Hal-hal yang dikuasai pengguna |
| `mistake` | Error masa lalu — hindari pengulangan |
| `context` | Konteks yang relevan dengan sesi |
| `note` | Catatan lain-lain |

## Prioritas

- `low` — bagus untuk diketahui
- `normal` — default
- `high` — penting
- `critical` — tidak boleh dilupakan (identitas pengguna, info hukum)

## Endpoint Inti

### GET /memory/recall

Mengembalikan SEMUA memori sebagai teks polos yang dioptimalkan untuk LLM. Panggil ini di setiap awal sesi.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall
```

Respons (text/plain):

```
Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

...
```

### POST /memory

Menyimpan memori baru atau memperbarui yang sudah ada (kategori + key yang sama = pembaruan).

```bash
curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "fact",
    "key": "user_name",
    "content": "The user's name is Michael Schäfer",
    "tags": ["person", "identity"],
    "priority": "critical"
  }'
```

Respons: `{ "id": "mem_001", "status": "stored" }`

### GET /memory

Mendaftar memori dengan filter opsional.

```bash
# Semua memori (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filter berdasarkan kategori
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# Filter berdasarkan tag
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

Memperbarui memori tertentu berdasarkan ID.

```bash
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'
```

### DELETE /memory/:id

Menghapus satu memori.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## Endpoint Pencarian

### GET /memory/search

Pencarian teks penuh menggunakan FTS5.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=docker+swarm"
```

Sintaks FTS5:

- Beberapa kata = AND: `docker swarm`
- Frasa: `"docker swarm"`
- Prefix: `docker*`
- Boolean: `docker OR kubernetes`
- Pengecualian: `docker -swarm`

### GET /memory/semantic-search

Pencarian konseptual menggunakan embeddings (lebih lambat dari FTS5 tetapi memahami makna).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"
```

Mengembalikan memori yang mirip secara semantik dengan kueri, meskipun tidak ada
kata kunci yang cocok. Berguna untuk "temukan memori tentang X" di mana X
dideskripsikan secara berbeda.

### GET /memory/by-tag

Mendaftar memori berdasarkan tag.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"
```

### GET /memory/related/:id

Menemukan memori yang terkait dengan memori tertentu (melalui tag bersama).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001
```

## Sinkronisasi & Diff

### GET /memory/diff

Sinkronisasi inkremental — mengembalikan memori yang berubah sejak timestamp tertentu.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"
```

Respons: `{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

Menerapkan diff dari instansi lain (untuk sinkronisasi self-hosted).

```bash
curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'
```

## Operasi Massal

### POST /memory/bulk-delete

Menghapus beberapa memori berdasarkan ID.

```bash
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

### POST /memory/embed-batch

Membuat embeddings untuk memori yang belum memilikinya (untuk pencarian semantik).

```bash
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'
```

### GET /memory/embed-batch-status

Memeriksa kemajuan pembuatan embedding.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## Verifikasi

Memori memiliki flag `verified`. Memori yang disimpan agen defaultnya tidak
terverifikasi (`source=agent`); memori yang disimpan manusia terverifikasi
(`source=user`).

### POST /memory/verify

Menandai memori sebagai terverifikasi (memerlukan JWT, bukan Mind Key).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"
```

### POST /memory/unverify

Menandai memori sebagai tidak terverifikasi (memerlukan JWT).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \
  -H "Authorization: Bearer YOUR_JWT"
```

### GET /memory/unverified

Mendaftar memori yang menunggu verifikasi manusia.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"
```

## Statistik & Audit

### GET /memory/stats

Statistik agregat untuk mind saat ini.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/stats
```

Mengembalikan: `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

Log audit dari semua operasi yang mengubah state.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"
```

### GET /memory/contradictions

Mendeteksi potensi kontradiksi dalam memori yang disimpan.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/contradictions
```

### GET /memory/expiring

Mendaftar memori dengan tanggal kedaluwarsa yang mendekat.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"
```

## Health & Export

### GET /memory/health

Pemeriksaan health cepat untuk sistem memori.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/health
```

### GET /memory/mind-export

Ekspor JSON lengkap dari semua memori (untuk backup).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mind-export > backup.json
```

### POST /memory/compact

Mengompak memori yang mirip (ringkasan otomatis).

```bash
curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

## Langkah Berikutnya

- [Quick Start untuk LLM](/docs/getting-started/quick-start-llm)
- [Praktik Terbaik Memori](/docs/guides/memory-best-practices)
- [Pencarian FTS5](/docs/concepts/fts5-search)
- [Pencarian Semantik](/docs/concepts/semantic-search)