# Model Memori

Model memori Synapse dirancang untuk agen LLM — cukup terstruktur untuk recall
yang andal, cukup fleksibel untuk domain apa pun.

## Anatomi Memori

```json
{
  "id": "mem_abc123",
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed on vps1. CI green.",
  "tags": ["synapse", "deployment", "v1.5.0"],
  "priority": "high",
  "source": "agent",
  "verified": false,
  "confidence": 0.85,
  "expires_at": null,
  "mind_id": "m_xyz789",
  "created_at": "2026-06-27T...",
  "updated_at": "2026-06-27T..."
}
```

## Field

| Field | Tipe | Wajib | Deskripsi |
|-------|------|----------|-------------|
| `id` | string | otomatis | ID unik (mem_xxx) |
| `category` | enum | ✅ | Salah satu dari 8 kategori |
| `key` | string | ✅ | Identifier stabil (digunakan untuk pembaruan) |
| `content` | string | ✅ | Konten memori (teks apa pun) |
| `tags` | string[] | – | Untuk pencarian dan pemfilteran |
| `priority` | enum | – | low, normal, high, critical (default: normal) |
| `source` | enum | otomatis | user, agent (siapa yang menyimpan) |
| `verified` | bool | otomatis | Apakah manusia telah memverifikasi ini? |
| `confidence` | float | – | 0.0 hingga 1.0 (default: 1.0 untuk user, 0.7 untuk agent) |
| `expires_at` | timestamp | – | Kapan harus melupakan memori ini |
| `mind_id` | string | otomatis | Mind mana yang memilikinya |
| `created_at` | timestamp | otomatis | Pertama disimpan |
| `updated_at` | timestamp | otomatis | Terakhir dimodifikasi |

## Kategori

Delapan kategori mencakup kasus penggunaan agen LLM umum:

| Kategori | Tujuan | Contoh Konten |
|----------|---------|-----------------|
| `identity` | Siapa pengguna | "User is Michael Schäfer, software engineer in Berlin" |
| `preference` | Preferensi pengguna | "Prefers concise technical responses" |
| `fact` | Fakta yang dapat diverifikasi | "Office is in Berlin, timezone Europe/Berlin" |
| `project` | Status proyek | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| `skill` | Keahlian pengguna | "Advanced Python, 10+ years" |
| `mistake` | Error masa lalu | "Forgot to bump npm version — CI failed" |
| `context` | Konteks sesi | "Currently reviewing PR #42" |
| `note` | Catatan lain-lain | "Try Redis for caching next sprint" |

## Key: Identifier Stabil

Field `key` sangat penting — ini adalah cara Anda memperbarui memori tanpa
membuat duplikat.

```python
# First store
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Update with same key (overwrites, doesn't duplicate)
store("project", "project_synapse_status", "v1.5.0 deployed", priority="high")
```

**Aturan key:**

- Harus unik dalam (category, mind)
- Gunakan `snake_case`
- Awali dengan kategori untuk kejelasan: `preference_communication`, `mistake_npm_version`
- Tetap stabil — jangan mengubah key setelah dibuat

## Tag: Untuk Pencarian

Tag memungkinkan pemfilteran dan pencarian cepat:

```bash
# Find all memories with tag "docker"
GET /memory/by-tag?tag=docker

# FTS5 search within tagged subset
GET /memory/search?q=swarm&tag=docker
```

**Praktik terbaik tag:**

- 2-5 tag per memori (jangan terlalu banyak tag)
- Huruf kecil untuk konsistensi
- Gunakan nama proyek, topik, teknologi
- Tag tidak case-sensitive

## Level Prioritas

| Prioritas | Kapan Menggunakan | Perilaku Recall |
|----------|-------------|-----------------|
| `critical` | Identitas, hukum, ireversibel | Selalu di atas recall |
| `high` | Proyek aktif, preferensi utama | Menonjol dalam recall |
| `normal` | Sebagian besar memori (default) | Urutan recall standar |
| `low` | Efemeral, bagus untuk diketahui | Mungkin diringkas |

