# Semantic Search (Embeddings)

Synapse รองรับ semantic search โดยใช้ vector embedding ต่างจาก FTS5 (keyword matching) ตรงที่ semantic search หา memory ตาม **ความหมาย** — แม้ไม่มี keyword ตรงกัน

## วิธีการทำงาน

```
1. Memory stored → embedding generated → vector stored
2. Search query → embedding generated → vector compared
3. Cosine similarity → top N results returned
```

### embedding คืออะไร?

embedding เป็นการแทน text ด้วย numerical vector text ที่มีความหมายคล้ายกันจะมี vector คล้ายกัน Synapse สร้าง vector (เช่น 1536 มิติ) สำหรับเนื้อหา memory แต่ละรายการ

### Cosine similarity

เพื่อหา memory ที่คล้ายเชิง semantic Synapse คำนวณ cosine similarity ระหว่าง query vector และ memory vector แต่ละตัว similarity สูง = เกี่ยวข้องมากกว่า

## เมื่อใดควรใช้ Semantic Search

### ใช้ semantic search เมื่อ:

- คุณต้องการ "memory เกี่ยวกับ X" โดย X ถูกอธิบายต่างจากที่เก็บ
- FTS5 ไม่ส่งกลับผลลัพธ์ (ไม่มี keyword ตรง)
- คุณต้องการการจัดกลุ่มเชิงแนวคิด (เช่น memory "deployment" ทั้งหมด แม้บางอันพูดถึง "release")
- Query เป็นคำถาม: "เราจัดการ authentication อย่างไร?"

### ใช้ FTS5 เมื่อ:

- คุณรู้ keyword ที่แน่นอน
- คุณต้องการ logic boolean (AND, OR, NOT)
- คุณต้องการ response ในระดับ sub-millisecond
- คุณต้องการ phrase matching

## Endpoint

### GET /memory/semantic-search

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

Response:

```json
{
  "results": [
    {
      "id": "mem_001",
      "category": "project",
      "key": "project_synapse_deployment",
      "content": "Synapse deployed using Docker Swarm on vps1...",
      "tags": ["docker", "swarm", "deployment"],
      "similarity": 0.89
    },
    {
      "id": "mem_042",
      "category": "fact",
      "key": "kubernetes_cluster",
      "content": "We use Kubernetes for production orchestration...",
      "tags": ["kubernetes", "orchestration"],
      "similarity": 0.84
    }
  ]
}
```

## ตัวอย่าง

### หา memory เกี่ยวกับ deployment

```bash
# FTS5 might miss some — semantic catches all
curl .../memory/semantic-search?q=deployment+process
```

ส่งกลับ memory เกี่ยวกับ "deployment", "release", "publishing", "rolling out" ฯลฯ

### หารูปแบบ authentication

```bash
curl .../memory/semantic-search?q=how+do+users+log+in
```

ส่งกลับ memory เกี่ยวกับ login, auth, JWT, session management, OAuth ฯลฯ

### หา memory ที่คล้ายกัน

```bash
# Find memories similar to a specific one
curl .../memory/related/mem_001
```

ใช้ semantic similarity (ผ่าน tag ที่ใช้ร่วมกันและ embedding vector)

## การสร้าง Embedding

### เมื่อใดจะสร้าง embedding?

- **เมื่อเก็บ memory** — หาก embeddings service ถูกกำหนดค่า, embedding ถูกสร้างแบบ synchronous
- **Batch generation** — `POST /memory/embed-batch` สร้าง embedding สำหรับ memory ที่ยังไม่มี
- **Async update** — เมื่อเนื้อหาถูกอัปเดต, embedding ถูกสร้างใหม่

### Embedding provider

Synapse รองรับ embedding provider ที่กำหนดค่าได้:

- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)
- **Local model** (ผ่าน Ollama หรือคล้ายกัน)
- **Custom** (implement embeddings interface)

กำหนดค่าผ่าน environment variable:

```bash
EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_API_KEY=sk-...
EMBEDDINGS_MODEL=text-embedding-3-small
```

### การสร้างแบบ Batch

สำหรับ mind ที่มี memory หลายรายการที่ยังไม่มี embedding:

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

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

## ประสิทธิภาพ

| การดำเนินการ | Latency |
|-----------|---------|
| สร้าง embedding (OpenAI) | 100-200ms |
| Semantic search (1k memory) | 50-100ms |
| Semantic search (10k memory) | 200-500ms |
| การสร้างแบบ batch (100 memory) | 10-20s |

> [!NOTE]
> Semantic search ช้ากว่า FTS5 เนื่องจากการคำนวณ vector ใช้ FTS5 สำหรับ keyword ที่รู้ ใช้ semantic สำหรับ query เชิงแนวคิด

## ข้อจำกัด

### ต้นทุน embedding

หากใช้ OpenAI การสร้าง embedding มีค่าใช้จ่าย (~$0.02 ต่อ 1M token สำหรับ text-embedding-3-small) สำหรับ 10,000 memory เฉลี่ย 100 token ต่อรายการ ประมาณ $0.02 — น้อยมาก

### Cold start

memory ที่เก็บก่อนกำหนดค่า embedding จะไม่มี embedding รัน `POST /memory/embed-batch` เพื่อ backfill

### การพึ่งพา provider

หาก embedding provider ล่ม semantic search จะล้มเหลวอย่างนุ่มนวล (ส่งกลับผลลัพธ์ว่างหรือ error) FTS5 ยังทำงานได้

## เมื่อ Embedding ไม่พร้อมใช้งาน

หาก embeddings service ไม่ถูกกำหนดค่า:

- `GET /memory/semantic-search` ส่งกลับ 503 Service Unavailable
- `POST /memory` ยังทำงานได้ (เพียงแค่ไม่สร้าง embedding)
- FTS5 search ยังทำงานได้

## แนวทางปฏิบัติที่ดีที่สุด

> [!TIP]
> - **ใช้ semantic สำหรับ query เชิงแนวคิด** — "เราจัดการ X อย่างไร?"
> - **ใช้ FTS5 สำหรับคำเฉพาะ** — "docker swarm"
> - **Backfill embedding เป็นคาบ** — `POST /memory/embed-batch`
> - **ตรวจสอบสุขภาพ provider** — semantic search พึ่งพามัน
> - **รวมกับ tag** — semantic + tag filter จำกัดผลลัพธ์

## ขั้นตอนถัดไป

- [FTS5 Search](/docs/concepts/fts5-search)
- [Memory API](/docs/api/memory)
- [Architecture](/docs/concepts/architecture)