{"title":"Memory API","slug":"memory","category":"api","summary":"Tham chiếu đầy đủ cho 22 endpoint bộ nhớ: lưu, thu hồi, tìm kiếm, tìm kiếm ngữ nghĩa, đồng bộ, kiểm toán, và hơn thế nữa.","audience":["human","llm"],"tags":["api","memory","crud","search","fts5","semantic"],"difficulty":"intermediate","updated":"2026-06-27","word_count":720,"read_minutes":4,"llm_context":"Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)\nALWAYS call GET /memory/recall at session start.\nPOST /memory with same category+key updates the existing memory.\nCategories: identity, preference, fact, project, skill, mistake, context, note, credentials\nPriorities: low, normal, high, critical\nSearch: GET /memory/search?q=... (FTS5 syntax: AND, OR, \"phrases\", prefix*)\nSemantic: GET /memory/semantic-search?q=... (slower, conceptual)\nSync: GET /memory/diff?since=TIMESTAMP (incremental sync)\nExport: GET /memory/mind-export (full JSON dump)\n","lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# Memory API\n\nMemory API là trái tim của Synapse. Nó cung cấp 22 endpoint để lưu trữ, truy\nxuấ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\nKey để xác thực.\n\n> [!CRITICAL]\n> **Luôn gọi `GET /memory/recall` ở đầu mỗi phiên.** Đây là cách duy nhất để\n> xây dựng lại ngữ cảnh từ các phiên trước.\n\n## Danh mục\n\nBộ nhớ được tổ chức thành 8 danh mục:\n\n| Danh mục | Trường hợp sử dụng |\n|----------|----------|\n| `identity` | Tên người dùng, vai trò, thông tin liên hệ, sở thích cá nhân |\n| `preference` | Thích/không thích, phong cách làm việc, tùy chọn giao tiếp |\n| `fact` | Sự kiện có thể kiểm chứng (chi tiết dự án, ngày tháng, URL) |\n| `project` | Trạng thái dự án, cột mốc, kiến trúc |\n| `skill` | Những thứ người dùng giỏi |\n| `mistake` | Lỗi trong quá khứ — tránh lặp lại |\n| `context` | Ngữ cảnh liên quan phiên |\n| `note` | Ghi chú linh tinh |\n\n## Mức ưu tiên\n\n- `low` — tốt nếu biết\n- `normal` — mặc định\n- `high` — quan trọng\n- `critical` — không bao giờ được quên (nhận dạng người dùng, thông tin pháp lý)\n\n## Endpoint cốt lõi\n\n### GET /memory/recall\n\nTrả 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\nnày ở đầu mỗi phiên.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\nPhản hồi (text/plain):\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n user_name\n Michael Schäfer\n Tags: person, identity\n\n...\n```\n\n### POST /memory\n\nLư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).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"category\": \"fact\",\n \"key\": \"user_name\",\n \"content\": \"The user's name is Michael Schäfer\",\n \"tags\": [\"person\", \"identity\"],\n \"priority\": \"critical\"\n }'\n```\n\nPhản hồi: `{ \"id\": \"mem_001\", \"status\": \"stored\" }`\n\n### GET /memory\n\nLiệt kê bộ nhớ với các bộ lọc tùy chọn.\n\n```bash\n# All memories (JSON)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?limit=50&offset=0\"\n\n# Filter by category\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?category=project\"\n\n# Filter by tag\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?tag=docker\"\n```\n\n### PUT /memory/:id\n\nCập nhật một bộ nhớ cụ thể theo ID.\n\n```bash\ncurl -X PUT https://synapse.schaefer.zone/memory/mem_001 \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Updated content\", \"priority\": \"high\"}'\n```\n\n### DELETE /memory/:id\n\nXóa một bộ nhớ đơn lẻ.\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Endpoint tìm kiếm\n\n### GET /memory/search\n\nTìm kiếm toàn văn sử dụng FTS5.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=docker+swarm\"\n```\n\nCú pháp FTS5:\n\n- Nhiều từ = AND: `docker swarm`\n- Cụm từ: `\"docker swarm\"`\n- Tiền tố: `docker*`\n- Boolean: `docker OR kubernetes`\n- Loại trừ: `docker -swarm`\n\n### GET /memory/semantic-search\n\nTìm kiếm khái niệm sử dụng embeddings (chậm hơn FTS5 nhưng hiểu ý nghĩa).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\nTrả về các bộ nhớ tương tự về mặt ngữ nghĩa với truy vấn, ngay cả khi không\nkhớp từ khóa. Hữu ích cho \"tìm bộ nhớ về X\" khi X được mô tả khác đi.\n\n### GET /memory/by-tag\n\nLiệt kê bộ nhớ theo tag.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/by-tag?tag=docker\"\n```\n\n### GET /memory/related/:id\n\nTìm bộ nhớ liên quan đến một bộ nhớ cụ thể (qua tag chung).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/related/mem_001\n```\n\n## Đồng bộ & Diff\n\n### GET /memory/diff\n\nĐồng bộ gia tăng — trả về bộ nhớ đã thay đổi kể từ một timestamp.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/diff?since=1700000000\"\n```\n\nPhản hồi: `{ \"added\": [...], \"updated\": [...], \"deleted\": [...] }`\n\n### POST /memory/sync\n\nÁp dụng một diff từ thể hiện khác (cho đồng bộ self-hosted).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/sync \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"added\": [...], \"updated\": [...], \"deleted\": [...]}'\n```\n\n## Thao tác hàng loạt\n\n### POST /memory/bulk-delete\n\nXóa nhiều bộ nhớ theo ID.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/bulk-delete \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n### POST /memory/embed-batch\n\nTạo embeddings cho các bộ nhớ chưa có (cho tìm kiếm ngữ nghĩa).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"limit\": 100}'\n```\n\n### GET /memory/embed-batch-status\n\nKiểm tra tiến độ tạo embedding.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## Xác minh\n\nBộ nhớ có cờ `verified`. Bộ nhớ do agent lưu mặc định chưa được xác minh\n(`source=agent`); bộ nhớ do con người lưu được xác minh (`source=user`).\n\n### POST /memory/verify\n\nĐánh dấu một bộ nhớ là đã xác minh (yêu cầu JWT, không phải Mind Key).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### POST /memory/unverify\n\nĐánh dấu một bộ nhớ là chưa xác minh (yêu cầu JWT).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### GET /memory/unverified\n\nLiệt kê bộ nhớ đang chờ xác minh bởi con người.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/unverified?limit=100\"\n```\n\n## Thống kê & Kiểm toán\n\n### GET /memory/stats\n\nThống kê tổng hợp cho mind hiện tại.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/stats\n```\n\nTrả về: `{ \"total\": 12, \"verified\": 10, \"unverified\": 2, \"by_category\": {...}, \"by_priority\": {...} }`\n\n### GET /memory/audit\n\nNhật ký kiểm toán của tất cả thao tác thay đổi trạng thái.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/audit?limit=100&action=store\"\n```\n\n### GET /memory/contradictions\n\nPhát hiện mâu thuẫn tiềm ẩn trong bộ nhớ đã lưu.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/contradictions\n```\n\n### GET /memory/expiring\n\nLiệt kê bộ nhớ có ngày hết hạn sắp tới.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/expiring?within=7d\"\n```\n\n## Sức khỏe & Xuất\n\n### GET /memory/health\n\nKiểm tra sức khỏe nhanh cho hệ thống bộ nhớ.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/health\n```\n\n### GET /memory/mind-export\n\nXuất JSON đầy đủ của tất cả bộ nhớ (để sao lưu).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mind-export > backup.json\n```\n\n### POST /memory/compact\n\nNén các bộ nhớ tương tự (tự động tóm tắt).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/compact \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"dry_run\": true}'\n```\n\n## Bước tiếp theo\n\n- [Quick Start cho LLM](/docs/getting-started/quick-start-llm)\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- [Tìm kiếm ngữ nghĩa](/docs/concepts/semantic-search)\n","content_html":"

Memory API

\n

Memory API là trái tim của Synapse. Nó cung cấp 22 endpoint để lưu trữ, truy\nxuấ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\nKey để xác thực.

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

Danh mục

\n

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

\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ụcTrường hợp sử dụng
identityTên người dùng, vai trò, thông tin liên hệ, sở thích cá nhân
preferenceThích/không thích, phong cách làm việc, tùy chọn giao tiếp
factSự kiện có thể kiểm chứng (chi tiết dự án, ngày tháng, URL)
projectTrạng thái dự án, cột mốc, kiến trúc
skillNhững thứ người dùng giỏi
mistakeLỗi trong quá khứ — tránh lặp lại
contextNgữ cảnh liên quan phiên
noteGhi chú linh tinh
\n

Mức ưu tiên

\n\n

Endpoint cốt lõi

\n

GET /memory/recall

\n

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\nnày ở đầu mỗi phiên.

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

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

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n...

POST /memory

\n

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).