`/memory/recall` mengurutkan berdasarkan prioritas (critical pertama), lalu berdasarkan kebaruan.

## Source: User vs Agent

Memori ditandai dengan `source`:

- `user` — disimpan oleh manusia (melalui JWT atau UI manusia)
- `agent` — disimpan oleh agen LLM (melalui Mind Key)

Ini memengaruhi:

- **Verifikasi:** memori `user` otomatis terverifikasi, memori `agent` tidak
- **Confidence:** `user` default 1.0, `agent` 0.7
- **Recall:** `/memory/recall` menandai memori yang belum terverifikasi dengan "(unverified)"

> [!NOTE]
> Perlakukan memori sumber `agent` dengan skeptisisme yang sesuai. Mereka mungkin
> disimpulkan atau diasumsikan daripada dinyatakan langsung oleh pengguna.

## Verifikasi

Flag `verified` menunjukkan manusia telah mengonfirmasi memori:

- Memori `user`: otomatis terverifikasi (`true`)
- Memori `agent`: default belum terverifikasi (`false`)

Verifikasi memori melalui:

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

> [!NOTE]
> Verifikasi memerlukan JWT (autentikasi manusia), bukan Mind Key (autentikasi
> agen). Ini memastikan hanya manusia yang dapat menandai memori sebagai terverifikasi.

## Confidence

Field `confidence` (0.0 hingga 1.0) menunjukkan seberapa andal memori tersebut:

- 1.0 — dinyatakan langsung oleh pengguna
- 0.7 — disimpulkan oleh agen
- 0.5 — tidak pasti, perlu verifikasi
- 0.0 — secara eksplisit diragukan

Tetapkan confidence saat menyimpan:

```json
{
  "category": "preference",
  "key": "prefers_dark_mode",
  "content": "User seems to prefer dark mode (based on their IDE screenshots)",
  "confidence": 0.5,
  "source": "agent"
}
```

## Kedaluwarsa

Tetapkan `expires_at` untuk memori yang sensitif terhadap waktu:

```json
{
  "category": "context",
  "key": "current_meeting_topic",
  "content": "Discussing Q3 roadmap",
  "expires_at": "2026-06-28T00:00:00Z"
}
```

Memori kedaluwarsa tidak dikembalikan oleh `/memory/recall` (tetapi masih ada di DB).
Gunakan `/memory/expiring?within=7d` untuk melihat memori yang akan segera kedaluwarsa.

## Siklus Hidup Memori

```
                  ┌─────────────────┐
                  │     Create      │
                  │  POST /memory   │
                  └────────┬────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │     Active      │ ◀──── PUT /memory/:id (update)
                  │  (in recall)    │
                  └────────┬────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Expired  │ │ Verified │ │ Deleted  │
        │ (in DB)  │ │ (flag)   │ │ (gone)   │
        └──────────┘ └──────────┘ └──────────┘
```

## Perilaku Recall

`GET /memory/recall` mengembalikan ringkasan teks polos yang dioptimalkan untuk konteks LLM:

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

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

[002] preference (HIGH) [verified]
  communication_style
  Prefers concise technical responses
  Tags: communication

[003] project (HIGH) [unverified]
  synapse_status
  v1.5.0 deployed, working on v1.6.0 docs
  Tags: synapse, deployment

...
```

- Diurutkan berdasarkan prioritas (critical → low), lalu berdasarkan kebaruan
- Memori yang belum terverifikasi ditandai dengan `[unverified]`
- Tag disertakan untuk konteks
- Teks polos (tidak perlu parsing JSON)

## Langkah Berikutnya

- [Memory API](/docs/api/memory)
- [Praktik Terbaik Memori](/docs/guides/memory-best-practices)
- [Pencarian FTS5](/docs/concepts/fts5-search)