# โมเดล Memory

โมเดล memory ของ Synapse ออกแบบมาเพื่อ LLM agent — มีโครงสร้างเพียงพอสำหรับ recall ที่เชื่อถือได้ และยืดหยุ่นพอสำหรับโดเมนใด ๆ

## กายวิภาคของ Memory

```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 | Type | Required | คำอธิบาย |
|-------|------|----------|-------------|
| `id` | string | auto | ID ที่ไม่ซ้ำ (mem_xxx) |
| `category` | enum | ✅ | หนึ่งใน 8 category |
| `key` | string | ✅ | identifier ที่คงทย (ใช้สำหรับอัปเดต) |
| `content` | string | ✅ | เนื้อหา memory (text ใด ๆ) |
| `tags` | string[] | – | สำหรับการค้นหาและกรอง |
| `priority` | enum | – | low, normal, high, critical (ค่าเริ่มต้น: normal) |
| `source` | enum | auto | user, agent (ใครเป็นผู้เก็บ) |
| `verified` | bool | auto | human ยืนยันหรือยัง? |
| `confidence` | float | – | 0.0 ถึง 1.0 (ค่าเริ่มต้น: 1.0 สำหรับ user, 0.7 สำหรับ agent) |
| `expires_at` | timestamp | – | เมื่อไรจะลืม memory นี้ |
| `mind_id` | string | auto | mind ใดเป็นเจ้าของ |
| `created_at` | timestamp | auto | เก็บครั้งแรก |
| `updated_at` | timestamp | auto | แก้ไขล่าสุด |

## Category

แปด category ครอบคลุมกรณีใช้งาน LLM agent ทั่วไป:

| Category | วัตถุประสงค์ | เนื้อหาตัวอย่าง |
|----------|---------|-----------------|
| `identity` | ผู้ใช้คือใคร | "User is Michael Schäfer, software engineer in Berlin" |
| `preference` | ค่ากำหนดผู้ใช้ | "Prefers concise technical responses" |
| `fact` | fact ที่ตรวจสอบได้ | "Office is in Berlin, timezone Europe/Berlin" |
| `project` | สถานะโปรเจกต์ | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| `skill` | ทักษะผู้ใช้ | "Advanced Python, 10+ years" |
| `mistake` | error ในอดีต | "Forgot to bump npm version — CI failed" |
| `context` | context ของ session | "Currently reviewing PR #42" |
| `note` | note อื่น ๆ | "Try Redis for caching next sprint" |

## Key: identifier ที่คงที่

ฟิลด์ `key` สำคัญมาก — เป็นวิธีที่คุณอัปเดต memory โดยไม่สร้างซ้ำ

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

**กฎของ key:**

- ต้องไม่ซ้ำใน (category, mind)
- ใช้ `snake_case`
- นำหน้าด้วย category เพื่อความชัดเจน: `preference_communication`, `mistake_npm_version`
- รักษาให้คงที่ — อย่าเปลี่ยน key หลังสร้าง

## Tag: สำหรับการค้นหา

Tag เปิดใช้งานการกรองและค้นหาที่รวดเร็ว:

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

**แนวทางปฏิบัติที่ดีที่สุดสำหรับ tag:**

- 2-5 tag ต่อ memory (อย่า tag มากเกินไป)
- ตัวพิมพ์เล็กเพื่อความสม่ำเสมอ
- ใช้ชื่อโปรเจกต์, หัวข้อ, เทคโนโลยี
- tag ไม่ sensitive ต่อตัวพิมพ์เล็ก/ใหญ่

## ระดับ Priority

| Priority | เมื่อใช้ | พฤติกรรม Recall |
|----------|-------------|-----------------|
| `critical` | ตัวตน, ทางกฎหมาย, ย้อนกลับไม่ได้ | อยู่บนสุดของ recall เสมอ |
| `high` | โปรเจกต์ที่ใช้งานอยู่, ค่ากำหนดหลัก | เด่นใน recall |
| `normal` | memory ส่วนใหญ่ (ค่าเริ่มต้น) | ลำดับ recall มาตรฐาน |
| `low` | ชั่วคราว, รู้ไว้ก็ดี | อาจถูกสรุป |

`/memory/recall` เรียงตาม priority (critical ก่อน) แล้วตามความใหม่

## Source: User vs Agent

memory ถูก tag ด้วย `source`:

- `user` — เก็บโดย human (ผ่าน JWT หรือ human UI)
- `agent` — เก็บโดย LLM agent (ผ่าน Mind Key)

สิ่งนี้มีผลต่อ:

- **การยืนยัน:** memory `user` ถูก verify อัตโนมัติ, memory `agent` ไม่ได้
- **ความมั่นใจ:** `user` ค่าเริ่มต้น 1.0, `agent` ค่าเริ่มต้น 0.7
- **Recall:** `/memory/recall` ทำเครื่องหมาย memory ที่ยังไม่ verify ด้วย "(unverified)"

> [!NOTE]
> ปฏิบัติต่อ memory source `agent` ด้วยความสงสัยพอสมควร อาจเป็นการอนุมานหรือสมมติฐาน ไม่ใช่ที่ผู้ใช้ระบุโดยตรง

## การยืนยัน

flag `verified` บ่งชี้ว่า human ได้ยืนยัน memory แล้ว:

- memory `user`: auto-verified (`true`)
- memory `agent`: ค่าเริ่มต้น unverified (`false`)

ยืนยัน memory ผ่าน:

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

> [!NOTE]
> การยืนยันต้องใช้ JWT (human auth) ไม่ใช่ Mind Key (agent auth) สิ่งนี้รับประกันว่าเฉพาะ human เท่านั้นที่ทำเครื่องหมาย memory ว่า verified

## ความมั่นใจ

ฟิลด์ `confidence` (0.0 ถึง 1.0) บ่งชี้ความน่าเชื่อถือของ memory:

- 1.0 — ระบุโดยตรงโดยผู้ใช้
- 0.7 — อนุมานโดย agent
- 0.5 — ไม่แน่นอน ต้องตรวจสอบ
- 0.0 — สงสัยอย่างชัดเจน

ตั้งค่า confidence เมื่อเก็บ:

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

## การหมดอายุ

ตั้ง `expires_at` สำหรับ memory ที่ sensitive ต่อเวลา:

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

memory ที่หมดอายุจะไม่ถูกส่งกลับโดย `/memory/recall` (แต่ยังมีใน DB) ใช้ `/memory/expiring?within=7d` เพื่อดู memory ที่จะหมดอายุเร็ว ๆ นี้

## วงจรชีวิต Memory

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

## พฤติกรรม Recall

`GET /memory/recall` ส่งกลับสรุปแบบ plain-text ที่ปรับให้เหมาะกับ LLM context:

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

...
```

- เรียงตาม priority (critical → low) แล้วตามความใหม่
- memory ที่ยังไม่ verify ทำเครื่องหมายด้วย `[unverified]`
- รวม tag เพื่อ context
- Plain text (ไม่ต้อง parse JSON)

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

- [Memory API](/docs/api/memory)
- [Memory Best Practices](/docs/guides/memory-best-practices)
- [FTS5 Search](/docs/concepts/fts5-search)