\n
curl -X POST https://synapse.schaefer.zone/memory \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "category": "fact",\n    "key": "user_name",\n    "content": "The user's name is Michael Schäfer",\n    "tags": ["person", "identity"],\n    "priority": "critical"\n  }'

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

\n

GET /memory

\n

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

\n
# All memories (JSON)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?limit=50&offset=0"\n\n# Filter by category\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?category=project"\n\n# Filter by tag\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?tag=docker"

PUT /memory/:id

\n

Cập nhật một bộ nhớ cụ thể theo ID.

\n
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"content": "Updated content", "priority": "high"}'

DELETE /memory/:id

\n

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

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

Endpoint tìm kiếm

\n

GET /memory/search

\n

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

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

Cú pháp FTS5:

\n\n

GET /memory/semantic-search

\n

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

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "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\nkhớp từ khóa. Hữu ích cho "tìm bộ nhớ về X" khi X được mô tả khác đi.

\n

GET /memory/by-tag

\n

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

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

GET /memory/related/:id

\n

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

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

Đồng bộ & Diff

\n

GET /memory/diff

\n

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

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

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

\n

POST /memory/sync

\n

Áp dụng một diff từ thể hiện khác (cho đồng bộ self-hosted).

\n
curl -X POST https://synapse.schaefer.zone/memory/sync \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"added": [...], "updated": [...], "deleted": [...]}'

Thao tác hàng loạt

\n

POST /memory/bulk-delete

\n

Xóa nhiều bộ nhớ theo ID.

\n
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'

POST /memory/embed-batch

\n

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

\n
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"limit": 100}'

GET /memory/embed-batch-status

\n

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

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

Xác minh

\n

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

\n

POST /memory/verify

\n

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

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

POST /memory/unverify

\n

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

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

GET /memory/unverified

\n

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

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

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

\n

GET /memory/stats

\n

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

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

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

\n

GET /memory/audit

\n

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

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

GET /memory/contradictions

\n

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

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

GET /memory/expiring

\n

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

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

Sức khỏe & Xuất

\n

GET /memory/health

\n

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

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

GET /memory/mind-export

\n

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

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

POST /memory/compact

\n

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

\n
curl -X POST https://synapse.schaefer.zone/memory/compact \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"dry_run": true}'

Bước tiếp theo

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