# Memory API

Memory API เป็นหัวใจของ Synapse ให้บริการ 22 endpoint สำหรับจัดเก็บ, ดึง, ค้นหา, และจัดการ memory ที่มีโครงสร้าง endpoint ทั้งหมดต้องใช้ Mind Key สำหรับการยืนยันตัวตน

> [!CRITICAL]
> **เรียก `GET /memory/recall` เสมอที่จุดเริ่มต้นของทุก session** นี่เป็นวิธีเดียวที่จะ rebuild context จาก session ก่อนหน้า

## Categories

memory ถูกจัดเป็น 8 category:

| Category | กรณีใช้งาน |
|----------|----------|
| `identity` | ชื่อผู้ใช้, role, ข้อมูลติดต่อ, ค่ากำหนดเกี่ยวกับตนเอง |
| `preference` | สิ่งที่ชอบ/ไม่ชอบ, สไตล์การทำงาน, ค่ากำหนดการสื่อสาร |
| `fact` | fact ที่ตรวจสอบได้ (รายละเอียดโปรเจกต์, วันที่, URL) |
| `project` | สถานะโปรเจกต์, milestone, architecture |
| `skill` | สิ่งที่ผู้ใช้ทำได้ดี |
| `mistake` | error ในอดีต — หลีกเลี่ยงการทำซ้ำ |
| `context` | context ที่เกี่ยวข้องกับ session |
| `note` | note อื่น ๆ |

## Priorities

- `low` — รู้ไว้ก็ดี
- `normal` — ค่าเริ่มต้น
- `high` — สำคัญ
- `critical` — ต้องไม่ลืมเด็ดขาด (ตัวตนผู้ใช้, ข้อมูลทางกฎหมาย)

## Core Endpoints

### GET /memory/recall

ส่งกลับ memory ทั้งหมดในรูปแบบ plain text ที่ปรับให้เหมาะกับ LLM เรียกสิ่งนี้ที่จุดเริ่มต้นของทุก session

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

Response (text/plain):

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

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

...
```

### POST /memory

จัดเก็บ memory ใหม่หรืออัปเดต memory ที่มีอยู่ (category + key เดียวกัน = อัปเดต)

```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"
  }'
```

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

### GET /memory

รายการ memory พร้อม filter ที่เลือกได้

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

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

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

### PUT /memory/:id

อัปเดต memory เฉพาะตาม 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

ลบ memory เดียว

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

## Search Endpoints

### GET /memory/search

Full-text search โดยใช้ FTS5

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

ไวยากรณ์ FTS5:

- หลายคำ = AND: `docker swarm`
- Phrase: `"docker swarm"`
- Prefix: `docker*`
- Boolean: `docker OR kubernetes`
- Exclude: `docker -swarm`

### GET /memory/semantic-search

การค้นหาเชิงแนวคิดโดยใช้ embeddings (ช้ากว่า FTS5 แต่เข้าใจความหมาย)

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

ส่งกลับ memory ที่คล้ายเชิง semantic กับ query แม้ไม่มี keyword ตรงกัน มีประโยชน์สำหรับ "ค้นหา memory เกี่ยวกับ X" โดยที่ X ถูกอธิบายต่างกัน

### GET /memory/by-tag

รายการ memory ตาม tag

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

### GET /memory/related/:id

ค้นหา memory ที่เกี่ยวข้องกับ memory เฉพาะ (ผ่าน tag ที่ใช้ร่วมกัน)

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

## Sync & Diff

### GET /memory/diff

Sync แบบ incremental — ส่งกลับ memory ที่เปลี่ยนแปลงตั้งแต่ timestamp

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

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

### POST /memory/sync

นำ diff จาก instance อื่นมาใช้ (สำหรับ self-hosted sync)

```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": [...]}'
```

## การดำเนินการแบบ Bulk

### POST /memory/bulk-delete

ลบ memory หลายรายการตาม 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

สร้าง embeddings สำหรับ memory ที่ยังไม่มี (สำหรับ semantic search)

```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

ตรวจสอบความคืบหน้าการสร้าง embedding

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

## การยืนยัน

memory มี flag `verified` memory ที่จัดเก็บโดย agent จะเป็น unverified โดยค่าเริ่มต้น (`source=agent`); memory ที่จัดเก็บโดย human จะเป็น verified (`source=user`)

### POST /memory/verify

ทำเครื่องหมาย memory ว่า verified (ต้องใช้ JWT ไม่ใช่ Mind Key)

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

### POST /memory/unverify

ทำเครื่องหมาย memory ว่า unverified (ต้องใช้ JWT)

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

### GET /memory/unverified

รายการ memory ที่รอการยืนยันจาก human

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

## Statistics & Audit

### GET /memory/stats

สถิติรวมสำหรับ mind ปัจจุบัน

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

ส่งกลับ: `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

Audit log ของการดำเนินการที่เปลี่ยนแปลงสถานะทั้งหมด

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

### GET /memory/contradictions

ตรวจหา contradiction ที่อาจเกิดขึ้นใน memory ที่จัดเก็บไว้

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

### GET /memory/expiring

รายการ memory ที่มีวันหมดอายุใกล้เข้ามา

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

## Health & Export

### GET /memory/health

Health check อย่างรวดเร็วสำหรับระบบ memory

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

### GET /memory/mind-export

JSON export แบบเต็มของ memory ทั้งหมด (สำหรับสำรองข้อมูล)

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

### POST /memory/compact

รวบรวม memory ที่คล้ายกัน (auto-summarization)

```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}'
```

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

- [Quick Start for LLMs](/docs/getting-started/quick-start-llm)
- [Memory Best Practices](/docs/guides/memory-best-practices)
- [FTS5 Search](/docs/concepts/fts5-search)
- [Semantic Search](/docs/concepts/semantic-search)