# Thực hành tốt nhất về bộ nhớ

Cách bạn cấu trúc bộ nhớ xác định độ hữu ích của chúng. Hướng dẫn này bao phủ
mẫu cho việc phân danh mục, gắn tag và ưu tiên bộ nhớ để LLM có thể thu hồi
thông tin đúng vào thời điểm đúng.

## Danh mục: Chọn cái cụ thể nhất

| Danh mục | Dùng cho | Ví dụ |
|----------|---------|---------|
| `identity` | Tên người dùng, vai trò, thông tin liên hệ | `"user_name": "Michael Schäfer"` |
| `preference` | Thích, không thích, phong cách làm việc | `"communication": "Prefers concise responses"` |
| `fact` | Sự kiện có thể kiểm chứng | `"office_location": "Berlin, Germany"` |
| `project` | Trạng thái dự án, quyết định | `"project_synapse": "v1.5.0 deployed"` |
| `skill` | Kỹ năng người dùng | `"skill_python": "Advanced, 10+ years"` |
| `mistake` | Lỗi quá khứ để tránh | `"mistake_npm_version": "Always bump version"` |
| `context` | Ngữ cảnh liên quan phiên | `"current_focus": "Working on docs system"` |
| `note` | Ghi chú linh tinh | `"note_idea": "Try Redis for caching"` |

> [!TIP]
> Khi nghi ngờ, sử dụng `fact` cho thông tin có thể kiểm chứng và `note` cho
> mọi thứ khác. Không phân danh mục quá mức — tốt hơn có một `fact` rõ ràng
> hơn một `context` gây nhầm lẫn.

## Key: Định danh ý nghĩa

Trường `key` là định danh của bộ nhớ. Sử dụng key ý nghĩa, ổn định:

**Key tốt:**
- `user_name`
- `project_synapse_status`
- `preference_communication_style`
- `mistake_npm_version_bump`

**Key xấu:**
- `mem_001` (không ý nghĩa)
- `temp` (không mô tả)
- `2026-06-27-note` (ngày không giúp thu hồi)

### Quy ước đặt tên key

- `snake_case` (chữ thường với dấu gạch dưới)
- Tiền tố với danh mục: `preference_*`, `project_*`, `mistake_*`
- Sử dụng danh từ mô tả, không động từ
- Giữ dưới 50 ký tự

## Tag: Dành cho tìm kiếm và lọc

Tag cho phép lọc và tìm kiếm nhanh. Thêm 2-5 tag mỗi bộ nhớ:

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

### Mẫu tag

- **Tên dự án**: `synapse`, `synapse-mcp`, `synapse-chat`
- **Chủ đề**: `deployment`, `ci`, `database`, `auth`
- **Trạng thái**: `active`, `completed`, `blocked`
- **Chỉ báo ưu tiên**: `urgent`, `long-term`

> [!NOTE]
> Tag không phân biệt chữ hoa chữ thường. Sử dụng chữ thường để nhất quán.

## Mức ưu tiên: Thực tế

| Ưu tiên | Dùng cho | % Bộ nhớ |
|----------|---------|---------------|
| `critical` | Nhận dạng người dùng, thông tin pháp lý, quyết định không thể đảo ngược | ~5% |
| `high` | Dự án đang hoạt động, sở thích quan trọng | ~20% |
| `normal` | Hầu hết sự kiện, ghi chú, ngữ cảnh | ~65% |
| `low` | Tạm thời, tốt nếu biết | ~10% |

> [!WARNING]
> Không đánh dấu mọi thứ `critical`. Nếu mọi thứ là critical, không có gì là
> critical cả. Dự trữ `critical` cho những thứ sẽ gây hại thực sự nếu quên.

## Khi nào lưu so với không lưu

### Luôn lưu

- Nhận dạng người dùng (tên, email, vai trò)
- Sở thích dài hạn
- Quyết định dự án và lý do
- Lỗi quá khứ và bài học
- Cam kết với người dùng

### Không lưu

