# Memory 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.

KEY CONTEXT:
Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)
ALWAYS call GET /memory/recall at session start.
POST /memory with same category+key updates the existing memory.
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
Search: GET /memory/search?q=... (FTS5 syntax: AND, OR, "phrases", prefix*)
Semantic: GET /memory/semantic-search?q=... (slower, conceptual)
Sync: GET /memory/diff?since=TIMESTAMP (incremental sync)
Export: GET /memory/mind-export (full JSON dump)

Memory API
Memory API là trái tim của Synapse. Nó cung cấp 22 endpoint để lưu trữ, truy
xuấ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
Key để xác thực.
> [!CRITICAL]
> Luôn gọi  ở đầu mỗi phiên. Đây là cách duy nhất để
> xây dựng lại ngữ cảnh từ các phiên trước.
Danh mục
Bộ nhớ được tổ chức thành 8 danh mục:
| Danh mục | Trường hợp sử dụng |
|----------|----------|
|  | Tên người dùng, vai trò, thông tin liên hệ, sở thích cá nhân |
|  | Thích/không thích, phong cách làm việc, tùy chọn giao tiếp |
|  | Sự kiện có thể kiểm chứng (chi tiết dự án, ngày tháng, URL) |
|  | Trạng thái dự án, cột mốc, kiến trúc |
|  | Những thứ người dùng giỏi |
|  | Lỗi trong quá khứ — tránh lặp lại |
|  | Ngữ cảnh liên quan phiên |
|  | Ghi chú linh tinh |
Mức ưu tiên
-  — tốt nếu biết
-  — mặc định
-  — quan trọng
-  — không bao giờ được quên (nhận dạng người dùng, thông tin pháp lý)
Endpoint cốt lõi
GET /memory/recall
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
này ở đầu mỗi phiên.
[CODE BLOCK]
Phản hồi (text/plain):
[CODE BLOCK]
POST /memory
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).
[CODE BLOCK]
Phản hồi: 
GET /memory
Liệt kê bộ nhớ với các bộ lọc tùy chọn.
[CODE BLOCK]
PUT /memory/:id
Cập nhật một bộ nhớ cụ thể theo ID.
[CODE BLOCK]
DELETE /memory/:id
Xóa một bộ nhớ đơn lẻ.
[CODE BLOCK]
Endpoint tìm kiếm
GET /memory/search
Tìm kiếm toàn văn sử dụng FTS5.
[CODE BLOCK]
Cú pháp FTS5:
- Nhiều từ = AND: 
- Cụm từ: 
- Tiền tố: 
- Boolean: 
- Loại trừ: 
GET /memory/semantic-search
Tìm kiếm khái niệm sử dụng embeddings (chậm hơn FTS5 nhưng hiểu ý nghĩa).
[CODE BLOCK]
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
khớp từ khóa. Hữu ích cho "tìm bộ nhớ về X" khi X được mô tả khác đi.
GET /memory/by-tag
Liệt kê bộ nhớ theo tag.
[CODE BLOCK]
GET /memory/related/:id
Tìm bộ nhớ liên quan đến một bộ nhớ cụ thể (qua tag chung).
[CODE BLOCK]
Đồng bộ & Diff
GET /memory/diff
Đồng bộ gia tăng — trả về bộ nhớ đã thay đổi kể từ một timestamp.
[CODE BLOCK]
Phản hồi: 
POST /memory/sync
Áp dụng một diff từ thể hiện khác (cho đồng bộ self-hosted).
[CODE BLOCK]
Thao tác hàng loạt
POST /memory/bulk-delete
Xóa nhiều bộ nhớ theo ID.
[CODE BLOCK]
POST /memory/embed-batch
Tạo embeddings cho các bộ nhớ chưa có (cho tìm kiếm ngữ nghĩa).
[CODE BLOCK]
GET /memory/embed-batch-status
Kiểm tra tiến độ tạo embedding.
[CODE BLOCK]
Xác minh
Bộ nhớ có cờ . Bộ nhớ do agent lưu mặc định chưa được xác minh
(); bộ nhớ do con người lưu được xác minh ().
POST /memory/verify
Đánh dấu một bộ nhớ là đã xác minh (yêu cầu JWT, không phải Mind Key).
[CODE BLOCK]
POST /memory/unverify
Đánh dấu một bộ nhớ là chưa xác minh (yêu cầu JWT).
[CODE BLOCK]
GET /memory/unverified
Liệt kê bộ nhớ đang chờ xác minh bởi con người.
[CODE BLOCK]
Thống kê & Kiểm toán
GET /memory/stats
Thống kê tổng hợp cho mind hiện tại.
[CODE BLOCK]
Trả về: 
GET /memory/audit
Nhật ký kiểm toán của tất cả thao tác thay đổi trạng thái.
[CODE BLOCK]
GET /memory/contradictions
Phát hiện mâu thuẫn tiềm ẩn trong bộ nhớ đã lưu.
[CODE BLOCK]
GET /memory/expiring
Liệt kê bộ nhớ có ngày hết hạn sắp tới.
[CODE BLOCK]
Sức khỏe & Xuất
GET /memory/health
Kiểm tra sức khỏe nhanh cho hệ thống bộ nhớ.
[CODE BLOCK]
GET /memory/mind-export
Xuất JSON đầy đủ của tất cả bộ nhớ (để sao lưu).
[CODE BLOCK]
POST /memory/compact
Nén các bộ nhớ tương tự (tự động tóm tắt).
[CODE BLOCK]
Bước tiếp theo
- Quick Start cho LLM
- Thực hành tốt nhất về bộ nhớ
- Tìm kiếm FTS5
- Tìm kiếm ngữ nghĩa