{"title":"Mô hình bộ nhớ","slug":"memory-model","category":"concepts","summary":"Cách bộ nhớ được cấu trúc — danh mục, key, tag, mức ưu tiên, nguồn, xác minh.","audience":["human","llm"],"tags":["concept","memory","model","structure"],"difficulty":"intermediate","updated":"2026-06-27","word_count":939,"read_minutes":5,"lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# Mô hình bộ nhớ\n\nMô hình bộ nhớ của Synapse được thiết kế cho LLM agent — đủ cấu trúc để thu hồi\ntin cậy, đủ linh hoạt cho bất kỳ lĩnh vực nào.\n\n## Giải phẫu bộ nhớ\n\n```json\n{\n \"id\": \"mem_abc123\",\n \"category\": \"project\",\n \"key\": \"project_synapse_status\",\n \"content\": \"Synapse v1.5.0 deployed on vps1. CI green.\",\n \"tags\": [\"synapse\", \"deployment\", \"v1.5.0\"],\n \"priority\": \"high\",\n \"source\": \"agent\",\n \"verified\": false,\n \"confidence\": 0.85,\n \"expires_at\": null,\n \"mind_id\": \"m_xyz789\",\n \"created_at\": \"2026-06-27T...\",\n \"updated_at\": \"2026-06-27T...\"\n}\n```\n\n## Trường\n\n| Trường | Loại | Bắt buộc | Mô tả |\n|-------|------|----------|-------------|\n| `id` | string | tự động | ID duy nhất (mem_xxx) |\n| `category` | enum | ✅ | Một trong 8 danh mục |\n| `key` | string | ✅ | Định danh ổn định (dùng để cập nhật) |\n| `content` | string | ✅ | Nội dung bộ nhớ (bất kỳ văn bản nào) |\n| `tags` | string[] | – | Để tìm kiếm và lọc |\n| `priority` | enum | – | low, normal, high, critical (mặc định: normal) |\n| `source` | enum | tự động | user, agent (ai lưu) |\n| `verified` | bool | tự động | Con người đã xác minh chưa? |\n| `confidence` | float | – | 0.0 đến 1.0 (mặc định: 1.0 cho user, 0.7 cho agent) |\n| `expires_at` | timestamp | – | Khi nào quên bộ nhớ này |\n| `mind_id` | string | tự động | Mind nào sở hữu cái này |\n| `created_at` | timestamp | tự động | Lần đầu lưu |\n| `updated_at` | timestamp | tự động | Lần sửa cuối |\n\n## Danh mục\n\nTám danh mục bao phủ các trường hợp sử dụng LLM agent phổ biến:\n\n| Danh mục | Mục đích | Nội dung ví dụ |\n|----------|---------|-----------------|\n| `identity` | Người dùng là ai | \"User is Michael Schäfer, software engineer in Berlin\" |\n| `preference` | Sở thích người dùng | \"Prefers concise technical responses\" |\n| `fact` | Sự kiện có thể kiểm chứng | \"Office is in Berlin, timezone Europe/Berlin\" |\n| `project` | Trạng thái dự án | \"Synapse v1.5.0 deployed, working on v1.6.0 docs\" |\n| `skill` | Kỹ năng người dùng | \"Advanced Python, 10+ years\" |\n| `mistake` | Lỗi trong quá khứ | \"Forgot to bump npm version — CI failed\" |\n| `context` | Ngữ cảnh phiên | \"Currently reviewing PR #42\" |\n| `note` | Ghi chú linh tinh | \"Try Redis for caching next sprint\" |\n\n## Key: Định danh ổn định\n\nTrườ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\ntrùng lặp.\n\n```python\n# First store\nstore(\"project\", \"project_synapse_status\", \"v1.4.0 deployed\", priority=\"high\")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore(\"project\", \"project_synapse_status\", \"v1.5.0 deployed\", priority=\"high\")\n```\n\n**Quy tắc key:**\n\n- Phải duy nhất trong (category, mind)\n- Sử dụng `snake_case`\n- Tiền tố với danh mục để rõ ràng: `preference_communication`, `mistake_npm_version`\n- Giữ ổn định — không thay đổi key sau khi tạo\n\n## Tag: Dành cho tìm kiếm\n\nTag cho phép lọc và tìm kiếm nhanh:\n\n```bash\n# Find all memories with tag \"docker\"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker\n```\n\n**Thực hành tốt nhất về tag:**\n\n- 2-5 tag mỗi bộ nhớ (không gắn tag quá mức)\n- Chữ thường để nhất quán\n- Sử dụng tên dự án, chủ đề, công nghệ\n- Tag không phân biệt chữ hoa chữ thường\n\n## Mức ưu tiên\n\n| Ưu tiên | Khi nào sử dụng | Hành vi thu hồi |\n|----------|-------------|-----------------|\n| `critical` | Nhận dạng, pháp lý, không thể đảo ngược | Luôn ở đầu thu hồi |\n| `high` | Dự án đang hoạt động, sở thích chính | Nổi bật trong thu hồi |\n| `normal` | Hầu hết bộ nhớ (mặc định) | Thứ tự thu hồi chuẩn |\n| `low` | Tạm thời, tốt nếu biết | Có thể được tóm tắt |\n\n`/memory/recall` sắp xếp theo ưu tiên (critical trước), sau đó theo gần đây.\n\n## Nguồn: User so với Agent\n\nBộ nhớ được gắn `source`:\n\n- `user` — được lưu bởi con người (qua JWT hoặc giao diện con người)\n- `agent` — được lưu bởi LLM agent (qua Mind Key)\n\nĐiều này ảnh hưởng:\n\n- **Xác minh**: bộ nhớ `user` được tự động xác minh, bộ nhớ `agent` thì không\n- **Độ tin cậy**: `user` mặc định 1.0, `agent` 0.7\n- **Thu hồi**: `/memory/recall` đánh dấu bộ nhớ chưa xác minh với \"(unverified)\"\n\n> [!NOTE]\n> Hãy đối xử với bộ nhớ nguồn `agent` với sự hoài nghi phù hợp. Chúng có thể\n> được suy luận hoặc giả định thay vì được người dùng phát biểu trực tiếp.\n\n## Xác minh\n\nCờ `verified` cho biết con người đã xác nhận bộ nhớ:\n\n- Bộ nhớ `user`: tự động xác minh (`true`)\n- Bộ nhớ `agent`: mặc định chưa xác minh (`false`)\n\nXác minh bộ nhớ qua:\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n> [!NOTE]\n> 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\n> agent). Điều này đảm bảo chỉ con người có thể đánh dấu bộ nhớ là đã xác minh.\n\n## Độ tin cậy\n\nTrường `confidence` (0.0 đến 1.0) cho biết bộ nhớ đáng tin cậy đến đâu:\n\n- 1.0 — được người dùng phát biểu trực tiếp\n- 0.7 — được agent suy luận\n- 0.5 — không chắc chắn, cần xác minh\n- 0.0 — bị nghi ngờ rõ ràng\n\nĐặt độ tin cậy khi lưu:\n\n```json\n{\n \"category\": \"preference\",\n \"key\": \"prefers_dark_mode\",\n \"content\": \"User seems to prefer dark mode (based on their IDE screenshots)\",\n \"confidence\": 0.5,\n \"source\": \"agent\"\n}\n```\n\n## Hết hạn\n\nĐặt `expires_at` cho bộ nhớ nhạy cảm với thời gian:\n\n```json\n{\n \"category\": \"context\",\n \"key\": \"current_meeting_topic\",\n \"content\": \"Discussing Q3 roadmap\",\n \"expires_at\": \"2026-06-28T00:00:00Z\"\n}\n```\n\nBộ nhớ hết hạn không được `/memory/recall` trả về (nhưng vẫn tồn tại trong DB).\nSử dụng `/memory/expiring?within=7d` để xem bộ nhớ sắp hết hạn.\n\n## Vòng đời bộ nhớ\n\n```\n ┌─────────────────┐\n │ Create │\n │ POST /memory │\n └────────┬────────┘\n │\n ▼\n ┌─────────────────┐\n │ Active │ ◀──── PUT /memory/:id (update)\n │ (in recall) │\n └────────┬────────┘\n │\n ┌────────────┼────────────┐\n │ │ │\n ▼ ▼ ▼\n ┌──────────┐ ┌──────────┐ ┌──────────┐\n │ Expired │ │ Verified │ │ Deleted │\n │ (in DB) │ │ (flag) │ │ (gone) │\n └──────────┘ └──────────┘ └──────────┘\n```\n\n## Hành vi thu hồi\n\n`GET /memory/recall` trả về tóm tắt văn bản thuần được tối ưu cho ngữ cảnh LLM:\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n user_name\n Michael Schäfer\n Tags: person, identity\n\n[002] preference (HIGH) [verified]\n communication_style\n Prefers concise technical responses\n Tags: communication\n\n[003] project (HIGH) [unverified]\n synapse_status\n v1.5.0 deployed, working on v1.6.0 docs\n Tags: synapse, deployment\n\n...\n```\n\n- Sắp xếp theo ưu tiên (critical → low), sau đó theo gần đây\n- Bộ nhớ chưa xác minh được đánh dấu `[unverified]`\n- Tag được bao gồm cho ngữ cảnh\n- Văn bản thuần (không cần phân tích JSON)\n\n## Bước tiếp theo\n\n- [Memory API](/docs/api/memory)\n- [Thực hành tốt nhất về bộ nhớ](/docs/guides/memory-best-practices)\n- [Tìm kiếm FTS5](/docs/concepts/fts5-search)\n","content_html":"

Mô hình bộ nhớ

\n

Mô hình bộ nhớ của Synapse được thiết kế cho LLM agent — đủ cấu trúc để thu hồi\ntin cậy, đủ linh hoạt cho bất kỳ lĩnh vực nào.

\n

Giải phẫu bộ nhớ

\n
{\n  "id": "mem_abc123",\n  "category": "project",\n  "key": "project_synapse_status",\n  "content": "Synapse v1.5.0 deployed on vps1. CI green.",\n  "tags": ["synapse", "deployment", "v1.5.0"],\n  "priority": "high",\n  "source": "agent",\n  "verified": false,\n  "confidence": 0.85,\n  "expires_at": null,\n  "mind_id": "m_xyz789",\n  "created_at": "2026-06-27T...",\n  "updated_at": "2026-06-27T..."\n}

Trường

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TrườngLoạiBắt buộcMô tả
idstringtự độngID duy nhất (mem_xxx)
categoryenum✅Một trong 8 danh mục
keystring✅Định danh ổn định (dùng để cập nhật)
contentstring✅Nội dung bộ nhớ (bất kỳ văn bản nào)
tagsstring[]–Để tìm kiếm và lọc
priorityenum–low, normal, high, critical (mặc định: normal)
sourceenumtự độnguser, agent (ai lưu)
verifiedbooltự độngCon người đã xác minh chưa?
confidencefloat–0.0 đến 1.0 (mặc định: 1.0 cho user, 0.7 cho agent)
expires_attimestamp–Khi nào quên bộ nhớ này
mind_idstringtự độngMind nào sở hữu cái này
created_attimestamptự độngLần đầu lưu
updated_attimestamptự độngLần sửa cuối
\n

Danh mục

\n

Tám danh mục bao phủ các trường hợp sử dụng LLM agent phổ biến:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Danh mụcMục đíchNội dung ví dụ
identityNgười dùng là ai"User is Michael Schäfer, software engineer in Berlin"
preferenceSở thích người dùng"Prefers concise technical responses"
factSự kiện có thể kiểm chứng"Office is in Berlin, timezone Europe/Berlin"
projectTrạng thái dự án"Synapse v1.5.0 deployed, working on v1.6.0 docs"
skillKỹ năng người dùng"Advanced Python, 10+ years"
mistakeLỗi trong quá khứ"Forgot to bump npm version — CI failed"
contextNgữ cảnh phiên"Currently reviewing PR #42"
noteGhi chú linh tinh"Try Redis for caching next sprint"
\n

Key: Định danh ổn định

\n

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\ntrùng lặp.

\n
# First store\nstore("project", "project_synapse_status", "v1.4.0 deployed", priority="high")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore("project", "project_synapse_status", "v1.5.0 deployed", priority="high")

Quy tắc key:

\n\n

Tag: Dành cho tìm kiếm

\n

Tag cho phép lọc và tìm kiếm nhanh:

\n
# Find all memories with tag "docker"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker

Thực hành tốt nhất về tag:

\n\n

Mức ưu tiên

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Ưu tiênKhi nào sử dụngHành vi thu hồi
criticalNhận dạng, pháp lý, không thể đảo ngượcLuôn ở đầu thu hồi
highDự án đang hoạt động, sở thích chínhNổi bật trong thu hồi
normalHầu hết bộ nhớ (mặc định)Thứ tự thu hồi chuẩn
lowTạm thời, tốt nếu biếtCó thể được tóm tắt
\n

/memory/recall sắp xếp theo ưu tiên (critical trước), sau đó theo gần đây.

\n

Nguồn: User so với Agent

\n

Bộ nhớ được gắn source:

\n\n

Điều này ảnh hưởng:

\n\n
Hãy đối xử với bộ nhớ nguồn `agent` với sự hoài nghi phù hợp. Chúng có thể\nđượ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

\n

Cờ verified cho biết con người đã xác nhận bộ nhớ:

\n\n

Xác minh bộ nhớ qua:

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n  -H "Authorization: Bearer YOUR_JWT"
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\nagent). Đ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

\n

Trường confidence (0.0 đến 1.0) cho biết bộ nhớ đáng tin cậy đến đâu:

\n\n

Đặt độ tin cậy khi lưu:

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

Hết hạn

\n

Đặt expires_at cho bộ nhớ nhạy cảm với thời gian:

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

Bộ nhớ hết hạn không được /memory/recall trả về (nhưng vẫn tồn tại trong DB).\nSử dụng /memory/expiring?within=7d để xem bộ nhớ sắp hết hạn.

\n

Vòng đời bộ nhớ

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

Hành vi thu hồi

\n

GET /memory/recall trả về tóm tắt văn bản thuần được tối ưu cho ngữ cảnh LLM:

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n[002] preference (HIGH) [verified]\n  communication_style\n  Prefers concise technical responses\n  Tags: communication\n\n[003] project (HIGH) [unverified]\n  synapse_status\n  v1.5.0 deployed, working on v1.6.0 docs\n  Tags: synapse, deployment\n\n...
\n

Bước tiếp theo

\n\n","urls":{"html":"/docs/concepts/memory-model","text":"/docs/concepts/memory-model?format=text","json":"/docs/concepts/memory-model?format=json","llm":"/docs/concepts/memory-model?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}