- Trạng thái tạm thời (sử dụng biến thay thế)
- Lịch sử hội thoại nguyên văn (hệ thống chat xử lý điều này)
- Dữ liệu nhạy cảm (mật khẩu, API key)
- Sự kiện dễ dàng suy ra (ngày hiện tại, nội dung tệp)
- Ngữ cảnh tạm thời (sử dụng danh mục `context` với ưu tiên thấp)

## Cập nhật bộ nhớ

POST `/memory` với cùng `category` + `key` cập nhật bộ nhớ hiện có:

```python
# Initial store
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Later: update with same key
store("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")
```

> [!TIP]
> Sử dụng key ổn định để bạn có thể cập nhật mà không tạo bản trùng lặp. LLM
> nên POST lại cùng key khi thông tin thay đổi, không tạo bộ nhớ mới.

## Vòng đời bộ nhớ

```
Create → Active → Stale → Archive → Delete
```

- **Create**: POST /memory với ngữ cảnh đầy đủ
- **Active**: Thu hồi thường xuyên, cập nhật khi cần
- **Stale**: Vẫn liên quan nhưng không được sử dụng tích cực (ưu tiên thấp hơn?)
- **Archive**: Đặt ưu tiên thành `low`, giữ cho tham chiếu lịch sử
- **Delete**: DELETE /memory/:id khi không còn liên quan

### Dọn dẹp định kỳ

```python
# Find memories not updated in 90 days
old_memories = requests.get(
    f"{URL}/memory/search?q=*",
    headers={"Authorization": f"Bearer {KEY}"}
)

for mem in old_memories["results"]:
    if is_stale(mem, days=90):
        # Either delete or lower priority
        if is_obsolete(mem):
            delete_memory(mem["id"])
        else:
            update_memory(mem["id"], priority="low")
```

## Mẫu: Kế thừa bộ nhớ

Cho ngữ cảnh phân cấp (dự án → dự án con → tác vụ):

```python
# Parent project
store("project", "project_synapse", "Main Synapse project", 
      tags=["synapse", "parent"], priority="high")

# Sub-project (tags link to parent)
store("project", "project_synapse_docs", "Docs system for Synapse",
      tags=["synapse", "docs", "synapse-parent"], priority="high")

# Specific task (tags link to sub-project)
store("project", "task_docs_loader", "Implement docs-loader.ts",
      tags=["synapse", "docs", "task"], priority="normal")
```

LLM có thể sau đó tìm `q=synapse+docs` để tìm tất cả bộ nhớ liên quan.

## Mẫu: Nhật ký quyết định

Lưu quyết định với lý do để LLM không tái thẩm lại chúng:

```python
store("fact", "decision_postgres_over_sqlite",
      "Chose PostgreSQL over SQLite for production. Reason: concurrent writes, "
      "FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.",
      tags=["decision", "database", "postgres", "sqlite"],
      priority="high")
```

## Mẫu: Tránh lỗi

Lưu lỗi với hướng dẫn tránh cụ thể:

```python
store("mistake", "mistake_forget_version_bump",
      "Forgot to bump package.json version after changes. npm publish failed. "
      "FIX: Always run `npm version patch` before pushing. "
      "CI fails with 'version already exists' if you forget.",
      tags=["npm", "ci", "publish", "version"],
      priority="high")
```

## Mẫu chống cần tránh

> [!WARNING]
> - **Lưu nhật ký hội thoại** — hệ thống chat xử lý điều này
> - **Lưu toàn bộ tệp** — sử dụng script store hoặc lưu trữ bên ngoài
> - **Lưu trạng thái tạm thời** — sử dụng biến
> - **Lưu bí mật** — sử dụng biến môi trường
> - **Trùng lặp bộ nhớ** — sử dụng key ổn định
> - **Gắn tag quá mức** — 2-5 tag mỗi bộ nhớ là lý tưởng
> - **Mọi thứ là critical** — thực tế với ưu tiên

## Bước tiếp theo

- [Memory API](/docs/api/memory)
- [LLM Agent cố định](/docs/guides/persistent-llm-agent)
- [Chiến lược gắn tag bộ nhớ](/docs/llm-cookbook/memory-tagging-strategy)