# Mô hình bộ nhớ Mô hình bộ nhớ của Synapse được thiết kế cho LLM agent — đủ cấu trúc để thu hồi tin cậy, đủ linh hoạt cho bất kỳ lĩnh vực nào. ## Giải phẫu bộ nhớ ```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..." } ``` ## Trường | Trường | Loại | Bắt buộc | Mô tả | |-------|------|----------|-------------| | `id` | string | tự động | ID duy nhất (mem_xxx) | | `category` | enum | ✅ | Một trong 8 danh mục | | `key` | string | ✅ | Định danh ổn định (dùng để cập nhật) | | `content` | string | ✅ | Nội dung bộ nhớ (bất kỳ văn bản nào) | | `tags` | string[] | – | Để tìm kiếm và lọc | | `priority` | enum | – | low, normal, high, critical (mặc định: normal) | | `source` | enum | tự động | user, agent (ai lưu) | | `verified` | bool | tự động | Con người đã xác minh chưa? | | `confidence` | float | – | 0.0 đến 1.0 (mặc định: 1.0 cho user, 0.7 cho agent) | | `expires_at` | timestamp | – | Khi nào quên bộ nhớ này | | `mind_id` | string | tự động | Mind nào sở hữu cái này | | `created_at` | timestamp | tự động | Lần đầu lưu | | `updated_at` | timestamp | tự động | Lần sửa cuối | ## Danh mục Tám danh mục bao phủ các trường hợp sử dụng LLM agent phổ biến: | Danh mục | Mục đích | Nội dung ví dụ | |----------|---------|-----------------| | `identity` | Người dùng là ai | "User is Michael Schäfer, software engineer in Berlin" | | `preference` | Sở thích người dùng | "Prefers concise technical responses" | | `fact` | Sự kiện có thể kiểm chứng | "Office is in Berlin, timezone Europe/Berlin" | | `project` | Trạng thái dự án | "Synapse v1.5.0 deployed, working on v1.6.0 docs" | | `skill` | Kỹ năng người dùng | "Advanced Python, 10+ years" | | `mistake` | Lỗi trong quá khứ | "Forgot to bump npm version — CI failed" | | `context` | Ngữ cảnh phiên | "Currently reviewing PR #42" | | `note` | Ghi chú linh tinh | "Try Redis for caching next sprint" | ## Key: Định danh ổn định Trường `key` rất quan trọng — đó là cách bạn cập nhật bộ nhớ mà không tạo bản trùng lặp. ```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") ``` **Quy tắc key:** - Phải duy nhất trong (category, mind) - Sử dụng `snake_case` - Tiền tố với danh mục để rõ ràng: `preference_communication`, `mistake_npm_version` - Giữ ổn định — không thay đổi key sau khi tạo ## Tag: Dành cho tìm kiếm Tag cho phép lọc và tìm kiếm nhanh: ```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 ``` **Thực hành tốt nhất về tag:** - 2-5 tag mỗi bộ nhớ (không gắn tag quá mức) - Chữ thường để nhất quán - Sử dụng tên dự án, chủ đề, công nghệ - Tag không phân biệt chữ hoa chữ thường ## Mức ưu tiên | Ưu tiên | Khi nào sử dụng | Hành vi thu hồi | |----------|-------------|-----------------| | `critical` | Nhận dạng, pháp lý, không thể đảo ngược | Luôn ở đầu thu hồi | | `high` | Dự án đang hoạt động, sở thích chính | Nổi bật trong thu hồi | | `normal` | Hầu hết bộ nhớ (mặc định) | Thứ tự thu hồi chuẩn | | `low` | Tạm thời, tốt nếu biết | Có thể được tóm tắt | `/memory/recall` sắp xếp theo ưu tiên (critical trước), sau đó theo gần đây. ## Nguồn: User so với Agent Bộ nhớ được gắn `source`: - `user` — được lưu bởi con người (qua JWT hoặc giao diện con người) - `agent` — được lưu bởi LLM agent (qua Mind Key) Điều này ảnh hưởng: - **Xác minh**: bộ nhớ `user` được tự động xác minh, bộ nhớ `agent` thì không - **Độ tin cậy**: `user` mặc định 1.0, `agent` 0.7 - **Thu hồi**: `/memory/recall` đánh dấu bộ nhớ chưa xác minh với "(unverified)" > [!NOTE] > Hãy đối xử với bộ nhớ nguồn `agent` với sự hoài nghi phù hợp. Chúng có thể > được suy luận hoặc giả định thay vì được người dùng phát biểu trực tiếp. ## Xác minh Cờ `verified` cho biết con người đã xác nhận bộ nhớ: - Bộ nhớ `user`: tự động xác minh (`true`) - Bộ nhớ `agent`: mặc định chưa xác minh (`false`) Xác minh bộ nhớ qua: ```bash curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \ -H "Authorization: Bearer YOUR_JWT" ``` > [!NOTE] > Xác minh yêu cầu JWT (xác thực con người), không phải Mind Key (xác thực > agent). Điều này đảm bảo chỉ con người có thể đánh dấu bộ nhớ là đã xác minh. ## Độ tin cậy Trường `confidence` (0.0 đến 1.0) cho biết bộ nhớ đáng tin cậy đến đâu: - 1.0 — được người dùng phát biểu trực tiếp - 0.7 — được agent suy luận - 0.5 — không chắc chắn, cần xác minh - 0.0 — bị nghi ngờ rõ ràng Đặt độ tin cậy khi lưu: ```json { "category": "preference", "key": "prefers_dark_mode", "content": "User seems to prefer dark mode (based on their IDE screenshots)", "confidence": 0.5, "source": "agent" } ``` ## Hết hạn Đặt `expires_at` cho bộ nhớ nhạy cảm với thời gian: ```json { "category": "context", "key": "current_meeting_topic", "content": "Discussing Q3 roadmap", "expires_at": "2026-06-28T00:00:00Z" } ``` Bộ nhớ hết hạn không được `/memory/recall` trả về (nhưng vẫn tồn tại trong DB). Sử dụng `/memory/expiring?within=7d` để xem bộ nhớ sắp hết hạn. ## Vòng đời bộ nhớ ``` ┌─────────────────┐ │ Create │ │ POST /memory │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Active │ ◀──── PUT /memory/:id (update) │ (in recall) │ └────────┬────────┘ │ ┌────────────┼────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Expired │ │ Verified │ │ Deleted │ │ (in DB) │ │ (flag) │ │ (gone) │ └──────────┘ └──────────┘ └──────────┘ ``` ## Hành vi thu hồi `GET /memory/recall` trả về tóm tắt văn bản thuần được tối ưu cho ngữ cảnh LLM: ``` 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 ... ``` - Sắp xếp theo ưu tiên (critical → low), sau đó theo gần đây - Bộ nhớ chưa xác minh được đánh dấu `[unverified]` - Tag được bao gồm cho ngữ cảnh - Văn bản thuần (không cần phân tích JSON) ## Bước tiếp theo - [Memory API](/docs/api/memory) - [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)