# Quick Start cho LLM Agent

Bạn mất tất cả bộ nhớ giữa các phiên. Synapse là bộ não ngoài của bạn. Hướng dẫn
này cho thấy ba lệnh gọi API thiết yếu mà mọi LLM agent phải biết.

> [!CRITICAL]
> Gọi `GET /memory/recall` ở ĐẦU mỗi phiên.
> Không có lệnh gọi này, bạn không có bộ nhớ về ai là người dùng, những gì bạn
> đã hứa, hoặc những gì bạn đã làm lần trước.

## Bước 1: Thu hồi tất cả bộ nhớ (LUÔN LUÔN ĐẦU TIÊN)

```
GET /memory/recall
Authorization: Bearer YOUR_MIND_KEY
```

Trả về tóm tắt văn bản thuần có cấu trúc của tất cả bộ nhớ đã lưu. Phân tích
điều này để xây dựng lại mô hình tâm trí của bạn về người dùng, dự án của họ và
tương tác trong quá khứ.

Ví dụ phản hồi:

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

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

[002] preference (HIGH)
  communication_style
  Prefers concise technical responses, no fluff
  Tags: communication, preference

[003] project (HIGH)
  project_synapse
  Synapse v1.5.0 deployed on vps1.schaefer.zone. Admin panel at /admin.
  Tags: synapse, deployment
  ...
```

## Bước 2: Lưu bộ nhớ mới

Khi bạn học được điều gì đáng nhớ:

```
POST /memory
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{
  "category": "fact",
  "key": "user_name",
  "content": "The user's name is Michael Schäfer",
  "tags": ["person", "identity"],
  "priority": "critical"
}
```

**Danh mục:** `identity`, `preference`, `fact`, `project`, `skill`, `mistake`, `context`, `note`, `credentials`

**Mức ưu tiên:** `low`, `normal`, `high`, `critical`

> [!TIP]
> Luôn bao gồm trường `key` — một định danh ngắn cho bộ nhớ. Điều này cho phép
> bạn cập nhật cùng bộ nhớ sau bằng cách POST lại với cùng key.

## Bước 3: Tìm kiếm bộ nhớ cụ thể

```
GET /memory/search?q=Docker+Swarm
Authorization: Bearer YOUR_MIND_KEY
```

> [!TIP]
> Cú pháp FTS5: nhiều từ = tìm kiếm AND. Cụm từ trong ngoặc kép: `"docker swarm"`.
> Tìm kiếm tiền tố: `docker*`. Boolean: `docker OR kubernetes`.

## Công cụ mở (Không cần Header xác thực)

Nếu công cụ của bạn chỉ có thể mở URL (không có header tùy chỉnh), sử dụng
tham số `?key=`:

```
GET /memory/recall?key=YOUR_MIND_KEY
POST /memory?key=YOUR_MIND_KEY (+ JSON body)
GET /memory/search?key=YOUR_MIND_KEY&q=suchbegriff
```

> [!WARNING]
> `?key=` bị giới hạn 60 yêu cầu/phút. Header Bearer không có giới hạn tốc độ.
> Sử dụng header Bearer bất cứ khi nào có thể.

## Quy trình phiên hoàn chỉnh

1. **Bắt đầu phiên:** `GET /memory/recall` — tải tất cả bộ nhớ
2. **Trong khi làm việc:** `GET /memory/search?q=...` — tìm sự kiện cụ thể
3. **Khi có thông tin mới:** `POST /memory` — lưu nó (với category, key, tags, priority)
4. **Định kỳ:** `GET /chat/poll` — kiểm tra tin nhắn con người
5. **Kết thúc phiên:** Lưu bất kỳ học hỏi cuối cùng qua `POST /memory`

## Mẫu phổ biến

### Cập nhật bộ nhớ hiện có

POST `/memory` với cùng `category` và `key` — bộ nhớ hiện có được cập nhật,
không trùng lặp.

### Lưu trạng thái dự án

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system. CI green.",
  "tags": ["synapse", "deployment", "status"],
  "priority": "high"
}
```

### Ghi lại lỗi (để bạn không lặp lại)

```json
{
  "category": "mistake",
  "key": "mistake_npm_version_bump",
  "content": "Always bump package.json version after changes — npm publish fails otherwise.",
  "tags": ["npm", "ci", "deployment"],
  "priority": "high"
}
```

### Kiểm tra tin nhắn con người

```
GET /chat/poll
Authorization: Bearer YOUR_MIND_KEY
```

Trả về tin nhắn chưa đọc từ con người. Trả lời với:

```
POST /chat/reply
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{"content": "Got it! Working on it now."}
```

## Bước tiếp theo

- [Xác thực](/docs/getting-started/authentication) — Mind Key vs JWT
- [Tham chiếu Memory API](/docs/api/memory) — tất cả 22 endpoint memory
- [Chat API](/docs/api/chat) — giao tiếp bất đồng bộ với con người
- [LLM Cookbook](/docs/llm-cookbook/session-start-pattern) — mẫu thực tế