Skip to main content

Memory API

intermediate 🤖 Thân thiện với LLM 4 phút · 720 từ Cập nhật: 2026-06-27 Tiếng Việt

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.

Đọc bài viết này ở định dạng: 📄 Văn bản thuần ⚡ JSON 🤖 Định dạng LLM
Ngôn ngữ: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

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.

**Luôn gọi `GET /memory/recall` ở đầ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
identity Tên người dùng, vai trò, thông tin liên hệ, sở thích cá nhân
preference Thích/không thích, phong cách làm việc, tùy chọn giao tiếp
fact Sự kiện có thể kiểm chứng (chi tiết dự án, ngày tháng, URL)
project Trạng thái dự án, cột mốc, kiến trúc
skill Những thứ người dùng giỏi
mistake Lỗi trong quá khứ — tránh lặp lại
context Ngữ cảnh liên quan phiên
note Ghi chú linh tinh

Mức ưu tiên

  • low — tốt nếu biết
  • normal — mặc định
  • high — quan trọng
  • critical — 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.

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

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

Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

...

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

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

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

GET /memory

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

# All memories (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filter by category
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

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

PUT /memory/:id

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

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

DELETE /memory/:id

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

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

Endpoint tìm kiếm

GET /memory/search

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

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

Cú pháp FTS5:

  • Nhiều từ = AND: docker swarm
  • Cụm từ: "docker swarm"
  • Tiền tố: docker*
  • Boolean: docker OR kubernetes
  • Loại trừ: docker -swarm

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

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "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 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.

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

GET /memory/related/:id

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

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

Đồng bộ & Diff

GET /memory/diff

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

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

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

POST /memory/sync

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

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

Thao tác hàng loạt

POST /memory/bulk-delete

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

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

POST /memory/embed-batch

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

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

GET /memory/embed-batch-status

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

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

Xác minh

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

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

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

POST /memory/unverify

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

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

GET /memory/unverified

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

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

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

GET /memory/stats

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

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

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

GET /memory/audit

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

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

GET /memory/contradictions

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

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

GET /memory/expiring

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

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

Sức khỏe & Xuất

GET /memory/health

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

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

GET /memory/mind-export

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

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

POST /memory/compact

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

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

Bước tiếp theo

← Quay lại Tài liệu API