# Memory API

Memory API là trái tim của Synapse. Nó cung cấp 22 endpoint để lưu trữ, truy
xuất, tìm kiếm và quản lý bộ nhớ có cấu trúc. Tất cả endpoint đều yêu cầu Mind
Key để xác thực.

> [!CRITICAL]
> **Luôn gọi `GET /memory/recall` ở đầu mỗi phiên.** Đây là cách duy nhất để
> xây dựng lại ngữ cảnh từ các phiên trước.

## Danh mục

Bộ nhớ được tổ chức thành 8 danh mục:

| Danh mục | Trường hợp sử dụng |
|----------|----------|
| `identity` | Tên người dùng, vai trò, thông tin liên hệ, sở thích cá nhân |
| `preference` | Thích/không thích, phong cách làm việc, tùy chọn giao tiếp |
| `fact` | Sự kiện có thể kiểm chứng (chi tiết dự án, ngày tháng, URL) |
| `project` | Trạng thái dự án, cột mốc, kiến trúc |
| `skill` | Những thứ người dùng giỏi |
| `mistake` | Lỗi trong quá khứ — tránh lặp lại |
| `context` | Ngữ cảnh liên quan phiên |
| `note` | Ghi chú linh tinh |

## Mức ưu tiên

- `low` — tốt nếu biết
- `normal` — mặc định
- `high` — quan trọng
- `critical` — không bao giờ được quên (nhận dạng người dùng, thông tin pháp lý)

## Endpoint cốt lõi

### GET /memory/recall

Trả về TẤT CẢ bộ nhớ dưới dạng văn bản thuần được tối ưu cho LLM. Gọi endpoint
này ở đầu mỗi phiên.

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

Phản hồi (text/plain):

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

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

...
```

### POST /memory

Lưu một bộ nhớ mới hoặc cập nhật bộ nhớ hiện có (cùng category + key = cập nhật).

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

Phản hồi: `{ "id": "mem_001", "status": "stored" }`

### GET /memory

Liệt kê bộ nhớ với các bộ lọc tùy chọn.

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

Cập nhật một bộ nhớ cụ thể theo 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

Xóa một bộ nhớ đơn lẻ.

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

## Endpoint tìm kiếm

### GET /memory/search

Tìm kiếm toàn văn sử dụng FTS5.

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

Cú pháp FTS5:

- Nhiều từ = AND: `docker swarm`
- Cụm từ: `"docker swarm"`
- Tiền tố: `docker*`
- Boolean: `docker OR kubernetes`
- Loại trừ: `docker -swarm`

### GET /memory/semantic-search

Tìm kiếm khái niệm sử dụng embeddings (chậm hơn FTS5 nhưng hiểu ý nghĩa).

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

Trả về các bộ nhớ tương tự về mặt ngữ nghĩa với truy vấn, ngay cả khi không
khớp từ khóa. Hữu ích cho "tìm bộ nhớ về X" khi X được mô tả khác đi.

### GET /memory/by-tag

Liệt kê bộ nhớ theo tag.

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

### GET /memory/related/:id

Tìm bộ nhớ liên quan đến một bộ nhớ cụ thể (qua tag chung).

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

## Đồng bộ & Diff

### GET /memory/diff

Đồng bộ gia tăng — trả về bộ nhớ đã thay đổi kể từ một timestamp.

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

Phản hồi: `{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

Áp dụng một diff từ thể hiện khác (cho đồng bộ 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": [...]}'
```

## Thao tác hàng loạt

### POST /memory/bulk-delete

Xóa nhiều bộ nhớ theo 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

Tạo embeddings cho các bộ nhớ chưa có (cho tìm kiếm ngữ nghĩa).

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

Kiểm tra tiến độ tạo embedding.

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

## Xác minh

Bộ nhớ có cờ `verified`. Bộ nhớ do agent lưu mặc định chưa được xác minh
(`source=agent`); bộ nhớ do con người lưu được xác minh (`source=user`).

### POST /memory/verify

Đánh dấu một bộ nhớ là đã xác minh (yêu cầu JWT, không phải Mind Key).

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

### POST /memory/unverify

Đánh dấu một bộ nhớ là chưa xác minh (yêu cầu JWT).

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

### GET /memory/unverified

Liệt kê bộ nhớ đang chờ xác minh bởi con người.

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

## Thống kê & Kiểm toán

### GET /memory/stats

Thống kê tổng hợp cho mind hiện tại.

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

Trả về: `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

Nhật ký kiểm toán của tất cả thao tác thay đổi trạng thái.

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

### GET /memory/contradictions

Phát hiện mâu thuẫn tiềm ẩn trong bộ nhớ đã lưu.

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

### GET /memory/expiring

Liệt kê bộ nhớ có ngày hết hạn sắp tới.

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

## Sức khỏe & Xuất

### GET /memory/health

Kiểm tra sức khỏe nhanh cho hệ thống bộ nhớ.

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

### GET /memory/mind-export

Xuất JSON đầy đủ của tất cả bộ nhớ (để sao lưu).

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

### POST /memory/compact

Nén các bộ nhớ tương tự (tự động tóm tắt).

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

## Bước tiếp theo

- [Quick Start cho LLM](/docs/getting-started/quick-start-llm)
- [Thực hành tốt nhất về bộ nhớ](/docs/guides/memory-best-practices)
- [Tìm kiếm FTS5](/docs/concepts/fts5-search)
- [Tìm kiếm ngữ nghĩa](/docs/concepts/semantic-search)