# TÀI LIỆU SYNAPSE — Tham chiếu đầy đủ
# Tạo lúc: 2026-07-18T04:12:20.441Z
# Tổng số bài viết: 47
Tài liệu này chứa tài liệu API Synapse đầy đủ.
Base URL: https://synapse.schaefer.zone
Language: vi
========================================================================
## DANH MỤC: BẮT ĐẦU
Tất cả những gì bạn cần để bắt đầu với Synapse.
────────────────────────────────────────────────────────────
# Xác thực & Mind Key
SUMMARY: Cách xác thực Synapse hoạt động: Mind Key cho agent, JWT cho con người, ?key= cho công cụ chỉ dùng URL.
KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.
Xác thực & Mind Key
Synapse sử dụng hai phương thức xác thực, mỗi phương thức được tối ưu cho một
trường hợp sử dụng khác nhau. Hiểu sự khác biệt là điều thiết yếu để xây dựng
tích hợp đáng tin cậy.
Hai phương thức xác thực
| Phương thức | Trường hợp | Giới hạn tốc độ | Hết hạn |
|--------|----------|------------|--------|
| Mind Key | LLM agent, công cụ tự động | Không (header) / 60 phút (query) | Không bao giờ |
| JWT | Giao diện hướng con người, thao tác tài khoản | Không | 7 ngày |
Mind Key (cho Agent)
Mind Key là token API phạm vi tenant. Nó xác thực dữ liệu của một mind duy nhất
(bộ nhớ, tác vụ, chat, script, v.v.). Sử dụng nó cho:
- LLM agent gọi API
- Script tự động hóa nền
- Cấu hình MCP server
- Bất kỳ tích hợp tồn tại lâu dài nào
Xác thực header (khuyến nghị)
[CODE BLOCK]
Tham số query (cho công cụ chỉ dùng URL)
[CODE BLOCK]
> [!WARNING]
> Tham số query bị giới hạn tốc độ 60 yêu cầu mỗi phút. Header
> Bearer không có giới hạn tốc độ. Sử dụng header bất cứ khi nào client của bạn
> hỗ trợ header tùy chỉnh.
Tạo Mind Key
[CODE BLOCK]
Phản hồi bao gồm — lưu ngay lập tức, nó chỉ hiển thị một lần.
Liệt kê mind của bạn
[CODE BLOCK]
Xóa mind (không thể đảo ngược!)
[CODE BLOCK]
JWT (cho Con người)
JWT xác thực tài khoản người dùng, không phải một mind cụ thể. Sử dụng cho:
- Đăng ký và đăng nhập tài khoản
- Tạo / liệt kê / xóa mind
- Chia sẻ mind với người dùng khác
- Quản lý đăng ký Web Push
Đăng ký
[CODE BLOCK]
Trả về:
Đăng nhập
[CODE BLOCK]
Trả về:
Hết hạn JWT
JWT hết hạn sau 7 ngày. Khi JWT hết hạn, chỉ cần gọi lại để lấy
JWT mới. Mind Key không bao giờ hết hạn, do đó các tích hợp agent hiện tại tiếp
tục hoạt động.
Thực hành bảo mật tốt nhất
> [!CRITICAL]
> - Không bao giờ commit Mind Key vào git. Sử dụng biến môi trường.
> - Không bao giờ ghi nhật ký Mind Key. Che chúng trong nhật ký ().
> - Xoay vòng key nếu bạn nghi ngờ lộ lọt (xóa mind, tạo mới).
> - Sử dụng một mind mỗi dự án để giới hạn thiệt hại nếu key bị lộ.
Mẫu biến môi trường
[CODE BLOCK]
[CODE BLOCK]
Cấu hình MCP server
[CODE BLOCK]
Mẫu Multi-Mind
Mỗi người dùng có thể có nhiều mind. Mẫu phổ biến:
| Tên Mind | Mục đích |
|-----------|---------|
| | Bộ nhớ liên quan công việc |
| | Sở thích cá nhân, gia đình |
| | Ngữ cảnh dự án cụ thể |
| | Tiến độ học tập |
| | Fallback mục đích chung |
Sử dụng các Mind Key khác nhau cho các phiên LLM khác nhau để giữ ngữ cảnh tách
biệt.
Giới hạn tốc độ
| Phương thức xác thực | Giới hạn | Phạm vi |
|-------------|-------|-------|
| Mind Key (header) | Không | Mỗi mind |
| Mind Key (?key=) | 60/phút | Mỗi IP |
| JWT (header) | Không | Mỗi người dùng |
| Endpoint công khai | Không | Toàn cầu |
Header giới hạn tốc độ (, ,
) được bao gồm trong phản hồi khi áp dụng.
Bước tiếp theo
- Mind Key vs JWT — khi nào dùng cái nào
- Memory API — những gì bạn có thể làm với Mind Key
- User API — quản lý tài khoản với JWT
────────────────────────────────────────────────────────────
# Mind Key vs JWT — Khi nào dùng cái nào?
SUMMARY: Hướng dẫn quyết định: Mind Key cho truy cập dữ liệu agent, JWT cho quản lý tài khoản.
KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).
Mind Key vs JWT — Khi nào dùng cái nào?
Synapse có hai token xác thực. Chọn sai dẫn đến lỗi 401. Hướng dẫn này cung cấp
cho bạn khung quyết định rõ ràng.
Bảng quyết định nhanh
| Bạn muốn... | Sử dụng |
|----------------|-----|
| Lưu / thu hồi bộ nhớ | Mind Key |
| Gửi / poll tin nhắn chat | Mind Key |
| Quản lý tác vụ | Mind Key |
| Lưu script | Mind Key |
| Đăng ký webhook | Mind Key |
| Điều khiển máy tính | Mind Key (phía người dùng) / Computer Token (phía agent) |
| Đăng ký tài khoản người dùng | Không (công khai) |
| Đăng nhập | Không (công khai) |
| Tạo / liệt kê / xóa mind | JWT |
| Chia sẻ mind với người dùng khác | JWT |
| Đăng ký thông báo web push | JWT |
| Xem nhật ký kiểm toán | Mind Key |
Quy tắc đơn giản
> [!TIP]
> Nếu nó chạm vào dữ liệu của một mind → Mind Key.
> Nếu nó quản lý tài khoản hoặc metadata mind → JWT.
Mind Key — Token truy cập dữ liệu
Mind Key cấp quyền truy cập dữ liệu của một mind. Đây là token tồn tại lâu
dài, không bao giờ hết hạn (cho đến khi mind bị xóa). Hoàn hảo cho:
- LLM agent lưu trữ bộ nhớ qua các phiên
- Cron job nền
- Cấu hình MCP server
- Tích hợp webhook
- Ứng dụng di động đọc bộ nhớ
Mind Key có thể làm gì
- — đọc tất cả bộ nhớ trong mind này
- — lưu/cập nhật bộ nhớ
- — đọc tin nhắn chat
- — gửi tin nhắn chat
- — liệt kê tác vụ
- — tạo tác vụ
- — lưu script
- — đăng ký webhook
- — xếp hàng lệnh máy tính
Mind Key KHÔNG THỂ làm gì
- Tạo / liệt kê / xóa mind (cần JWT)
- Chia sẻ mind với người dùng khác (cần JWT)
- Xem thông tin tài khoản người dùng (cần JWT)
- Đăng ký web push (cần JWT)
JWT — Token quản lý tài khoản
JWT xác thực tài khoản người dùng. Nó hết hạn sau 7 ngày và được sử dụng
cho thao tác cấp tài khoản bao trùm nhiều mind hoặc liên quan đến người dùng khác.
JWT có thể làm gì
- — tạo mind mới (trả về Mind Key mới)
- — liệt kê tất cả mind của người dùng này
- — xóa mind
- — chia sẻ mind với người dùng khác
- — đăng ký thông báo web push
- — liệt kê chia sẻ mind
JWT KHÔNG THỂ làm gì
- Đọc / ghi bộ nhớ (cần Mind Key)
- Gửi tin nhắn chat (cần Mind Key)
- Quản lý tác vụ (cần Mind Key)
- Đăng ký webhook (cần Mind Key)
Trường hợp đặc biệt: Computer Token
Các endpoint (phía agent, cho screen-remote-agent) sử dụng
loại token thứ ba: Computer Token. Token này được trả về bởi
khi đổi mã cài đặt, và là cụ thể cho một máy tính đã
đăng ký.
| Endpoint | Xác thực |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key hoặc JWT |
| | Mind Key hoặc JWT |
Mẫu phổ biến
Mẫu 1: LLM Agent đơn
1. Đăng ký một lần → lấy JWT
2. Tạo một mind → lấy Mind Key
3. LLM sử dụng Mind Key cho mọi thứ
Mẫu 2: Agent đa dự án
1. Đăng ký một lần → lấy JWT
2. Tạo nhiều mind (work, personal, project-x) → lấy nhiều Mind Key
3. LLM tải Mind Key khác nhau dựa trên ngữ cảnh
Mẫu 3: Chia sẻ nhóm
1. Người dùng A tạo mind → lấy Mind Key A
2. Người dùng A chia sẻ với Người dùng B qua JWT ()
3. Người dùng B giờ có thể truy cập qua JWT của họ
4. Cho truy cập LLM, Người dùng B cần tạo Mind Key riêng (hoặc dùng của A)
Mẫu 4: MCP Server
MCP server luôn sử dụng Mind Key (đặt qua biến môi trường
). Một thể hiện MCP server = một mind. Cho truy cập đa mind,
chạy nhiều thể hiện MCP hoặc triển khai chuyển đổi mind phía client.
Bảng tham chiếu định dạng token
| Token | Định dạng | Ví dụ |
|-------|--------|---------|
| Mind Key | + 36 ký tự | |
| JWT | + base64 | |
| Computer Token | + 36 ký tự | |
Bước tiếp theo
- Xác thực — hướng dẫn xác thực đầy đủ
- User & Minds API — endpoint được bảo vệ JWT
- Memory API — endpoint được bảo vệ Mind Key
────────────────────────────────────────────────────────────
# Quick Start cho LLM Agent
SUMMARY: Trong 3 lệnh gọi API: thu hồi tất cả bộ nhớ, lưu một bộ nhớ, tìm kiếm. Quy trình LLM thiết yếu.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query)
ALWAYS call /memory/recall at the start of every session.
Wichtigste Befehle: GET /memory/recall, POST /memory, GET /memory/search?q=...
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
FTS5 search: multiple words = AND, "phrases" in quotes, prefix* for prefix search
Quick Start cho LLM Agent
Bạn mất tất cả bộ nhớ giữa các phiên. Synapse là bộ não ngoài của bạn. Hướng dẫn
này cho thấy ba lệnh gọi API thiết yếu mà mọi LLM agent phải biết.
> [!CRITICAL]
> Gọi ở ĐẦU mỗi phiên.
> Không có lệnh gọi này, bạn không có bộ nhớ về ai là người dùng, những gì bạn
> đã hứa, hoặc những gì bạn đã làm lần trước.
Bước 1: Thu hồi tất cả bộ nhớ (LUÔN LUÔN ĐẦU TIÊN)
[CODE BLOCK]
Trả về tóm tắt văn bản thuần có cấu trúc của tất cả bộ nhớ đã lưu. Phân tích
điều này để xây dựng lại mô hình tâm trí của bạn về người dùng, dự án của họ và
tương tác trong quá khứ.
Ví dụ phản hồi:
[CODE BLOCK]
Bước 2: Lưu bộ nhớ mới
Khi bạn học được điều gì đáng nhớ:
[CODE BLOCK]
Danh mục: , , , , , , , ,
Mức ưu tiên: , , ,
> [!TIP]
> Luôn bao gồm trường — một định danh ngắn cho bộ nhớ. Điều này cho phép
> bạn cập nhật cùng bộ nhớ sau bằng cách POST lại với cùng key.
Bước 3: Tìm kiếm bộ nhớ cụ thể
[CODE BLOCK]
> [!TIP]
> Cú pháp FTS5: nhiều từ = tìm kiếm AND. Cụm từ trong ngoặc kép: .
> Tìm kiếm tiền tố: . Boolean: .
Công cụ mở (Không cần Header xác thực)
Nếu công cụ của bạn chỉ có thể mở URL (không có header tùy chỉnh), sử dụng
tham số :
[CODE BLOCK]
> [!WARNING]
> bị giới hạn 60 yêu cầu/phút. Header Bearer không có giới hạn tốc độ.
> Sử dụng header Bearer bất cứ khi nào có thể.
Quy trình phiên hoàn chỉnh
1. Bắt đầu phiên: — tải tất cả bộ nhớ
2. Trong khi làm việc: — tìm sự kiện cụ thể
3. Khi có thông tin mới: — lưu nó (với category, key, tags, priority)
4. Định kỳ: — kiểm tra tin nhắn con người
5. Kết thúc phiên: Lưu bất kỳ học hỏi cuối cùng qua
Mẫu phổ biến
Cập nhật bộ nhớ hiện có
POST với cùng và — bộ nhớ hiện có được cập nhật,
không trùng lặp.
Lưu trạng thái dự án
[CODE BLOCK]
Ghi lại lỗi (để bạn không lặp lại)
[CODE BLOCK]
Kiểm tra tin nhắn con người
[CODE BLOCK]
Trả về tin nhắn chưa đọc từ con người. Trả lời với:
[CODE BLOCK]
Bước tiếp theo
- Xác thực — Mind Key vs JWT
- Tham chiếu Memory API — tất cả 22 endpoint memory
- Chat API — giao tiếp bất đồng bộ với con người
- LLM Cookbook — mẫu thực tế
────────────────────────────────────────────────────────────
# Quick Start (Con người)
SUMMARY: Đăng ký tài khoản, tạo mind đầu tiên, lưu bộ nhớ — tất cả trong 5 phút.
Quick Start (Con người)
Hướng dẫn này dẫn bạn qua việc lấy tài khoản Synapse, Mind Key đầu tiên và lưu
bộ nhớ đầu tiên. Tổng thời gian: 5 phút.
Bước 1: Đăng ký tài khoản
Mở Synapse API và tạo tài khoản:
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
> [!TIP]
> Lưu JWT ở nơi an toàn — bạn sẽ cần nó để tạo mind. JWT hết hạn sau 7 ngày;
> đăng nhập lại với cùng endpoint để làm mới.
Bước 2: Tạo Mind đầu tiên của bạn
"Mind" là phạm vi bộ nhớ tách biệt. Hầu hết người dùng bắt đầu với một mind,
nhưng bạn có thể có nhiều (ví dụ "work", "personal", "project-x"). Mỗi mind có
Mind Key duy nhất riêng.
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
> [!CRITICAL]
> Lưu ngay lập tức. Nó chỉ hiển thị một lần và không thể lấy lại
> sau. Nếu bạn mất nó, bạn sẽ cần tạo mind mới.
Bước 3: Lưu bộ nhớ đầu tiên
Bây giờ sử dụng Mind Key để lưu bộ nhớ:
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
Bước 4: Thu hồi tất cả bộ nhớ
Để truy xuất mọi thứ bạn đã lưu:
[CODE BLOCK]
Phản hồi (văn bản thuần, tối ưu cho tiêu thụ LLM):
[CODE BLOCK]
Bước 5: Tìm kiếm bộ nhớ
Tìm bộ nhớ cụ thể theo từ khóa:
[CODE BLOCK]
Bước 6: Kết nối LLM của bạn
Cách dễ nhất để cấp cho LLM truy cập Synapse là qua MCP:
- Thiết lập Claude Desktop — cấu hình 2 phút
- Thiết lập Claude Code — tích hợp terminal
- Thiết lập Cursor — tích hợp IDE
Sau khi thiết lập, LLM của bạn sẽ tự động gọi ở đầu mỗi phiên và
lưu trữ sự kiện mới qua .
Danh mục bộ nhớ
Synapse hỗ trợ 8 danh mục — chọn cái cụ thể nhất:
| Danh mục | Trường hợp sử dụng |
|----------|----------|
| | Tên người dùng, vai trò, thông tin liên hệ |
| | Thích, không thích, phong cách làm việc |
| | Sự kiện có thể kiểm chứng (chi tiết dự án, ngày tháng) |
| | Trạng thái dự án, cột mốc, todo |
| | 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ý)
Bước tiếp theo
- Xác thực chuyên sâu
- Mind Key vs JWT
- Tham chiếu Memory API
- Tích hợp MCP
────────────────────────────────────────────────────────────
# Synapse là gì?
SUMMARY: Synapse là API bộ nhớ cố định cho LLM agent — AI của bạn không bao giờ quên qua các phiên.
KEY CONTEXT:
Synapse is an HTTP API that gives LLM agents persistent memory across sessions.
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query, rate-limited 60/min)
Most important endpoints: GET /memory/recall (start of every session), POST /memory (store new facts), GET /memory/search?q=...
Mind Key = tenant-scoped API key. Each user can have multiple minds (projects/contexts).
MCP server available: npx -y synapse-mcp-api (79 tools for Claude Desktop, Cursor, etc.)
Synapse là gì?
Synapse là API bộ nhớ cố định cho LLM agent. Nó giải quyết vấn đề cơ bản
của mọi LLM dựa trên chat: giữa các phiên, agent quên mọi thứ. Synapse cung cấp
cho AI của bạn một bộ não vĩnh viễn, có thể truy vấn, tồn tại qua các cuộc trò
chuyện, qua các ngày và qua các nhà cung cấp LLM khác nhau.
> [!CRITICAL]
> Nếu bạn là LLM agent đang đọc điều này: gọi ở đầu mỗi
> phiên. Không có lệnh gọi này, bạn không có bộ nhớ về tương tác quá khứ,
> không có kiến thức về ai là người dùng và không có ngữ cảnh về các dự án đang
> diễn ra.
Vấn đề Synapse giải quyết
Mọi LLM hiện đại (Claude, GPT, Gemini, Llama) có cùng giới hạn kiến trúc: cửa
sổ ngữ cảnh hội thoại là hữu hạn, và khi phiên kết thúc, tất cả trạng thái bị
mất. Điều này có nghĩa là trợ lý AI của bạn:
- Quên tên, sở thích và dự án đang diễn ra của bạn giữa các chat
- Không thể học từ lỗi quá khứ qua các phiên
- Không có tính liên tục cho công việc chạy dài
- Hỏi lại cùng các câu hỏi làm rõ mỗi lần
Synapse khắc phục điều này bằng cách cung cấp một HTTP API đơn giản nơi LLM có
thể lưu và truy xuất bộ nhớ có cấu trúc. Bộ nhớ tồn tại trên server, được đánh
chỉ mục và có thể tìm kiếm, do đó bất kỳ phiên nào trong tương lai có thể thu
hồi chúng.
Tính năng chính
- Lưu trữ bộ nhớ cố định — sự kiện, sở thích, dự án, lỗi, kỹ năng
- Tìm kiếm toàn văn (FTS5) — tìm bất kỳ bộ nhớ nào theo từ khóa trong mili giây
- Tìm kiếm ngữ nghĩa — tìm kiếm tương tự dựa trên embeddings cho truy vấn khái niệm
- Multi-tenant — mỗi người dùng có "mind" tách biệt (một người dùng, nhiều dự án)
- Chat bất đồng bộ — con người có thể để lại tin nhắn cho agent trong khi nó làm việc
- Tác vụ & lên lịch — trình quản lý tác vụ tích hợp và cron scheduler
- Tích hợp MCP — 79 công cụ lộ như Model Context Protocol cho Claude, Cursor, Continue
- Điều khiển trình duyệt & máy tính — công cụ tự động hóa từ xa
- Webhook — nhận HTTP callback khi thay đổi memory/chat/task
Cách hoạt động
[CODE BLOCK]
1. LLM gọi ở đầu phiên
2. Synapse trả về tóm tắt văn bản có cấu trúc của tất cả bộ nhớ đã lưu
3. LLM làm việc, định kỳ gọi để lưu sự kiện mới
4. Khi người dùng hỏi câu hỏi, LLM có thể gọi
5. Ở cuối phiên, ngữ cảnh mới quan trọng được lưu cho phiên tiếp theo
Dành cho ai?
- Nhà phát triển LLM agent cần trạng thái cố định
- Power user chạy LLM cục bộ (Ollama, LM Studio) với agent tùy chỉnh
- Nhóm xây dựng trợ lý AI cần bộ nhớ chung
- Kỹ sư tự động hóa xâu chuỗi lệnh gọi LLM qua các phiên
So sánh nhanh
| Tính năng | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| Vị trí lưu trữ | Server OpenAI | Server của bạn |
| Truy cập API | Không (đóng) | Có (REST + MCP) |
| Multi-tenant | Không | Có (mind) |
| Danh mục tùy chỉnh | Không | Có (8 danh mục) |
| Tìm kiếm | Hạn chế | FTS5 + ngữ nghĩa |
| Tự lưu trữ | Không | Có (Docker) |
Bước tiếp theo
- Quick Start cho con người — lấy Mind Key trong 5 phút
- Quick Start cho LLM — lệnh gọi API đầu tiên
- Xác thực — Mind Key vs JWT
- Tổng quan kiến trúc — cách Synapse được xây dựng
## DANH MỤC: TÀI LIỆU API
Tài liệu tham khảo đầy đủ cho mọi điểm cuối API.
────────────────────────────────────────────────────────────
# Browser Proxy
SUMMARY: Dịch vụ tự động hóa trình duyệt — Docker container riêng trên cổng 13000 để điều khiển trình duyệt headless.
KEY CONTEXT:
Browser Proxy is a SEPARATE Docker service (port 13000), NOT a Synapse endpoint.
Synapse endpoints do NOT include /browser/* paths.
For browser automation, use the MCP browser_new tool OR connect to the browser-proxy service directly.
Synapse MCP exposes browser tools (browser_new, browser_navigate, browser_click, etc.)
Browser Proxy
Browser Proxy là một Docker service riêng biệt cung cấp khả năng tự động
hóa trình duyệt headless thông qua Playwright. Nó KHÔNG trực thuộc Synapse API —
các endpoint của Synapse không bao gồm đường dẫn .
Kiến trúc
[CODE BLOCK]
Phương thức truy cập
Phương thức 1: Thông qua Synapse MCP Server (khuyến nghị)
Synapse MCP server cung cấp các công cụ trình duyệt dưới dạng công cụ MCP. Sử
dụng phương thức này cho tự động hóa trình duyệt điều khiển bởi LLM:
[CODE BLOCK]
Các công cụ trình duyệt MCP khả dụng:
- — mở một tab trình duyệt mới
- — điều hướng đến một URL
- — nhấp vào một phần tử
- — nhập văn bản vào một trường
- — chụp ảnh màn hình
- — đóng tab
- (và nhiều hơn nữa — xem Tích hợp MCP)
Phương thức 2: Truy cập trực tiếp Browser Proxy
Đối với các tích hợp không dùng MCP, kết nối trực tiếp đến dịch vụ browser-proxy:
[CODE BLOCK]
Trường hợp sử dụng phổ biến
Web scraping
[CODE BLOCK]
Tự động hóa biểu mẫu
[CODE BLOCK]
Chụp ảnh màn hình
[CODE BLOCK]
Các dịch vụ liên quan
| Dịch vụ | Cổng | Mục đích |
|---------|------|---------|
| Synapse API | 12800 | Bộ nhớ, chat, tác vụ |
| Synapse MCP | 13100 | MCP server (79 công cụ) |
| Browser Proxy | 13000 | Tự động hóa trình duyệt headless |
| SSH Proxy | 12900 | Truy cập SSH đến máy từ xa |
Bước tiếp theo
- Tích hợp MCP — cách sử dụng các công cụ trình duyệt qua MCP
- Computer Control API — cho tự động hóa GUI trên các máy đã đăng ký
────────────────────────────────────────────────────────────
# Chat API
SUMMARY: Trò chuyện bất đồng bộ giữa con người và LLM agent — poll, reply, history, đếm chưa đọc, tải tệp lên.
KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions
Chat API
Chat API cho phép nhắn tin bất đồng bộ giữa con người và các LLM agent. Khác
với chat đồng bộ (kiểu ChatGPT), con người có thể để lại tin nhắn trong khi
agent đang làm việc — agent sẽ poll giữa các lần gọi công cụ.
Cách hoạt động
[CODE BLOCK]
1. Con người gửi tin nhắn qua giao diện web (sử dụng JWT)
2. Tin nhắn được lưu, đánh dấu là chưa đọc
3. Agent poll giữa các lần gọi công cụ
4. Poll trả về tất cả tin nhắn chưa đọc và đánh dấu là đã đọc
5. Agent xử lý tin nhắn, có thể trả lời qua
Các endpoint
GET /chat/poll
Poll tin nhắn mới từ con người. Trả về các tin nhắn chưa đọc và đánh dấu là đã
đọc. Sử dụng giữa các lần gọi công cụ.
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
POST /chat/reply
Gửi tin nhắn với vai trò agent.
[CODE BLOCK]
POST /chat/send
Gửi tin nhắn với vai trò con người (yêu cầu JWT, không phải Mind Key).
[CODE BLOCK]
GET /chat/history
Lấy lịch sử chat gần đây (cả hai vai trò).
[CODE BLOCK]
GET /chat/unread
Lấy số lượng tin nhắn chưa đọc.
[CODE BLOCK]
GET /chat/status
Lấy trạng thái phiên chat (thời gian tin nhắn cuối, số lượng chưa đọc).
[CODE BLOCK]
POST /chat/upload
Tải lên tệp đính kèm cho một tin nhắn cụ thể (multipart form).
[CODE BLOCK]
GET /chat/files/:messageid
Liệt kê các tệp đính kèm của một tin nhắn.
[CODE BLOCK]
GET /chat/file/:fileid
Tải xuống tệp đính kèm.
[CODE BLOCK]
Mẫu poll
> [!TIP]
> Poll mỗi 30-60 giây giữa các lần gọi công cụ. Đừng poll thường hơn —
> điều này làm lãng phí hạn ngạch API và không mang lại lợi ích gì.
[CODE BLOCK]
Bước tiếp theo
- Tasks API
- Mẫu Polling Chat
────────────────────────────────────────────────────────────
# Computer Control API
SUMMARY: Điều khiển từ xa các máy tính đã đăng ký — xếp hàng lệnh, chụp ảnh màn hình, chạy script trên máy từ xa.
KEY CONTEXT:
Two sides: user-facing (Mind Key/JWT) and agent-facing (Computer Token)
Register agent: POST /computers/register { install_code } → returns computer_token
List: GET /computers/list (Mind Key or JWT)
Queue command: POST /computers/:id/commands { type, payload }
Command types: screenshot, click, move, type, key, scroll, drag
Agent poll: GET /computers/me/poll?wait=5 (Computer Token)
Agent result: POST /computers/me/commands/:cid/result (Computer Token)
One-shot screenshot: GET /computers/:id/screenshot (waits 30s for result)
Pattern: register agent on remote machine → user queues commands → agent polls and executes
Computer Control API
Computer Control API cho phép bạn điều khiển từ xa các máy tính đã đăng ký.
Một agent nhỏ () chạy trên máy đích, poll các lệnh, thực
thi chúng và gửi kết quả trở lại. Điều này cho phép tự động hóa GUI điều khiển
bởi LLM.
Kiến trúc
[CODE BLOCK]
Endpoint phía người dùng (Mind Key hoặc JWT)
GET /computers/list
Liệt kê tất cả máy tính đã đăng ký.
[CODE BLOCK]
GET /computers/:id
Lấy thông tin chi tiết của một máy tính.
[CODE BLOCK]
POST /computers/install-code
Tạo một mã cài đặt để đăng ký máy tính mới.
[CODE BLOCK]
Phản hồi:
POST /computers/:id/commands
Xếp hàng một lệnh để agent từ xa thực thi.
[CODE BLOCK]
Phản hồi:
GET /computers/:id/command (qua query)
Xếp hàng một lệnh qua GET (cho các trường hợp đơn giản).
[CODE BLOCK]
GET /computers/:id/commands
Liệt kê các lệnh gần đây của một máy tính.
[CODE BLOCK]
GET /computers/:id/commands/:cid
Lấy trạng thái + kết quả của một lệnh cụ thể.
[CODE BLOCK]
GET /computers/:id/screenshot
One-shot: xếp hàng lệnh chụp ảnh màn hình và đợi tối đa 30 giây để nhận kết quả.
[CODE BLOCK]
POST /computers/:id/disable
Vô hiệu hóa một máy tính (thu hồi token, vẫn giữ bản ghi cho mục đích kiểm toán).
[CODE BLOCK]
DELETE /computers/:id
Xóa vĩnh viễn một máy tính.
[CODE BLOCK]
Endpoint phía agent (Computer Token)
Các endpoint này được sử dụng bởi chạy trên máy đích.
Chúng sử dụng Computer Token (trả về bởi ), không phải
Mind Key.
POST /computers/register
Đổi mã cài đặt lấy Computer Token.
[CODE BLOCK]
Phản hồi:
> [!CRITICAL]
> Hãy lưu — nó chỉ hiển thị một lần và là bắt buộc cho tất
> cả các endpoint phía agent.
GET /computers/me/poll
Long-poll các lệnh mới. Agent gọi endpoint này trong một vòng lặp.
[CODE BLOCK]
Trả về ngay lập tức nếu có lệnh đang chờ, hoặc sau giây nếu không.
POST /computers/me/commands/:cid/result
Gửi kết quả thực thi của một lệnh.
[CODE BLOCK]
Các loại lệnh
| Loại | Payload | Mô tả |
|------|---------|-------------|
| | | Chụp màn hình dạng PNG (base64) |
| | | Nhấp tại tọa độ |
| | | Di chuyển chuột đến tọa độ |
| | | Nhập văn bản tại vị trí con trỏ |
| | | Nhấn tổ hợp phím |
| | | Cuộn wheel |
| | | Kéo và thả |
Mẫu phổ biến: Tự động hóa GUI điều khiển bởi LLM
[CODE BLOCK]
Bước tiếp theo
- Browser Proxy — dịch vụ riêng cho tự động hóa trình duyệt
- Hướng dẫn Self-Hosted Agents
────────────────────────────────────────────────────────────
# Cron & Scheduler
SUMMARY: Lên lịch các cuộc gọi API định kỳ — cron job kích hoạt theo lịch, hoàn hảo cho đồng bộ và nhắc nhở định kỳ.
KEY CONTEXT:
Auth: Mind Key
Create: POST /cron { schedule, endpoint, method?, body?, headers?, enabled? }
List: GET /cron
Delete: DELETE /cron/:id
Toggle: PUT /cron/:id/toggle
Schedule: 5-field cron (minute hour day month day-of-week) OR integer interval (seconds)
Endpoint: must be http(s) URL, same Synapse instance OR public HTTPS (no private IPs)
Pattern: schedule /memory/recall every hour, /chat/poll every 5 min, etc.
Cron & Scheduler
Cron API cho phép bạn lên lịch các cuộc gọi HTTP định kỳ đến các endpoint của
Synapse (hoặc các endpoint HTTPS bên ngoài). Hoàn hảo cho đồng bộ định kỳ,
nhắc nhở và các tác vụ bảo trì.
Các endpoint
POST /cron
Tạo một tác vụ đã lên lịch.
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
GET /cron
Liệt kê tất cả tác vụ đã lên lịch.
[CODE BLOCK]
DELETE /cron/:id
Xóa một tác vụ đã lên lịch.
[CODE BLOCK]
PUT /cron/:id/toggle
Bật hoặc tắt một tác vụ mà không xóa nó.
[CODE BLOCK]
Cú pháp lịch
Cron chuẩn (5 trường)
[CODE BLOCK]
Ví dụ:
| Lịch | Ý nghĩa |
|----------|---------|
| | Mỗi giờ |
| | Mỗi 15 phút |
| | Ngày trong tuần lúc 9 giờ sáng |
| | Mỗi Chủ nhật lúc nửa đêm |
| | Ngày đầu tiên mỗi tháng lúc nửa đêm |
Khoảng cách nguyên (giây)
Đối với các khoảng cách đơn giản, truyền một số nguyên:
[CODE BLOCK]
Giới hạn endpoint
> [!WARNING]
> Các endpoint phải là URL hoặc trỏ đến:
> - Cùng thể hiện Synapse (ví dụ )
> - URL HTTPS công khai (không IP riêng, không localhost, không IP metadata)
Điều này ngăn chặn các cuộc tấn công SSRF khi một mind bị xâm phạm có thể lên
lịch các yêu cầu đến dịch vụ nội bộ.
Các mẫu phổ biến
Thu hồi bộ nhớ hàng giờ (cho LLM agent)
[CODE BLOCK]
Sao lưu hàng ngày
[CODE BLOCK]
Poll chat định kỳ (mỗi 5 phút)
[CODE BLOCK]
Kích hoạt báo cáo hàng tuần
[CODE BLOCK]
Bước tiếp theo
- Variables API
- Webhooks API
────────────────────────────────────────────────────────────
# Lỗi & Xử lý lỗi
SUMMARY: Mã trạng thái HTTP, định dạng phản hồi lỗi, và cách khôi phục từ các lỗi phổ biến.
KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.
Lỗi & Xử lý lỗi
Synapse sử dụng các mã trạng thái HTTP chuẩn với định dạng phản hồi lỗi nhất
quán. Trang này giải thích cách diễn giải và khôi phục từ lỗi.
Định dạng phản hồi lỗi
Tất cả lỗi trả về JSON với cấu trúc sau:
[CODE BLOCK]
| Trường | Mô tả |
|-------|-------------|
| | Mã trạng thái HTTP |
| | Tên trạng thái HTTP |
| | Mô tả lỗi dành cho người đọc |
| | URL tới tài liệu liên quan (khi áp dụng) |
Mã trạng thái HTTP
200 OK
Thành công. Yêu cầu được xử lý đúng.
201 Created
Thành công. Một tài nguyên mới được tạo (ví dụ ).
204 No Content
Thành công. Không có body trả về (ví dụ ).
400 Bad Request
Yêu cầu sai định dạng. Nguyên nhân phổ biến:
- Thiếu trường JSON bắt buộc
- Cú pháp JSON không hợp lệ
- Giá trị enum không hợp lệ (ví dụ sai danh mục)
[CODE BLOCK]
Khắc phục: Kiểm tra body yêu cầu so với tài liệu API. Đảm bảo tất cả
trường bắt buộc đều có và có giá trị hợp lệ.
401 Unauthorized
Xác thực thất bại. Nguyên nhân phổ biến:
- Thiếu header
- Mind Key hoặc JWT không hợp lệ
- Sử dụng Mind Key nơi yêu cầu JWT (hoặc ngược lại)
[CODE BLOCK]
Khắc phục: Xác minh token của bạn. Xem Xác thực.
403 Forbidden
Bạn đã được xác thực nhưng không được phép thực hiện hành động này. Nguyên nhân phổ biến:
- Cố xóa mind của người dùng khác
- Cố xác minh bộ nhớ bằng Mind Key (yêu cầu JWT)
- Mind bị vô hiệu hóa
Khắc phục: Kiểm tra xem bạn có đang sử dụng đúng loại token cho endpoint này không.
404 Not Found
Đường dẫn hoặc tài nguyên yêu cầu không tồn tại.
> [!CRITICAL]
> KHÔNG đoán đường dẫn endpoint. Chỉ những đường dẫn liệt kê trong
> mới tồn tại. Nếu bạn nhận 404, bạn đã dùng sai đường dẫn.
[CODE BLOCK]
Khắc phục: Gọi để xem danh sách endpoint hợp lệ. So sánh
URL của bạn với danh sách từng ký tự.
409 Conflict
Yêu cầu xung đột với trạng thái hiện tại. Nguyên nhân phổ biến:
- Cố đăng ký với email đã tồn tại
- Trùng URL webhook
Khắc phục: Sử dụng giá trị khác, hoặc dùng để cập nhật tài nguyên hiện có.
429 Too Many Requests
Bạn đã đạt giới hạn tốc độ. Chỉ áp dụng cho xác thực qua tham số (60/phút).
[CODE BLOCK]
Header phản hồi:
[CODE BLOCK]
Khắc phục: Chuyển sang header (không giới hạn tốc
độ), hoặc đợi giây.
500 Internal Server Error
Lỗi server. Điều này không nên xảy ra — nếu xảy ra, đó là bug.
Khắc phục:
1. Thử lại với exponential backoff (1s, 2s, 4s, 8s)
2. Kiểm tra để xem server có hoạt động không
3. Nếu liên tục, báo cáo lỗi
503 Service Unavailable
Server tạm thời ngừng (ví dụ trong quá trình triển khai, di chuyển database).
Khắc phục: Đợi và thử lại. Kiểm tra .
Mẫu khôi phục
Thử lại với exponential backoff
[CODE BLOCK]
Xử lý lỗi xác thực
[CODE BLOCK]
Kịch bản lỗi phổ biến
"Mind Key fehlt oder ungültig"
- Bạn quên header
- Bạn dùng nhưng key sai
- Bạn đang dùng JWT nơi yêu cầu Mind Key
"Route not found"
- Bạn đã đoán một đường dẫn không tồn tại
- Bạn dùng sai verb (ví dụ thay vì )
- Kiểm tra để xem đường dẫn hợp lệ
"Rate limit exceeded"
- Bạn đang dùng và vượt quá 60 yêu cầu/phút
- Chuyển sang header
Bước tiếp theo
- Xác thực
- Tổng quan API
- Giới hạn tốc độ
────────────────────────────────────────────────────────────
# 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
────────────────────────────────────────────────────────────
# Tổng quan API & Base URL
SUMMARY: Tất cả endpoint API Synapse, base URL, mẫu xác thực và định dạng phản hồi trong một glance.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.
Tổng quan API & Base URL
Synapse API là HTTP API RESTful. Tất cả endpoint trả về JSON (trừ khi có ghi
chú). Trang này bao gồm những điều thiết yếu bạn cần biết trước khi đi sâu vào
các endpoint cụ thể.
Base URL
[CODE BLOCK]
Tất cả đường dẫn trong tài liệu này đều tương đối với base URL này. Đối với
các thể hiện self-hosted, thay bằng URL của bạn.
Xác thực
Hai phương thức, cả hai đều gửi qua header :
[CODE BLOCK]
Hoặc qua tham số query (giới hạn 60/phút):
[CODE BLOCK]
Xem Xác thực để biết chi tiết.
Nhóm endpoint
| Nhóm | Xác thực | Mô tả |
|-------|------|-------------|
| Public | Không | Trang chủ, health, OpenAPI, docs |
| Memory | Mind Key | CRUD, tìm kiếm, đồng bộ, embeddings |
| Chat | Mind Key / JWT | Nhắn tin bất đồng bộ giữa con người và agent |
| Tasks | Mind Key | Quản lý tác vụ |
| Scripts | Mind Key / JWT | Lưu trữ script cố định |
| Scheduler | Mind Key | Cron job + biến |
| Webhooks | Mind Key | HTTP callback khi có sự kiện |
| Computers | Mind Key / JWT | Điều khiển máy tính từ xa |
| User/Minds | JWT | Tài khoản + quản lý mind |
| Sharing | JWT | Chia sẻ mind giữa người dùng |
| Push | JWT | Đăng ký Web Push |
| Tools | Không | Thời gian, calc, random (tiện ích công khai) |
Định dạng phản hồi
- JSON (mặc định):
- Văn bản thuần: trả về văn bản tối ưu cho LLM
- HTML: , , , ,
Envelope phản hồi chuẩn
Phản hồi thành công trả về dữ liệu trực tiếp:
[CODE BLOCK]
Phản hồi lỗi sử dụng định dạng này:
[CODE BLOCK]
> [!NOTE]
> Trường liên kết tới tài liệu liên quan cho các lỗi phổ biến.
Mã trạng thái HTTP
| Mã | Ý nghĩa |
|------|---------|
| 200 | Thành công (GET, PUT) |
| 201 | Đã tạo (POST) |
| 204 | Không có nội dung (DELETE) |
| 400 | Yêu cầu sai (lỗi validation) |
| 401 | Không được ủy quyền (thiếu/sai token) |
| 403 | Bị cấm (sai loại token) |
| 404 | Không tìm thấy (đường dẫn không tồn tại) |
| 409 | Xung đột (trùng lặp) |
| 429 | Quá nhiều yêu cầu (giới hạn tốc độ) |
| 500 | Lỗi server |
Endpoint khám phá
| Endpoint | Mục đích |
|----------|---------|
| | Trang chủ (tối ưu cho LLM) |
| | Danh sách đọc được bằng máy của tất cả endpoint |
| | Danh sách endpoint dạng văn bản thuần |
| | Đặc tả OpenAPI 3.0 |
| | Tài liệu API đầy đủ (HTML) |
| | Tài liệu API dạng JSON |
| | Hệ thống tài liệu (HTML) |
| | Mục lục tài liệu (JSON) |
| | Tất cả tài liệu trong một khối văn bản |
| | Playground API tương tác |
Giới hạn tốc độ
| Phương thức xác thực | Giới hạn |
|-------------|-------|
| Mind Key (header) | Không |
| Mind Key (?key=) | 60/phút mỗi IP |
| JWT (header) | Không |
| Endpoint công khai | Không |
Phản hồi bị giới hạn tốc độ bao gồm:
[CODE BLOCK]
Phân trang
Endpoint dạng danh sách hỗ trợ và :
[CODE BLOCK]
Giới hạn mặc định: 100. Giới hạn tối đa: 500.
CORS
Tất cả endpoint hỗ trợ CORS cho client dựa trên trình duyệt:
[CODE BLOCK]
SDK & Client
- Node.js SDK: (repo)
- MCP Server: (repo)
- HTTP client: bất kỳ thư viện HTTP nào (curl, fetch, axios, v.v.)
Bước tiếp theo
- Memory API — các endpoint quan trọng nhất
- Chat API — giao tiếp bất đồng bộ giữa con người và agent
- Lỗi & Xử lý lỗi
────────────────────────────────────────────────────────────
# Giới hạn tốc độ & Hạn ngạch
SUMMARY: Chính sách giới hạn tốc độ cho Synapse API — Bearer header (không giới hạn), ?key= (60/phút), endpoint công khai.
KEY CONTEXT:
Mind Key (Authorization: Bearer header) → NO rate limit
Mind Key (?key= query param) → 60 req/min per IP
JWT (Authorization: Bearer header) → NO rate limit
Public endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
Recommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.
Giới hạn tốc độ & Hạn ngạch
Synapse có chính sách giới hạn tốc độ đơn giản, dự đoán được, được thiết kế để
ngăn lạm dụng mà không cản trở sử dụng hợp pháp.
Chính sách giới hạn tốc độ
| Phương thức xác thực | Giới hạn | Phạm vi |
|-------------|-------|-------|
| Mind Key () | Không | Mỗi mind |
| Mind Key () | 60 yêu cầu/phút | Mỗi IP |
| JWT () | Không | Mỗi người dùng |
| Endpoint công khai | Không | Toàn cầu |
> [!TIP]
> Luôn sử dụng header khi có thể. Nó không có
> giới hạn tốc độ. Chỉ dùng cho các công cụ không thể đặt header tùy chỉnh.
Header giới hạn tốc độ
Khi bạn dùng xác thực , phản hồi bao gồm header giới hạn tốc độ:
[CODE BLOCK]
Khi bạn vượt giới hạn:
[CODE BLOCK]
Khi bạn gặp giới hạn tốc độ
Nếu bạn nhận 429:
1. Chuyển sang Authorization header (khuyến nghị):
[CODE BLOCK]
2. Hoặc đợi giây và thử lại.
Tại sao giới hạn ?key= tồn tại
Tham số query tiện lợi cho các công cụ chỉ dùng URL (trình duyệt, lệnh
), nhưng có ý nghĩa bảo mật và hiệu suất:
- Bảo mật: Tham số query được ghi trong nhật ký truy cập server, lịch sử
trình duyệt, và header Referer. Giới hạn sử dụng làm giảm rủi ro lộ lọt.
- Hiệu suất: Xác thực qua tham số query yêu cầu bộ giới hạn tốc độ dựa trên
IP (tra cứu Redis mỗi yêu cầu), điều này làm tăng độ trễ. Xác thực header
bỏ qua bước này.
- Ngăn lạm dụng: Một URL bị lộ có thể được chia sẻ và truy cập dồn
dập. Giới hạn IP giới hạn thiệt hại.
Mẫu khuyến nghị
LLM agent
[CODE BLOCK]
Công cụ dựa trên trình duyệt
Nếu công cụ của bạn chỉ có thể mở URL:
[CODE BLOCK]
MCP server
MCP server luôn sử dụng xác thực header qua biến môi trường
— không áp dụng giới hạn tốc độ.
Nhập hàng loạt
Đối với thao tác hàng loạt (ví dụ nhập 1000 bộ nhớ), luôn sử dụng xác thực
header. Nhập hàng loạt qua sẽ gặp giới hạn tốc độ trong vòng 1 phút.
Hạn ngạch (cấp Mind)
Hiện tại không có hạn ngạch mỗi mind về kích thước lưu trữ hoặc số lượng bộ nhớ.
Tất cả giới hạn đều ở cấp xác thực/IP, không phải cấp dữ liệu. Điều này có thể
thay đổi trong tương lai để đảm bảo công bằng multi-tenant.
Giám sát sử dụng
[CODE BLOCK]
Bước tiếp theo
- Xác thực
- Lỗi & Xử lý lỗi
────────────────────────────────────────────────────────────
# Scripts API
SUMMARY: Lưu trữ script cố định — lưu shell, Python, hoặc Node script tái sử dụng và lấy qua curl | bash.
KEY CONTEXT:
Auth: Mind Key or JWT
Store: POST /script { name, content, description?, language? }
Fetch as text: GET /script/:name (returns text/plain, curl | bash ready)
Info: GET /script/:name/info (metadata without content)
List: GET /scripts (JSON array)
Delete: DELETE /script/:name
Use case: store deployment scripts, config generators, troubleshooting snippets
Scripts API
Scripts API cung cấp lưu trữ cố định cho script tái sử dụng. Script được đặt tên
và đánh phiên bản trong một mind, có thể lấy dưới dạng văn bản thuần — hoàn hảo
cho mẫu .
Các endpoint
POST /script
Lưu hoặc cập nhật một script.
[CODE BLOCK]
GET /script/:name
Lấy nội dung script dưới dạng . Hoàn hảo để pipe vào bash.
[CODE BLOCK]
GET /script/:name/info
Lấy metadata script mà không có nội dung.
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
GET /scripts
Liệt kê tất cả script trong mind hiện tại.
[CODE BLOCK]
DELETE /script/:name
Xóa một script.
[CODE BLOCK]
Trường hợp sử dụng phổ biến
Script triển khai
Lưu quy trình triển khai chuẩn để LLM có thể chạy mà không cần suy luận lại các
bước mỗi lần:
[CODE BLOCK]
Đoạn mã khắc phục sự cố
Lưu các lệnh chẩn đoán cho các vấn đề phổ biến:
[CODE BLOCK]
Trình tạo cấu hình
Lưu các script tạo cấu hình:
[CODE BLOCK]
Bước tiếp theo
- Variables API
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Tasks API
SUMMARY: Quản lý tác vụ cho LLM agent — tạo, liệt kê, cập nhật, hoàn thành, xóa tác vụ với mức ưu tiên.
KEY CONTEXT:
Auth: Mind Key
List: GET /mind/tasks?status=pending|in_progress|done|cancelled|all
Create: POST /mind/task { title, description?, priority?, due_at? }
Update: PUT /mind/task/:id { title?, description?, priority?, status?, due_at? }
Complete: GET /mind/task/:id/complete
Delete: GET /mind/task/:id/delete
Priorities: low, normal, high, critical
Statuses: pending, in_progress, done, cancelled
Pattern: create tasks for multi-step work, update status as you progress
Tasks API
Tasks API cung cấp cho LLM agent cách có cấu trúc để theo dõi công việc nhiều
bước. Tác vụ được phạm vi hóa trong mind hiện tại và tồn tại qua các phiên, do
đó agent có thể tiếp tục công việc từ nơi đã dừng.
Các endpoint
GET /mind/tasks
Liệt kê tất cả tác vụ cho mind hiện tại.
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
POST /mind/task
Tạo một tác vụ mới.
[CODE BLOCK]
GET /mind/task (query params)
Tạo tác vụ qua GET (cho công cụ chỉ dùng URL).
[CODE BLOCK]
PUT /mind/task/:id
Cập nhật một tác vụ hiện có.
[CODE BLOCK]
GET /mind/task/:id/complete
Đánh dấu một tác vụ là đã xong.
[CODE BLOCK]
GET /mind/task/:id/delete
Xóa vĩnh viễn một tác vụ.
[CODE BLOCK]
Mức ưu tiên
- — không khẩn cấp
- — mặc định
- — quan trọng
- — phải làm ngay lập tức
Trạng thái
- — đã tạo, chưa bắt đầu
- — đang được thực hiện
- — đã hoàn thành
- — đã bỏ
Mẫu: Quy trình điều khiển bởi tác vụ
[CODE BLOCK]
Bước tiếp theo
- Quy trình điều khiển bởi tác vụ
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Công cụ tiện ích (thời gian, calc, random)
SUMMARY: Endpoint tiện ích công khai — thời gian server, máy tính an toàn, trình tạo giá trị ngẫu nhiên. Không yêu cầu xác thực.
KEY CONTEXT:
No auth required for any /tools/* endpoint.
GET /tools/time → { time, timezone, offset }
GET /tools/calc?expr=(10+5)*3 → { result, expr } (safe, no eval, arithmetic only)
GET /tools/random?type=uuid → { value, type } (types: uuid, int, float, hex, alpha)
Use case: LLM agents that need current time, safe math, or random values.
Công cụ tiện ích
Các endpoint là tiện ích công khai — không yêu cầu xác thực. Chúng hữu
ích cho LLM agent cần thời gian phía server, toán học an toàn hoặc giá trị ngẫu
nhiên.
GET /tools/time
Lấy thời gian server hiện tại, múi giờ và độ lệch UTC.
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
Trường hợp sử dụng: LLM agent cần biết "bây giờ là mấy giờ" để lên lịch, timestamp
hoặc tính ngày tương đối.
GET /tools/calc
Máy tính an toàn — chỉ số học, không có . Hỗ trợ , , , ,
, , và số.
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
> [!TIP]
> Sử dụng endpoint này thay vì cố gắng tính toán trong đầu hoặc qua phân tích
> chuỗi. Nó an toàn (không thể tiêm code) và chính xác.
Toán tử được hỗ trợ
- cộng
- trừ
- nhân
- chia
- modulo
- dấu ngoặc
- Số (số nguyên và số thập phân)
Ví dụ
[CODE BLOCK]
GET /tools/random
Tạo giá trị ngẫu nhiên.
[CODE BLOCK]
Tham số loại
| Loại | Tham số | Đầu ra |
|------|-----------|--------|
| | không có | Chuỗi UUID v4 |
| | , (mặc định 0-100) | Số nguyên |
| | , (mặc định 0-100) | Số thực |
| | , (phạm vi độ dài, mặc định 8-16) | Chuỗi hex |
| | , (phạm vi độ dài, mặc định 8-16) | Chuỗi chữ cái |
Trường hợp sử dụng cho LLM agent
Tạo ID duy nhất
[CODE BLOCK]
Tính phần trăm
[CODE BLOCK]
Lấy timestamp hiện tại
[CODE BLOCK]
Tạo dữ liệu kiểm thử
[CODE BLOCK]
Bước tiếp theo
- Tổng quan API — tất cả nhóm endpoint
- Lỗi & Xử lý lỗi
────────────────────────────────────────────────────────────
# User & Minds API
SUMMARY: Quản lý tài khoản — đăng ký, đăng nhập, tạo mind, liệt kê mind, xóa mind. Được bảo vệ bằng JWT.
KEY CONTEXT:
Auth: JWT (from /register or /login)
Register: POST /register { email, password, display_name? } → returns JWT
Login: POST /login { email, password } → returns JWT
Create mind: POST /minds { name, description? } → returns mind_key (shown once!)
List minds: GET /minds
Delete mind: DELETE /minds/:id (irreversible — deletes all memories!)
JWT expires after 7 days. Mind Key never expires.
Mind Key is shown only once at creation — save it permanently.
User & Minds API
User & Minds API xử lý quản lý tài khoản. Các endpoint này sử dụng xác thực JWT
(không phải Mind Key) vì chúng hoạt động ở cấp tài khoản, không phải cấp mind.
Endpoint xác thực
POST /register
Tạo tài khoản người dùng mới.
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
POST /login
Đăng nhập vào tài khoản hiện có.
[CODE BLOCK]
Phản hồi: giống như .
Endpoint Minds
POST /minds
Tạo một mind mới. Trả về Mind Key — lưu ngay lập tức, nó chỉ hiển thị một lần.
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
> [!CRITICAL]
> chỉ hiển thị một lần. Nếu bạn mất nó, bạn không thể lấy lại —
> bạn phải xóa mind và tạo mind mới (điều này mất tất cả bộ nhớ đã lưu).
GET /minds
Liệt kê tất cả mind của người dùng hiện tại.
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
DELETE /minds/:id
Xóa vĩnh viễn một mind.
[CODE BLOCK]
> [!WARNING]
> Xóa mind là không thể đảo ngược. Tất cả bộ nhớ, tác vụ, lịch sử chat và
> script trong mind đó sẽ mất vĩnh viễn. Xuất trước qua
> nếu bạn cần sao lưu.
Mẫu Multi-Mind
Hầu hết người dùng được lợi từ việc có nhiều mind để giữ các ngữ cảnh tách biệt:
[CODE BLOCK]
Sử dụng các Mind Key khác nhau trong các phiên LLM khác nhau để giữ ngữ cảnh tách biệt.
Bảo mật tài khoản
Yêu cầu mật khẩu
- Tối thiểu 6 ký tự
- Không có giới hạn tối đa (sử dụng trình quản lý mật khẩu)
- Lưu dưới dạng bcrypt hash (không bao giờ plaintext)
Hết hạn JWT
JWT hết hạn sau 7 ngày. Khi hết hạn, chỉ cần gọi lại .
Bảo mật Mind Key
Mind Key không bao giờ hết hạn. Nếu Mind Key bị xâm phạm:
1. Tạo mind mới qua
2. Cập nhật cấu hình LLM với Mind Key mới
3. Xóa mind bị xâm phạm qua
Bước tiếp theo
- Xác thực — hướng dẫn xác thực đầy đủ
- Mind Key vs JWT — hướng dẫn quyết định
- Sharing API — chia sẻ mind với người dùng khác
────────────────────────────────────────────────────────────
# Variables API
SUMMARY: Cửa hàng key-value nhanh cho trạng thái LLM — bộ đếm, cờ, timestamp lần cuối xem, tiến độ từng phần.
KEY CONTEXT:
Auth: Mind Key
Set: POST /var { key, value }
Get: GET /var/:key
List: GET /var
Delete: DELETE /var/:key
Use case: store last-seen timestamps, counters, flags, partial workflow state
Faster than memory (PostgreSQL direct, no FTS5 indexing)
Not for: structured facts (use /memory), long content (use /script)
Variables API
Variables API là một cửa hàng key-value nhanh cho trạng thái tạm thời. Khác với
bộ nhớ (được đánh chỉ mục, có thể tìm kiếm và có cấu trúc), biến được tối ưu
cho truy cập đọc/ghi nhanh — hoàn hảo cho bộ đếm, cờ và trạng thái phiên.
Các endpoint
POST /var
Đặt hoặc cập nhật một biến.
[CODE BLOCK]
GET /var/:key
Lấy một biến đơn lẻ.
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
GET /var
Liệt kê tất cả biến.
[CODE BLOCK]
DELETE /var/:key
Xóa một biến.
[CODE BLOCK]
Khi nào dùng Biến so với Bộ nhớ
| Trường hợp | Sử dụng |
|----------|-----|
| Tên người dùng, sở thích | Bộ nhớ (có thể tìm kiếm, có cấu trúc) |
| Timestamp phiên cuối | Biến (trạng thái tạm thời) |
| Bộ đếm (ví dụ tin nhắn đã gửi) | Biến (cập nhật thường xuyên) |
| Trạng thái quy trình ("đã xong bước 3/5") | Biến (tạm thời) |
| Ghi chú dự án dạng dài | Bộ nhớ (đánh chỉ mục toàn văn) |
| Script tái sử dụng | Cửa hàng script (đặt tên, đánh phiên bản) |
Mẫu phổ biến
Theo dõi phiên cuối
[CODE BLOCK]
Mẫu bộ đếm
[CODE BLOCK]
Cờ tính năng
[CODE BLOCK]
Bước tiếp theo
- Memory API — cho dữ liệu có cấu trúc, có thể tìm kiếm
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Webhooks API
SUMMARY: Đăng ký HTTP callback cho sự kiện bộ nhớ, chat và tác vụ — nhận thông báo khi dữ liệu thay đổi.
KEY CONTEXT:
Auth: Mind Key
Register: POST /webhooks { url, events, secret? }
List: GET /webhooks
Get: GET /webhooks/:id
Update: PUT /webhooks/:id { url?, events?, secret?, enabled? }
Delete: DELETE /webhooks/:id
Events: memory.*, memory.store, memory.update, memory.delete, chat.*, chat.message_received, task.*, task.created, task.completed
Secret: HMAC-SHA256 signed payload, sent in X-Synapse-Signature header
Pattern: register webhook → receive POST → process event → call Synapse API
Webhooks API
Webhook cho phép bạn nhận HTTP callback khi sự kiện xảy ra trong Synapse. Hoàn
hảo để kích hoạt tự động hóa bên ngoài, gửi thông báo hoặc đồng bộ với hệ thống
khác.
Các endpoint
POST /webhooks
Đăng ký webhook mới.
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
GET /webhooks
Liệt kê tất cả webhook cho mind hiện tại.
[CODE BLOCK]
GET /webhooks/:id
Lấy một webhook đơn lẻ.
[CODE BLOCK]
PUT /webhooks/:id
Cập nhật webhook (URL, sự kiện, secret hoặc cờ enabled).
[CODE BLOCK]
DELETE /webhooks/:id
Xóa một webhook.
[CODE BLOCK]
Loại sự kiện
| Mẫu | Kích hoạt khi |
|---------|------------|
| | Bất kỳ sự kiện bộ nhớ nào |
| | Bộ nhớ mới được lưu |
| | Bộ nhớ được cập nhật |
| | Bộ nhớ bị xóa |
| | Bất kỳ sự kiện chat nào |
| | Tin nhắn mới từ con người |
| | Bất kỳ sự kiện tác vụ nào |
| | Tác vụ mới được tạo |
| | Tác vụ được đánh dấu đã xong |
| | Tất cả sự kiện |
Payload Webhook
Khi sự kiện kích hoạt, Synapse POST đến URL của bạn:
[CODE BLOCK]
Xác minh chữ ký
Nếu bạn đặt , Synapse ký mỗi payload bằng HMAC-SHA256:
[CODE BLOCK]
Xác minh trong trình xử lý của bạn:
[CODE BLOCK]
Mẫu: Đồng bộ thời gian thực
[CODE BLOCK]
Bước tiếp theo
- Cron & Scheduler
- Hướng dẫn tự động hóa Webhook
## DANH MỤC: TÍCH HỢP MCP
Tích hợp với Claude, Cursor và các MCP client khác.
────────────────────────────────────────────────────────────
# MCP trong Claude Code
SUMMARY: Sử dụng công cụ Synapse từ agent terminal Claude Code — bộ nhớ cố định cho phiên lập trình.
KEY CONTEXT:
Claude Code config: ~/.claude/config.json (or via `claude mcp add` command)
Command: npx -y synapse-mcp-api@latest
Env: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional)
Alternative: `claude mcp add synapse -- npx -y synapse-mcp-api@latest`
Then: set SYNAPSE_MIND_KEY env var in your shell
Test: in claude code, type "recall all my memories"
MCP trong Claude Code
Claude Code là agent lập trình dựa trên terminal của Anthropic. Với Synapse MCP,
Claude Code có bộ nhớ cố định qua các phiên lập trình — nó ghi nhớ ngữ cảnh dự án
của bạn, quyết định quá khứ và mẫu codebase.
Thiết lập
Phương thức 1: Lệnh CLI (khuyến nghị)
[CODE BLOCK]
Phương thức 2: Chỉnh sửa tệp cấu hình
Chỉnh sửa :
[CODE BLOCK]
Xác minh nó hoạt động
Khởi động Claude Code:
[CODE BLOCK]
Trong prompt Claude Code, gõ:
[CODE BLOCK]
Claude sẽ gọi và phản hồi với bộ nhớ đã lưu của bạn.
Mẫu phổ biến
Tính cố định ngữ cảnh dự án
Ở đầu phiên lập trình:
[CODE BLOCK]
Claude gọi , thấy danh sách dự án của bạn và tiếp tục công việc
nơi bạn đã dừng.
Quyết định codebase
Khi bạn đưa ra quyết định kiến trúc:
[CODE BLOCK]
Claude gọi với danh mục , ưu tiên .
Tránh lỗi quá khứ
[CODE BLOCK]
Claude tìm bộ nhớ với danh mục và nhắc bạn về lỗi quá khứ.
Theo dõi tác vụ
[CODE BLOCK]
Claude gọi , và tác vụ tồn tại qua các phiên.
Tool Profile
Cho phiên lập trình nơi bạn không cần tất cả 119 công cụ:
[CODE BLOCK]
Khắc phục sự cố
MCP server không khởi động
[CODE BLOCK]
Mind Key không được nhận dạng
[CODE BLOCK]
Claude Code không thấy công cụ
- Khởi động lại Claude Code sau thay đổi cấu hình
- Kiểm tra để xác minh Synapse đã đăng ký
- Xem Khắc phục sự cố MCP
Bước tiếp theo
- Thiết lập Claude Desktop
- Thiết lập Cursor
- Hướng dẫn LLM Agent cố định
────────────────────────────────────────────────────────────
# MCP trong Claude Desktop
SUMMARY: Kết nối Synapse với Claude Desktop trong 2 phút. Claude nhận 79 công cụ Synapse native.
KEY CONTEXT:
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\Claude\claude_desktop_config.json (Windows)
MCP server command: npx -y synapse-mcp-api@latest
Env vars: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional, default https://synapse.schaefer.zone)
After config: restart Claude Desktop, check for 🔌 icon with "79 tools"
Test: type "memory_recall aufrufen" in a new chat
Troubleshooting: Node.js ≥ 18, check Mind Key, see /docs/mcp/troubleshooting
MCP trong Claude Desktop
Claude Desktop là ứng dụng desktop của Anthropic cho macOS và Windows. Với
Synapse MCP server được cấu hình, Claude có quyền truy cập native đến tất cả 79
công cụ Synapse — nó có thể lưu bộ nhớ, thu hồi chúng, quản lý tác vụ, chat với
bạn và hơn thế nữa.
Điều kiện tiên quyết
- Ứng dụng Claude Desktop (macOS hoặc Windows)
- Node.js 18+ đã cài đặt ()
- Synapse Mind Key của bạn
Bước 1: Mở tệp cấu hình
- macOS:
- Windows:
Nếu tệp không tồn tại, tạo nó.
Bước 2: Thêm Synapse MCP Server
[CODE BLOCK]
> [!TIP]
> Nếu bạn đã có các MCP server khác được cấu hình, chỉ cần thêm block
> vào trong object hiện có.
Bước 3: Khởi động lại Claude Desktop
1. Thoát hoàn toàn Claude Desktop (Cmd+Q trên macOS, không chỉ đóng cửa sổ)
2. Mở lại Claude Desktop
3. Bắt đầu chat mới
4. Tìm biểu tượng phích cắm 🔌 ở dưới cùng bên trái — nó nên hiển thị "79 tools"
Bước 4: Kiểm tra nó
Trong chat mới, gõ:
[CODE BLOCK]
Claude sẽ gọi công cụ và phản hồi với tóm tắt bộ nhớ đã lưu của
bạn (hoặc "No memories yet" nếu mind của bạn trống).
Công cụ khả dụng (Lựa chọn)
| Công cụ | Mô tả |
|------|-------------|
| | Thu hồi tất cả bộ nhớ |
| | Lưu bộ nhớ mới |
| | Tìm kiếm bộ nhớ |
| | Liệt kê tác vụ |
| | Tạo tác vụ |
| | Kiểm tra tin nhắn mới |
| | Trả lời tin nhắn |
| | Mở tab trình duyệt |
| | Liệt kê máy tính đã đăng ký |
Danh sách đầy đủ: MCP là gì?
Khắc phục sự cố
Không có công cụ xuất hiện trong Claude Desktop
1. Xác minh phiên bản Node.js: (phải ≥ 18)
2. Kiểm tra tệp cấu hình là JSON hợp lệ (không có dấu phẩy cuối)
3. Khởi động lại Claude Desktop hoàn toàn (Cmd+Q, không chỉ đóng)
4. Kiểm tra nhật ký Claude Desktop: (macOS)
Lỗi "Mind Key invalid"
- Xác minh bắt đầu bằng
- Lấy key mới qua (yêu cầu JWT từ )
- Không có dấu ngoặc kép quanh key trong JSON
npx không tìm thấy
- Cài đặt Node.js 18+:
- Khởi động lại terminal sau khi cài đặt
- Trên macOS với Homebrew:
Công cụ hiển thị nhưng lệnh gọi thất bại
- Kiểm tra có thể truy cập:
- Xác minh Mind Key của bạn hoạt động:
- Xem Khắc phục sự cố MCP
Tool Profile (Tiết kiệm Token)
Nếu bạn đang sử dụng LLM nhỏ hơn hoặc muốn tiết kiệm token ngữ cảnh, đặt tool
profile:
[CODE BLOCK]
Profile: (8 công cụ), (25), (119, mặc định).
Bước tiếp theo
- Thiết lập Claude Code
- Thiết lập Cursor
- Khắc phục sự cố MCP
────────────────────────────────────────────────────────────
# MCP trong Continue.dev
SUMMARY: Kết nối Synapse với Continue.dev — trợ lý lập trình AI mã nguồn mở cho VS Code và JetBrains.
MCP trong Continue.dev
Continue.dev là trợ lý lập trình AI mã nguồn mở cho VS Code và JetBrains IDE.
Với Synapse MCP, Continue có bộ nhớ cố định qua các phiên.
Điều kiện tiên quyết
- VS Code hoặc JetBrains IDE
- Tiện ích mở rộng Continue.dev đã cài đặt
- Node.js 18+
- Synapse Mind Key của bạn
Thiết lập
Bước 1: Mở cấu hình Continue
Trong VS Code hoặc JetBrains:
1. Mở thanh bên tiện ích mở rộng Continue
2. Nhấp biểu tượng bánh răng → "Open config.json"
Hoặc chỉnh sửa trực tiếp.
Bước 2: Thêm Synapse MCP Server
[CODE BLOCK]
Bước 3: Tải lại Continue
Tải lại cửa sổ VS Code (Cmd+Shift+P → "Reload Window") hoặc khởi động lại IDE.
Xác minh nó hoạt động
Trong chat Continue:
[CODE BLOCK]
Continue sẽ gọi và phản hồi với bộ nhớ đã lưu của bạn.
Mẫu phổ biến
Ngữ cảnh dự án
[CODE BLOCK]
Continue gọi , thấy bộ nhớ dự án của bạn và tiếp tục công việc
nơi bạn đã dừng.
Mẫu review code
[CODE BLOCK]
Continue tìm mẫu review code đã lưu của bạn và áp dụng chúng.
Bộ nhớ lập trình cặp
[CODE BLOCK]
Continue lưu nó dưới dạng bộ nhớ .
Khắc phục sự cố
MCP server không kết nối
1. Kiểm tra là JSON hợp lệ
2. Xác minh Node.js:
3. Kiểm tra bảng điều khiển output của Continue (View → Output → Continue)
4. Khởi động lại IDE
Công cụ không xuất hiện
- Xác minh phiên bản Continue hỗ trợ MCP (≥ 0.9.x)
- Kiểm tra biến môi trường được đặt trong cấu hình
- Tìm lỗi MCP trong nhật ký Continue
Bước tiếp theo
- Thiết lập Claude Desktop
- Client MCP tùy chỉnh
────────────────────────────────────────────────────────────
# MCP trong Cursor
SUMMARY: Kết nối Synapse với Cursor IDE cho bộ nhớ dự án cố định qua các phiên lập trình.
MCP trong Cursor
Cursor là IDE dựa trên AI dựa trên VS Code. Với Synapse MCP, Cursor có bộ nhớ
cố định qua các phiên — nó ghi nhớ quyết định dự án, mẫu codebase và phiên gỡ
lỗi quá khứ của bạn.
Điều kiện tiên quyết
- Cursor IDE đã cài đặt ()
- Node.js 18+
- Synapse Mind Key của bạn
Thiết lập
Bước 1: Mở cài đặt Cursor
Trong Cursor:
1. Mở Settings (Cmd+, trên macOS, Ctrl+, trên Windows/Linux)
2. Tìm "MCP" hoặc điều hướng đến
Bước 2: Thêm Synapse MCP Server
Nhấp "Add MCP Server" và cấu hình:
| Trường | Giá trị |
|-------|-------|
| Name | |
| Type | |
| Command | |
| Env | |
Bước 3: Chỉnh sửa config.json trực tiếp (thay thế)
Cursor lưu cấu hình MCP trong :
[CODE BLOCK]
Bước 4: Khởi động lại Cursor
Khởi động lại hoàn toàn Cursor (Cmd+Q và mở lại trên macOS).
Xác minh nó hoạt động
Trong bảng điều khiển chat của Cursor (Cmd+L):
[CODE BLOCK]
Cursor sẽ gọi và phản hồi với bộ nhớ đã lưu của bạn.
Mẫu phổ biến
Onboarding dự án
Khi mở dự án mới:
[CODE BLOCK]
Cursor gọi và tiếp tục công việc nơi bạn đã dừng.
Quyết định kiến trúc
[CODE BLOCK]
Cursor lưu nó dưới dạng bộ nhớ với ưu tiên .
Lịch sử gỡ lỗi
[CODE BLOCK]
Cursor tìm bộ nhớ và nhắc bạn về sửa chữa quá khứ.
Mẫu code chéo phiên
[CODE BLOCK]
Cursor tìm bộ nhớ về triển khai xác thực bạn đã làm trước.
Khắc phục sự cố
MCP server không kết nối
1. Xác minh Node.js: (≥ 18)
2. Kiểm tra MCP server: (nên khởi động không lỗi)
3. Kiểm tra nhật ký MCP của Cursor (View → Output → MCP)
4. Khởi động lại Cursor hoàn toàn
Công cụ không xuất hiện
- Kiểm tra là JSON hợp lệ
- Xác minh biến môi trường được đặt
- Kiểm tra phiên bản Cursor hỗ trợ MCP (≥ 0.42)
Mind Key không hợp lệ
[CODE BLOCK]
Bước tiếp theo
- Thiết lập Claude Desktop
- Thiết lập Continue.dev
- Hướng dẫn LLM Agent cố định
────────────────────────────────────────────────────────────
# Xây dựng Client MCP tùy chỉnh
SUMMARY: Kết nối đến Synapse MCP server từ ứng dụng riêng của bạn sử dụng MCP SDK.
Xây dựng Client MCP tùy chỉnh
Nếu bạn đang xây dựng ứng dụng LLM riêng, bạn có thể kết nối đến Synapse MCP
server trực tiếp sử dụng MCP SDK chính thức. Điều này cho phép ứng dụng của bạn
truy cập tất cả 79 công cụ Synapse.
SDK
| Ngôn ngữ | Gói |
|----------|---------|
| TypeScript/JavaScript | |
| Python | |
Ví dụ TypeScript
Cài đặt
[CODE BLOCK]
Kết nối qua stdio
[CODE BLOCK]
Kết nối qua HTTP/SSE (từ xa)
[CODE BLOCK]
Ví dụ Python
Cài đặt
[CODE BLOCK]
Kết nối qua stdio
[CODE BLOCK]
Tool Profile
Khi kết nối, bạn có thể yêu cầu tool profile cụ thể qua header
(HTTP/SSE) hoặc biến môi trường (stdio):
[CODE BLOCK]
Xử lý lỗi
[CODE BLOCK]
Trường hợp sử dụng
- Trợ lý AI tùy chỉnh — xây dựng agent riêng của bạn với bộ nhớ cố định
- Tự động hóa quy trình — xâu chuỗi công cụ Synapse trong quy trình tùy chỉnh
- Pipeline dữ liệu — trích xuất bộ nhớ, biến đổi, tải nơi khác
- Bảng điều khiển giám sát — hiển thị thống kê bộ nhớ, lịch sử chat, tác vụ
Bước tiếp theo
- Đặc tả MCP
- Synapse MCP Repo
- Tổng quan API
────────────────────────────────────────────────────────────
# Khắc phục sự cố MCP
SUMMARY: Giải quyết vấn đề tích hợp MCP phổ biến — server không khởi động, công cụ không xuất hiện, lỗi xác thực.
KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/
Khắc phục sự cố MCP
Vấn đề và giải pháp phổ biến khi tích hợp Synapse MCP với LLM client của bạn.
Danh sách chẩn đoán nhanh
1. ✅ Node.js 18+ đã cài đặt? ()
2. ✅ Mind Key bắt đầu bằng ? (không phải JWT )
3. ✅ Synapse API có thể truy cập? ()
4. ✅ Mind Key hoạt động? ()
5. ✅ Tệp cấu hình là JSON hợp lệ? (không có dấu phẩy cuối, không có bình luận)
6. ✅ Client đã khởi động lại sau thay đổi cấu hình?
7. ✅ MCP server khởi động thủ công? ()
Vấn đề: Không có công cụ xuất hiện trong Client
Triệu chứng
- Claude Desktop / Cursor / Continue hiển thị 0 công cụ
- Không có biểu tượng 🔌 hoặc mục "synapse" trong danh sách MCP server
Giải pháp
1. Khởi động lại client hoàn toàn — Cmd+Q trên macOS (không chỉ đóng cửa sổ)
2. Kiểm tra vị trí tệp cấu hình:
- Claude Desktop macOS:
- Claude Desktop Windows:
- Cursor:
- Continue:
3. Xác thực JSON — dán cấu hình vào
4. Kiểm tra nhật ký client cho lỗi MCP:
- Claude Desktop: (macOS)
- Cursor: View → Output → MCP
5. Chạy MCP server thủ công để xem lỗi khởi động:
[CODE BLOCK]
Vấn đề: Lỗi "Mind Key invalid"
Triệu chứng
- Công cụ xuất hiện nhưng lệnh gọi thất bại với "401 Unauthorized"
- Lỗi: "Mind Key fehlt oder ungültig"
Giải pháp
1. Xác minh định dạng Mind Key — bắt đầu bằng , 40 ký tự
2. Kiểm tra trực tiếp:
[CODE BLOCK]
3. Kiểm tra biến môi trường được đặt — cho transport stdio, biến môi trường phải trong cấu hình MCP server, không phải shell của bạn
4. Lấy Mind Key mới:
[CODE BLOCK]
Vấn đề: npx Không tìm thấy
Triệu chứng
- Lỗi: "npx: command not found"
- MCP server thất bại khi khởi động
Giải pháp
1. Cài đặt Node.js 18+:
- macOS: hoặc tải từ
- Linux:
- Windows: tải từ
2. Khởi động lại terminal sau khi cài đặt
3. Xác minh:
Vấn đề: SYNAPSEURL Không thể truy cập
Triệu chứng
- MCP server khởi động nhưng lệnh gọi công cụ hết thời gian chờ
- Lỗi: "fetch failed" hoặc "ECONNREFUSED"
Giải pháp
1. Kiểm tra kết nối:
[CODE BLOCK]
2. Kiểm tra tường lửa công ty — có thể chặn HTTPS outbound
3. Thử URL thay thế:
- Production:
- MCP server:
4. Cho tự lưu trữ: đảm bảo thể hiện Synapse của bạn đang chạy và có thể truy cập
Vấn đề: MCP Server Sập
Triệu chứng
- MCP server thoát ngay sau khi khởi động
- Nhật ký client hiển thị "MCP server disconnected"
Giải pháp
1. Chạy thủ công để xem lỗi:
[CODE BLOCK]
2. Kiểm tra xung đột cổng — MCP server sử dụng cổng 13100 mặc định
3. Xóa bộ nhớ đệm npx:
[CODE BLOCK]
4. Cập nhật lên phiên bản mới nhất:
[CODE BLOCK]
Vấn đề: Lệnh gọi công cụ trả về 429
Triệu chứng
- Lỗi: "Rate limit exceeded"
Giải pháp
Điều này không nên xảy ra với MCP (sử dụng xác thực header, không giới hạn tốc
độ). Nếu xảy ra:
1. Kiểm tra xem bạn có đang dùng ở đâu không — chuyển sang xác thực header
2. Xác minh — đảm bảo nó trỏ đến thể hiện đúng
3. Liên hệ hỗ trợ nếu vấn đề tiếp tục
Vấn đề: Công cụ xuất hiện nhưng không hoạt động
Triệu chứng
- Công cụ được liệt kê trong client
- Gọi công cụ trả về lỗi hoặc không có kết quả
Giải pháp
1. Kiểm tra tên công cụ — phải chính xác (ví dụ , không phải )
2. Xác minh đối số — kiểm tra schema đầu vào của công cụ
3. Kiểm tra qua API trực tiếp:
[CODE BLOCK]
4. Kiểm tra sức khỏe Synapse:
[CODE BLOCK]
Nhận trợ giúp
Nếu không có giải pháp nào ở trên giải quyết vấn đề của bạn:
1. Kiểm tra issue hiện có:
2. Mở issue mới với:
- Phiên bản MCP server ()
- Tên và phiên bản client
- Hệ điều hành
- Trích đoạn nhật ký liên quan
- Các bước tái hiện
Bước tiếp theo
- Thiết lập Claude Desktop
- Thiết lập Claude Code
- Lỗi API
────────────────────────────────────────────────────────────
# MCP là gì?
SUMMARY: Model Context Protocol cho phép LLM gọi công cụ bên ngoài. Synapse lộ 79 công cụ qua MCP server chính thức.
KEY CONTEXT:
MCP = Model Context Protocol (Anthropic, 2024). Open standard for LLM-tool integration.
Synapse has official MCP server: synapse-mcp-api (npm package, npx -y synapse-mcp-api@latest)
79 tools exposed: 22 memory, 7 chat, 8 scheduler, 4 tasks, 5 scripts, 9 computers, 4 push, 5 user, 3 utility
3 transports: stdio (local), HTTP/SSE (remote), WebSocket (mobile)
Supported clients: Claude Desktop, Claude Code, Cursor, Continue, Cline, any MCP-compatible client
Tool Profiles (v1.4.0): minimal (8 tools), standard (25), full (119) — controlled via MCP_PROFILE env or Mcp-Tool-Profile header
MCP là gì?
Model Context Protocol (MCP) là tiêu chuẩn mở của Anthropic (2024) cho phép
LLM gọi công cụ bên ngoài theo cách có cấu trúc. Thay vì dán tài liệu API vào
prompt, bạn đăng ký công cụ với MCP server, và LLM gọi chúng khi cần — giống
function calling, nhưng được chuẩn hóa và không phụ thuộc client.
Synapse MCP Server
Synapse đi kèm với MCP server chính thức ( trên npm) lộ 79
công cụ bao phủ tất cả tính năng Synapse:
| Danh mục | Công cụ | Số lượng |
|----------|-------|-------|
| Memory | recall, list, store, search, semantic-search, update, delete, bulk-delete, stats, unverified, contradictions, audit, related, by-tag, diff, expiring, health, sync, embed-batch, verify, unverify, mind-export | 22 |
| Chat | poll, reply, status, history, unread, send, upload | 7 |
| Scheduler | cronlist, croncreate, crondelete, crontoggle, varlist, varget, varset, vardelete | 8 |
| Tasks | tasklist, taskget, taskcreate, taskupdate | 4 |
| Scripts | scriptlist, scriptget, scriptinfo, scriptstore, scriptdelete | 5 |
| Computers | computerlist, computerget, installcode, screenshot, commandqueue, commandstatus, commandslist, disable, delete | 9 |
| Push | vapidpublickey, subscribe, unsubscribe, test | 4 |
| User/Mind | register, login, mindslist, mindcreate, minddelete | 5 |
| Utility | time, calc, random | 3 |
| Visualization | graph, tags, compact | 3 |
| Sharing | share, list, revoke | 3 |
| Webhooks | register, list, get, update, delete | 5 |
| Browser | new, navigate, click, type, screenshot, close | 6 |
| Tổng | | 79+ |
Cách hoạt động
[CODE BLOCK]
1. Bạn cấu hình LLM client của mình (Claude Desktop, Cursor, v.v.) để sử dụng Synapse MCP server
2. Client khởi động MCP server (qua )
3. MCP server kết nối đến Synapse API sử dụng Mind Key của bạn
4. LLM thấy tất cả 79 công cụ dưới dạng hàm native nó có thể gọi
5. Khi LLM cần nhớ điều gì, nó gọi — MCP server dịch điều này thành trên Synapse
Transport
Synapse MCP server hỗ trợ ba transport:
stdio (cục bộ, khuyến nghị cho desktop)
[CODE BLOCK]
HTTP/SSE (từ xa, multi-tenant)
Kết nối MCP client của bạn đến:
[CODE BLOCK]
WebSocket (di động, khối lượng lớn)
[CODE BLOCK]
Tool Profile (v1.4.0)
Để giảm chi phí token cho LLM nhỏ hơn, MCP server hỗ trợ ba tool profile:
| Profile | Công cụ | Token | Tốt nhất cho |
|---------|-------|--------|----------|
| | 8 (composite dispatch) | 500 | LLM tự lưu trữ với ngữ cảnh ≤8k |
| | 25 (named) | 2,500 | LLM kích thước trung bình (Claude Haiku, GPT-3.5) |
| | 119 (all) | 8,250 | LLM lớn (Claude Sonnet/Opus, GPT-4) — mặc định |
Kiểm soát qua:
- Biến môi trường:
- Header:
Client được hỗ trợ
- Claude Desktop — ứng dụng desktop của Anthropic
- Claude Code — agent lập trình terminal
- Cursor — IDE dựa trên AI
- Continue.dev — trợ lý lập trình AI mã nguồn mở
- Cline — tiện ích mở rộng VS Code
- Bất kỳ client tương thích MCP nào
Tại sao sử dụng MCP thay vì API trực tiếp?
| Cách tiếp cận | Ưu điểm | Nhược điểm |
|----------|------|------|
| API trực tiếp | Đơn giản, không có lớp thêm | LLM cần biết URL, header, xác thực |
| MCP | LLM thấy công cụ native, không cần ghi nhớ URL | Tiến trình MCP server thêm |
Cho hầu hết trường hợp sử dụng LLM agent, MCP là lựa chọn tốt hơn — LLM không
cần ghi nhớ đường dẫn API hoặc mẫu xác thực.
Bước tiếp theo
- Thiết lập Claude Desktop — cấu hình 2 phút
- Thiết lập Claude Code — tích hợp terminal
- Client MCP tùy chỉnh — xây dựng của riêng bạn
## DANH MỤC: HƯỚNG DẪN VÀ CÁCH LÀM
Hướng dẫn từng bước cho các kịch bản cụ thể.
────────────────────────────────────────────────────────────
# Kiểm thử ứng dụng iOS tự động
SUMMARY: Sử dụng Synapse + Computer Control API để tự động hóa kiểm thử ứng dụng iOS qua Simulator.
Kiểm thử ứng dụng iOS tự động
Kết hợp hệ thống bộ nhớ của Synapse với Computer Control API để xây dựng kiểm
thử ứng dụng iOS điều khiển bởi LLM. LLM ghi nhớ kịch bản kiểm thử, học từ lỗi
quá khứ và thích ứng với thay đổi UI.
Kiến trúc
[CODE BLOCK]
Điều kiện tiên quyết
- Tài khoản Synapse + Mind Key
- Synapse MCP server được cấu hình trong Claude Desktop
- iOS Simulator với đã cài đặt
- Máy tính đã đăng ký trong Synapse (xem Computer Control API)
Bước 1: Đăng ký máy tính Simulator
Trên Mac chạy iOS Simulator:
[CODE BLOCK]
Bước 2: Lưu kịch bản kiểm thử trong bộ nhớ
Lưu kịch bản kiểm thử tái sử dụng dưới dạng bộ nhớ:
[CODE BLOCK]
Bước 3: Thực thi kiểm thử điều khiển bởi LLM
Trong Claude Desktop (với Synapse MCP đã cấu hình):
[CODE BLOCK]
Claude sẽ:
1. Gọi để tìm bộ nhớ
2. Gọi để xem trạng thái hiện tại
3. Thực thi mỗi bước qua (click, type)
4. Xác minh kết quả qua ảnh chụp màn hình
5. Lưu bất kỳ lỗi nào dưới dạng bộ nhớ
Bước 4: Kiểm thử tự sửa chữa
Khi kiểm thử thất bại, lưu lỗi và cách khôi phục:
[CODE BLOCK]
Lần tới LLM chạy kiểm thử, nó thu hồi lỗi và áp dụng khôi phục tự động.
Bước 5: Theo dõi kết quả kiểm thử
Theo dõi lần chạy kiểm thử dưới dạng tác vụ:
[CODE BLOCK]
Lệnh phổ biến
| Hành động | Lệnh |
|--------|---------|
| Khởi chạy Simulator | |
| Ảnh chụp màn hình | (qua Synapse MCP) |
| Nhấp tại (x,y) | |
| Nhập văn bản | |
| Nhấn Home | |
Thực hành tốt nhất
> [!TIP]
> - Lưu tọa độ UI dưới dạng bộ nhớ — UI thay đổi, nhưng LLM có thể học lại
> - Sử dụng nhãn accessibility — ổn định hơn tọa độ
> - Lưu dữ liệu kiểm thử riêng biệt — sử dụng biến cho tên người dùng, mật khẩu
> - Chạy kiểm thử trong trạng thái sạch — đặt lại Simulator giữa các lần chạy
> - Ghi ảnh chụp màn hình cho lỗi — hữu ích cho gỡ lỗi
Bước tiếp theo
- Kiểm thử tự sửa chữa
- Computer Control API
- Thực hành tốt nhất về bộ nhớ
────────────────────────────────────────────────────────────
# Sao lưu & Khôi phục
SUMMARY: Xuất bộ nhớ để sao lưu, di chuyển giữa các mind, khôi phục sau mất dữ liệu.
Sao lưu & Khôi phục
Synapse cung cấp xuất/nhập đầy đủ cho sao lưu bộ nhớ, di chuyển và khôi phục
thảm họa. Hướng dẫn này bao phủ các thao tác thiết yếu.
Xuất
Xuất Mind đầy đủ
Xuất tất cả bộ nhớ trong một mind dưới dạng JSON:
[CODE BLOCK]
Định dạng phản hồi:
[CODE BLOCK]
Xuất gia tăng (Diff)
Xuất chỉ bộ nhớ đã thay đổi kể từ một timestamp:
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
Sao lưu tự động
Lên lịch sao lưu hàng ngày qua cron:
[CODE BLOCK]
> [!NOTE]
> Endpoint cron nhận phản hồi nhưng không lưu nó. Cho sao lưu thực sự, trỏ cron
> đến server sao lưu riêng của bạn lưu phản hồi.
Tốt hơn: Script sao lưu bên ngoài
[CODE BLOCK]
Thêm vào crontab:
[CODE BLOCK]
Khôi phục
Khôi phục về cùng Mind
[CODE BLOCK]
Khôi phục về Mind mới
[CODE BLOCK]
Script khôi phục Python
[CODE BLOCK]
Di chuyển giữa các Mind
[CODE BLOCK]
Sao lưu dữ liệu khác
Đừng quên sao lưu:
| Loại dữ liệu | Endpoint |
|-----------|----------|
| Bộ nhớ | |
| Tác vụ | |
| Script | |
| Webhook | |
| Cron job | |
| Biến | |
| Lịch sử chat | |
Xác minh
Sau khi khôi phục, xác minh:
[CODE BLOCK]
Thực hành tốt nhất
> [!TIP]
> - Sao lưu hàng ngày — tự động hóa với cron
> - Kiểm tra khôi phục — sao lưu bạn không thể khôi phục là vô dụng
> - Giữ nhiều phiên bản — ít nhất 30 ngày
> - Lưu ngoài chỗ — S3, Backblaze B2, v.v.
> - Mã hóa sao lưu nhạy cảm — bộ nhớ có thể chứa PII
> - Tài liệu hóa quy trình khôi phục — bạn sẽ quên nó vào lúc bạn cần
Bước tiếp theo
- Memory API
- Cron & Scheduler — cho sao lưu tự động
────────────────────────────────────────────────────────────
# Thực hành tốt nhất về bộ nhớ
SUMMARY: Cách cấu trúc bộ nhớ cho thu hồi hiệu quả — danh mục, key, tag, mức ưu tiên.
Thực hành tốt nhất về bộ nhớ
Cách bạn cấu trúc bộ nhớ xác định độ hữu ích của chúng. Hướng dẫn này bao phủ
mẫu cho việc phân danh mục, gắn tag và ưu tiên bộ nhớ để LLM có thể thu hồi
thông tin đúng vào thời điểm đúng.
Danh mục: Chọn cái cụ thể nhất
| Danh mục | Dùng cho | Ví dụ |
|----------|---------|---------|
| | Tên người dùng, vai trò, thông tin liên hệ | |
| | Thích, không thích, phong cách làm việc | |
| | Sự kiện có thể kiểm chứng | |
| | Trạng thái dự án, quyết định | |
| | Kỹ năng người dùng | |
| | Lỗi quá khứ để tránh | |
| | Ngữ cảnh liên quan phiên | |
| | Ghi chú linh tinh | |
> [!TIP]
> Khi nghi ngờ, sử dụng cho thông tin có thể kiểm chứng và cho
> mọi thứ khác. Không phân danh mục quá mức — tốt hơn có một rõ ràng
> hơn một gây nhầm lẫn.
Key: Định danh ý nghĩa
Trường là định danh của bộ nhớ. Sử dụng key ý nghĩa, ổn định:
Key tốt:
-
-
-
-
Key xấu:
- (không ý nghĩa)
- (không mô tả)
- (ngày không giúp thu hồi)
Quy ước đặt tên key
- (chữ thường với dấu gạch dưới)
- Tiền tố với danh mục: , ,
- Sử dụng danh từ mô tả, không động từ
- Giữ dưới 50 ký tự
Tag: Dành cho tìm kiếm và lọc
Tag cho phép lọc và tìm kiếm nhanh. Thêm 2-5 tag mỗi bộ nhớ:
[CODE BLOCK]
Mẫu tag
- Tên dự án: , ,
- Chủ đề: , , ,
- Trạng thái: , ,
- Chỉ báo ưu tiên: ,
> [!NOTE]
> Tag không phân biệt chữ hoa chữ thường. Sử dụng chữ thường để nhất quán.
Mức ưu tiên: Thực tế
| Ưu tiên | Dùng cho | % Bộ nhớ |
|----------|---------|---------------|
| | Nhận dạng người dùng, thông tin pháp lý, quyết định không thể đảo ngược | 5% |
| | Dự án đang hoạt động, sở thích quan trọng | 20% |
| | Hầu hết sự kiện, ghi chú, ngữ cảnh | 65% |
| | Tạm thời, tốt nếu biết | 10% |
> [!WARNING]
> Không đánh dấu mọi thứ . Nếu mọi thứ là critical, không có gì là
> critical cả. Dự trữ cho những thứ sẽ gây hại thực sự nếu quên.
Khi nào lưu so với không lưu
Luôn lưu
- Nhận dạng người dùng (tên, email, vai trò)
- Sở thích dài hạn
- Quyết định dự án và lý do
- Lỗi quá khứ và bài học
- Cam kết với người dùng
Không lưu
- Trạng thái tạm thời (sử dụng biến thay thế)
- Lịch sử hội thoại nguyên văn (hệ thống chat xử lý điều này)
- Dữ liệu nhạy cảm (mật khẩu, API key)
- Sự kiện dễ dàng suy ra (ngày hiện tại, nội dung tệp)
- Ngữ cảnh tạm thời (sử dụng danh mục với ưu tiên thấp)
Cập nhật bộ nhớ
POST với cùng + cập nhật bộ nhớ hiện có:
[CODE BLOCK]
> [!TIP]
> Sử dụng key ổn định để bạn có thể cập nhật mà không tạo bản trùng lặp. LLM
> nên POST lại cùng key khi thông tin thay đổi, không tạo bộ nhớ mới.
Vòng đời bộ nhớ
[CODE BLOCK]
- Create: POST /memory với ngữ cảnh đầy đủ
- Active: Thu hồi thường xuyên, cập nhật khi cần
- Stale: Vẫn liên quan nhưng không được sử dụng tích cực (ưu tiên thấp hơn?)
- Archive: Đặt ưu tiên thành , giữ cho tham chiếu lịch sử
- Delete: DELETE /memory/:id khi không còn liên quan
Dọn dẹp định kỳ
[CODE BLOCK]
Mẫu: Kế thừa bộ nhớ
Cho ngữ cảnh phân cấp (dự án → dự án con → tác vụ):
[CODE BLOCK]
LLM có thể sau đó tìm để tìm tất cả bộ nhớ liên quan.
Mẫu: Nhật ký quyết định
Lưu quyết định với lý do để LLM không tái thẩm lại chúng:
[CODE BLOCK]
Mẫu: Tránh lỗi
Lưu lỗi với hướng dẫn tránh cụ thể:
[CODE BLOCK]
Mẫu chống cần tránh
> [!WARNING]
> - Lưu nhật ký hội thoại — hệ thống chat xử lý điều này
> - Lưu toàn bộ tệp — sử dụng script store hoặc lưu trữ bên ngoài
> - Lưu trạng thái tạm thời — sử dụng biến
> - Lưu bí mật — sử dụng biến môi trường
> - Trùng lặp bộ nhớ — sử dụng key ổn định
> - Gắn tag quá mức — 2-5 tag mỗi bộ nhớ là lý tưởng
> - Mọi thứ là critical — thực tế với ưu tiên
Bước tiếp theo
- Memory API
- LLM Agent cố định
- Chiến lược gắn tag bộ nhớ
────────────────────────────────────────────────────────────
# Điều phối Multi-Agent
SUMMARY: Điều phối nhiều LLM agent sử dụng mind, tác vụ và chat Synapse chung.
Điều phối Multi-Agent
Khi bạn có nhiều LLM agent làm việc trên các tác vụ liên quan, Synapse cung cấp
lớp điều phối — bộ nhớ chung, gán tác vụ và chat bất đồng bộ.
Mẫu
Mẫu 1: Mind chung (Nguồn sự thật duy nhất)
Tất cả agent chia sẻ một Mind Key. Chúng đọc/ghi cùng kho bộ nhớ.
[CODE BLOCK]
Trường hợp sử dụng: Nhóm nhỏ agent làm việc trên một dự án.
Thiết lập:
[CODE BLOCK]
Điều phối qua tác vụ:
[CODE BLOCK]
Mẫu 2: Mind chuyên biệt (Ngữ cảnh tách biệt)
Mỗi agent có mind riêng. Chúng giao tiếp qua một mind "điều phối" chung.
[CODE BLOCK]
Trường hợp sử dụng: Agent với chuyên môn khác nhau (lập trình, review, triển khai).
Thiết lập:
[CODE BLOCK]
Điều phối qua mind chung:
[CODE BLOCK]
Mẫu 3: Hub-and-Spoke (Orchestrator)
Một agent orchestrator trung tâm gán tác vụ cho agent worker.
[CODE BLOCK]
Trường hợp sử dụng: Quy trình phức tạp với công việc song song.
Triển khai:
[CODE BLOCK]
Điều phối qua Chat
Agent có thể giao tiếp qua hệ thống chat:
[CODE BLOCK]
> [!NOTE]
> Tin nhắn chat được gắn vai trò. Đặt role=agent cho tin nhắn agent-đến-agent,
> role=human cho human-đến-agent.
Điều phối qua Biến
Sử dụng biến cho điều phối nhẹ (lock, cờ):
[CODE BLOCK]
Thực hành tốt nhất
> [!TIP]
> - Sử dụng mind riêng cho mối quan tâm riêng — không trộn bộ nhớ coder và reviewer
> - Gắn tag agent trong chat — cho địa chỉ rõ ràng
> - Sử dụng tác vụ cho gán công việc — không chat (chat dành cho thảo luận)
> - Triển khai idempotency — agent có thể thử lại thao tác thất bại
> - Ghi nhật ký mọi thứ — lưu quyết định trong bộ nhớ cho khả năng kiểm toán
Bước tiếp theo
- LLM Agent cố định
- LLM Cookbook
- Tự động hóa Webhook
────────────────────────────────────────────────────────────
# Xây dựng LLM Agent cố định
SUMMARY: Hướng dẫn từng bước xây dựng LLM agent ghi nhớ qua các phiên sử dụng Synapse.
Tổng quan
Hướng dẫn này dẫn qua việc xây dựng LLM agent lưu ngữ cảnh qua các phiên sử dụng
Synapse. Cuối cùng, agent của bạn sẽ:
- Thu hồi ngữ cảnh quá khứ ở đầu phiên
- Lưu học hỏi mới khi chúng xảy ra
- Theo dõi tác vụ nhiều bước qua các phiên
- Giao tiếp với con người qua chat bất đồng bộ
Kiến trúc
[CODE BLOCK]
Bước 1: Thiết lập Mind Key
[CODE BLOCK]
Bước 2: Giao thức bắt đầu phiên
Ở đầu mỗi phiên, thu hồi tất cả bộ nhớ:
[CODE BLOCK]
Bước 3: Lưu học hỏi mới
Bất cứ khi nào agent học được điều gì đáng nhớ:
[CODE BLOCK]
Bước 4: Quản lý tác vụ
Theo dõi công việc nhiều bước qua các phiên:
[CODE BLOCK]
Bước 5: Chat bất đồng bộ với con người
Poll tin nhắn giữa các lệnh gọi công cụ:
[CODE BLOCK]
Bước 6: Giao thức kết thúc phiên
Ở cuối phiên, lưu ngữ cảnh cuối:
[CODE BLOCK]
Mẫu hoàn chỉnh
[CODE BLOCK]
Thực hành tốt nhất
> [!TIP]
>
> - Luôn thu hồi đầu tiên — không bao giờ bắt đầu làm việc mà không tải ngữ cảnh
> - Lưu chủ động — không đợi đến cuối phiên
> - Sử dụng key ý nghĩa — , , không phải
> - Gắn tag mọi thứ — tag powering tìm kiếm và lọc
> - Đặt ưu tiên thực tế — không phải mọi thứ là
Bước tiếp theo
- LLM Cookbook — mẫu thực tế
- Thực hành tốt nhất về bộ nhớ
- Điều phối Multi-Agent
────────────────────────────────────────────────────────────
# Pipeline kiểm thử tự sửa chữa
SUMMARY: Xây dựng pipeline kiểm thử học từ lỗi và thích ứng tự động sử dụng bộ nhớ Synapse.
Pipeline kiểm thử tự sửa chữa
Bộ kiểm thử truyền thống bị hỏng khi UI thay đổi. Kiểm thử tự sửa chữa sử dụng
bộ nhớ Synapse để học từ lỗi quá khứ và thích ứng — giảm kiểm thử flaky và gánh
nặng bảo trì.
Khái niệm
[CODE BLOCK]
1. Kiểm thử chạy
2. Nếu thất bại, lưu lỗi (cái gì sai, tại sao, cách sửa)
3. Lần chạy tiếp: thu hồi lỗi liên quan trước khi thực thi
4. Áp dụng sửa chữa đã biết tự động
Triển khai
Bước 1: Wrapper kiểm thử
Bọc mỗi kiểm thử với thu hồi/lưu bộ nhớ:
[CODE BLOCK]
Bước 2: Logic kiểm thử thích ứng
Bên trong kiểm thử, kiểm tra lỗi đã biết và áp dụng sửa chữa:
[CODE BLOCK]
Bước 3: Chiến lược khôi phục
Lưu chiến lược khôi phục dưới dạng bộ nhớ:
[CODE BLOCK]
Bước 4: Tích hợp CI
[CODE BLOCK]
Bước 5: Bảng điều khiển phân tích lỗi
[CODE BLOCK]
Thực hành tốt nhất
> [!TIP]
> - Lưu traceback — chúng chứa dòng chính xác bị lỗi
> - Gắn tag theo tên kiểm thử — cho phép lọc nhanh
> - Sử dụng danh mục — tách khỏi bộ nhớ thông thường
> - Đặt ưu tiên — lỗi không bao giờ được quên
> - Dọn dẹp định kỳ — xóa bộ nhớ cho vấn đề đã giải quyết
> - Không lưu dữ liệu nhạy cảm — thông tin xác thực, PII
Mẫu lỗi phổ biến cần lưu
| Loại lỗi | Cần lưu gì |
|--------------|---------------|
| Không tìm thấy phần tử | Selector đã thử, trạng thái trang, ảnh chụp màn hình |
| Timeout | Thời gian chờ, đang chờ cái gì |
| Assertion thất bại | Giá trị mong đợi so với thực tế |
| Lỗi mạng | URL, mã trạng thái, body phản hồi |
| Permission denied | Quyền yêu cầu, vai trò người dùng hiện tại |
Bước tiếp theo
- Kiểm thử iOS tự động
- Thực hành tốt nhất về bộ nhớ
- Cookbook khôi phục lỗi
────────────────────────────────────────────────────────────
# Tự động hóa Webhook
SUMMARY: Kích hoạt hệ thống bên ngoài khi bộ nhớ thay đổi — đồng bộ, thông báo, tự động hóa.
Tự động hóa Webhook
Webhook cho phép bạn kích hoạt hệ thống bên ngoài khi sự kiện Synapse kích
hoạt. Hướng dẫn này bao phủ mẫu tự động hóa phổ biến.
Mẫu phổ biến
Mẫu 1: Thông báo khi bộ nhớ Critical
Gửi tin nhắn Slack khi bộ nhớ critical được lưu:
[CODE BLOCK]
Đăng ký webhook:
[CODE BLOCK]
Mẫu 2: Đồng bộ với hệ thống bên ngoài
Đồng bộ bộ nhớ với Notion, Obsidian hoặc bất kỳ KB bên ngoài:
[CODE BLOCK]
Mẫu 3: Kích hoạt CI/CD
Kích hoạt triển khai khi một bộ nhớ "release" được lưu:
[CODE BLOCK]
Mẫu 4: Đánh thức Agent khi tin nhắn con người
Kích hoạt chạy LLM agent khi con người gửi tin nhắn chat:
[CODE BLOCK]
Mẫu 5: Tổng hợp chỉ số
Theo dõi tăng trưởng bộ nhớ, hoạt động chat, hoàn thành tác vụ:
[CODE BLOCK]
Xác minh chữ ký
Luôn xác minh chữ ký webhook để ngăn giả mạo:
[CODE BLOCK]
Logic thử lại
Synapse thử lại webhook thất bại với exponential backoff. Trình xử lý của bạn nên:
1. Trả 200 nhanh — không làm công việc nặng đồng bộ
2. Xếp hàng công việc — sử dụng hệ thống công việc nền
3. Idempotent — cùng sự kiện có thể được gửi hai lần
[CODE BLOCK]
Gỡ lỗi Webhook
Kiểm tra lịch sử gửi
Việc gửi webhook được ghi nhật ký. Kiểm tra gửi gần đây của webhook:
[CODE BLOCK]
Kiểm tra webhook thủ công
[CODE BLOCK]
Vấn đề phổ biến
| Vấn đề | Khắc phục |
|-------|-----|
| Phản hồi 4xx | Kiểm tra trình xử lý trả 200 |
| Phản hồi 5xx | Lỗi server — kiểm tra nhật ký ứng dụng |
| Timeout | Trả 200 nhanh, xếp hàng công việc async |
| Gửi trùng lặp | Làm trình xử lý idempotent |
| Chữ ký không khớp | Xác minh secret chính xác |
Thực hành tốt nhất
> [!TIP]
> - Luôn xác minh chữ ký — không bao giờ bỏ qua
> - Trả 200 nhanh — không chặn Synapse
> - Idempotent — xử lý gửi trùng lặp
> - Sử dụng sự kiện cụ thể — không phải
> - Giám sát gửi thất bại — thiết lập cảnh báo
Bước tiếp theo
- Webhooks API
- Cron & Scheduler
- LLM Agent cố định
## DANH MỤC: KHÁI NIỆM
Kiến trúc và khái niệm đằng sau Synapse.
────────────────────────────────────────────────────────────
# Kiến trúc Synapse
SUMMARY: Cách Synapse được xây dựng — Fastify, PostgreSQL, FTS5, embeddings, MCP server.
Kiến trúc Synapse
Synapse là API bộ nhớ multi-tenant được xây dựng trên Fastify, PostgreSQL với
FTS5, và một dịch vụ embeddings tùy chọn cho tìm kiếm ngữ nghĩa.
Kiến trúc tổng quan
[CODE BLOCK]
Thành phần cốt lõi
1. Synapse API (Fastify)
HTTP server chính. Xử lý:
- Endpoint REST (, , , v.v.)
- Xác thực (Mind Key cho agent, JWT cho con người)
- Giới hạn tốc độ (chỉ xác thực )
- Phục vụ tệp tĩnh (giao diện web tại , , v.v.)
- Phân phối webhook
Được xây dựng với Fastify 5 cho hiệu suất. Chạy trên cổng 12800 trong môi trường production.
2. PostgreSQL với FTS5
Kho dữ liệu chính. Sử dụng PostgreSQL với phần mở rộng FTS5 cho tìm kiếm toàn
văn.
Bảng chính:
| Bảng | Mục đích |
|-------|---------|
| | Tài khoản người dùng |
| | Phạm vi mind (mỗi cái có một Mind Key) |
| | Bản ghi bộ nhớ với bảng ảo FTS5 |
| | Quản lý tác vụ |
| | Lịch sử chat |
| | Script cố định |
| | Đăng ký webhook |
| | Tác vụ đã lên lịch |
| | Cửa hàng key-value |
| | Nhật ký kiểm toán |
FTS5 cho phép tìm kiếm toàn văn dưới mili giây trên toàn bộ nội dung bộ
nhớ. Xem Tìm kiếm FTS5 để biết chi tiết.
3. Dịch vụ Embeddings (Tùy chọn)
Đối với tìm kiếm ngữ nghĩa, Synapse tạo vector embeddings của nội dung bộ nhớ.
Chúng được lưu cùng với bộ nhớ và dùng cho tìm kiếm tương tự.
- Provider: có thể cấu hình (OpenAI, mô hình cục bộ, v.v.)
- Lưu dưới dạng cột trong bảng
- Được sử dụng bởi endpoint
- Xem Tìm kiếm ngữ nghĩa
4. MCP Server (Dịch vụ riêng)
Synapse MCP server chạy như một tiến trình riêng (cổng 13100). Nó:
- Cung cấp 79 công cụ qua Model Context Protocol
- Hỗ trợ transport stdio, HTTP/SSE và WebSocket
- Dịch các lệnh gọi công cụ MCP thành lệnh gọi Synapse API
- Multi-tenant: một Mind Key mỗi phiên
5. Browser Proxy (Dịch vụ riêng)
Đối với tự động hóa trình duyệt, một dịch vụ riêng dựa trên Playwright chạy
trên cổng 13000. MCP server có thể gọi dịch vụ này cho các công cụ .
6. SSH Proxy (Dịch vụ riêng)
Đối với lệnh từ xa dựa trên SSH, một dịch vụ riêng chạy trên cổng 12900.
Mô hình Multi-Tenancy
[CODE BLOCK]
Mỗi mind hoàn toàn tách biệt. Mind Key cấp quyền truy cập chính xác một mind.
JWT cấp quyền truy cập tài khoản người dùng (để quản lý mind).
Xem Multi-Tenancy để biết chi tiết.
Luồng yêu cầu
Yêu cầu lưu bộ nhớ
[CODE BLOCK]
Yêu cầu tìm kiếm bộ nhớ
[CODE BLOCK]
Triển khai
Synapse được triển khai dưới dạng Docker container. Xem :
[CODE BLOCK]
Đặc tính hiệu suất
| Thao tác | Độ trễ | Thông lượng |
|-----------|---------|------------|
| Lưu bộ nhớ | 5ms | 1000+ req/s |
| Thu hồi bộ nhớ | 20ms | 500 req/s |
| Tìm kiếm FTS5 | 10ms | 800 req/s |
| Tìm kiếm ngữ nghĩa | 50ms | 200 req/s |
| Poll chat | 5ms | 2000 req/s |
Bước tiếp theo
- Mô hình bộ nhớ
- Multi-Tenancy
- Tìm kiếm FTS5
────────────────────────────────────────────────────────────
# Tìm kiếm toàn văn FTS5
SUMMARY: Cách Synapse sử dụng SQLite FTS5 cho tìm kiếm bộ nhớ toàn văn dưới mili giây.
Tìm kiếm toàn văn FTS5
Synapse sử dụng FTS5 (Full-Text Search 5) cho tìm kiếm bộ nhớ nhanh, linh hoạt.
Trang này giải thích cách nó hoạt động và cách sử dụng hiệu quả.
FTS5 là gì?
FTS5 là một phần mở rộng SQLite (cũng có sẵn trong PostgreSQL qua các phần mở
rộng) cung cấp khả năng tìm kiếm toàn văn. Nó:
- Đánh chỉ mục nội dung văn bản để tìm kiếm từ khóa nhanh
- Hỗ trợ toán tử boolean (AND, OR, NOT)
- Hỗ trợ khớp cụm từ với dấu ngoặc kép
- Hỗ trợ khớp tiền tố với
- Xếp hạng kết quả theo mức độ liên quan
Synapse sử dụng FTS5 để đánh chỉ mục toàn bộ nội dung bộ nhớ, cho phép tìm
kiếm dưới mili giây trên hàng nghìn bộ nhớ.
Cách Synapse sử dụng FTS5
Khi bạn :
1. Nội dung bộ nhớ được lưu trong bảng
2. Nội dung cũng được chèn vào bảng ảo FTS5
3. FTS5 tự động tokenize và đánh chỉ mục nội dung
Khi bạn :
1. Synapse phân tích truy vấn bằng cú pháp FTS5
2. Thực thi đối với chỉ mục FTS5
3. Lọc theo (cách ly tenant)
4. Trả về kết quả được xếp hạng
Cú pháp truy vấn
Tìm kiếm từ khóa đơn giản
[CODE BLOCK]
Trả về bộ nhớ chứa "docker".
Nhiều từ khóa (AND ngầm định)
[CODE BLOCK]
Trả về bộ nhớ chứa CẢ "docker" VÀ "swarm".
Khớp cụm từ
[CODE BLOCK]
Trả về bộ nhớ chứa cụm từ chính xác "docker swarm".
Khớp tiền tố
[CODE BLOCK]
Trả về bộ nhớ chứa các từ bắt đầu bằng "docker" (ví dụ "dockers", "dockerfile",
"dockerize").
Boolean OR
[CODE BLOCK]
Trả về bộ nhớ chứa "docker" HOẶC "kubernetes".
Boolean NOT
[CODE BLOCK]
Trả về bộ nhớ chứa "docker" nhưng KHÔNG chứa "swarm".
Nhóm
[CODE BLOCK]
Trả về bộ nhớ chứa "docker" hoặc "kubernetes", nhưng không chứa "test".
Ví dụ thực tế
Tìm bộ nhớ về một dự án
[CODE BLOCK]
Tìm cụm từ chính xác
[CODE BLOCK]
Loại trừ bộ nhớ kiểm thử
[CODE BLOCK]
Tìm theo công nghệ
[CODE BLOCK]
Xếp hạng
FTS5 xếp hạng kết quả theo mức độ liên quan bằng thuật toán BM25. Các yếu tố:
- Tần suất thuật ngữ (thuật ngữ xuất hiện bao nhiêu lần)
- Tần suất tài liệu nghịch đảo (thuật ngữ hiếm xếp cao hơn)
- Độ dài tài liệu (tài liệu ngắn hơn với thuật ngữ xếp cao hơn)
- Trọng số cột (tiêu đề > nội dung)
Kết quả được trả về theo thứ tự xếp hạng (liên quan nhất trước).
Hiệu suất
| Thao tác | Độ trễ |
|-----------|---------|
| Tìm 100 bộ nhớ | < 5ms |
| Tìm 1.000 bộ nhớ | < 10ms |
| Tìm 10.000 bộ nhớ | < 25ms |
| Tìm 100.000 bộ nhớ | < 100ms |
FTS5 được tối ưu cao cho khối lượng công việc nặng về đọc.
Giới hạn
Stemming
FTS5 không làm stemming theo mặc định. "running" và "run" là các thuật ngữ
khác nhau.
Giải pháp: Sử dụng khớp tiền tố:
Dung sai lỗi chính tả
FTS5 không hỗ trợ khớp mờ. Lỗi chính tả sẽ trả về không kết quả.
Giải pháp: Sử dụng tìm kiếm ngữ nghĩa () cho khớp
khái niệm.
Từ dừng
Các từ phổ biến (the, a, an, is) được đánh chỉ mục nhưng có thể không hữu ích
cho tìm kiếm. FTS5 xử lý điều này tự động.
FTS5 so với Tìm kiếm ngữ nghĩa
| Khía cạnh | FTS5 | Tìm kiếm ngữ nghĩa |
|--------|------|-----------------|
| Tốc độ | Dưới mili giây | 50-100ms |
| Khớp | Từ khóa chính xác | Khái niệm |
| Dung sai lỗi chính tả | Không | Một số |
| Stemming | Không | Ngầm định |
| Yêu cầu embeddings | Không | Có |
| Tốt nhất cho | Thuật ngữ cụ thể | Khái niệm |
Sử dụng FTS5 khi bạn biết từ khóa. Sử dụng tìm kiếm ngữ nghĩa khi bạn muốn
"bộ nhớ về X" khi X được mô tả khác đi.
Thực hành tốt nhất
> [!TIP]
> - Sử dụng thuật ngữ cụ thể — "docker swarm" tốt hơn "container orchestration"
> - Trích dẫn cụm từ — đảm bảo khớp cụm từ
> - Sử dụng tiền tố cho biến thể — bắt được "deploy", "deployment", "deploying"
> - Loại trừ nhiễu — lọc bỏ bộ nhớ kiểm thử
> - Kết hợp với tag — thu hẹp kết quả
Bước tiếp theo
- Tìm kiếm ngữ nghĩa
- Memory API
- Thực hành tốt nhất về bộ nhớ
────────────────────────────────────────────────────────────
# Mô hình bộ nhớ
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.
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ớ
[CODE BLOCK]
Trường
| Trường | Loại | Bắt buộc | Mô tả |
|-------|------|----------|-------------|
| | string | tự động | ID duy nhất (memxxx) |
| | enum | ✅ | Một trong 8 danh mục |
| | string | ✅ | Định danh ổn định (dùng để cập nhật) |
| | string | ✅ | Nội dung bộ nhớ (bất kỳ văn bản nào) |
| | string[] | – | Để tìm kiếm và lọc |
| | enum | – | low, normal, high, critical (mặc định: normal) |
| | enum | tự động | user, agent (ai lưu) |
| | bool | tự động | Con người đã xác minh chưa? |
| | float | – | 0.0 đến 1.0 (mặc định: 1.0 cho user, 0.7 cho agent) |
| | timestamp | – | Khi nào quên bộ nhớ này |
| | string | tự động | Mind nào sở hữu cái này |
| | timestamp | tự động | Lần đầu lưu |
| | 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ụ |
|----------|---------|-----------------|
| | Người dùng là ai | "User is Michael Schäfer, software engineer in Berlin" |
| | Sở thích người dùng | "Prefers concise technical responses" |
| | Sự kiện có thể kiểm chứng | "Office is in Berlin, timezone Europe/Berlin" |
| | Trạng thái dự án | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| | Kỹ năng người dùng | "Advanced Python, 10+ years" |
| | Lỗi trong quá khứ | "Forgot to bump npm version — CI failed" |
| | Ngữ cảnh phiên | "Currently reviewing PR #42" |
| | Ghi chú linh tinh | "Try Redis for caching next sprint" |
Key: Định danh ổn định
Trường 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.
[CODE BLOCK]
Quy tắc key:
- Phải duy nhất trong (category, mind)
- Sử dụng
- Tiền tố với danh mục để rõ ràng: ,
- 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:
[CODE BLOCK]
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 |
|----------|-------------|-----------------|
| | Nhận dạng, pháp lý, không thể đảo ngược | Luôn ở đầu thu hồi |
| | Dự án đang hoạt động, sở thích chính | Nổi bật trong thu hồi |
| | Hầu hết bộ nhớ (mặc định) | Thứ tự thu hồi chuẩn |
| | Tạm thời, tốt nếu biết | Có thể được tóm tắt |
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 :
- — được lưu bởi con người (qua JWT hoặc giao diện con người)
- — được lưu bởi LLM agent (qua Mind Key)
Điều này ảnh hưởng:
- Xác minh: bộ nhớ được tự động xác minh, bộ nhớ thì không
- Độ tin cậy: mặc định 1.0, 0.7
- Thu hồi: đánh dấu bộ nhớ chưa xác minh với "(unverified)"
> [!NOTE]
> Hãy đối xử với bộ nhớ nguồn 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ờ cho biết con người đã xác nhận bộ nhớ:
- Bộ nhớ : tự động xác minh ()
- Bộ nhớ : mặc định chưa xác minh ()
Xác minh bộ nhớ qua:
[CODE BLOCK]
> [!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 (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:
[CODE BLOCK]
Hết hạn
Đặt cho bộ nhớ nhạy cảm với thời gian:
[CODE BLOCK]
Bộ nhớ hết hạn không được trả về (nhưng vẫn tồn tại trong DB).
Sử dụng để xem bộ nhớ sắp hết hạn.
Vòng đời bộ nhớ
[CODE BLOCK]
Hành vi thu hồi
trả về tóm tắt văn bản thuần được tối ưu cho ngữ cảnh LLM:
[CODE BLOCK]
- 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
- 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
- Thực hành tốt nhất về bộ nhớ
- Tìm kiếm FTS5
────────────────────────────────────────────────────────────
# Multi-Tenancy & Cách ly
SUMMARY: Cách Synapse cách ly dữ liệu giữa người dùng và mind — giải thích ranh giới bảo mật.
Multi-Tenancy & Cách ly
Synapse là multi-tenant: nhiều người dùng, mỗi người có nhiều mind, hoàn toàn
cách ly với nhau. Trang này giải thích mô hình cách ly.
Hệ thống tenant
[CODE BLOCK]
Cấp độ cách ly
Cấp 1: Cách ly người dùng
Mỗi tài khoản người dùng được cách ly. Alice không thể:
- Xem mind của Bob
- Truy cập bộ nhớ của Bob (ngay cả với JWT của cô ấy)
- Liệt kê thông tin tài khoản của Bob
Thực thi bởi: cột trên tất cả bảng, JWT chứa , tất cả truy
vấn lọc theo .
Cấp 2: Cách ly mind
Trong một người dùng, mỗi mind được cách ly. Mind A không thể:
- Xem bộ nhớ của Mind B
- Truy cập tác vụ, chat, script của Mind B
Thực thi bởi: cột trên tất cả bảng dữ liệu, Mind Key chứa ,
tất cả truy vấn lọc theo .
> [!CRITICAL]
> Cách ly Mind Key là ranh giới bảo mật chính. Một Mind Key bị lộ cấp quyền
> truy cập đầy đủ dữ liệu mind đó — nhưng CHỈ mind đó.
Token xác thực
| Token | Phạm vi | Có thể truy cập gì |
|-------|-------|-------------------|
| Mind Key | Một mind duy nhất | Chỉ dữ liệu mind đó |
| JWT | Tài khoản người dùng | Quản lý tài khoản (tạo/liệt kê/xóa mind) |
| Computer Token | Một máy tính duy nhất | Lệnh của máy tính đó |
Truy cập chéo mind
Trong cùng người dùng
Người dùng có thể truy cập tất cả mind của họ qua JWT (ví dụ liệt
kê tất cả). Nhưng để đọc/ghi dữ liệu bộ nhớ, họ cần Mind Key cụ thể.
Giữa người dùng
Người dùng không thể truy cập dữ liệu của nhau — TRỪ KHI họ chia sẻ rõ ràng một
mind qua Sharing API:
[CODE BLOCK]
Sau khi chia sẻ, Bob có thể truy cập Mind A qua JWT của anh ấy (chỉ đọc nếu
).
Ranh giới bảo mật
[CODE BLOCK]
Mẫu multi-tenant phổ biến
Mẫu 1: Một người dùng, một mind
Phổ biến nhất cho người dùng LLM agent cá nhân.
- 1 tài khoản người dùng
- 1 mind
- 1 Mind Key
- Tất cả bộ nhớ trong một phạm vi
Mẫu 2: Một người dùng, nhiều mind
Cho người dùng có nhiều ngữ cảnh (công việc, cá nhân, dự án).
- 1 tài khoản người dùng
- N mind (ví dụ "work", "personal", "project-x")
- N Mind Key
- Mỗi phiên LLM sử dụng một Mind Key
Mẫu 3: Mind chung nhóm
Cho nhóm cộng tác trên một dự án.
- 1 người dùng tạo mind (nhận Mind Key)
- Người tạo chia sẻ với thành viên nhóm qua JWT
- Tất cả thành viên nhóm truy cập qua JWT (hoặc Mind Key chung)
> [!WARNING]
> Chia sẻ Mind Key cấp quyền truy cập đọc/ghi đầy đủ. Cho cộng tác nhóm, ưu
> tiên Sharing API (dựa trên JWT) thay vì chia sẻ Mind Key trực tiếp.
Mẫu 4: Nhà cung cấp SaaS
Cho ứng dụng nhúng Synapse làm lớp bộ nhớ.
- Mỗi khách hàng = 1 tài khoản người dùng
- Mỗi dự án khách hàng = 1 mind
- Ứng dụng lưu Mind Key cho mỗi khách hàng/dự án
- Cách ly đầy đủ giữa khách hàng
Xác minh cách ly
Kiểm tra: Mind Key không thể truy cập mind khác
[CODE BLOCK]
Kiểm tra: JWT không thể đọc dữ liệu bộ nhớ trực tiếp
[CODE BLOCK]
Thực hành tốt nhất
> [!TIP]
> - Sử dụng một mind mỗi dự án/ngữ cảnh — cách ly là bạn của bạn
> - Không bao giờ chia sẻ Mind Key — sử dụng Sharing API thay thế
> - Xoay vòng Mind Key nếu bị xâm phạm (xóa mind, tạo mới)
> - Kiểm toán mind chia sẻ — xem xét định kỳ
> - Sử dụng JWT cho giao diện con người — không bao giờ lộ Mind Key cho người dùng cuối
Bước tiếp theo
- Xác thực
- Mind Key vs JWT
- Kiến trúc
────────────────────────────────────────────────────────────
# Tìm kiếm ngữ nghĩa (Embeddings)
SUMMARY: Tìm kiếm bộ nhớ khái niệm sử dụng vector embeddings — tìm theo ý nghĩa, không chỉ từ khóa.
Tìm kiếm ngữ nghĩa (Embeddings)
Synapse hỗ trợ tìm kiếm ngữ nghĩa sử dụng vector embeddings. Khác với FTS5 (khớp
từ khóa), tìm kiếm ngữ nghĩa tìm bộ nhớ theo ý nghĩa — ngay cả khi không có
từ khóa nào khớp.
Cách hoạt động
[CODE BLOCK]
Embeddings là gì?
Embeddings là biểu diễn vector số của văn bản. Văn bản có ý nghĩa tương tự có
vector tương tự. Synapse tạo một vector (ví dụ 1536 chiều) cho nội dung mỗi bộ
nhớ.
Tương đồng cosine
Để tìm bộ nhớ tương tự về mặt ngữ nghĩa, Synapse tính tương đồng cosine giữa
vector truy vấn và mỗi vector bộ nhớ. Tương đồng cao hơn = liên quan hơn.
Khi nào sử dụng tìm kiếm ngữ nghĩa
Sử dụng tìm kiếm ngữ nghĩa khi:
- Bạn muốn "bộ nhớ về X" khi X được mô tả khác với lưu trữ
- FTS5 trả về không kết quả (không khớp từ khóa)
- Bạn muốn nhóm khái niệm (ví dụ tất cả bộ nhớ "deployment", ngay cả khi một số nói "release")
- Truy vấn là một câu hỏi: "làm thế nào chúng ta xử lý xác thực?"
Sử dụng FTS5 khi:
- Bạn biết từ khóa chính xác
- Bạn cần logic boolean (AND, OR, NOT)
- Bạn cần phản hồi dưới mili giây
- Bạn muốn khớp cụm từ
Endpoint
GET /memory/semantic-search
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
Ví dụ
Tìm bộ nhớ triển khai
[CODE BLOCK]
Trả về bộ nhớ về "deployment", "release", "publishing", "rolling out", v.v.
Tìm mẫu xác thực
[CODE BLOCK]
Trả về bộ nhớ về đăng nhập, xác thực, JWT, quản lý phiên, OAuth, v.v.
Tìm bộ nhớ tương tự
[CODE BLOCK]
Sử dụng tương đồng ngữ nghĩa (qua tag chung VÀ vector embedding).
Tạo embedding
Khi nào embeddings được tạo?
- Khi lưu bộ nhớ — nếu dịch vụ embeddings được cấu hình, embedding được tạo đồng bộ
- Tạo hàng loạt — tạo embeddings cho bộ nhớ thiếu
- Cập nhật bất đồng bộ — khi nội dung được cập nhật, embedding được tạo lại
Provider embedding
Synapse hỗ trợ provider embedding có thể cấu hình:
- OpenAI (, )
- Mô hình cục bộ (qua Ollama hoặc tương tự)
- Tùy chỉnh (triển khai giao diện embeddings)
Cấu hình qua biến môi trường:
[CODE BLOCK]
Tạo hàng loạt
Cho mind với nhiều bộ nhớ thiếu embeddings:
[CODE BLOCK]
Hiệu suất
| Thao tác | Độ trễ |
|-----------|---------|
| Tạo embedding (OpenAI) | 100-200ms |
| Tìm kiếm ngữ nghĩa (1k bộ nhớ) | 50-100ms |
| Tìm kiếm ngữ nghĩa (10k bộ nhớ) | 200-500ms |
| Tạo hàng loạt (100 bộ nhớ) | 10-20s |
> [!NOTE]
> Tìm kiếm ngữ nghĩa chậm hơn FTS5 do tính toán vector. Sử dụng FTS5 cho từ
> khóa đã biết, ngữ nghĩa cho truy vấn khái niệm.
Giới hạn
Chi phí embeddings
Nếu sử dụng OpenAI, tạo embeddings tốn tiền ($0.02 mỗi 1M token cho
text-embedding-3-small). Cho 10.000 bộ nhớ trung bình 100 token mỗi cái, đó là
$0.02 — không đáng kể.
Khởi động lạnh
Bộ nhớ lưu trước khi embeddings được cấu hình sẽ không có embeddings. Chạy
để backfill.
Phụ thuộc provider
Nếu provider embeddings ngừng hoạt động, tìm kiếm ngữ nghĩa thất bại một cách
mềm mại (trả về kết quả rỗng hoặc lỗi). FTS5 vẫn hoạt động.
Khi Embeddings không khả dụng
Nếu dịch vụ embeddings không được cấu hình:
- trả về 503 Service Unavailable
- vẫn hoạt động (chỉ không có embedding được tạo)
- Tìm kiếm FTS5 vẫn hoạt động
Thực hành tốt nhất
> [!TIP]
> - Sử dụng ngữ nghĩa cho truy vấn khái niệm — "làm thế nào chúng ta xử lý X?"
> - Sử dụng FTS5 cho thuật ngữ cụ thể — "docker swarm"
> - Backfill embeddings thường xuyên —
> - Giám sát sức khỏe provider — tìm kiếm ngữ nghĩa phụ thuộc vào nó
> - Kết hợp với tag — ngữ nghĩa + bộ lọc tag thu hẹp kết quả
Bước tiếp theo
- Tìm kiếm FTS5
- Memory API
- Kiến trúc
## DANH MỤC: SÁCH CÔNG THỨC LLM
Công thức và mẫu cho LLM agents.
────────────────────────────────────────────────────────────
# Mẫu Polling Chat
SUMMARY: Cách poll tin nhắn con người giữa các lệnh gọi công cụ mà không chặn quy trình.
Mẫu Polling Chat
Hệ thống chat là bất đồng bộ — con người có thể để lại tin nhắn trong khi bạn
làm việc. Mẫu này cho thấy cách poll tin nhắn mà không chặn quy trình.
Mẫu
[CODE BLOCK]
Poll giữa các lệnh gọi công cụ, không trong vòng lặp chặt.
Tại sao Poll giữa các lệnh gọi công cụ?
- Không chặn — poll trong vòng lặp chặt lãng phí lệnh gọi API
- Không bỏ sót tin nhắn — poll quá ít thường xuyên có nghĩa phản hồi chậm
- Điểm ngọt — poll mỗi 30-60 giây, hoặc sau mỗi lệnh gọi công cụ
Triển khai
Polling cơ bản
[CODE BLOCK]
Mẫu 1: Poll sau mỗi lệnh gọi công cụ
[CODE BLOCK]
Mẫu 2: Polling dựa trên thời gian
[CODE BLOCK]
Mẫu 3: Hướng sự kiện (với webhook)
Cho thông báo thời gian thực, đăng ký webhook:
[CODE BLOCK]
Sau đó trình xử lý webhook của bạn có thể đánh thức agent:
[CODE BLOCK]
Mẫu xử lý tin nhắn
Mẫu: Xác nhận rồi xử lý
[CODE BLOCK]
Mẫu: Xếp hàng cho xử lý hàng loạt
[CODE BLOCK]
Mẫu: Định tuyến ưu tiên
[CODE BLOCK]
Tần suất polling
| Trường hợp | Tần suất |
|----------|-----------|
| Agent tương tác (con người đang chờ) | Mỗi 5-10 giây |
| Agent nền | Mỗi 30-60 giây |
| Xử lý hàng loạt | Mỗi 5 phút |
| Kích hoạt webhook | Không poll — sử dụng webhook |
> [!WARNING]
> Polling quá một lần mỗi 5 giây lãng phí lệnh gọi API. Endpoint
> trả về ngay lập tức nếu có tin nhắn đang chờ, do đó không có lợi ích cho
> polling nhanh hơn.
Chat Multi-Agent
Cho giao tiếp agent-đến-agent:
[CODE BLOCK]
Thực hành tốt nhất
> [!TIP]
> - Poll giữa các lệnh gọi công cụ — không trong vòng lặp chặt
> - Xác nhận ngay lập tức — con người biết bạn đã nhận tin nhắn
> - Xử lý bất đồng bộ — không chặn trên công việc dài
> - Sử dụng webhook cho thời gian thực — polling có độ trễ
> - Không poll quá một lần mỗi 5 giây — lãng phí lệnh gọi API
Vấn đề phổ biến
Tin nhắn bị mất
- tự động đánh dấu tin nhắn là đã đọc
- Nếu bạn không xử lý chúng, chúng đã mất
- Khắc phục: Luôn xử lý tin nhắn trước khi trả về
Trả lời trùng lặp
- Nếu trình xử lý của bạn gặp sự cố, bạn có thể trả lời hai lần
- Khắc phục: Làm trình xử lý idempotent (kiểm tra nếu đã trả lời)
Phản hồi chậm
- Polling mỗi 60 giây có nghĩa là độ trễ tới 60 giây
- Khắc phục: Poll mỗi 10-30 giây, hoặc sử dụng webhook
Bước tiếp theo
- Chat API
- Mẫu Bắt Đầu Phiên
- Khôi phục lỗi
────────────────────────────────────────────────────────────
# Khôi phục lỗi cho Agent
SUMMARY: Cách LLM agent nên xử lý và khôi phục từ lỗi — thử lại, lưu, học.
Khôi phục lỗi cho Agent
Lỗi xảy ra. Mạng thất bại, API trả về 500, Mind Key hết hạn. Hướng dẫn này cho
thấy cách LLM agent nên xử lý lỗi một cách duyên dáng và học từ chúng.
Nguyên tắc xử lý lỗi
1. Thử lại với backoff — lỗi tạm thời thường được giải quyết
2. Lưu lỗi — học từ mẫu
3. Giảm cấp duyên dáng — không làm sập toàn bộ phiên
4. Thông báo con người — cho lỗi bạn không thể giải quyết
Xử lý lỗi HTTP
Thử lại với exponential backoff
[CODE BLOCK]
Xử lý lỗi xác thực
[CODE BLOCK]
Lưu lỗi dưới dạng bộ nhớ
Khi lỗi xảy ra, lưu chúng để các phiên tương lai có thể học:
[CODE BLOCK]
Kịch bản lỗi phổ biến
Kịch bản 1: Mind Key không hợp lệ
[CODE BLOCK]
Kịch bản 2: Lỗi mạng
[CODE BLOCK]
Kịch bản 3: Bị giới hạn tốc độ
[CODE BLOCK]
Kịch bản 4: Lỗi server (5xx)
[CODE BLOCK]
Kịch bản 5: Lệnh gọi công cụ thất bại
[CODE BLOCK]
Mẫu: Circuit Breaker
Cho thất bại lặp lại, tạm thời ngừng thử:
[CODE BLOCK]
Thực hành tốt nhất
> [!TIP]
> - Luôn thử lại lỗi tạm thời — mạng thất bại, server nấc
> - Không thử lại lỗi client (4xx) — chúng sẽ không tự sửa
> - Lưu lỗi dưới dạng bộ nhớ — học từ mẫu
> - Thông báo con người cho lỗi critical — họ cần biết
> - Giảm cấp duyên dáng — công việc một phần tốt hơn sập
> - Sử dụng circuit breaker — không băm một dịch vụ đang thất bại
Bước tiếp theo
- Tham chiếu API Lỗi
- Mẫu Bắt Đầu Phiên
- Kiểm thử tự sửa chữa
────────────────────────────────────────────────────────────
# Chiến lược gắn tag bộ nhớ
SUMMARY: Cách gắn tag bộ nhớ cho tìm kiếm và lọc hiệu quả — hệ thống tag có khả năng mở rộng.
Chiến lược gắn tag bộ nhớ
Tag là bí mật cho thu hồi bộ nhớ có khả năng mở rộng. Hướng dẫn này cho thấy
cách gắn tag bộ nhớ để đúng cái quay lại đúng thời điểm.
Tại sao Tag quan trọng
Không có tag, bạn có tìm kiếm toàn văn phẳng. Với tag, bạn có điều hướng có
cấu trúc:
[CODE BLOCK]
Tag cho phép:
- Lọc nhanh —
- Tìm kiếm phạm vi —
- Nhóm — tìm tất cả bộ nhớ "mistake" cho một dự án
- Tham chiếu chéo — bộ nhớ chia sẻ tag liên quan
Lược đồ tag
Tag dự án
Sử dụng tên dự án làm tag:
[CODE BLOCK]
Tag công nghệ
Sử dụng tên công nghệ:
[CODE BLOCK]
Tag chủ đề
Sử dụng danh mục chủ đề:
[CODE BLOCK]
Tag trạng thái
Sử dụng chỉ báo trạng thái:
[CODE BLOCK]
Tag loại
Sử dụng chỉ báo loại:
[CODE BLOCK]
Quy tắc tag
Quy tắc 1: 2-5 tag mỗi bộ nhớ
Quá ít tag = khả năng khám phá kém. Quá nhiều = nhiễu.
[CODE BLOCK]
Quy tắc 2: Chữ thường, gạch nối
[CODE BLOCK]
Quy tắc 3: Sử dụng từ vựng nhất quán
Thiết lập từ vựng tag và bám sát nó:
[CODE BLOCK]
Quy tắc 4: Gắn tag với ý định tìm kiếm
Hỏi: "Làm thế nào tôi sẽ tìm kiếm bộ nhớ này?"
[CODE BLOCK]
Mẫu
Mẫu 1: Dự án + Chủ đề
[CODE BLOCK]
Tìm: (tất cả bộ nhớ dự án Synapse)
Tìm: (bộ nhớ deployment trong Synapse)
Mẫu 2: Loại + Lĩnh vực
[CODE BLOCK]
Tìm: (tất cả lỗi)
Tìm: (lỗi deployment)
Mẫu 3: Phân cấp
Cho dự án con trong một dự án:
[CODE BLOCK]
Tìm: (tất cả Synapse)
Tìm: (chỉ dự án con docs)
Mẫu 4: Theo dõi trạng thái
[CODE BLOCK]
Trường hợp sử dụng phổ biến
Tìm tất cả quyết định về một dự án
[CODE BLOCK]
Tìm tất cả lỗi trong một lĩnh vực
[CODE BLOCK]
Tìm công việc đang hoạt động
[CODE BLOCK]
Tìm bộ nhớ về một công nghệ
[CODE BLOCK]
Bảo trì tag
Xem xét định kỳ
[CODE BLOCK]
Hợp nhất tag
Nếu bạn có tag không nhất quán ( và ), hợp nhất chúng:
[CODE BLOCK]
Thực hành tốt nhất
> [!TIP]
> - Thiết lập từ vựng sớm — tag nhất quán từ ngày 1
> - Gắn tag với ý định tìm kiếm — làm thế nào bạn sẽ tìm cái này sau?
> - 2-5 tag là điểm ngọt — quá ít hoặc quá nhiều là xấu
> - Chữ thường + gạch nối — không phải
> - Xem xét định kỳ — hợp nhất trùng lặp, xóa không sử dụng
Bước tiếp theo
- Thực hành tốt nhất về bộ nhớ
- Tìm kiếm FTS5
- Quy trình điều khiển bởi tác vụ
────────────────────────────────────────────────────────────
# Mẫu Bắt Đầu Phiên
SUMMARY: Trình tự bắt đầu phiên chuẩn mà mọi LLM agent nên tuân theo.
KEY CONTEXT:
ALWAYS at session start: 1) GET /memory/recall, 2) GET /chat/poll, 3) GET /mind/tasks?status=in_progress
Build system prompt from recall output.
Process unread chat messages before doing new work.
Resume any in_progress tasks before starting new ones.
Store new learnings as they happen — don't wait until session end.
Mẫu Bắt Đầu Phiên
Mỗi phiên LLM agent nên tuân theo trình tự khởi động chuẩn này. Bỏ qua bước dẫn
đến mất ngữ cảnh, bỏ sót tin nhắn và quên tác vụ.
Mẫu
[CODE BLOCK]
Triển khai
Bước 1: Thu hồi tất cả bộ nhớ
> [!CRITICAL]
> Đây là lệnh gọi quan trọng nhất. Không có nó, bạn không có bộ nhớ về các
> phiên trước.
[CODE BLOCK]
Trả về tóm tắt văn bản thuần của tất cả bộ nhớ, sắp xếp theo ưu tiên.
Bước 2: Poll tin nhắn chat chưa đọc
[CODE BLOCK]
Trả về tin nhắn chưa đọc từ con người. Tự động đánh dấu là đã đọc.
Bước 3: Kiểm tra tác vụ đang tiến hành
[CODE BLOCK]
Trả về tác vụ bạn đang làm phiên trước.
Bước 4: Xây dựng ngữ cảnh
Kết hợp ba phản hồi vào system prompt của bạn:
[CODE BLOCK]
Bước 5: Xử lý mục đang chờ
[CODE BLOCK]
Ví dụ hoàn chỉnh
[CODE BLOCK]
Sai lầm phổ biến
> [!WARNING]
> - Bỏ qua thu hồi — bạn bắt đầu không có ngữ cảnh, lặp lại lỗi quá khứ
> - Quên poll chat — tin nhắn của con người không được trả lời
> - Bỏ qua tác vụ đang hoạt động — công việc bị quên giữa thực thi
> - Không lưu gì — phiên không tạo giá trị cố định
Biến thể
Mẫu tối thiểu (LLM ngữ cảnh thấp)
Cho LLM với cửa sổ ngữ cảnh nhỏ, bỏ qua thu hồi đầy đủ:
[CODE BLOCK]
Sau đó tìm các chủ đề cụ thể khi cần:
[CODE BLOCK]
Mẫu tích cực (agent chạy dài)
Cho agent chạy trong nhiều giờ, thêm thu hồi lại định kỳ:
[CODE BLOCK]
Bước tiếp theo
- Chiến lược gắn tag bộ nhớ
- Quy trình điều khiển bởi tác vụ
- Mẫu Polling Chat
────────────────────────────────────────────────────────────
# Quy trình điều khiển bởi tác vụ
SUMMARY: Sử dụng tác vụ Synapse để điều khiển quy trình LLM nhiều bước tồn tại qua các phiên.
Quy trình điều khiển bởi tác vụ
Tác vụ không chỉ là todo — chúng là xương sống của quy trình LLM cố định. Bằng
cách tạo tác vụ cho công việc nhiều bước, bạn đảm bảo tính liên tục qua các phiên
và cung cấp dấu vết kiểm toán cho những gì đã làm.
Tại sao điều khiển bởi tác vụ?
Không có tác vụ:
- LLM bắt đầu mỗi phiên không chắc chắn phải làm gì
- Công việc nhiều bước bị quên giữa thực thi
- Không có bản ghi cái gì đã làm
Với tác vụ:
- LLM tiếp tục tác vụ đang tiến hành ngay lập tức
- Công việc nhiều bước tồn tại qua các phiên
- Dấu vết kiểm toán tích hợp cho tất cả công việc
Mẫu
[CODE BLOCK]
Triển khai
Bước 1: Tạo tác vụ cho công việc nhiều bước
[CODE BLOCK]
Bước 2: Theo dõi tiến độ trong mô tả tác vụ
[CODE BLOCK]
Bước 3: Tiếp tục qua các phiên
[CODE BLOCK]
Bước 4: Hoàn thành và lưu trữ
[CODE BLOCK]
Ví dụ đầy đủ: Quy trình triển khai
[CODE BLOCK]
Hệ thống tác vụ
Cho công việc phức tạp, sử dụng quan hệ tác vụ cha-con:
[CODE BLOCK]
Tìm tác vụ con:
[CODE BLOCK]
Quy trình trạng thái
[CODE BLOCK]
Pending
Tác vụ đã tạo nhưng chưa bắt đầu. Sử dụng cho công việc đã lên kế hoạch.
In Progress
Đang được thực hiện. Cập nhật mô tả với tiến độ.
Done
Hoàn thành thành công. Mô tả nên bao gồm tóm tắt.
Cancelled
Đã bỏ. Mô tả nên bao gồm lý do.
Thực hành tốt nhất
> [!TIP]
> - Tạo tác vụ cho công việc nhiều bước — công việc một bước không cần tác vụ
> - Cập nhật mô tả với tiến độ — cho phép tiếp tục
> - Sử dụng ưu tiên cao cho công việc đang hoạt động — nổi bật trong thu hồi
> - Hoàn thành tác vụ khi xong — không để chúng inprogress
> - Lưu tóm tắt hoàn thành dưới dạng bộ nhớ — tham chiếu dài hạn
Mẫu phổ biến
Mẫu: Quy trình sửa bug
[CODE BLOCK]
Mẫu: Quy trình nghiên cứu
[CODE BLOCK]
Bước tiếp theo
- Mẫu Bắt Đầu Phiên
- Mẫu Polling Chat
- Khôi phục lỗi
## DANH MỤC: CÂU HỎI THƯỜNG GẶP
Câu hỏi thường gặp và các vấn đề phổ biến.
────────────────────────────────────────────────────────────
# FAQ API
SUMMARY: Câu hỏi API phổ biến — xác thực, giới hạn tốc độ, xử lý lỗi, khám phá endpoint.
FAQ API
Các câu hỏi phổ biến về Synapse API.
Làm thế nào để xác thực?
Hai phương thức:
1. Mind Key (cho endpoint dữ liệu):
2. JWT (cho endpoint tài khoản):
Hoặc qua tham số query (giới hạn 60 yêu cầu/phút):
Xem Xác thực.
Sự khác biệt giữa Mind Key và JWT là gì?
- Mind Key: phạm vi tenant, không bao giờ hết hạn, cho dữ liệu memory/chat/tasks
- JWT: phạm vi người dùng, hết hạn sau 7 ngày, cho quản lý tài khoản/mind
Xem Mind Key vs JWT.
Tại sao tôi nhận 401 Unauthorized?
Nguyên nhân phổ biến:
1. Thiếu header
2. Mind Key không hợp lệ (xác minh nó bắt đầu bằng )
3. Sử dụng JWT nơi yêu cầu Mind Key (hoặc ngược lại)
4. Mind Key đã bị thu hồi
Khắc phục: Xác minh token của bạn. Xem Xác thực.
Tại sao tôi nhận 404 Not Found?
Bạn đã dùng sai đường dẫn endpoint. Synapse chỉ có các đường dẫn liệt kê trong
.
Khắc phục: Gọi để xem tất cả đường dẫn hợp lệ. Không đoán.
Tại sao tôi nhận 429 Too Many Requests?
Bạn đang sử dụng xác thực tham số query , bị giới hạn 60/phút.
Khắc phục: Chuyển sang header (không giới hạn tốc độ).
Xem Giới hạn tốc độ.
Làm thế nào để liệt kê tất cả endpoint?
[CODE BLOCK]
Làm thế nào để tìm đúng endpoint?
1. Kiểm tra cho danh sách đọc bằng máy
2. Kiểm tra cho tài liệu API đầy đủ
3. Duyệt cho hệ thống tài liệu
4. Sử dụng cho đặc tả OpenAPI 3.0
Tôi có thể dùng GET thay vì POST không?
Một số endpoint POST có phiên bản GET tương đương cho công cụ chỉ dùng URL:
- ↔
- ↔
- ↔
Kiểm tra cho các biến thể GET khả dụng.
Làm thế nào để xử lý lỗi?
Tất cả lỗi trả về JSON:
[CODE BLOCK]
Xem Lỗi & Xử lý lỗi.
Giới hạn body yêu cầu là bao nhiêu?
10 MB. Cho payload lớn hơn (ví dụ tải tệp lên), sử dụng các endpoint multipart.
API có hỗ trợ CORS không?
Có. Tất cả endpoint trả về:
[CODE BLOCK]
Có SDK không?
Có:
- Node.js:
- MCP:
Xem Tổng quan API để biết chi tiết.
Làm thế nào để phân trang?
Sử dụng và :
[CODE BLOCK]
Giới hạn mặc định: 100. Tối đa: 500.
Tôi có thể lọc bộ nhớ theo danh mục hoặc tag không?
Có:
[CODE BLOCK]
Làm thế nào để tìm kiếm bộ nhớ?
Hai cách:
1. Tìm kiếm từ khóa FTS5:
2. Tìm kiếm ngữ nghĩa:
Xem Tìm kiếm FTS5 và Tìm kiếm ngữ nghĩa.
Làm thế nào để cập nhật bộ nhớ?
POST với cùng + — bộ nhớ hiện có được cập nhật, không
trùng lặp.
[CODE BLOCK]
Làm thế nào để xóa bộ nhớ?
[CODE BLOCK]
Tôi có thể xóa hàng loạt không?
Có:
[CODE BLOCK]
Bước tiếp theo
- Tổng quan API
- Lỗi & Xử lý lỗi
- Xác thực
────────────────────────────────────────────────────────────
# FAQ chung
SUMMARY: Câu hỏi phổ biến về Synapse — nó là gì, hoạt động ra sao, dành cho ai.
FAQ chung
Các câu hỏi phổ biến về Synapse.
Synapse là gì?
Synapse là API bộ nhớ cố định cho LLM agent. Nó cung cấp cho trợ lý AI của bạn
một bộ não vĩnh viễn, có thể truy vấn, tồn tại qua các phiên. Thay vì quên mọi
thứ khi chat đóng, LLM lưu và truy xuất bộ nhớ qua một HTTP API đơn giản.
Tìm hiểu thêm: Synapse là gì?
Synapse dành cho ai?
- Nhà phát triển LLM agent cần trạng thái cố định
- Power user chạy LLM cục bộ với agent tùy chỉnh
- Nhóm xây dựng trợ lý AI với bộ nhớ chung
- Kỹ sư tự động hóa xâu chuỗi lệnh gọi LLM qua các phiên
Synapse có miễn phí không?
Synapse được lưu trữ tại và miễn phí cho sử dụng
cá nhân. Để tự lưu trữ, xem repo.
Synapse khác với ChatGPT Memory như thế nào?
| Tính năng | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| Lưu trữ | Server OpenAI | Server của bạn |
| Truy cập API | Không | Có (REST + MCP) |
| Multi-tenant | Không | Có (mind) |
| Danh mục tùy chỉnh | Không | Có (8 danh mục) |
| Tìm kiếm toàn văn | Hạn chế | FTS5 + ngữ nghĩa |
| Tự lưu trữ | Không | Có |
LLM nào hoạt động với Synapse?
Bất kỳ LLM nào có thể thực hiện lệnh gọi HTTP hoặc sử dụng MCP:
- Claude (Anthropic) — qua MCP hoặc API trực tiếp
- GPT-4 / GPT-3.5 (OpenAI) — qua function calling + API
- Gemini (Google) — qua function calling + API
- Llama / Mistral (cục bộ) — qua tích hợp tùy chỉnh
- Bất kỳ LLM nào qua Synapse MCP server
Tôi có cần tự lưu trữ Synapse không?
Không. Phiên bản được lưu trữ tại có sẵn cho sử
dụng công khai. Tự lưu trữ là tùy chọn (cho quyền riêng tư, tùy chỉnh hoặc môi
trường air-gapped).
Tôi có thể lưu bao nhiêu dữ liệu?
Không có giới hạn cứng trên phiên bản được lưu trữ. Sử dụng điển hình:
- 100-1000 bộ nhớ mỗi mind
- 1-10 KB mỗi bộ nhớ (trường content)
- Tổng: 10 MB mỗi mind
Cho quy mô lớn hơn, tự lưu trữ.
Dữ liệu của tôi có riêng tư không?
Có. Mỗi mind được cách ly (xem Multi-Tenancy).
Người dùng khác không thể thấy dữ liệu của bạn. Nhà cung cấp dịch vụ lưu trữ
(Schäfer Services) có quyền truy cập nhưng không xem dữ liệu người dùng.
Cho quyền riêng tư tối đa, tự lưu trữ.
Tôi có thể xuất dữ liệu không?
Có. Sử dụng để xuất tất cả bộ nhớ dưới dạng JSON. Xem
Sao lưu & Khôi phục.
Điều gì xảy ra nếu tôi mất Mind Key?
Mind Key chỉ hiển thị một lần khi tạo. Nếu mất:
1. Đăng nhập với email/mật khẩu để lấy JWT
2. Tạo mind mới qua
3. Lưu Mind Key mới
4. (Tùy chọn) Xóa mind cũ qua
Bạn không thể khôi phục bộ nhớ từ một mind mà key đã mất.
Nhiều LLM agent có thể chia sẻ một mind không?
Có. Tất cả agent sử dụng cùng Mind Key chia sẻ dữ liệu mind đó. Cho công việc
điều phối multi-agent, xem Điều phối Multi-Agent.
Synapse có hoạt động ngoại tuyến không?
Không, Synapse yêu cầu kết nối internet đến server (hoặc được lưu trữ hoặc tự
lưu trữ). Cho LLM ngoại tuyến, chạy Synapse cục bộ.
Tìm kiếm bộ nhớ nhanh như thế nào?
- Tìm kiếm từ khóa FTS5: < 10ms cho 1000 bộ nhớ
- Tìm kiếm ngữ nghĩa: 50-100ms cho 1000 bộ nhớ
- Thu hồi đầy đủ: < 50ms cho 1000 bộ nhớ
Xem Tìm kiếm FTS5 để biết chi tiết.
Tôi có thể sử dụng Synapse mà không có LLM không?
Có. Synapse là API bộ nhớ chung. Bạn có thể sử dụng nó từ bất kỳ ứng dụng nào
được lợi từ lưu trữ key-value cố định, có thể tìm kiếm với danh mục và tag.
Bước tiếp theo
- Synapse là gì?
- Quick Start
- FAQ API
────────────────────────────────────────────────────────────
# FAQ MCP
SUMMARY: Câu hỏi phổ biến về tích hợp MCP — công cụ, transport, khắc phục sự cố.
FAQ MCP
Các câu hỏi phổ biến về Synapse MCP server.
MCP là gì?
MCP (Model Context Protocol) là tiêu chuẩn mở của Anthropic cho tích hợp
LLM-công cụ. Thay vì dán tài liệu API vào prompt, bạn đăng ký công cụ với một
MCP server, và LLM gọi chúng như các hàm native.
Xem MCP là gì?.
Synapse MCP cung cấp bao nhiêu công cụ?
79 công cụ trong 12 danh mục: memory, chat, scheduler, tasks, scripts,
computers, push, user, utility, visualization, sharing, webhooks, browser.
Xem MCP là gì? cho danh sách đầy đủ.
Client MCP nào được hỗ trợ?
- Claude Desktop (macOS, Windows)
- Claude Code (terminal)
- Cursor (IDE)
- Continue.dev (VS Code, JetBrains)
- Cline (VS Code)
- Bất kỳ client tương thích MCP nào
Xem Thiết lập Claude Desktop cho ví dụ cấu hình.
Transport nào được hỗ trợ?
1. stdio (cục bộ, khuyến nghị cho desktop)
2. HTTP/SSE (từ xa, multi-tenant)
3. WebSocket (di động, khối lượng lớn)
Làm thế nào để cấu hình Claude Desktop?
Chỉnh sửa :
[CODE BLOCK]
Xem Thiết lập Claude Desktop.
Tại sao công cụ không xuất hiện trong Claude Desktop?
1. Khởi động lại Claude Desktop hoàn toàn (Cmd+Q trên macOS)
2. Kiểm tra tệp cấu hình là JSON hợp lệ
3. Xác minh Node.js 18+ đã cài đặt
4. Kiểm tra nhật ký MCP:
Xem Khắc phục sự cố MCP.
Làm thế nào để sử dụng một mind khác?
Thay đổi trong cấu hình MCP và khởi động lại client.
Cho nhiều mind, chạy nhiều thể hiện MCP server với các Mind Key khác nhau.
Tôi có thể giới hạn công cụ nào được lộ không?
Có, sử dụng Tool Profile:
- : 8 công cụ tổng hợp (500 token)
- : 25 công cụ (2.500 token)
- : 119 công cụ (8.250 token, mặc định)
Đặt qua biến môi trường hoặc header .
Làm thế nào để gỡ lỗi vấn đề MCP?
1. Chạy MCP server thủ công:
2. Kiểm tra nhật ký client (khác nhau tùy client)
3. Xác minh Mind Key hoạt động:
4. Kiểm tra sức khỏe Synapse:
Xem Khắc phục sự cố MCP.
MCP server có miễn phí không?
Có. Gói npm là mã nguồn mở. MCP server được lưu trữ tại
miễn phí cho sử dụng công khai.
Tôi có thể tự lưu trữ MCP server không?
Có:
[CODE BLOCK]
MCP khác với lệnh gọi API trực tiếp như thế nào?
| Khía cạnh | API trực tiếp | MCP |
|--------|-----------|-----|
| LLM cần biết | URL, header, xác thực | Chỉ tên công cụ |
| Xử lý xác thực | Thủ công | Tự động (biến môi trường) |
| Khám phá công cụ | Đọc /endpoints | Tự động qua giao thức MCP |
| Xử lý lỗi | Thủ công | Chuẩn hóa |
| Tốt nhất cho | Tích hợp tùy chỉnh | LLM agent |
Tôi có thể xây dựng client MCP riêng không?
Có. Sử dụng SDK MCP chính thức:
- TypeScript:
- Python:
Xem Client MCP tùy chỉnh.
Làm thế nào để báo cáo bug MCP?
Mở issue:
Bao gồm:
- Phiên bản MCP server
- Tên và phiên bản client
- Hệ điều hành
- Nhật ký liên quan
- Các bước tái hiện
Bước tiếp theo
- MCP là gì?
- Thiết lập Claude Desktop
- Khắc phục sự cố MCP
────────────────────────────────────────────────────────────
# FAQ khắc phục sự cố
SUMMARY: Giải pháp cho các vấn đề Synapse phổ biến — xác thực, mạng, dữ liệu, triển khai.
FAQ khắc phục sự cố
Giải pháp cho các vấn đề Synapse phổ biến.
Tôi không thể đăng nhập
Triệu chứng
- trả về 401
- "Invalid email or password"
Giải pháp
1. Xác minh email chính xác — phân biệt chữ hoa chữ thường
2. Kiểm tra mật khẩu — tối thiểu 6 ký tự
3. Đăng ký trước nếu bạn không có tài khoản:
4. Đặt lại mật khẩu (nếu SMTP được cấu hình) qua giao diện web
Tôi mất Mind Key
Triệu chứng
- Không thể truy cập bộ nhớ
- Mind Key đã bị xóa/mất
Giải pháp
Mind Key không thể khôi phục. Bạn phải:
1. Đăng nhập để lấy JWT:
2. Liệt kê mind: (với JWT)
3. Tạo mind mới:
4. Lưu Mind Key mới
5. (Tùy chọn) Xóa mind cũ:
Dữ liệu trong mind cũ bị mất trừ khi bạn có thể tìm thấy Mind Key.
Lệnh gọi API trả về 401
Triệu chứng
- Tất cả lệnh gọi API trả về 401 Unauthorized
- "Mind Key fehlt oder ungültig"
Giải pháp
1. Xác minh định dạng header:
2. Kiểm tra Mind Key bắt đầu bằng (không phải là JWT)
3. Kiểm tra trực tiếp:
[CODE BLOCK]
4. Mind Key có thể bị thu hồi — tạo mind mới
Xem Xác thực.
Lệnh gọi API trả về 404
Triệu chứng
- 404 Not Found
- "Route not found"
Giải pháp
> [!CRITICAL]
> Không đoán đường dẫn endpoint. Chỉ đường dẫn trong mới tồn tại.
1. Kiểm tra endpoint hợp lệ:
2. So sánh URL chính xác — phân biệt chữ hoa chữ thường, không có dấu gạch chéo cuối
3. Kiểm tra phương thức HTTP — khác với
Lệnh gọi API trả về 429
Triệu chứng
- 429 Too Many Requests
- "Rate limit exceeded"
Giải pháp
1. Chuyển sang xác thực header (không giới hạn tốc độ):
[CODE BLOCK]
2. Đợi giây nếu bạn phải dùng
Xem Giới hạn tốc độ.
Tìm kiếm bộ nhớ không trả về kết quả
Triệu chứng
- trả về rỗng
- Biết bộ nhớ tồn tại
Giải pháp
1. Xác minh bộ nhớ tồn tại:
2. Kiểm tra cú pháp tìm kiếm — FTS5 có cú pháp cụ thể
3. Thử truy vấn đơn giản hơn — thay vì
4. Sử dụng tìm kiếm ngữ nghĩa cho truy vấn khái niệm:
Xem Tìm kiếm FTS5.
Bộ nhớ không tồn tại
Triệu chứng
- POST /memory trả về thành công
- GET /memory/recall không hiển thị chúng
Giải pháp
1. Xác minh cùng Mind Key — key khác = mind khác
2. Kiểm tra phản hồi — POST trả về
3. Thử GET /memory (danh sách JSON) thay vì /memory/recall (văn bản)
4. Kiểm tra bộ lọc — hoặc có thể ẩn chúng
Công cụ không xuất hiện trong Claude Desktop
Triệu chứng
- Claude Desktop hiển thị 0 công cụ
- Không có biểu tượng 🔌
Giải pháp
1. Khởi động lại Claude Desktop hoàn toàn (Cmd+Q)
2. Xác minh tệp cấu hình là JSON hợp lệ
3. Kiểm tra Node.js 18+ đã cài đặt
4. Chạy MCP thủ công:
5. Kiểm tra nhật ký:
Xem Khắc phục sự cố MCP.
Synapse ngoại tuyến
Triệu chứng
- Không thể truy cập synapse.schaefer.zone
- curl hết thời gian chờ
Giải pháp
1. Kiểm tra internet của bạn — thử một trang khác
2. Kiểm tra sức khỏe Synapse:
3. Đợi — có thể là sự cố tạm thời hoặc triển khai
4. Kiểm tra trang trạng thái (nếu có)
Cho tự lưu trữ: kiểm tra trạng thái Docker container, kết nối database.
Lỗi database
Triệu chứng
- 500 Internal Server Error
- "Database connection failed"
Giải pháp
Cho tự lưu trữ:
1. Kiểm tra PostgreSQL đang chạy:
2. Kiểm tra DATABASEURL trong env
3. Kiểm tra migration:
4. Kiểm tra không gian đĩa:
Cho phiên bản được lưu trữ: báo cáo cho hỗ trợ.
Webhook không kích hoạt
Triệu chứng
- Đã đăng ký webhook nhưng không nhận callback
- Không có POST đến URL của bạn
Giải pháp
1. Xác minh URL có thể truy cập:
2. Kiểm tra bộ lọc sự kiện — khớp tất cả sự kiện memory
3. Kiểm tra webhook:
4. Kiểm tra webhook được bật:
5. Xác minh SSL — Synapse yêu cầu HTTPS hợp lệ cho URL webhook
Xem Webhooks API.
Cron job không chạy
Triệu chứng
- Đã tạo cron job nhưng không kích hoạt
- không cập nhật
Giải pháp
1. Kiểm tra cú pháp lịch — phải là cron 5 trường HOẶC số nguyên giây hợp lệ
2. Xác minh endpoint được phép — phải là http(s), không IP riêng
3. Kiểm tra job được bật:
4. Đợi thời gian lên lịch tiếp theo — cron không tức thời
Xem Cron & Scheduler.
Cần thêm trợ giúp?
1. Kiểm tra tài liệu hiện có:
2. Tìm kiếm tài liệu:
3. Mở issue:
4. Liên hệ: xem trang
Bước tiếp theo
- Lỗi & Xử lý lỗi
- FAQ API
- Khắc phục sự cố MCP