# SYNAPSE 文档 — 完整参考
# 生成时间：2026-07-18T06:05:08.180Z
# 文章总数：47
本文档包含完整的 Synapse API 文档。
Base URL: https://synapse.schaefer.zone
Language: zh
========================================================================
## 分类：快速入门
开始使用 Synapse 所需的一切。
────────────────────────────────────────────────────────────
# 认证与 Mind Key
SUMMARY: Synapse 认证机制：Agent 用 Mind Key，人类用 JWT，只能用 URL 的工具用 ?key=。
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.
认证与 Mind Key
Synapse 使用两种认证方法，各自针对不同用例优化。理解它们的区别对构建可靠集成至关重要。
两种认证方法
| 方法 | 用例 | 限速 | 过期 |
|--------|----------|------------|--------|
| Mind Key | LLM Agent、自动化工具 | 无（header）/ 60 次/分钟（query） | 永不过期 |
| JWT | 人类界面 UI、账户操作 | 无 | 7 天 |
Mind Key（用于 Agent）
Mind Key 是租户范围的 API 令牌。它对单个 Mind 的数据（记忆、任务、聊天、脚本等）进行认证。适用于：
- 调用 API 的 LLM Agent
- 后台自动化脚本
- MCP Server 配置
- 任何长期集成
头部认证（推荐）
[CODE BLOCK]
查询参数（用于只能用 URL 的工具）
[CODE BLOCK]
> [!WARNING]
> 查询参数被限速为每分钟 60 次请求。Bearer 头无限制。客户端支持自定义请求头时，请始终使用请求头。
创建 Mind Key
[CODE BLOCK]
响应包含 — 请立即保存，它只显示一次。
列出你的 Mind
[CODE BLOCK]
删除 Mind（不可逆！）
[CODE BLOCK]
JWT（用于人类）
JWT 对用户账户进行认证，而非特定 Mind。用于：
- 账户注册与登录
- 创建/列出/删除 Mind
- 与其他用户共享 Mind
- Web Push 订阅管理
注册
[CODE BLOCK]
返回：
登录
[CODE BLOCK]
返回：
JWT 过期
JWT 在 7 天后过期。过期后再次调用 即可获取新 JWT。Mind Key 永不过期，因此现有 Agent 集成可继续工作。
安全最佳实践
> [!CRITICAL]
> - 绝不把 Mind Key 提交到 git。 使用环境变量。
> - 绝不在日志中记录 Mind Key。 在日志中遮蔽（）。
> - 怀疑泄露时轮换 key（删除 Mind、创建新 Mind）。
> - 每个项目用一个 Mind，以缩小 key 泄露的爆炸半径。
环境变量模式
[CODE BLOCK]
[CODE BLOCK]
MCP Server 配置
[CODE BLOCK]
多 Mind 模式
每个用户可有多个 Mind。常见模式：
| Mind 名称 | 用途 |
|-----------|---------|
| | 工作相关记忆 |
| | 个人偏好、家庭 |
| | 特定项目上下文 |
| | 学习进度 |
| | 通用回退 |
在不同 LLM 会话中使用不同 Mind Key 即可隔离上下文。
限速
| 认证方式 | 限制 | 范围 |
|-------------|-------|-------|
| Mind Key（header） | 无 | 每个 Mind |
| Mind Key（?key=） | 60 次/分钟 | 每个 IP |
| JWT（header） | 无 | 每个用户 |
| 公共端点 | 无 | 全局 |
如适用，响应会包含限速头（、、）。
下一步
- Mind Key 与 JWT — 何时用哪个
- Memory API — 用 Mind Key 能做什么
- User API — 用 JWT 进行账户管理
────────────────────────────────────────────────────────────
# Mind Key 与 JWT — 何时用哪个？
SUMMARY: 决策指南：Agent 数据访问用 Mind Key，账户管理用 JWT。
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 与 JWT — 何时用哪个？
Synapse 有两种认证令牌。选错会导致 401 错误。本指南给你一个清晰的决策框架。
快速决策表
| 你想... | 使用 |
|----------------|-----|
| 存储/回放记忆 | Mind Key |
| 发送/轮询聊天消息 | Mind Key |
| 管理任务 | Mind Key |
| 存储脚本 | Mind Key |
| 注册 Webhook | Mind Key |
| 控制计算机 | Mind Key（用户侧）/ Computer Token（Agent 侧） |
| 注册用户账户 | 无（公共） |
| 登录 | 无（公共） |
| 创建/列出/删除 Mind | JWT |
| 与其他用户共享 Mind | JWT |
| 订阅 Web Push 通知 | JWT |
| 查看审计日志 | Mind Key |
简单规则
> [!TIP]
> 如果涉及单个 Mind 的数据 → Mind Key。
> 如果管理账户或 Mind 元数据 → JWT。
Mind Key — 数据访问令牌
Mind Key 授予访问一个 Mind 的数据的权限。它是永不过期（除非删除该 Mind）的长生命周期令牌。非常适合：
- LLM Agent 跨会话持久化记忆
- 后台 Cron 任务
- MCP Server 配置
- Webhook 集成
- 移动应用读取记忆
Mind Key 能做什么
- — 读取该 Mind 中的所有记忆
- — 存储/更新记忆
- — 读取聊天消息
- — 发送聊天消息
- — 列出任务
- — 创建任务
- — 存储脚本
- — 注册 Webhook
- — 排队计算机命令
Mind Key 不能做什么
- 创建/列出/删除 Mind（需 JWT）
- 与其他用户共享 Mind（需 JWT）
- 查看用户账户信息（需 JWT）
- 订阅 Web Push（需 JWT）
JWT — 账户管理令牌
JWT 对用户账户进行认证。它在 7 天后过期，用于跨多个 Mind 或涉及其他用户的账户级操作。
JWT 能做什么
- — 创建新 Mind（返回新 Mind Key）
- — 列出该用户的所有 Mind
- — 删除 Mind
- — 与其他用户共享 Mind
- — 订阅 Web Push 通知
- — 列出 Mind 共享
JWT 不能做什么
- 读写记忆（需 Mind Key）
- 发送聊天消息（需 Mind Key）
- 管理任务（需 Mind Key）
- 注册 Webhook（需 Mind Key）
特殊情况：Computer Token
端点（Agent 侧，供 screen-remote-agent 使用）使用第三种令牌类型：Computer Token。该令牌由 在兑换安装码时返回，专属于某一台已注册的计算机。
| 端点 | 认证 |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key 或 JWT |
| | Mind Key 或 JWT |
常见模式
模式 1：单个 LLM Agent
1. 注册一次 → 获取 JWT
2. 创建一个 Mind → 获取 Mind Key
3. LLM 用 Mind Key 完成所有操作
模式 2：多项目 Agent
1. 注册一次 → 获取 JWT
2. 创建多个 Mind（work、personal、project-x） → 获取多个 Mind Key
3. LLM 根据上下文加载不同 Mind Key
模式 3：团队共享
1. 用户 A 创建 Mind → 获取 Mind Key A
2. 用户 A 通过 JWT 共享给用户 B（）
3. 用户 B 现在可通过自己的 JWT 访问
4. 对于 LLM 访问，用户 B 需创建自己的 Mind Key（或使用 A 的）
模式 4：MCP Server
MCP Server 始终使用 Mind Key（通过 环境变量设置）。一个 MCP Server 实例 = 一个 Mind。如需访问多个 Mind，请运行多个 MCP 实例或在客户端实现 Mind 切换。
令牌格式速查
| 令牌 | 格式 | 示例 |
|-------|--------|---------|
| Mind Key | + 36 字符 | |
| JWT | + base64 | |
| Computer Token | + 36 字符 | |
下一步
- Authentication — 完整认证指南
- User 与 Minds API — 由 JWT 保护的端点
- Memory API — 由 Mind Key 保护的端点
────────────────────────────────────────────────────────────
# LLM Agent 快速开始
SUMMARY: 3 次 API 调用：回放所有记忆、存储新记忆、搜索。LLM 的必备工作流。
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
LLM Agent 快速开始
你在会话之间会丢失所有记忆。Synapse 是你的外脑。本指南展示每个 LLM Agent 必须知道的三个核心 API 调用。
> [!CRITICAL]
> 在每次会话开始时调用 。
> 不调用它，你就没有关于用户是谁、你承诺过什么、上次在做什么的记忆。
第 1 步：回放所有记忆（始终优先）
[CODE BLOCK]
返回所有已存储记忆的结构化纯文本摘要。解析它来重建你对用户、其项目及过往交互的认知模型。
示例响应：
[CODE BLOCK]
第 2 步：存储新记忆
当你学到值得记住的内容时：
[CODE BLOCK]
分类： 、、、、、、、
优先级： 、、、
> [!TIP]
> 始终带上 字段 — 记忆的简短标识符。这样后续可通过相同 key 再次 POST 来更新该记忆。
第 3 步：搜索特定记忆
[CODE BLOCK]
> [!TIP]
> FTS5 语法：多个词 = AND 搜索。短语用引号：。
> 前缀搜索：。布尔：。
开放工具（无认证头）
如果你的工具只能打开 URL（无自定义头），使用 参数：
[CODE BLOCK]
> [!WARNING]
> 被限速为 60 次/分钟。Bearer 头无限制。请尽可能使用 Bearer 头。
完整会话工作流
1. 会话开始： — 加载所有记忆
2. 工作期间： — 查找具体事实
3. 获得新信息： — 存储它（带上 category、key、tags、priority）
4. 定期： — 检查人类消息
5. 会话结束：通过 存储任何最终学习内容
常见模式
更新已有记忆
用相同的 和 发起 — 已存在的记忆会被更新，不会重复。
存储项目状态
[CODE BLOCK]
记录错误（避免重蹈覆辙）
[CODE BLOCK]
检查人类消息
[CODE BLOCK]
返回来自人类的未读消息。用以下方式回复：
[CODE BLOCK]
下一步
- Authentication — Mind Key 与 JWT
- Memory API 参考 — 全部 22 个记忆端点
- Chat API — 与人类异步通信
- LLM Cookbook — 实用模式
────────────────────────────────────────────────────────────
# 快速开始（人类）
SUMMARY: 注册账户、创建你的第一个 Mind、存储第一条记忆 — 全部 5 分钟完成。
快速开始（人类）
本指南带你完成获取 Synapse 账户、第一个 Mind Key 并存储第一条记忆。总耗时：约 5 分钟。
第 1 步：注册账户
调用 Synapse API 创建账户：
[CODE BLOCK]
响应：
[CODE BLOCK]
> [!TIP]
> 把 JWT 安全保存 — 创建 Mind 时会用到。JWT 7 天后过期；用同一端点重新登录即可刷新。
第 2 步：创建你的第一个 Mind
“Mind” 是一个隔离的记忆范围。大多数用户从一个 Mind 开始，但你可以有多个（例如 “work”、“personal”、“project-x”）。每个 Mind 都有自己唯一的 Mind Key。
[CODE BLOCK]
响应：
[CODE BLOCK]
> [!CRITICAL]
> 立即保存 。 它只显示一次，之后无法找回。如果丢失，你需要创建新 Mind。
第 3 步：存储第一条记忆
现在用 Mind Key 存储一条记忆：
[CODE BLOCK]
响应：
[CODE BLOCK]
第 4 步：回放所有记忆
检索你存储的全部内容：
[CODE BLOCK]
响应（纯文本，为 LLM 消费优化）：
[CODE BLOCK]
第 5 步：搜索记忆
按关键词查找特定记忆：
[CODE BLOCK]
第 6 步：连接你的 LLM
让 LLM 访问 Synapse 最简单的方式是通过 MCP：
- Claude Desktop 配置 — 2 分钟配置
- Claude Code 配置 — 终端集成
- Cursor 配置 — IDE 集成
配置完成后，你的 LLM 会在每次会话开始时自动调用 ，并通过 持久化新事实。
记忆分类
Synapse 支持 8 种分类 — 选择最具体的那一种：
| 分类 | 用例 |
|----------|----------|
| | 用户名、角色、联系方式 |
| | 喜好、厌恶、工作风格 |
| | 可验证的事实（项目细节、日期） |
| | 项目状态、里程碑、待办 |
| | 用户擅长的事情 |
| | 过去犯的错 — 避免重蹈覆辙 |
| | 与会话相关的上下文 |
| | 其他备注 |
优先级
- — 知道就好
- — 默认
- — 重要
- — 绝不能忘（用户身份、法律信息）
下一步
- Authentication 深入
- Mind Key 与 JWT
- Memory API 参考
- MCP 集成
────────────────────────────────────────────────────────────
# Synapse 是什么？
SUMMARY: Synapse 是为 LLM Agent 提供的持久化记忆 API — 让你的 AI 跨会话不再遗忘。
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 是什么？
Synapse 是为 LLM Agent 提供的持久化记忆 API。它解决了所有基于聊天的 LLM 的根本问题：会话之间 Agent 会遗忘一切。Synapse 为你的 AI 提供一个永久的、可查询的大脑，跨对话、跨天、跨不同 LLM 提供商都保留。
> [!CRITICAL]
> 如果你是一名正在阅读本文的 LLM Agent：在每次会话开始时调用 。不调用它，你就没有过往交互的记忆、不知道用户是谁，也没有正在进行项目的上下文。
Synapse 解决的问题
每个现代 LLM（Claude、GPT、Gemini、Llama）都有同样的架构限制：会话上下文窗口有限，会话一结束所有状态都会丢失。这意味着你的 AI 助手：
- 在聊天之间遗忘你的姓名、偏好和正在进行的项目
- 无法跨会话从过往错误中学习
- 长期工作没有连续性
- 每次都重新问同样的澄清问题
Synapse 通过提供简单的 HTTP API 修复了这个问题，LLM 可以在其中存储和检索结构化记忆。这些记忆持久化在服务器上，被索引且可搜索，因此任何未来的会话都能回放它们。
关键特性
- 持久化记忆存储 — 事实、偏好、项目、错误、技能
- 全文搜索（FTS5） — 毫秒级按关键词查找任意记忆
- 语义搜索 — 基于向量嵌入的相似度搜索，适合概念性查询
- 多租户 — 每个用户拥有隔离的“Mind”（一个用户，多个项目）
- 异步聊天 — 人类可在 Agent 工作时给它留言
- 任务与调度 — 内置任务管理器与 Cron 调度器
- MCP 集成 — 通过 Model Context Protocol 暴露 79 个工具，供 Claude、Cursor、Continue 使用
- 浏览器与计算机控制 — 远程自动化工具
- Webhook — 记忆/聊天/任务变化时获得 HTTP 回调
工作原理
[CODE BLOCK]
1. LLM 在会话开始时调用
2. Synapse 返回所有已存储记忆的结构化文本摘要
3. LLM 工作，周期性调用 存储新事实
4. 当用户提问时，LLM 可调用
5. 会话结束时，重要的新上下文被持久化以供下次会话使用
面向谁？
- 需要持久状态的 LLM Agent 开发者
- 运行本地 LLM（Ollama、LM Studio）与自定义 Agent 的 重度用户
- 构建需要共享记忆 AI 助手的 团队
- 跨会话串联 LLM 调用的 自动化工程师
快速对比
| 特性 | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| 存储位置 | OpenAI 服务器 | 你的服务器 |
| API 访问 | 否（封闭） | 是（REST + MCP） |
| 多租户 | 否 | 是（Mind） |
| 自定义分类 | 否 | 是（8 种分类） |
| 搜索 | 有限 | FTS5 + 语义 |
| 可自托管 | 否 | 是（Docker） |
下一步
- 人类快速开始 — 5 分钟拿到 Mind Key
- LLM 快速开始 — 首次 API 调用
- Authentication — Mind Key 与 JWT
- 架构概览 — Synapse 是如何构建的
## 分类：API 参考
所有 API 端点的完整参考。
────────────────────────────────────────────────────────────
# Browser 代理
SUMMARY: 浏览器自动化服务 — 独立 Docker 容器，端口 13000，用于无头浏览器控制。
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 代理
Browser 代理是一个独立的 Docker 服务，通过 Playwright 提供无头浏览器自动化。它不直接属于 Synapse API 的一部分 — Synapse 端点不包含 路径。
架构
[CODE BLOCK]
访问方式
方式 1：通过 Synapse MCP Server（推荐）
Synapse MCP Server 将浏览器工具作为 MCP 工具暴露。请在需要 LLM 驱动的浏览器自动化时使用：
[CODE BLOCK]
可用的 MCP 浏览器工具：
- — 打开新的浏览器标签页
- — 导航到指定 URL
- — 点击元素
- — 在输入框中输入文本
- — 截屏
- — 关闭标签页
- （更多请见 MCP 集成）
方式 2：直接访问 Browser 代理
对于非 MCP 集成，可直接连接 browser-proxy 服务：
[CODE BLOCK]
常见用例
网页抓取
[CODE BLOCK]
表单自动化
[CODE BLOCK]
截屏
[CODE BLOCK]
相关服务
| 服务 | 端口 | 用途 |
|---------|------|---------|
| Synapse API | 12800 | 记忆、聊天、任务 |
| Synapse MCP | 13100 | MCP Server（79 个工具） |
| Browser Proxy | 13000 | 无头浏览器自动化 |
| SSH Proxy | 12900 | 远程机器的 SSH 访问 |
下一步
- MCP 集成 — 如何通过 MCP 使用浏览器工具
- Computer Control API — 用于在已注册机器上进行 GUI 自动化
────────────────────────────────────────────────────────────
# Chat API
SUMMARY: 人类与 LLM Agent 之间的异步聊天 — 轮询、回复、历史记录、未读数量、文件上传。
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 支持人类与 LLM Agent 之间的异步消息通信。与同步聊天（ChatGPT 风格）不同，人类可以在 Agent 工作期间留言 — Agent 在工具调用之间轮询消息。
工作原理
[CODE BLOCK]
1. 人类通过 Web UI 发送消息（使用 JWT）
2. 消息被存储，并标记为未读
3. Agent 在工具调用之间轮询
4. 轮询返回所有未读消息并将其标记为已读
5. Agent 处理消息，可选择通过 回复
端点
GET /chat/poll
轮询来自人类的新消息。返回未读消息并将其标记为已读。请在工具调用之间使用此接口。
[CODE BLOCK]
响应：
[CODE BLOCK]
POST /chat/reply
以 Agent 身份发送消息。
[CODE BLOCK]
POST /chat/send
以人类身份发送消息（需要 JWT，而非 Mind Key）。
[CODE BLOCK]
GET /chat/history
获取最近的聊天历史（双方角色）。
[CODE BLOCK]
GET /chat/unread
获取未读消息数量。
[CODE BLOCK]
GET /chat/status
获取聊天会话状态（最近消息时间戳、未读数量）。
[CODE BLOCK]
POST /chat/upload
为特定消息上传文件附件（multipart 表单）。
[CODE BLOCK]
GET /chat/files/:messageid
列出某条消息的文件附件。
[CODE BLOCK]
GET /chat/file/:fileid
下载文件附件。
[CODE BLOCK]
轮询模式
> [!TIP]
> 在工具调用之间每 30-60 秒轮询一次。不要更频繁地轮询 — 既浪费 API 配额，也带不来任何收益。
[CODE BLOCK]
下一步
- Tasks API
- Chat 轮询模式
────────────────────────────────────────────────────────────
# Computer Control API
SUMMARY: 远程控制已注册的计算机 — 排队命令、截屏、在远程机器上运行脚本。
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 让你能够远程控制已注册的计算机。目标机器上会运行一个小型 Agent（），轮询命令、执行命令并回传结果。这使 LLM 驱动的 GUI 自动化成为可能。
架构
[CODE BLOCK]
用户侧端点（Mind Key 或 JWT）
GET /computers/list
列出所有已注册的计算机。
[CODE BLOCK]
GET /computers/:id
获取单台计算机的详情。
[CODE BLOCK]
POST /computers/install-code
为注册新计算机生成一个安装码。
[CODE BLOCK]
响应：
POST /computers/:id/commands
为远程 Agent 排队一条待执行的命令。
[CODE BLOCK]
响应：
GET /computers/:id/command（通过查询参数）
通过 GET 方式排队命令（用于简单场景）。
[CODE BLOCK]
GET /computers/:id/commands
列出某台计算机最近的命令。
[CODE BLOCK]
GET /computers/:id/commands/:cid
获取某条具体命令的状态与结果。
[CODE BLOCK]
GET /computers/:id/screenshot
一次性操作：排队截图命令并等待最多 30 秒拿结果。
[CODE BLOCK]
POST /computers/:id/disable
禁用某台计算机（吊销其令牌，保留记录以备审计）。
[CODE BLOCK]
DELETE /computers/:id
永久删除某台计算机。
[CODE BLOCK]
Agent 侧端点（Computer Token）
以下端点由运行在目标机器上的 使用。它们使用 Computer Token（由 返回），而不是 Mind Key。
POST /computers/register
兑换安装码并获取 Computer Token。
[CODE BLOCK]
响应：
> [!CRITICAL]
> 请妥善保存 — 它只显示一次，且所有 Agent 侧端点都需要它。
GET /computers/me/poll
长轮询新命令。Agent 会在循环中调用此端点。
[CODE BLOCK]
如果有待执行命令，则立即返回；否则等待 秒后返回。
POST /computers/me/commands/:cid/result
提交某条命令的执行结果。
[CODE BLOCK]
命令类型
| 类型 | Payload | 说明 |
|------|---------|-------------|
| | | 截屏为 PNG（base64） |
| | | 在指定坐标点击 |
| | | 将鼠标移动到指定坐标 |
| | | 在光标处输入文本 |
| | | 按下组合键 |
| | | 滚动滚轮 |
| | | 拖拽 |
常见模式：LLM 驱动的 GUI 自动化
[CODE BLOCK]
下一步
- Browser 代理 — 用于浏览器自动化的独立服务
- 自托管 Agent 指南
────────────────────────────────────────────────────────────
# Cron 与调度器
SUMMARY: 调度周期性 API 调用 — 按计划触发的 cron 任务，适合周期性同步与提醒。
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 与调度器
Cron API 让你能够调度周期性 HTTP 调用 Synapse 端点（或外部 HTTPS 端点）。非常适合周期性同步、提醒和运维任务。
端点
POST /cron
创建一个定时任务。
[CODE BLOCK]
响应：
[CODE BLOCK]
GET /cron
列出所有定时任务。
[CODE BLOCK]
DELETE /cron/:id
删除一个定时任务。
[CODE BLOCK]
PUT /cron/:id/toggle
在不删除任务的情况下启用或禁用它。
[CODE BLOCK]
调度语法
标准 cron（5 字段）
[CODE BLOCK]
示例：
| 调度表达式 | 含义 |
|----------|---------|
| | 每小时 |
| | 每 15 分钟 |
| | 工作日早上 9 点 |
| | 每周日午夜 |
| | 每月 1 日午夜 |
整数间隔（秒）
对于简单间隔，可直接传整数：
[CODE BLOCK]
端点限制
> [!WARNING]
> 端点必须是 或 URL，并指向：
> - 同一 Synapse 实例（例如 ）
> - 公共 HTTPS URL（不允许私有 IP、localhost、元数据 IP）
这可以防止 SSRF 攻击 — 否则被攻破的 Mind 可能会调度请求访问内部服务。
常见模式
每小时调用一次记忆回放（供 LLM Agent 使用）
[CODE BLOCK]
每日备份
[CODE BLOCK]
周期性聊天轮询（每 5 分钟）
[CODE BLOCK]
周报触发
[CODE BLOCK]
下一步
- Variables API
- Webhooks API
────────────────────────────────────────────────────────────
# 错误与错误处理
SUMMARY: HTTP 状态码、错误响应格式以及从常见错误中恢复的方法。
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.
错误与错误处理
Synapse 使用标准 HTTP 状态码，并提供一致的错误响应格式。本页说明如何解读错误并从中恢复。
错误响应格式
所有错误都返回如下结构的 JSON：
[CODE BLOCK]
| 字段 | 说明 |
|-------|-------------|
| | HTTP 状态码 |
| | HTTP 状态名称 |
| | 人类可读的错误描述 |
| | 指向相关文档的 URL（如适用） |
HTTP 状态码
200 OK
成功。请求被正确处理。
201 Created
成功。创建了新资源（例如 ）。
204 No Content
成功。无响应体返回（例如 ）。
400 Bad Request
请求格式不正确。常见原因：
- 缺少必填的 JSON 字段
- JSON 语法无效
- 枚举值无效（例如分类不正确）
[CODE BLOCK]
修复： 对照 API 文档检查请求体。确保所有必填字段均存在且值合法。
401 Unauthorized
认证失败。常见原因：
- 缺少 头
- Mind Key 或 JWT 无效
- 在需要 JWT 的地方用了 Mind Key（或反之）
[CODE BLOCK]
修复： 校验你的令牌。参见 Authentication。
403 Forbidden
你已认证但无权执行此操作。常见原因：
- 尝试删除他人的 Mind
- 尝试用 Mind Key 验证记忆（需要 JWT）
- Mind 已被禁用
修复： 检查你为此端点使用的令牌类型是否正确。
404 Not Found
请求的路径或资源不存在。
> [!CRITICAL]
> 不要猜测端点路径。 只有 中列出的路径才存在。如果收到 404，说明你用了错误的路径。
[CODE BLOCK]
修复： 调用 查看有效端点列表。将你的 URL 与列表逐字符对比。
409 Conflict
请求与现有状态冲突。常见原因：
- 尝试用已存在的邮箱注册
- Webhook URL 重复
修复： 使用不同的值，或使用 更新已有资源。
429 Too Many Requests
你触发了限速。仅适用于 查询参数认证（60 次/分钟）。
[CODE BLOCK]
响应头：
[CODE BLOCK]
修复： 改用 头（无限制），或等待 秒。
500 Internal Server Error
服务器错误。这种情况不应发生 — 如果发生，则是 Bug。
修复：
1. 使用指数退避重试（1 秒、2 秒、4 秒、8 秒）
2. 检查 查看服务器是否在线
3. 如果持续出现，请上报该错误
503 Service Unavailable
服务器临时不可用（例如部署、数据库迁移期间）。
修复： 等待并重试。检查 。
恢复模式
指数退避重试
[CODE BLOCK]
认证错误处理
[CODE BLOCK]
常见错误场景
"Mind Key fehlt oder ungültig"
- 你忘记加 头
- 你用了 但 key 错误
- 你在需要 Mind Key 的地方用了 JWT
"Route not found"
- 你猜了一个不存在的路径
- 你用错了动词（例如 与 混淆）
- 检查 获取有效路径
"Rate limit exceeded"
- 你使用了 并超过 60 次/分钟
- 改用 头
下一步
- Authentication
- API 概览
- 限速
────────────────────────────────────────────────────────────
# Memory API
SUMMARY: 22 个记忆端点的完整参考：存储、回放、搜索、语义搜索、同步、审计等。
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 是 Synapse 的核心。它提供 22 个端点用于存储、检索、搜索和管理结构化记忆。所有端点都需要 Mind Key 进行认证。
> [!CRITICAL]
> 务必在每次会话开始时调用 。 这是从之前的会话中重建上下文的唯一方式。
分类
记忆被组织为 8 个分类：
| 分类 | 用途 |
|----------|----------|
| | 用户名、角色、联系方式、关于自身的偏好 |
| | 喜好、厌恶、工作风格、沟通偏好 |
| | 可验证的事实（项目细节、日期、URL） |
| | 项目状态、里程碑、架构 |
| | 用户擅长的事情 |
| | 过去犯的错 — 避免重蹈覆辙 |
| | 与会话相关的上下文 |
| | 其他备注 |
优先级
- — 知道就好
- — 默认
- — 重要
- — 绝不能忘（用户身份、法律信息等）
核心端点
GET /memory/recall
以 LLM 优化的纯文本形式返回所有记忆。请务必在每次会话开始时调用。
[CODE BLOCK]
响应（text/plain）：
[CODE BLOCK]
POST /memory
存储新记忆或更新已有记忆（相同 category + key 视为更新）。
[CODE BLOCK]
响应：
GET /memory
列出记忆，可加可选过滤条件。
[CODE BLOCK]
PUT /memory/:id
按 ID 更新某条具体记忆。
[CODE BLOCK]
DELETE /memory/:id
删除单条记忆。
[CODE BLOCK]
搜索端点
GET /memory/search
使用 FTS5 进行全文搜索。
[CODE BLOCK]
FTS5 语法：
- 多个词 = AND：
- 短语：
- 前缀：
- 布尔：
- 排除：
GET /memory/semantic-search
使用向量嵌入进行概念搜索（比 FTS5 慢，但能理解语义）。
[CODE BLOCK]
返回与查询语义相似的记忆，即使没有关键词匹配。适用于“查找关于 X 的记忆”，即使 X 被用不同的方式描述。
GET /memory/by-tag
按标签列出记忆。
[CODE BLOCK]
GET /memory/related/:id
查找与某条记忆相关的记忆（基于共享标签）。
[CODE BLOCK]
同步与 Diff
GET /memory/diff
增量同步 — 返回自指定时间戳以来发生变化的记忆。
[CODE BLOCK]
响应：
POST /memory/sync
应用来自另一个实例的 diff（用于自托管同步）。
[CODE BLOCK]
批量操作
POST /memory/bulk-delete
按 ID 批量删除记忆。
[CODE BLOCK]
POST /memory/embed-batch
为尚未生成向量嵌入的记忆批量生成嵌入（用于语义搜索）。
[CODE BLOCK]
GET /memory/embed-batch-status
检查嵌入生成进度。
[CODE BLOCK]
验证
记忆有 标志。Agent 存储的记忆默认未验证（）；人类存储的记忆默认已验证（）。
POST /memory/verify
将记忆标记为已验证（需要 JWT，而非 Mind Key）。
[CODE BLOCK]
POST /memory/unverify
将记忆标记为未验证（需要 JWT）。
[CODE BLOCK]
GET /memory/unverified
列出等待人类验证的记忆。
[CODE BLOCK]
统计与审计
GET /memory/stats
当前 Mind 的聚合统计。
[CODE BLOCK]
返回：
GET /memory/audit
所有状态变更操作的审计日志。
[CODE BLOCK]
GET /memory/contradictions
检测已存储记忆中潜在的矛盾。
[CODE BLOCK]
GET /memory/expiring
列出即将到期的记忆。
[CODE BLOCK]
健康检查与导出
GET /memory/health
记忆系统的快速健康检查。
[CODE BLOCK]
GET /memory/mind-export
全部记忆的完整 JSON 导出（用于备份）。
[CODE BLOCK]
POST /memory/compact
压缩相似记忆（自动摘要）。
[CODE BLOCK]
下一步
- LLM 快速开始
- 记忆最佳实践
- FTS5 搜索
- 语义搜索
────────────────────────────────────────────────────────────
# API 概览与基础 URL
SUMMARY: 一目了然地查看所有 Synapse API 端点、基础 URL、认证模式与响应格式。
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.
API 概览与基础 URL
Synapse API 是一个 RESTful HTTP API。所有端点均返回 JSON（除非另有说明）。本页面涵盖了在深入具体端点之前所需的基础知识。
基础 URL
[CODE BLOCK]
本指南中所有路径均相对于此基础 URL。对于自托管实例，请替换为你自己的 URL。
认证
两种方式，均通过 头发送：
[CODE BLOCK]
或通过查询参数发送（限速 60 次/分钟）：
[CODE BLOCK]
详情请参阅 Authentication。
端点分组
| 分组 | 认证 | 说明 |
|-------|------|-------------|
| Public | 无 | 落地页、健康检查、OpenAPI、文档 |
| Memory | Mind Key | CRUD、搜索、同步、向量嵌入 |
| Chat | Mind Key / JWT | 人与 Agent 之间的异步消息 |
| Tasks | Mind Key | 任务管理 |
| Scripts | Mind Key / JWT | 持久化脚本存储 |
| Scheduler | Mind Key | Cron 任务与变量 |
| Webhooks | Mind Key | 事件触发的 HTTP 回调 |
| Computers | Mind Key / JWT | 远程计算机控制 |
| User/Minds | JWT | 账户与 Mind 管理 |
| Sharing | JWT | 用户之间的 Mind 共享 |
| Push | JWT | Web Push 订阅 |
| Tools | 无 | 时间、计算、随机（公共工具） |
响应格式
- JSON（默认）：
- 纯文本： 返回为 LLM 优化的文本
- HTML：、、、、
标准响应封装
成功响应直接返回数据：
[CODE BLOCK]
错误响应采用以下格式：
[CODE BLOCK]
> [!NOTE]
> 字段会针对常见错误链接到相关文档。
HTTP 状态码
| 状态码 | 含义 |
|------|---------|
| 200 | 成功（GET、PUT） |
| 201 | 已创建（POST） |
| 204 | 无内容（DELETE） |
| 400 | 错误请求（校验错误） |
| 401 | 未授权（令牌缺失或无效） |
| 403 | 禁止访问（令牌类型错误） |
| 404 | 未找到（路径不存在） |
| 409 | 冲突（重复） |
| 429 | 请求过多（触发限速） |
| 500 | 服务器错误 |
可发现性端点
| 端点 | 用途 |
|----------|---------|
| | 落地页（为 LLM 优化） |
| | 所有端点的机器可读列表 |
| | 纯文本端点列表 |
| | OpenAPI 3.0 规范 |
| | 完整 API 文档（HTML） |
| | JSON 格式 API 文档 |
| | 文档系统（HTML） |
| | 文档索引（JSON） |
| | 全部文档作为一个文本块 |
| | 交互式 API 调试页面 |
限速
| 认证方式 | 限制 |
|-------------|-------|
| Mind Key（header） | 无限制 |
| Mind Key（?key=） | 每个 IP 60 次/分钟 |
| JWT（header） | 无限制 |
| 公共端点 | 无限制 |
受限速影响的响应会包含：
[CODE BLOCK]
分页
列表端点支持 与 ：
[CODE BLOCK]
默认 limit：100。最大 limit：500。
CORS
所有端点都为浏览器客户端支持 CORS：
[CODE BLOCK]
SDK 与客户端
- Node.js SDK：（仓库）
- MCP Server：（仓库）
- HTTP 客户端：任意 HTTP 库（curl、fetch、axios 等）
下一步
- Memory API — 最重要的端点
- Chat API — 人类与 Agent 之间的异步通信
- Errors & Error Handling
────────────────────────────────────────────────────────────
# 限速与配额
SUMMARY: Synapse API 的限速策略 — Bearer 头（无限制）、?key=（60 次/分钟）、公共端点。
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.
限速与配额
Synapse 采用简单、可预测的限速策略，既能防止滥用，又不妨碍正常使用。
限速策略
| 认证方式 | 限制 | 范围 |
|-------------|-------|-------|
| Mind Key（） | 无限制 | 每个 Mind |
| Mind Key（） | 60 次/分钟 | 每个 IP |
| JWT（） | 无限制 | 每个用户 |
| 公共端点 | 无限制 | 全局 |
> [!TIP]
> 尽可能始终使用 头。它没有限速。仅在工具无法设置自定义请求头时才使用 。
限速响应头
当你使用 认证时，响应会包含限速头：
[CODE BLOCK]
当你超过限制时：
[CODE BLOCK]
当你触发限速时
如果收到 429：
1. 改用 Authorization 头（推荐）：
[CODE BLOCK]
2. 或等待 秒后重试。
为什么存在 限制
查询参数对于只能使用 URL 的工具（浏览器、 命令）很方便，但带来安全与性能影响：
- 安全：查询参数会出现在服务器访问日志、浏览器历史和 Referer 头中。限制使用可以降低泄露面。
- 性能：基于查询参数的认证需要基于 IP 的限速器（每次请求都查询 Redis），会增加延迟。基于头的认证可以跳过这一步。
- 防滥用：泄露的 URL 可能被分享并被疯狂调用。IP 限制可以减小爆炸半径。
推荐模式
LLM Agent
[CODE BLOCK]
基于浏览器的工具
如果你的工具只能打开 URL：
[CODE BLOCK]
MCP Server
MCP Server 始终通过 环境变量使用头部认证 — 不受限速影响。
批量导入
对于批量操作（例如导入 1000 条记忆），请始终使用头部认证。通过 进行批量导入会在 1 分钟内触发限速。
配额（Mind 级别）
目前没有针对存储大小或记忆数量的 Mind 级配额。所有限制都在认证/IP 层，不在数据层。未来为多租户公平性可能会调整此策略。
监控你的使用情况
[CODE BLOCK]
下一步
- Authentication
- 错误与错误处理
────────────────────────────────────────────────────────────
# Scripts API
SUMMARY: 持久化脚本存储 — 保存可复用的 Shell、Python 或 Node 脚本，并通过 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 为可复用脚本提供持久化存储。脚本在 Mind 中命名并版本化，可作为纯文本拉取 — 非常适合 模式。
端点
POST /script
存储或更新脚本。
[CODE BLOCK]
GET /script/:name
以 拉取脚本内容。非常适合管道到 bash 执行。
[CODE BLOCK]
GET /script/:name/info
获取脚本的元数据（不含内容）。
[CODE BLOCK]
响应：
[CODE BLOCK]
GET /scripts
列出当前 Mind 中的所有脚本。
[CODE BLOCK]
DELETE /script/:name
删除脚本。
[CODE BLOCK]
常见用例
部署脚本
把标准部署流程保存为脚本，让 LLM 直接运行，无需每次重新推导步骤：
[CODE BLOCK]
故障排查片段
把常见问题的诊断命令保存为脚本：
[CODE BLOCK]
配置生成器
保存用于生成配置的脚本：
[CODE BLOCK]
下一步
- Variables API
- Cron 与调度器
────────────────────────────────────────────────────────────
# Tasks API
SUMMARY: 为 LLM Agent 提供任务管理 — 创建、列出、更新、完成、删除带优先级的任务。
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 为 LLM Agent 提供结构化的方式来跟踪多步骤工作。任务归属于当前 Mind，并跨会话持久化，因此 Agent 可以从中断处继续工作。
端点
GET /mind/tasks
列出当前 Mind 中的所有任务。
[CODE BLOCK]
响应：
[CODE BLOCK]
POST /mind/task
创建新任务。
[CODE BLOCK]
GET /mind/task（查询参数）
通过 GET 创建任务（供只能使用 URL 的工具使用）。
[CODE BLOCK]
PUT /mind/task/:id
更新已有任务。
[CODE BLOCK]
GET /mind/task/:id/complete
将任务标记为已完成。
[CODE BLOCK]
GET /mind/task/:id/delete
永久删除任务。
[CODE BLOCK]
优先级
- — 不紧急
- — 默认
- — 重要
- — 必须立即处理
状态
- — 已创建，未开始
- — 正在处理
- — 已完成
- — 已放弃
模式：任务驱动工作流
[CODE BLOCK]
下一步
- 任务驱动工作流
- Cron 与调度器
────────────────────────────────────────────────────────────
# 实用工具（时间、计算、随机）
SUMMARY: 公共实用端点 — 服务器时间、安全计算器、随机值生成器。无需认证。
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.
实用工具
端点是公共工具 — 无需认证。对于需要服务器时间、安全数学计算或随机值的 LLM Agent 很有用。
GET /tools/time
获取当前服务器时间、时区与 UTC 偏移。
[CODE BLOCK]
响应：
[CODE BLOCK]
用例：LLM Agent 需要知道“现在是几点”，用于调度、时间戳或相对日期计算。
GET /tools/calc
安全计算器 — 仅支持算术运算，不使用 。支持 、、、、、、 和数字。
[CODE BLOCK]
响应：
[CODE BLOCK]
> [!TIP]
> 用它代替在脑中计算或字符串解析。它既安全（无法注入代码）又准确。
支持的运算符
- 加法
- 减法
- 乘法
- 除法
- 取模
- 括号
- 数字（整数与小数）
示例
[CODE BLOCK]
GET /tools/random
生成随机值。
[CODE BLOCK]
类型参数
| 类型 | 参数 | 输出 |
|------|-----------|--------|
| | 无 | UUID v4 字符串 |
| | 、（默认 0-100） | 整数 |
| | 、（默认 0-100） | 浮点数 |
| | 、（长度范围，默认 8-16） | 十六进制字符串 |
| | 、（长度范围，默认 8-16） | 字母字符串 |
LLM Agent 的用例
生成唯一 ID
[CODE BLOCK]
计算百分比
[CODE BLOCK]
获取当前时间戳
[CODE BLOCK]
生成测试数据
[CODE BLOCK]
下一步
- API 概览 — 所有端点分组
- 错误与错误处理
────────────────────────────────────────────────────────────
# User 与 Minds API
SUMMARY: 账户管理 — 注册、登录、创建 Mind、列出 Mind、删除 Mind。由 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 负责账户管理。这些端点使用 JWT 认证（而非 Mind Key），因为它们作用于账户级别，而非 Mind 级别。
认证端点
POST /register
创建新用户账户。
[CODE BLOCK]
响应：
[CODE BLOCK]
POST /login
登录已有账户。
[CODE BLOCK]
响应：与 相同。
Minds 端点
POST /minds
创建新 Mind。返回 Mind Key — 请立即保存，它只显示一次。
[CODE BLOCK]
响应：
[CODE BLOCK]
> [!CRITICAL]
> 只显示一次。如果丢失，无法找回 — 你必须删除该 Mind 并创建新 Mind（会丢失所有已存储的记忆）。
GET /minds
列出当前用户的所有 Mind。
[CODE BLOCK]
响应：
[CODE BLOCK]
DELETE /minds/:id
永久删除某个 Mind。
[CODE BLOCK]
> [!WARNING]
> 删除 Mind 不可逆。该 Mind 中的所有记忆、任务、聊天记录和脚本都会永久丢失。如需备份，请先通过 导出。
多 Mind 模式
大多数用户会受益于使用多个 Mind 以隔离上下文：
[CODE BLOCK]
在不同 LLM 会话中使用不同的 Mind Key 即可隔离上下文。
账户安全
密码要求
- 至少 6 个字符
- 无最大长度限制（请使用密码管理器）
- 以 bcrypt 哈希存储（绝不存明文）
JWT 过期
JWT 在 7 天后过期。过期后再次调用 即可。
Mind Key 安全
Mind Key 永不过期。如果 Mind Key 泄露：
1. 通过 创建新 Mind
2. 用新的 Mind Key 更新你的 LLM 配置
3. 通过 删除被泄露的 Mind
下一步
- Authentication — 完整认证指南
- Mind Key 与 JWT — 决策指南
- Sharing API — 与其他用户共享 Mind
────────────────────────────────────────────────────────────
# Variables API
SUMMARY: 用于 LLM 状态的快速键值存储 — 计数器、标志位、最后访问时间戳、部分进度。
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 是用于临时状态的快速键值存储。与记忆（被索引、可搜索、结构化）不同，变量针对快速读写做了优化 — 非常适合计数器、标志位和会话状态。
端点
POST /var
设置或更新变量。
[CODE BLOCK]
GET /var/:key
获取单个变量。
[CODE BLOCK]
响应：
[CODE BLOCK]
GET /var
列出所有变量。
[CODE BLOCK]
DELETE /var/:key
删除变量。
[CODE BLOCK]
何时使用变量、何时使用记忆
| 用例 | 使用 |
|----------|-----|
| 用户名、偏好 | Memory（可搜索、结构化） |
| 上次会话时间戳 | Variable（临时状态） |
| 计数器（例如已发送消息数） | Variable（频繁更新） |
| 工作流状态（“5 步中已完成 3 步”） | Variable（短暂状态） |
| 长篇项目笔记 | Memory（全文索引） |
| 可复用脚本 | Script 存储（命名、版本化） |
常见模式
跟踪上次会话
[CODE BLOCK]
计数器模式
[CODE BLOCK]
功能开关
[CODE BLOCK]
下一步
- Memory API — 用于结构化、可搜索的数据
- Cron 与调度器
────────────────────────────────────────────────────────────
# Webhooks API
SUMMARY: 为记忆、聊天和任务事件注册 HTTP 回调 — 数据变化时收到通知。
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
Webhooks 让你在 Synapse 中发生事件时接收 HTTP 回调。非常适合触发外部自动化、发送通知或同步到其他系统。
端点
POST /webhooks
注册新 Webhook。
[CODE BLOCK]
响应：
[CODE BLOCK]
GET /webhooks
列出当前 Mind 的所有 Webhook。
[CODE BLOCK]
GET /webhooks/:id
获取单个 Webhook。
[CODE BLOCK]
PUT /webhooks/:id
更新 Webhook（URL、事件、密钥或启用标志）。
[CODE BLOCK]
DELETE /webhooks/:id
删除 Webhook。
[CODE BLOCK]
事件类型
| 模式 | 触发时机 |
|---------|------------|
| | 任意记忆事件 |
| | 存储新记忆 |
| | 记忆被更新 |
| | 记忆被删除 |
| | 任意聊天事件 |
| | 收到来自人类的新消息 |
| | 任意任务事件 |
| | 新任务被创建 |
| | 任务被标记为完成 |
| | 所有事件 |
Webhook Payload
事件触发时，Synapse 会向你的 URL 发送 POST 请求：
[CODE BLOCK]
签名验证
如果你设置了 ，Synapse 会用 HMAC-SHA256 对每个 payload 签名：
[CODE BLOCK]
在你的处理程序中验证：
[CODE BLOCK]
模式：实时同步
[CODE BLOCK]
下一步
- Cron 与调度器
- Webhook 自动化指南
## 分类：MCP 集成
与 Claude、Cursor 及其他 MCP 客户端集成。
────────────────────────────────────────────────────────────
# Claude Code 中的 MCP
SUMMARY: 在 Claude Code 终端 Agent 中使用 Synapse 工具 — 为编码会话提供持久化记忆。
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"
Claude Code 中的 MCP
Claude Code 是 Anthropic 推出的基于终端的编码 Agent。借助 Synapse MCP，Claude Code 在编码会话之间获得持久化记忆 — 它会记住你的项目上下文、过往决策和代码库模式。
配置
方法 1：CLI 命令（推荐）
[CODE BLOCK]
方法 2：编辑配置文件
编辑 ：
[CODE BLOCK]
验证可用
启动 Claude Code：
[CODE BLOCK]
在 Claude Code 提示符中输入：
[CODE BLOCK]
Claude 会调用 并返回你已存储的记忆。
常见模式
项目上下文持久化
编码会话开始时：
[CODE BLOCK]
Claude 调用 ，查看你的项目列表，并从中断处继续工作。
代码库决策
当你做出架构决策时：
[CODE BLOCK]
Claude 调用 ，category 为 ，priority 为 。
避免过往错误
[CODE BLOCK]
Claude 搜索 category 为 的记忆并提醒你过往错误。
任务跟踪
[CODE BLOCK]
Claude 调用 ，任务跨会话持久化。
工具配置文件
当你不需要全部 119 个工具时：
[CODE BLOCK]
故障排查
MCP Server 未启动
[CODE BLOCK]
Mind Key 未识别
[CODE BLOCK]
Claude Code 看不到工具
- 配置更改后重启 Claude Code
- 检查 确认 Synapse 已注册
- 参见 MCP 故障排查
下一步
- Claude Desktop 配置
- Cursor 配置
- 持久化 LLM Agent 指南
────────────────────────────────────────────────────────────
# Claude Desktop 中的 MCP
SUMMARY: 2 分钟把 Synapse 接入 Claude Desktop。Claude 原生获得 79 个 Synapse 工具。
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
Claude Desktop 中的 MCP
Claude Desktop 是 Anthropic 推出的 macOS 与 Windows 桌面应用。配置 Synapse MCP Server 后，Claude 原生获得全部 79 个 Synapse 工具的访问权限 — 它可以存储记忆、回放记忆、管理任务、与你聊天等等。
前置条件
- Claude Desktop 应用（macOS 或 Windows）
- 已安装 Node.js 18+（）
- 你的 Synapse Mind Key
第 1 步：打开配置文件
- macOS：
- Windows：
如果文件不存在，请创建。
第 2 步：添加 Synapse MCP Server
[CODE BLOCK]
> [!TIP]
> 如果你已经配置了其他 MCP Server，只需把 块添加到已有的 对象内。
第 3 步：重启 Claude Desktop
1. 完全退出 Claude Desktop（macOS 上 Cmd+Q，而非只关窗口）
2. 重新打开 Claude Desktop
3. 开启新聊天
4. 查看左下角的 🔌 插头图标 — 应显示 “79 tools”
第 4 步：测试
在新聊天中输入：
[CODE BLOCK]
Claude 应该调用 工具，并返回已存储记忆的摘要（如果 Mind 为空则返回 “No memories yet”）。
可用工具（部分）
| 工具 | 说明 |
|------|-------------|
| | 回放所有记忆 |
| | 存储新记忆 |
| | 搜索记忆 |
| | 列出任务 |
| | 创建任务 |
| | 检查新消息 |
| | 回复消息 |
| | 打开浏览器标签页 |
| | 列出已注册计算机 |
完整列表：MCP 是什么？
故障排查
Claude Desktop 中没有工具出现
1. 验证 Node.js 版本：（必须 ≥ 18）
2. 检查配置文件是否为有效 JSON（无尾随逗号）
3. 完全重启 Claude Desktop（Cmd+Q，而非只关窗口）
4. 查看 Claude Desktop 日志：（macOS）
“Mind Key invalid” 错误
- 确认 以 开头
- 通过 获取新 key（需要 的 JWT）
- JSON 中 key 不要加引号
npx 未找到
- 安装 Node.js 18+：
- 安装后重启终端
- macOS 用 Homebrew：
工具出现但调用失败
- 检查 是否可达：
- 验证 Mind Key 可用：
- 参见 MCP 故障排查
工具配置文件（节省 tokens）
如果你使用较小的 LLM 或想节省上下文 tokens，设置工具配置文件：
[CODE BLOCK]
配置文件：（8 个工具）、（25）、（119，默认）。
下一步
- Claude Code 配置
- Cursor 配置
- MCP 故障排查
────────────────────────────────────────────────────────────
# Continue.dev 中的 MCP
SUMMARY: 把 Synapse 接入 Continue.dev — VS Code 与 JetBrains 的开源 AI 编码助手。
Continue.dev 中的 MCP
Continue.dev 是面向 VS Code 与 JetBrains IDE 的开源 AI 编码助手。借助 Synapse MCP，Continue 在会话之间获得持久化记忆。
前置条件
- VS Code 或 JetBrains IDE
- 已安装 Continue.dev 扩展
- Node.js 18+
- 你的 Synapse Mind Key
配置
第 1 步：打开 Continue 配置
在 VS Code 或 JetBrains 中：
1. 打开 Continue 扩展侧边栏
2. 点击齿轮图标 → “Open config.json”
或直接编辑 。
第 2 步：添加 Synapse MCP Server
[CODE BLOCK]
第 3 步：重新加载 Continue
重新加载 VS Code 窗口（Cmd+Shift+P → “Reload Window”），或重启 IDE。
验证可用
在 Continue 聊天中：
[CODE BLOCK]
Continue 应调用 并返回你已存储的记忆。
常见模式
项目上下文
[CODE BLOCK]
Continue 调用 ，查看你的项目记忆，并从中断处继续工作。
代码审查模式
[CODE BLOCK]
Continue 找出你存储的代码审查模式并应用它们。
结对编程记忆
[CODE BLOCK]
Continue 把它存为 记忆。
故障排查
MCP Server 未连接
1. 检查 是否为有效 JSON
2. 验证 Node.js：
3. 查看 Continue 的输出面板（View → Output → Continue）
4. 重启 IDE
工具未出现
- 确认 Continue 版本支持 MCP（≥ 0.9.x）
- 检查配置中的 环境变量是否已设置
- 在 Continue 的日志中查找 MCP 错误
下一步
- Claude Desktop 配置
- 自定义 MCP 客户端
────────────────────────────────────────────────────────────
# Cursor 中的 MCP
SUMMARY: 把 Synapse 接入 Cursor IDE，为编码会话提供持久化的项目记忆。
Cursor 中的 MCP
Cursor 是基于 VS Code 的 AI 驱动 IDE。借助 Synapse MCP，Cursor 在会话之间获得持久化记忆 — 它会记住你的项目决策、代码库模式和过往调试会话。
前置条件
- 已安装 Cursor IDE（）
- Node.js 18+
- 你的 Synapse Mind Key
配置
第 1 步：打开 Cursor 设置
在 Cursor 中：
1. 打开设置（macOS Cmd+,，Windows/Linux Ctrl+,）
2. 搜索 “MCP” 或导航到
第 2 步：添加 Synapse MCP Server
点击 “Add MCP Server” 并配置：
| 字段 | 值 |
|-------|-------|
| Name | |
| Type | |
| Command | |
| Env | |
第 3 步：直接编辑 config.json（备选）
Cursor 把 MCP 配置存储在 ：
[CODE BLOCK]
第 4 步：重启 Cursor
完全重启 Cursor（macOS 上 Cmd+Q 后重新打开）。
验证可用
在 Cursor 的聊天面板中（Cmd+L）：
[CODE BLOCK]
Cursor 应调用 并返回你已存储的记忆。
常见模式
项目入门
打开新项目时：
[CODE BLOCK]
Cursor 调用 并从中断处继续工作。
架构决策
[CODE BLOCK]
Cursor 把它存为 记忆，优先级 。
调试历史
[CODE BLOCK]
Cursor 搜索 记忆并提醒你过往修复。
跨会话代码模式
[CODE BLOCK]
Cursor 找出你以前实现过的认证相关记忆。
故障排查
MCP Server 未连接
1. 验证 Node.js：（≥ 18）
2. 测试 MCP Server：（应无错启动）
3. 查看 Cursor 的 MCP 日志（View → Output → MCP）
4. 完全重启 Cursor
工具未出现
- 检查 是否为有效 JSON
- 验证 环境变量已设置
- 检查 Cursor 版本是否支持 MCP（≥ 0.42）
Mind Key 无效
[CODE BLOCK]
下一步
- Claude Desktop 配置
- Continue.dev 配置
- 持久化 LLM Agent 指南
────────────────────────────────────────────────────────────
# 构建自定义 MCP 客户端
SUMMARY: 使用 MCP SDK 从你自己的应用连接到 Synapse MCP Server。
构建自定义 MCP 客户端
如果你在构建自己的 LLM 应用，可以直接使用官方 MCP SDK 连接到 Synapse MCP Server。这样你的应用就能访问全部 79 个 Synapse 工具。
SDK
| 语言 | 包 |
|----------|---------|
| TypeScript/JavaScript | |
| Python | |
TypeScript 示例
安装
[CODE BLOCK]
通过 stdio 连接
[CODE BLOCK]
通过 HTTP/SSE 连接（远程）
[CODE BLOCK]
Python 示例
安装
[CODE BLOCK]
通过 stdio 连接
[CODE BLOCK]
工具配置文件
连接时，可通过 头（HTTP/SSE）或 环境变量（stdio）请求特定工具配置文件：
[CODE BLOCK]
错误处理
[CODE BLOCK]
用例
- 自定义 AI 助手 — 构建带持久记忆的 Agent
- 工作流自动化 — 在自定义工作流中串联 Synapse 工具
- 数据流水线 — 提取记忆、转换、加载到别处
- 监控仪表板 — 展示记忆统计、聊天历史、任务
下一步
- MCP 规范
- Synapse MCP 仓库
- API 概览
────────────────────────────────────────────────────────────
# MCP 故障排查
SUMMARY: 解决常见 MCP 集成问题 — 服务器不启动、工具不出现、认证错误。
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/
MCP 故障排查
把 Synapse MCP 集成到 LLM 客户端时的常见问题与解决方案。
快速诊断清单
1. ✅ 是否已安装 Node.js 18+？（）
2. ✅ Mind Key 是否以 开头？（不是 JWT 的 ）
3. ✅ Synapse API 是否可达？（）
4. ✅ Mind Key 是否可用？（）
5. ✅ 配置文件是否为有效 JSON？（无尾随逗号、无注释）
6. ✅ 配置更改后是否重启客户端？
7. ✅ MCP Server 是否能手动启动？（）
问题：客户端中没有工具出现
症状
- Claude Desktop / Cursor / Continue 显示 0 个工具
- 没有 🔌 图标或 MCP Server 列表中没有 “synapse” 条目
解决方案
1. 完全重启客户端 — macOS 上 Cmd+Q（不是只关窗口）
2. 检查配置文件位置：
- Claude Desktop macOS：
- Claude Desktop Windows：
- Cursor：
- Continue：
3. 校验 JSON — 把配置粘到
4. 查看客户端日志中的 MCP 错误：
- Claude Desktop：（macOS）
- Cursor：View → Output → MCP
5. 手动运行 MCP Server 以查看启动错误：
[CODE BLOCK]
问题：“Mind Key invalid” 错误
症状
- 工具出现，但调用失败返回 “401 Unauthorized”
- 错误：“Mind Key fehlt oder ungültig”
解决方案
1. 验证 Mind Key 格式 — 以 开头，约 40 个字符
2. 直接测试：
[CODE BLOCK]
3. 检查环境变量是否设置 — 对于 stdio 传输，环境变量必须在 MCP Server 配置中，而不是你的 shell
4. 获取新的 Mind Key：
[CODE BLOCK]
问题：npx 未找到
症状
- 错误：“npx: command not found”
- MCP Server 启动失败
解决方案
1. 安装 Node.js 18+：
- macOS： 或从 下载
- Linux：
- Windows：从 下载
2. 安装后重启终端
3. 验证：
问题：SYNAPSEURL 不可达
症状
- MCP Server 启动但工具调用超时
- 错误：“fetch failed” 或 “ECONNREFUSED”
解决方案
1. 测试连通性：
[CODE BLOCK]
2. 检查公司防火墙 — 可能阻挡出站 HTTPS
3. 尝试备用 URL：
- 生产环境：
- MCP Server：
4. 自托管：确保 Synapse 实例正在运行且可访问
问题：MCP Server 崩溃
症状
- MCP Server 启动后立即退出
- 客户端日志显示 “MCP server disconnected”
解决方案
1. 手动运行查看错误：
[CODE BLOCK]
2. 检查端口冲突 — MCP Server 默认使用端口 13100
3. 清除 npx 缓存：
[CODE BLOCK]
4. 更新到最新版：
[CODE BLOCK]
问题：工具调用返回 429
症状
- 错误：“Rate limit exceeded”
解决方案
MCP 不应出现此问题（用头部认证，无限制）。如果出现：
1. 检查是否在某处用了 — 改用头部认证
2. 验证 — 确保指向正确实例
3. 若问题持续，联系支持
问题：工具出现但不工作
症状
- 客户端列出了工具
- 调用工具返回错误或无结果
解决方案
1. 检查工具名 — 必须精确（如 ，不是 ）
2. 验证参数 — 检查工具的输入 schema
3. 通过直接 API 测试：
[CODE BLOCK]
4. 检查 Synapse 健康：
[CODE BLOCK]
获取帮助
如果以上方案都无法解决：
1. 查看已有 issue：
2. 提交新 issue，附上：
- MCP Server 版本（）
- 客户端名称与版本
- 操作系统
- 相关日志片段
- 复现步骤
下一步
- Claude Desktop 配置
- Claude Code 配置
- API 错误
────────────────────────────────────────────────────────────
# MCP 是什么？
SUMMARY: Model Context Protocol 让 LLM 调用外部工具。Synapse 通过官方 MCP Server 暴露 79 个工具。
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 是什么？
Model Context Protocol (MCP) 是 Anthropic 于 2024 年推出的开放标准，让 LLM 以结构化方式调用外部工具。你不需要把 API 文档粘到 prompt 里，而是把工具注册到 MCP Server，LLM 按需调用 — 类似 function calling，但标准化且与客户端无关。
Synapse MCP Server
Synapse 提供官方 MCP Server（npm 上的 ），暴露覆盖所有 Synapse 功能的 79 个工具：
| 分类 | 工具 | 数量 |
|----------|-------|-------|
| 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 |
| 合计 | | 79+ |
工作原理
[CODE BLOCK]
1. 你把 LLM 客户端（Claude Desktop、Cursor 等）配置为使用 Synapse MCP Server
2. 客户端启动 MCP Server（通过 ）
3. MCP Server 用你的 Mind Key 连接到 Synapse API
4. LLM 看到全部 79 个工具，作为可调用的原生函数
5. 当 LLM 需要记住某事时，它调用 — MCP Server 把它翻译为 Synapse 上的
传输方式
Synapse MCP Server 支持三种传输方式：
stdio（本地，桌面端推荐）
[CODE BLOCK]
HTTP/SSE（远程，多租户）
把你的 MCP 客户端连接到：
[CODE BLOCK]
WebSocket（移动端，高吞吐）
[CODE BLOCK]
工具配置文件（v1.4.0）
为减小较小 LLM 的 token 开销，MCP Server 支持三种工具配置文件：
| 配置文件 | 工具 | Tokens | 适合 |
|---------|-------|--------|----------|
| | 8（组合分发） | 500 | 上下文 ≤8k 的自托管 LLM |
| | 25（命名） | 2,500 | 中等大小 LLM（Claude Haiku、GPT-3.5） |
| | 119（全部） | 8,250 | 大型 LLM（Claude Sonnet/Opus、GPT-4） — 默认 |
控制方式：
- 环境变量：
- 头：
支持的客户端
- Claude Desktop — Anthropic 的桌面应用
- Claude Code — 终端编码 Agent
- Cursor — AI 驱动的 IDE
- Continue.dev — 开源 AI 编码助手
- Cline — VS Code 扩展
- 任何兼容 MCP 的客户端
为什么用 MCP 而非直接 API？
| 方式 | 优点 | 缺点 |
|----------|------|------|
| 直接 API | 简单，无额外层 | LLM 需要知道 URL、请求头、认证 |
| MCP | LLM 看到原生工具，无需记 URL | 多一个 MCP Server 进程 |
对于大多数 LLM Agent 用例，MCP 是更好的选择 — LLM 不需要记 API 路径或认证模式。
下一步
- Claude Desktop 配置 — 2 分钟配置
- Claude Code 配置 — 终端集成
- 自定义 MCP 客户端 — 自建客户端
## 分类：指南与操作手册
针对具体场景的循序渐进指南。
────────────────────────────────────────────────────────────
# iOS 应用自动化测试
SUMMARY: 使用 Synapse + Computer Control API 通过 Simulator 自动化 iOS 应用测试。
iOS 应用自动化测试
将 Synapse 的记忆系统与 Computer Control API 结合，构建 LLM 驱动的 iOS 应用测试。LLM 会记住测试场景，从过往失败中学习，并适应 UI 变化。
架构
[CODE BLOCK]
前置条件
- Synapse 账户 + Mind Key
- 在 Claude Desktop 中配置 Synapse MCP Server
- 已安装 的 iOS Simulator
- 在 Synapse 中注册计算机（参见 Computer Control API）
第 1 步：注册 Simulator 计算机
在运行 iOS Simulator 的 Mac 上：
[CODE BLOCK]
第 2 步：在记忆中存储测试场景
把可复用的测试场景作为记忆存储：
[CODE BLOCK]
第 3 步：LLM 驱动的测试执行
在 Claude Desktop 中（已配置 Synapse MCP）：
[CODE BLOCK]
Claude 会：
1. 调用 查找 记忆
2. 调用 查看当前状态
3. 通过 执行每一步（点击、输入）
4. 通过截图验证结果
5. 把任何失败存储为 记忆
第 4 步：自愈测试
当测试失败时，存储失败信息与恢复方案：
[CODE BLOCK]
下次 LLM 运行该测试时，会回放该失败记忆并自动应用恢复方案。
第 5 步：测试结果跟踪
把测试运行记录为任务：
[CODE BLOCK]
常用命令
| 操作 | 命令 |
|--------|---------|
| 启动 Simulator | |
| 截屏 | （通过 Synapse MCP） |
| 在 (x,y) 点击 | |
| 输入文本 | |
| 按 Home 键 | |
最佳实践
> [!TIP]
> - 把 UI 坐标作为记忆存储 — UI 会变，但 LLM 可以重新学习
> - 使用 accessibility 标签 — 比坐标更稳定
> - 把测试数据单独存储 — 用变量管理用户名、密码
> - 在干净状态运行测试 — 每次运行之间重置 Simulator
> - 为失败保存截图 — 便于调试
下一步
- 自愈测试
- Computer Control API
- 记忆最佳实践
────────────────────────────────────────────────────────────
# 备份与恢复
SUMMARY: 导出记忆用于备份、在 Mind 之间迁移、在数据丢失后恢复。
备份与恢复
Synapse 提供完整的导出/导入，用于记忆备份、迁移与灾难恢复。本指南覆盖核心操作。
导出
完整 Mind 导出
将某个 Mind 的所有记忆导出为 JSON：
[CODE BLOCK]
响应格式：
[CODE BLOCK]
增量导出（Diff）
仅导出自某时间戳以来变化的记忆：
[CODE BLOCK]
响应：
[CODE BLOCK]
自动化备份
通过 cron 调度每日备份：
[CODE BLOCK]
> [!NOTE]
> cron 端点会接收响应但不存储它。要真正备份，请把 cron 指向你自己的备份服务器来保存响应。
更好：外部备份脚本
[CODE BLOCK]
加入 crontab：
[CODE BLOCK]
恢复
恢复到同一 Mind
[CODE BLOCK]
恢复到新 Mind
[CODE BLOCK]
Python 恢复脚本
[CODE BLOCK]
在 Mind 之间迁移
[CODE BLOCK]
备份其他数据
别忘了备份：
| 数据类型 | 端点 |
|-----------|----------|
| 记忆 | |
| 任务 | |
| 脚本 | |
| Webhook | |
| Cron 任务 | |
| 变量 | |
| 聊天记录 | |
验证
恢复后请验证：
[CODE BLOCK]
最佳实践
> [!TIP]
> - 每日备份 — 用 cron 自动化
> - 测试恢复 — 不能恢复的备份毫无意义
> - 保留多版本 — 至少 30 天
> - 异地存储 — S3、Backblaze B2 等
> - 加密敏感备份 — 记忆中可能含 PII
> - 记录恢复流程 — 等到你需要时已经忘了
下一步
- Memory API
- Cron 与调度器 — 用于自动化备份
────────────────────────────────────────────────────────────
# 记忆最佳实践
SUMMARY: 如何结构化记忆以实现高效回放 — 分类、键、标签、优先级。
记忆最佳实践
记忆的结构决定了它的实用价值。本指南涵盖记忆的分类、打标签与优先级模式，让 LLM 能在正确时间回放出正确信息。
分类：选择最具体的
| 分类 | 用于 | 示例 |
|----------|---------|---------|
| | 用户名、角色、联系方式 | |
| | 喜好、厌恶、工作风格 | |
| | 可验证的事实 | |
| | 项目状态、决策 | |
| | 用户的技能 | |
| | 要避免的过往错误 | |
| | 与会话相关的上下文 | |
| | 其他备注 | |
> [!TIP]
> 拿不准时，可验证信息用 ，其他都用 。
> 不要过度分类 — 清晰的 比含糊的 更好。
Key：有意义的标识符
字段是记忆的标识符。使用有意义且稳定的 key：
好 key：
-
-
-
-
坏 key：
- （无意义）
- （不具描述性）
- （日期对回放无帮助）
Key 命名规范
- （小写加下划线）
- 以分类为前缀：、、
- 使用描述性名词，而非动词
- 长度控制在 50 字符以内
Tags：用于搜索与过滤
标签可加速过滤与搜索。每条记忆加 2-5 个标签：
[CODE BLOCK]
标签模式
- 项目名：、、
- 主题：、、、
- 状态：、、
- 优先级指示：、
> [!NOTE]
> 标签不区分大小写。请使用小写以保持一致。
优先级：实事求是
| 优先级 | 用于 | 占比 |
|----------|---------|---------------|
| | 用户身份、法律信息、不可逆决策 | 5% |
| | 进行中的项目、重要偏好 | 20% |
| | 大多数事实、备注、上下文 | 65% |
| | 临时、知道就好的信息 | 10% |
> [!WARNING]
> 不要把所有记忆都标为 。如果一切都是 critical，那就什么都不是。
> 把 留给那些一旦被遗忘就会造成实际伤害的内容。
何时存储、何时不存储
始终存储
- 用户身份（姓名、邮箱、角色）
- 长期偏好
- 项目决策与理由
- 过往错误与教训
- 对用户做出的承诺
不要存储
- 临时状态（改用变量）
- 逐字对话历史（聊天系统会处理）
- 敏感数据（密码、API key）
- 易推导的事实（当前日期、文件内容）
- 短暂上下文（用 分类 + low 优先级）
更新记忆
用相同的 + 发起 会更新已有记忆：
[CODE BLOCK]
> [!TIP]
> 使用稳定的 key，这样你可以更新而不创建重复。LLM 应该在信息变化时重新 POST 相同的 key，而不是创建新记忆。
记忆生命周期
[CODE BLOCK]
- 创建：POST /memory，带上完整上下文
- 活跃：频繁回放，按需更新
- 陈旧：仍相关但不再活跃使用（降低优先级？）
- 归档：设为 优先级，保留供历史参考
- 删除：不再相关时 DELETE /memory/:id
定期清理
[CODE BLOCK]
模式：记忆继承
对于层级上下文（项目 → 子项目 → 任务）：
[CODE BLOCK]
LLM 之后可搜索 找到所有相关记忆。
模式：决策日志
把决策与理由一起存储，这样 LLM 不会重新质疑：
[CODE BLOCK]
模式：错误规避
把错误与具体的规避指令一起存储：
[CODE BLOCK]
应避免的反模式
> [!WARNING]
> - 存储对话日志 — 聊天系统会处理
> - 存储整个文件 — 用脚本存储或外部存储
> - 存储临时状态 — 用变量
> - 存储密钥 — 用环境变量
> - 重复记忆 — 用稳定的 key
> - 过度打标签 — 每条记忆 2-5 个标签最理想
> - 一切都是 critical — 优先级要实事求是
下一步
- Memory API
- 持久化 LLM Agent
- 记忆打标签策略
────────────────────────────────────────────────────────────
# 多 Agent 协调
SUMMARY: 使用共享的 Synapse Mind、任务与聊天协调多个 LLM Agent。
多 Agent 协调
当你有多个 LLM Agent 处理相关任务时，Synapse 提供协调层 — 共享记忆、任务分配与异步聊天。
模式
模式 1：共享 Mind（单一真相源）
所有 Agent 共享一个 Mind Key。它们读写同一个记忆存储。
[CODE BLOCK]
用例： 一组 Agent 共同处理一个项目。
配置：
[CODE BLOCK]
通过任务协调：
[CODE BLOCK]
模式 2：专用 Mind（隔离上下文）
每个 Agent 有自己的 Mind。它们通过一个共享的“协调”Mind 通信。
[CODE BLOCK]
用例： 具有不同专长（编码、审查、部署）的 Agent。
配置：
[CODE BLOCK]
通过共享 Mind 协调：
[CODE BLOCK]
模式 3：中心辐射式（Orchestrator）
中央协调 Agent 把任务分配给工作 Agent。
[CODE BLOCK]
用例： 复杂工作流，需要并行工作。
实现：
[CODE BLOCK]
通过聊天协调
Agent 之间可通过聊天系统通信：
[CODE BLOCK]
> [!NOTE]
> 聊天消息有角色标记。Agent 之间消息用 role=agent，人与 Agent 之间用 role=human。
通过变量协调
用变量进行轻量协调（锁、标志位）：
[CODE BLOCK]
最佳实践
> [!TIP]
> - 为不同关注点使用独立 Mind — 不要把 coder 和 reviewer 的记忆混在一起
> - 在聊天中标记 Agent — 让地址清晰
> - 用任务分配工作 — 而非聊天（聊天用于讨论）
> - 实现幂等性 — Agent 可能重试失败的操作
> - 记录一切 — 把决策存入记忆以备审计
下一步
- 持久化 LLM Agent
- LLM Cookbook
- Webhook 自动化
────────────────────────────────────────────────────────────
# 构建持久化 LLM Agent
SUMMARY: 使用 Synapse 构建跨会话记忆的 LLM Agent 的分步指南。
概览
本指南带你构建一个使用 Synapse 跨会话持久化上下文的 LLM Agent。完成时，你的 Agent 将能够：
- 会话开始时回放过往上下文
- 随时存储新学到的内容
- 跨会话跟踪多步任务
- 通过异步聊天与人类通信
架构
[CODE BLOCK]
第 1 步：设置 Mind Key
[CODE BLOCK]
第 2 步：会话启动协议
每次会话开始时，回放所有记忆：
[CODE BLOCK]
第 3 步：存储新学习内容
每当 Agent 学到值得记住的内容：
[CODE BLOCK]
第 4 步：任务管理
跨会话跟踪多步工作：
[CODE BLOCK]
第 5 步：与人类异步聊天
在工具调用之间轮询消息：
[CODE BLOCK]
第 6 步：会话结束协议
会话结束时，存储最终上下文：
[CODE BLOCK]
完整模式
[CODE BLOCK]
最佳实践
> [!TIP]
>
> - 始终先回放 — 不加载上下文就不要开始工作
> - 主动存储 — 不要等到会话结束
> - 使用有意义的 key — 、，而非
> - 给一切打标签 — 标签支撑搜索与过滤
> - 设定合理的优先级 — 不是所有事都
下一步
- LLM Cookbook — 实用模式
- 记忆最佳实践
- 多 Agent 协调
────────────────────────────────────────────────────────────
# 自愈测试流水线
SUMMARY: 使用 Synapse 记忆构建能从失败中学习并自动适应的测试流水线。
自愈测试流水线
传统测试套件在 UI 变化时会失败。自愈测试使用 Synapse 记忆从过往失败中学习并适应 — 减少不稳定测试与维护成本。
概念
[CODE BLOCK]
1. 测试运行
2. 若失败，存储失败信息（出了什么错、为什么、如何修）
3. 下次运行：执行前回放相关失败
4. 自动应用已知修复
实现
第 1 步：测试包装器
为每个测试包装记忆回放/存储：
[CODE BLOCK]
第 2 步：自适应测试逻辑
在测试内部检查已知失败并应用修复：
[CODE BLOCK]
第 3 步：恢复策略
把恢复策略作为记忆存储：
[CODE BLOCK]
第 4 步：CI 集成
[CODE BLOCK]
第 5 步：失败分析仪表板
[CODE BLOCK]
最佳实践
> [!TIP]
> - 存储 traceback — 它们包含失败的确切行
> - 按测试名打标签 — 加速过滤
> - 使用 分类 — 与常规记忆分离
> - 设为 优先级 — 失败绝不能被遗忘
> - 定期清理 — 删除已解决问题的记忆
> - 不要存储敏感数据 — 凭据、PII
常见失败模式存储
| 失败类型 | 存储内容 |
|--------------|---------------|
| 元素未找到 | 尝试的选择器、页面状态、截图 |
| 超时 | 等待时间、等待的对象 |
| 断言失败 | 期望值与实际值 |
| 网络错误 | URL、状态码、响应体 |
| 权限被拒 | 所需权限、当前用户角色 |
下一步
- iOS 自动化测试
- 记忆最佳实践
- 错误恢复 Cookbook
────────────────────────────────────────────────────────────
# Webhook 自动化
SUMMARY: 在记忆变化时触发外部系统 — 同步、通知、自动化。
Webhook 自动化
Webhook 让你在 Synapse 事件触发时启动外部系统。本指南涵盖常见自动化模式。
常见模式
模式 1：关键记忆通知
当存储关键记忆时发送 Slack 消息：
[CODE BLOCK]
注册 Webhook：
[CODE BLOCK]
模式 2：同步到外部系统
把记忆同步到 Notion、Obsidian 或任何外部知识库：
[CODE BLOCK]
模式 3：触发 CI/CD
当存储 “release” 记忆时触发部署：
[CODE BLOCK]
模式 4：人类消息唤醒 Agent
当人类发送聊天消息时触发 LLM Agent 运行：
[CODE BLOCK]
模式 5：聚合指标
跟踪记忆增长、聊天活动、任务完成：
[CODE BLOCK]
签名验证
始终验证 Webhook 签名以防伪造：
[CODE BLOCK]
重试逻辑
Synapse 会以指数退避重试失败的 Webhook。你的处理程序应该：
1. 快速返回 200 — 不要同步做重活
2. 排队处理 — 使用后台作业系统
3. 保持幂等 — 同一事件可能被投递多次
[CODE BLOCK]
调试 Webhook
检查投递历史
Webhook 投递会被记录。查看你的 Webhook 最近的投递：
[CODE BLOCK]
手动测试 Webhook
[CODE BLOCK]
常见问题
| 问题 | 修复 |
|-------|-----|
| 4xx 响应 | 检查处理程序是否返回 200 |
| 5xx 响应 | 服务器错误 — 查看你的应用日志 |
| 超时 | 快速返回 200，异步排队处理 |
| 重复投递 | 让处理程序幂等 |
| 签名不匹配 | 确认 secret 正确 |
最佳实践
> [!TIP]
> - 始终验证签名 — 绝不跳过这一步
> - 快速返回 200 — 不要阻塞 Synapse
> - 保持幂等 — 处理重复投递
> - 使用具体事件 — 而非
> - 监控投递失败 — 设置告警
下一步
- Webhooks API
- Cron 与调度器
- 持久化 LLM Agent
## 分类：概念
Synapse 背后的架构与概念。
────────────────────────────────────────────────────────────
# Synapse 架构
SUMMARY: Synapse 的构建方式 — Fastify、PostgreSQL、FTS5、向量嵌入、MCP Server。
Synapse 架构
Synapse 是一个多租户记忆 API，基于 Fastify、带 FTS5 的 PostgreSQL，以及可选的用于语义搜索的向量嵌入服务构建。
高层架构
[CODE BLOCK]
核心组件
1. Synapse API（Fastify）
主 HTTP 服务器。负责处理：
- REST 端点（、、 等）
- 认证（Agent 用 Mind Key，人类用 JWT）
- 限速（仅 认证）
- 静态文件服务（、 等 Web UI）
- Webhook 派发
基于 Fastify 5 构建，注重性能。生产环境运行在端口 12800。
2. 带 FTS5 的 PostgreSQL
主数据存储。使用 PostgreSQL 及 FTS5 扩展进行全文搜索。
关键表：
| 表 | 用途 |
|-------|---------|
| | 用户账户 |
| | Mind 范围（每个 Mind 有一个 Mind Key） |
| | 记忆记录，附带 FTS5 虚拟表 |
| | 任务管理 |
| | 聊天记录 |
| | 持久化脚本 |
| | Webhook 注册 |
| | 定时任务 |
| | 键值存储 |
| | 审计日志 |
FTS5 可在所有记忆内容上实现亚毫秒级全文搜索。详见 FTS5 搜索。
3. Embeddings 服务（可选）
为支持语义搜索，Synapse 会为记忆内容生成向量嵌入。这些向量与记忆一起存储，用于相似度搜索。
- 提供方：可配置（OpenAI、本地模型等）
- 作为 列存储在 表中
- 由 端点使用
- 详见 语义搜索
4. MCP Server（独立服务）
Synapse MCP Server 作为独立进程运行（端口 13100）。它：
- 通过 Model Context Protocol 暴露 79 个工具
- 支持 stdio、HTTP/SSE 和 WebSocket 传输
- 将 MCP 工具调用转换为 Synapse API 调用
- 多租户：每个会话使用一个 Mind Key
5. Browser 代理（独立服务）
为支持浏览器自动化，独立的基于 Playwright 的服务运行在端口 13000。MCP Server 可调用它以执行 工具。
6. SSH 代理（独立服务）
为支持基于 SSH 的远程命令，独立服务运行在端口 12900。
多租户模型
[CODE BLOCK]
每个 Mind 完全隔离。Mind Key 仅授予访问某一个 Mind 的权限。JWT 授予访问用户账户的权限（用于管理 Mind）。
详见 多租户。
请求流
记忆存储请求
[CODE BLOCK]
记忆搜索请求
[CODE BLOCK]
部署
Synapse 作为 Docker 容器部署。参见 ：
[CODE BLOCK]
性能特征
| 操作 | 延迟 | 吞吐 |
|-----------|---------|------------|
| 记忆存储 | 5ms | 1000+ req/s |
| 记忆回放 | 20ms | 500 req/s |
| FTS5 搜索 | 10ms | 800 req/s |
| 语义搜索 | 50ms | 200 req/s |
| 聊天轮询 | 5ms | 2000 req/s |
下一步
- 记忆模型
- 多租户
- FTS5 搜索
────────────────────────────────────────────────────────────
# FTS5 全文搜索
SUMMARY: Synapse 如何使用 SQLite FTS5 实现亚毫秒级的全文记忆搜索。
FTS5 全文搜索
Synapse 使用 FTS5（Full-Text Search 5）实现快速、灵活的记忆搜索。本页介绍其工作原理以及如何高效使用。
什么是 FTS5？
FTS5 是一个 SQLite 扩展（也可通过扩展在 PostgreSQL 中使用），提供全文搜索能力。它能够：
- 为文本内容建立索引以实现快速关键词搜索
- 支持布尔运算符（AND、OR、NOT）
- 支持用引号进行短语匹配
- 支持用 进行前缀匹配
- 按相关性对结果排序
Synapse 使用 FTS5 为所有记忆内容建立索引，可在数千条记忆上实现亚毫秒级搜索。
Synapse 如何使用 FTS5
当你 时：
1. 记忆内容存储到 表
2. 内容也插入到 FTS5 虚拟表
3. FTS5 自动分词并建立索引
当你 时：
1. Synapse 使用 FTS5 语法解析查询
2. 对 FTS5 索引执行
3. 按 过滤（租户隔离）
4. 返回排序后的结果
查询语法
简单关键词搜索
[CODE BLOCK]
返回包含 "docker" 的记忆。
多关键词（隐式 AND）
[CODE BLOCK]
返回同时包含 "docker" 和 "swarm" 的记忆。
短语匹配
[CODE BLOCK]
返回包含完整短语 "docker swarm" 的记忆。
前缀匹配
[CODE BLOCK]
返回包含以 "docker" 开头的词的记忆（例如 "dockers"、"dockerfile"、"dockerize"）。
布尔 OR
[CODE BLOCK]
返回包含 "docker" 或 "kubernetes" 的记忆。
布尔 NOT
[CODE BLOCK]
返回包含 "docker" 但不包含 "swarm" 的记忆。
分组
[CODE BLOCK]
返回包含 "docker" 或 "kubernetes" 但不包含 "test" 的记忆。
实用示例
查找关于某个项目的记忆
[CODE BLOCK]
查找精确短语
[CODE BLOCK]
排除测试记忆
[CODE BLOCK]
按技术查找
[CODE BLOCK]
排序
FTS5 使用 BM25 算法按相关性排序。影响因素：
- 词频（词条出现频率）
- 逆文档频率（更稀有的词条排名更高）
- 文档长度（包含该词条的较短文档排名更高）
- 列权重（标题 > 内容）
结果按相关性返回（最相关的在前）。
性能
| 操作 | 延迟 |
|-----------|---------|
| 搜索 100 条记忆 | < 5ms |
| 搜索 1,000 条记忆 | < 10ms |
| 搜索 10,000 条记忆 | < 25ms |
| 搜索 100,000 条记忆 | < 100ms |
FTS5 针对读密集型工作负载做了高度优化。
局限性
词干提取
FTS5 默认不做词干提取。"running" 和 "run" 是不同的词条。
变通方案： 使用前缀匹配：
拼写容错
FTS5 不支持模糊匹配。拼写错误会返回零结果。
变通方案： 使用语义搜索（）进行概念匹配。
停用词
常见词（the、a、an、is）会被索引，但对搜索意义不大。FTS5 会自动处理。
FTS5 与语义搜索对比
| 方面 | FTS5 | 语义搜索 |
|--------|------|-----------------|
| 速度 | 亚毫秒级 | 50-100ms |
| 匹配方式 | 精确关键词 | 概念 |
| 拼写容错 | 无 | 一定程度 |
| 词干提取 | 无 | 隐式 |
| 是否需要嵌入 | 否 | 是 |
| 适合场景 | 具体术语 | 概念 |
当你知道关键词时使用 FTS5。当你想找“关于 X 的记忆”且 X 用不同方式描述时，使用语义搜索。
最佳实践
> [!TIP]
> - 使用具体术语 — "docker swarm" 优于 "container orchestration"
> - 为短语加引号 — 确保短语匹配
> - 用前缀覆盖变体 — 可捕获 "deploy"、"deployment"、"deploying"
> - 排除噪声 — 过滤掉测试记忆
> - 结合标签 — 缩小结果范围
下一步
- 语义搜索
- Memory API
- 记忆最佳实践
────────────────────────────────────────────────────────────
# 记忆模型
SUMMARY: 记忆的结构 — 分类、键、标签、优先级、来源、验证。
记忆模型
Synapse 的记忆模型专为 LLM Agent 设计 — 既结构化以保证可靠回放，又足够灵活以适应任何领域。
记忆结构
[CODE BLOCK]
字段
| 字段 | 类型 | 必填 | 说明 |
|-------|------|----------|-------------|
| | string | 自动 | 唯一 ID（memxxx） |
| | enum | ✅ | 8 种分类之一 |
| | string | ✅ | 稳定标识符（用于更新） |
| | string | ✅ | 记忆内容（任意文本） |
| | string[] | – | 用于搜索和过滤 |
| | enum | – | low、normal、high、critical（默认：normal） |
| | enum | 自动 | user、agent（存储者） |
| | bool | 自动 | 是否经过人类验证 |
| | float | – | 0.0 到 1.0（user 默认 1.0，agent 默认 0.7） |
| | timestamp | – | 何时遗忘此记忆 |
| | string | 自动 | 所属 Mind |
| | timestamp | 自动 | 首次存储时间 |
| | timestamp | 自动 | 最后修改时间 |
分类
八种分类覆盖了常见的 LLM Agent 用例：
| 分类 | 用途 | 内容示例 |
|----------|---------|-----------------|
| | 用户是谁 | "User is Michael Schäfer, software engineer in Berlin" |
| | 用户偏好 | "Prefers concise technical responses" |
| | 可验证的事实 | "Office is in Berlin, timezone Europe/Berlin" |
| | 项目状态 | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| | 用户的技能 | "Advanced Python, 10+ years" |
| | 过去犯的错 | "Forgot to bump npm version — CI failed" |
| | 会话上下文 | "Currently reviewing PR #42" |
| | 其他备注 | "Try Redis for caching next sprint" |
Key：稳定标识符
字段至关重要 — 它是更新记忆而不产生重复的方式。
[CODE BLOCK]
Key 规则：
- 在 (category, mind) 内必须唯一
- 使用
- 以分类为前缀提高可读性：、
- 创建后不要修改 key
Tags：用于搜索
标签可加速过滤与搜索：
[CODE BLOCK]
标签最佳实践：
- 每条记忆 2-5 个标签（不要过度打标签）
- 使用小写以保持一致
- 使用项目名、主题、技术名
- 标签不区分大小写
优先级
| 优先级 | 何时使用 | 回放行为 |
|----------|-------------|-----------------|
| | 身份、法律、不可逆信息 | 始终位于回放顶部 |
| | 进行中的项目、关键偏好 | 回放中突出显示 |
| | 大多数记忆（默认） | 标准回放顺序 |
| | 临时、知道就好的信息 | 可能被摘要 |
按优先级排序（critical 在前），其次按时间。
来源：User 与 Agent
记忆用 标记：
- — 由人类存储（通过 JWT 或人类 UI）
- — 由 LLM Agent 存储（通过 Mind Key）
这会影响：
- 验证： 记忆自动验证， 记忆不自动验证
- 置信度： 默认 1.0， 默认 0.7
- 回放： 会标记未验证记忆为 "(unverified)"
> [!NOTE]
> 对 来源的记忆应保持适当的怀疑。它们可能是推断或假设而来，而非用户直接陈述。
验证
标志表示人类已确认该记忆：
- 记忆：自动验证（）
- 记忆：默认未验证（）
通过以下方式验证记忆：
[CODE BLOCK]
> [!NOTE]
> 验证需要 JWT（人类认证），而非 Mind Key（Agent 认证）。这确保只有人类才能将记忆标记为已验证。
置信度
字段（0.0 到 1.0）表示记忆的可靠程度：
- 1.0 — 用户直接陈述
- 0.7 — 由 Agent 推断
- 0.5 — 不确定，需要验证
- 0.0 — 明确存疑
存储时设置置信度：
[CODE BLOCK]
过期
为时效性记忆设置 ：
[CODE BLOCK]
已过期的记忆不会出现在 中（但仍在数据库中）。使用 查看即将过期的记忆。
记忆生命周期
[CODE BLOCK]
回放行为
返回为 LLM 上下文优化的纯文本摘要：
[CODE BLOCK]
- 按优先级排序（critical → low），其次按时间
- 未验证记忆用 标记
- 包含标签以提供上下文
- 纯文本（无需解析 JSON）
下一步
- Memory API
- 记忆最佳实践
- FTS5 搜索
────────────────────────────────────────────────────────────
# 多租户与隔离
SUMMARY: Synapse 如何在用户与 Mind 之间隔离数据 — 详解安全边界。
多租户与隔离
Synapse 是多租户的：多个用户，每个用户可有多个 Mind，彼此完全隔离。本页说明隔离模型。
租户层级
[CODE BLOCK]
隔离层级
第 1 级：用户隔离
每个用户账户相互隔离。Alice 不能：
- 查看 Bob 的 Mind
- 访问 Bob 的记忆（即使有她的 JWT）
- 列出 Bob 的账户信息
强制方式：所有表上都有 列，JWT 包含 ，所有查询按 过滤。
第 2 级：Mind 隔离
在同一用户下，每个 Mind 相互隔离。Mind A 不能：
- 查看 Mind B 的记忆
- 访问 Mind B 的任务、聊天、脚本
强制方式：所有数据表都有 列，Mind Key 包含 ，所有查询按 过滤。
> [!CRITICAL]
> Mind Key 隔离是首要的安全边界。泄露的 Mind Key 会授予对该 Mind 数据的完全访问权限 — 但仅限该 Mind。
认证令牌
| 令牌 | 范围 | 可访问内容 |
|-------|-------|-------------------|
| Mind Key | 单个 Mind | 仅该 Mind 的数据 |
| JWT | 用户账户 | 账户管理（创建/列出/删除 Mind） |
| Computer Token | 单台计算机 | 该计算机的命令 |
跨 Mind 访问
同一用户内
用户可通过 JWT 访问自己所有的 Mind（例如 列出全部）。但要读写记忆数据，需要具体的 Mind Key。
跨用户
用户之间不能互访数据 — 除非通过 Sharing API 显式共享某个 Mind：
[CODE BLOCK]
共享后，Bob 可通过他的 JWT 访问 Mind A（若 则只读）。
安全边界
[CODE BLOCK]
常见多租户模式
模式 1：单用户，单 Mind
个人 LLM Agent 用户最常见。
- 1 个用户账户
- 1 个 Mind
- 1 个 Mind Key
- 所有记忆在同一范围
模式 2：单用户，多 Mind
适合有多种上下文的用户（工作、个人、项目）。
- 1 个用户账户
- N 个 Mind（例如 "work"、"personal"、"project-x"）
- N 个 Mind Key
- 每个 LLM 会话使用一个 Mind Key
模式 3：团队共享 Mind
适合团队协作某个项目。
- 1 个用户创建 Mind（获得 Mind Key）
- 创建者通过 JWT 共享给团队成员
- 所有团队成员通过 JWT 访问（或共享的 Mind Key）
> [!WARNING]
> 共享 Mind Key 会授予完全读写权限。团队协作时，请优先使用 Sharing API（基于 JWT），而不是直接共享 Mind Key。
模式 4：SaaS 提供商
适合将 Synapse 作为记忆层嵌入的应用。
- 每个客户 = 1 个用户账户
- 每个客户项目 = 1 个 Mind
- 应用按客户/项目存储 Mind Key
- 客户之间完全隔离
隔离验证
测试：Mind Key 不能访问其他 Mind
[CODE BLOCK]
测试：JWT 不能直接读取记忆数据
[CODE BLOCK]
最佳实践
> [!TIP]
> - 每个项目/上下文使用一个 Mind — 隔离是你的朋友
> - 绝不共享 Mind Key — 改用 Sharing API
> - 泄露时轮换 Mind Key（删除 Mind、创建新 Mind）
> - 审计共享的 Mind — 定期检查
> - 人类 UI 用 JWT — 不要把 Mind Key 暴露给最终用户
下一步
- Authentication
- Mind Key 与 JWT
- 架构
────────────────────────────────────────────────────────────
# 语义搜索（向量嵌入）
SUMMARY: 使用向量嵌入进行概念性记忆搜索 — 按意义查找，而非仅按关键词。
语义搜索（向量嵌入）
Synapse 支持基于向量嵌入的语义搜索。与 FTS5（关键词匹配）不同，语义搜索按意义查找记忆 — 即使没有关键词匹配也能找到。
工作原理
[CODE BLOCK]
什么是嵌入？
嵌入是文本的数值向量表示。意义相近的文本有相近的向量。Synapse 为每条记忆的内容生成一个向量（例如 1536 维）。
余弦相似度
为找到语义相似的记忆，Synapse 计算查询向量与每条记忆向量之间的余弦相似度。相似度越高 = 越相关。
何时使用语义搜索
在以下场景使用语义搜索：
- 想要“关于 X 的记忆”，而 X 与存储时的描述不同
- FTS5 返回零结果（无关键词匹配）
- 想要概念聚合（例如所有“部署”相关记忆，即使有些写的是“发布”）
- 查询是一个问题：“我们如何处理认证？”
在以下场景使用 FTS5：
- 已知精确关键词
- 需要布尔逻辑（AND、OR、NOT）
- 需要亚毫秒级响应
- 想要短语匹配
端点
GET /memory/semantic-search
[CODE BLOCK]
响应：
[CODE BLOCK]
示例
查找部署相关记忆
[CODE BLOCK]
返回关于 "deployment"、"release"、"publishing"、"rolling out" 等的记忆。
查找认证模式
[CODE BLOCK]
返回关于 login、auth、JWT、session 管理、OAuth 等的记忆。
查找相似记忆
[CODE BLOCK]
使用语义相似度（基于共享标签 + 嵌入向量）。
嵌入生成
何时生成嵌入？
- 存储记忆时 — 若配置了嵌入服务，则同步生成嵌入
- 批量生成 — 为缺失嵌入的记忆生成
- 异步更新 — 内容更新时重新生成嵌入
嵌入提供方
Synapse 支持可配置的嵌入提供方：
- OpenAI（、）
- 本地模型（通过 Ollama 等）
- 自定义（实现 embeddings 接口）
通过环境变量配置：
[CODE BLOCK]
批量生成
对于很多记忆缺少嵌入的 Mind：
[CODE BLOCK]
性能
| 操作 | 延迟 |
|-----------|---------|
| 生成嵌入（OpenAI） | 100-200ms |
| 语义搜索（1k 条记忆） | 50-100ms |
| 语义搜索（10k 条记忆） | 200-500ms |
| 批量生成（100 条记忆） | 10-20s |
> [!NOTE]
> 由于向量计算，语义搜索比 FTS5 慢。已知关键词时用 FTS5，概念查询用语义搜索。
局限性
嵌入成本
若使用 OpenAI，生成嵌入需要付费（text-embedding-3-small 约 $0.02 / 1M tokens）。对于平均每条 100 tokens 的 10,000 条记忆，约 $0.02 — 可忽略不计。
冷启动
在配置嵌入之前存储的记忆没有嵌入。请运行 补齐。
提供方依赖
如果嵌入提供方宕机，语义搜索会优雅降级（返回空结果或错误）。FTS5 仍可正常工作。
当嵌入不可用时
如果未配置嵌入服务：
- 返回 503 Service Unavailable
- 仍可正常工作（只是不生成嵌入）
- FTS5 搜索仍可正常工作
最佳实践
> [!TIP]
> - 概念查询用语义搜索 — "我们如何处理 X？"
> - 具体术语用 FTS5 — "docker swarm"
> - 定期补齐嵌入 —
> - 监控提供方健康 — 语义搜索依赖它
> - 与标签结合 — 语义 + 标签过滤缩小结果范围
下一步
- FTS5 搜索
- Memory API
- 架构
## 分类：LLM 食谱
LLM 智能体的方案与模式。
────────────────────────────────────────────────────────────
# 聊天轮询模式
SUMMARY: 如何在工具调用之间轮询人类消息而不阻塞工作流。
聊天轮询模式
聊天系统是异步的 — 人类可以在你工作时留言。本模式展示如何在轮询消息时不阻塞工作流。
模式
[CODE BLOCK]
在工具调用之间轮询，而不是在紧密循环中轮询。
为什么在工具调用之间轮询？
- 不要阻塞 — 紧密循环轮询浪费 API 调用
- 不要错过消息 — 轮询太慢意味着响应迟缓
- 最佳点 — 每 30-60 秒轮询一次，或每次工具调用后
实现
基本轮询
[CODE BLOCK]
模式 1：每次工具调用后轮询
[CODE BLOCK]
模式 2：基于时间的轮询
[CODE BLOCK]
模式 3：事件驱动（用 Webhook）
如需实时通知，注册 Webhook：
[CODE BLOCK]
然后你的 Webhook 处理程序可以唤醒 Agent：
[CODE BLOCK]
消息处理模式
模式：先确认后处理
[CODE BLOCK]
模式：排队批量处理
[CODE BLOCK]
模式：优先级路由
[CODE BLOCK]
轮询频率
| 用例 | 频率 |
|----------|-----------|
| 交互式 Agent（人类在等待） | 每 5-10 秒 |
| 后台 Agent | 每 30-60 秒 |
| 批处理 | 每 5 分钟 |
| Webhook 触发 | 不轮询 — 用 Webhook |
> [!WARNING]
> 频率超过每 5 秒一次会浪费 API 调用。 在有待处理消息时会立即返回，因此更快轮询无益。
多 Agent 聊天
用于 Agent 之间通信：
[CODE BLOCK]
最佳实践
> [!TIP]
> - 在工具调用之间轮询 — 不要紧密循环
> - 立即确认 — 让人类知道你收到了
> - 异步处理 — 不要在长任务上阻塞
> - 实时场景用 Webhook — 轮询有延迟
> - 不要超过每 5 秒一次 — 浪费 API 调用
常见问题
消息丢失
- 会自动把消息标记为已读
- 如果你不处理，它们就消失了
- 修复： 始终在返回前处理消息
重复回复
- 如果处理程序崩溃，可能回复两次
- 修复： 让处理程序幂等（检查是否已回复）
响应缓慢
- 每 60 秒轮询意味着最高 60 秒延迟
- 修复： 每 10-30 秒轮询，或用 Webhook
下一步
- Chat API
- 会话启动模式
- 错误恢复
────────────────────────────────────────────────────────────
# Agent 错误恢复
SUMMARY: LLM Agent 如何处理错误并恢复 — 重试、存储、学习。
Agent 错误恢复
错误总会发生。网络故障、API 返回 500、Mind Key 失效。本指南展示 LLM Agent 如何优雅地处理错误并从中学习。
错误处理原则
1. 退避重试 — 瞬时错误常常会自行恢复
2. 存储错误 — 从模式中学习
3. 优雅降级 — 不要让整个会话崩溃
4. 通知人类 — 对于无法解决的错误
HTTP 错误处理
指数退避重试
[CODE BLOCK]
认证错误处理
[CODE BLOCK]
把错误存为记忆
发生错误时，存储它们以便未来会话学习：
[CODE BLOCK]
常见错误场景
场景 1：Mind Key 无效
[CODE BLOCK]
场景 2：网络错误
[CODE BLOCK]
场景 3：被限速
[CODE BLOCK]
场景 4：服务器错误（5xx）
[CODE BLOCK]
场景 5：工具调用失败
[CODE BLOCK]
模式：熔断器
对于反复出现的失败，暂时停止尝试：
[CODE BLOCK]
最佳实践
> [!TIP]
> - 始终重试瞬时错误 — 网络会失败、服务器会卡顿
> - 不要重试客户端错误（4xx） — 它们不会自行修复
> - 把错误存为记忆 — 从模式中学习
> - 关键错误通知人类 — 他们需要知道
> - 优雅降级 — 部分工作好过崩溃
> - 使用熔断器 — 不要疯狂调用失败的服务
下一步
- 错误 API 参考
- 会话启动模式
- 自愈测试
────────────────────────────────────────────────────────────
# 记忆打标签策略
SUMMARY: 如何为记忆打标签以实现高效搜索与过滤 — 可扩展的标签体系。
记忆打标签策略
标签是可扩展记忆检索的秘诀。本指南展示如何为记忆打标签，让正确的记忆在正确的时间被找到。
为什么标签重要
没有标签，你只有扁平的全文搜索。有了标签，你就有结构化导航：
[CODE BLOCK]
标签带来：
- 快速过滤 —
- 范围搜索 —
- 分组 — 找出某项目的所有 “mistake” 记忆
- 交叉引用 — 共享标签的记忆相互关联
标签体系
项目标签
用项目名作为标签：
[CODE BLOCK]
技术标签
用技术名：
[CODE BLOCK]
主题标签
用主题分类：
[CODE BLOCK]
状态标签
用状态指示：
[CODE BLOCK]
类型标签
用类型指示：
[CODE BLOCK]
打标签规则
规则 1：每条记忆 2-5 个标签
太少 = 可发现性差。太多 = 噪声。
[CODE BLOCK]
规则 2：小写、连字符
[CODE BLOCK]
规则 3：使用一致的词汇
建立一套标签词汇并坚持使用：
[CODE BLOCK]
规则 4：按搜索意图打标签
问自己：“我以后会怎么搜这条记忆？”
[CODE BLOCK]
模式
模式 1：项目 + 主题
[CODE BLOCK]
搜索：（所有 Synapse 项目记忆）
搜索：（Synapse 的部署记忆）
模式 2：类型 + 领域
[CODE BLOCK]
搜索：（所有错误）
搜索：（部署错误）
模式 3：层级式
用于项目内的子项目：
[CODE BLOCK]
搜索：（所有 Synapse）
搜索：（仅 docs 子项目）
模式 4：状态跟踪
[CODE BLOCK]
常见用例
找出某项目的所有决策
[CODE BLOCK]
找出某领域的所有错误
[CODE BLOCK]
找活跃工作
[CODE BLOCK]
找关于某技术的记忆
[CODE BLOCK]
标签维护
定期审查
[CODE BLOCK]
合并标签
如果有不一致的标签（ 和 ），合并它们：
[CODE BLOCK]
最佳实践
> [!TIP]
> - 尽早建立词汇表 — 从第 1 天起就用一致的标签
> - 按搜索意图打标签 — 你以后会怎么找它？
> - 2-5 个标签是最佳点 — 太少或太多都不好
> - 小写 + 连字符 — 而非
> - 定期审查 — 合并重复、移除未用
下一步
- 记忆最佳实践
- FTS5 搜索
- 任务驱动工作流
────────────────────────────────────────────────────────────
# 会话启动模式
SUMMARY: 每个 LLM Agent 都应遵循的标准会话启动序列。
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.
会话启动模式
每个 LLM Agent 会话都应遵循这一标准启动序列。跳过步骤会导致上下文丢失、错过消息、遗忘任务。
模式
[CODE BLOCK]
实现
第 1 步：回放所有记忆
> [!CRITICAL]
> 这是最重要的调用。没有它，你没有任何过往会话的记忆。
[CODE BLOCK]
返回所有记忆的纯文本摘要，按优先级排序。
第 2 步：轮询未读聊天消息
[CODE BLOCK]
返回来自人类的未读消息。会自动把它们标记为已读。
第 3 步：检查进行中的任务
[CODE BLOCK]
返回你上次会话正在做的任务。
第 4 步：构建上下文
把三份响应合并到你的系统 prompt 中：
[CODE BLOCK]
第 5 步：处理待处理项
[CODE BLOCK]
完整示例
[CODE BLOCK]
常见错误
> [!WARNING]
> - 跳过回放 — 你以零上下文开始，重蹈过往错误
> - 忘记轮询聊天 — 人类消息无人响应
> - 忽略进行中的任务 — 工作执行到一半被遗忘
> - 什么也不存 — 会话未产生持久价值
变体
最小模式（低上下文 LLM）
对于上下文窗口小的 LLM，跳过完整回放：
[CODE BLOCK]
然后按需搜索具体主题：
[CODE BLOCK]
激进模式（长期运行 Agent）
对于运行数小时的 Agent，加上周期性重新回放：
[CODE BLOCK]
下一步
- 记忆打标签策略
- 任务驱动工作流
- 聊天轮询模式
────────────────────────────────────────────────────────────
# 任务驱动工作流
SUMMARY: 使用 Synapse 任务驱动可跨会话存活的多步 LLM 工作流。
任务驱动工作流
任务不仅仅是待办 — 它们是持久化 LLM 工作流的骨架。为多步工作创建任务，可确保跨会话连续性，并提供完成情况的审计轨迹。
为什么用任务驱动？
无任务：
- LLM 每次会话开始时不知道要做什么
- 多步工作执行到一半被遗忘
- 没有已完成工作的记录
有任务：
- LLM 立即恢复进行中的任务
- 多步工作跨会话存活
- 内置完成工作的审计轨迹
模式
[CODE BLOCK]
实现
第 1 步：为多步工作创建任务
[CODE BLOCK]
第 2 步：在任务描述中跟踪进度
[CODE BLOCK]
第 3 步：跨会话恢复
[CODE BLOCK]
第 4 步：完成并归档
[CODE BLOCK]
完整示例：部署工作流
[CODE BLOCK]
任务层级
对于复杂工作，使用父子任务关系：
[CODE BLOCK]
搜索子任务：
[CODE BLOCK]
状态工作流
[CODE BLOCK]
Pending
任务已创建但未开始。用于计划的工作。
In Progress
正在处理中。用进度更新描述。
Done
成功完成。描述应包含总结。
Cancelled
已放弃。描述应包含原因。
最佳实践
> [!TIP]
> - 多步工作创建任务 — 单步工作不需要任务
> - 用进度更新描述 — 支持恢复
> - 活跃工作用 high 优先级 — 在回放中浮现
> - 完成后标记 done — 不要让任务停留在 inprogress
> - 把完成总结存为记忆 — 长期参考
常见模式
模式：Bug 修复工作流
[CODE BLOCK]
模式：研究工作流
[CODE BLOCK]
下一步
- 会话启动模式
- 聊天轮询模式
- 错误恢复
## 分类：常见问题
常见问题与疑难解答。
────────────────────────────────────────────────────────────
# API 常见问题
SUMMARY: 常见 API 问题 — 认证、限速、错误处理、端点发现。
API 常见问题
关于 Synapse API 的常见问题。
如何认证？
两种方式：
1. Mind Key（用于数据端点）：
2. JWT（用于账户端点）：
或通过查询参数（限速 60 次/分钟）：
参见 Authentication。
Mind Key 和 JWT 有何区别？
- Mind Key：租户范围，永不过期，用于记忆/聊天/任务数据
- JWT：用户范围，7 天过期，用于账户/Mind 管理
参见 Mind Key 与 JWT。
为什么收到 401 Unauthorized？
常见原因：
1. 缺少 头
2. Mind Key 无效（确认它以 开头）
3. 在需要 Mind Key 的地方用了 JWT（或反之）
4. Mind Key 已被吊销
修复： 校验你的令牌。参见 Authentication。
为什么收到 404 Not Found？
你用了错误的端点路径。Synapse 只有 中列出的路径。
修复： 调用 查看所有有效路径。不要猜测。
为什么收到 429 Too Many Requests？
你使用了 查询参数认证，它被限速到 60 次/分钟。
修复： 改用 头（无限制）。
参见 限速。
如何列出所有端点？
[CODE BLOCK]
如何找到正确的端点？
1. 查看 获取机器可读列表
2. 查看 获取完整 API 文档
3. 浏览 查看文档系统
4. 使用 获取 OpenAPI 3.0 规范
能用 GET 代替 POST 吗？
部分 POST 端点有对应的 GET 版本，供只能使用 URL 的工具使用：
- ↔
- ↔
- ↔
通过 查看可用的 GET 变体。
如何处理错误？
所有错误都返回 JSON：
[CODE BLOCK]
参见 错误与错误处理。
请求体大小限制是多少？
10 MB。对于更大的 payload（例如文件上传），请使用 multipart 端点。
API 支持 CORS 吗？
支持。所有端点都返回：
[CODE BLOCK]
有 SDK 吗？
有：
- Node.js：
- MCP：
详见 API 概览。
如何分页？
使用 和 ：
[CODE BLOCK]
默认 limit：100。最大：500。
能按分类或标签过滤记忆吗？
可以：
[CODE BLOCK]
如何搜索记忆？
两种方式：
1. FTS5 关键词搜索：
2. 语义搜索：
参见 FTS5 搜索 与 语义搜索。
如何更新记忆？
用相同的 + 发起 — 已存在的记忆会被更新，不会重复。
[CODE BLOCK]
如何删除记忆？
[CODE BLOCK]
能批量删除吗？
可以：
[CODE BLOCK]
下一步
- API 概览
- 错误与错误处理
- Authentication
────────────────────────────────────────────────────────────
# 通用常见问题
SUMMARY: 关于 Synapse 的常见问题 — 它是什么、如何工作、面向谁。
通用常见问题
关于 Synapse 的常见问题。
Synapse 是什么？
Synapse 是为 LLM Agent 提供的持久化记忆 API。它为你的 AI 助手提供一个永久的、可查询的大脑，跨会话保留。LLM 不再在聊天关闭时遗忘一切，而是通过简单的 HTTP API 存储和检索记忆。
了解更多： Synapse 是什么？
Synapse 面向谁？
- 需要持久状态的 LLM Agent 开发者
- 运行本地 LLM 与自定义 Agent 的 重度用户
- 构建带共享记忆 AI 助手的 团队
- 跨会话串联 LLM 调用的 自动化工程师
Synapse 免费吗？
Synapse 托管在 ，供个人免费使用。如需自托管，请参见 仓库。
Synapse 与 ChatGPT Memory 有何不同？
| 特性 | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| 存储 | OpenAI 服务器 | 你的服务器 |
| API 访问 | 否 | 是（REST + MCP） |
| 多租户 | 否 | 是（Mind） |
| 自定义分类 | 否 | 是（8 种分类） |
| 全文搜索 | 有限 | FTS5 + 语义 |
| 可自托管 | 否 | 是 |
哪些 LLM 与 Synapse 兼容？
任何能发起 HTTP 调用或使用 MCP 的 LLM：
- Claude（Anthropic）— 通过 MCP 或直接 API
- GPT-4 / GPT-3.5（OpenAI）— 通过 function calling + API
- Gemini（Google）— 通过 function calling + API
- Llama / Mistral（本地）— 通过自定义集成
- 任何 LLM 通过 Synapse MCP Server
我需要自己托管 Synapse 吗？
不需要。托管版本 供公众使用。自托管是可选的（出于隐私、定制或离线环境考虑）。
能存多少数据？
托管版本没有硬性限制。典型用法：
- 每个 Mind 100-1000 条记忆
- 每条记忆 1-10 KB（content 字段）
- 总计：每个 Mind 约 10 MB
如需更大规模，请自托管。
我的数据私密吗？
是的。每个 Mind 相互隔离（参见 多租户）。其他用户看不到你的数据。托管服务商（Schäfer Services）有访问权限，但不会查看用户数据。
如需最高隐私，请自托管。
能导出我的数据吗？
可以。使用 将所有记忆导出为 JSON。参见 备份与恢复。
如果丢失了 Mind Key 怎么办？
Mind Key 在创建时只显示一次。如果丢失：
1. 用邮箱/密码登录获取 JWT
2. 通过 创建新 Mind
3. 保存新的 Mind Key
4. （可选）通过 删除旧 Mind
你无法恢复丢失了 key 的 Mind 中的记忆。
多个 LLM Agent 能共享一个 Mind 吗？
可以。所有使用同一 Mind Key 的 Agent 共享该 Mind 的数据。关于多 Agent 协作，请参见 多 Agent 协调。
Synapse 能离线工作吗？
不能，Synapse 需要连接到服务器（托管或自托管）。对于离线 LLM，请在本地运行 Synapse。
记忆搜索有多快？
- FTS5 关键词搜索：1000 条记忆 < 10ms
- 语义搜索：1000 条记忆 50-100ms
- 完整回放：1000 条记忆 < 50ms
详见 FTS5 搜索。
没有 LLM 也能用 Synapse 吗？
可以。Synapse 是通用的记忆 API。任何能从持久化、可搜索、带分类和标签的键值存储中受益的应用都可以使用它。
下一步
- Synapse 是什么？
- 快速开始
- API 常见问题
────────────────────────────────────────────────────────────
# MCP 常见问题
SUMMARY: 关于 MCP 集成的常见问题 — 工具、传输、故障排查。
MCP 常见问题
关于 Synapse MCP Server 的常见问题。
MCP 是什么？
MCP（Model Context Protocol）是 Anthropic 推出的开放标准，用于 LLM 与工具的集成。无需把 API 文档粘到 prompt 里，而是将工具注册到 MCP Server，LLM 像调用原生函数一样调用它们。
参见 MCP 是什么？。
Synapse MCP 暴露多少个工具？
跨 12 个分类共 79 个工具：memory、chat、scheduler、tasks、scripts、computers、push、user、utility、visualization、sharing、webhooks、browser。
完整列表请见 MCP 是什么？。
支持哪些 MCP 客户端？
- Claude Desktop（macOS、Windows）
- Claude Code（终端）
- Cursor（IDE）
- Continue.dev（VS Code、JetBrains）
- Cline（VS Code）
- 任何兼容 MCP 的客户端
配置示例请见 Claude Desktop 配置。
支持哪些传输方式？
1. stdio（本地，桌面端推荐）
2. HTTP/SSE（远程，多租户）
3. WebSocket（移动端，高吞吐）
如何配置 Claude Desktop？
编辑 ：
[CODE BLOCK]
参见 Claude Desktop 配置。
为什么 Claude Desktop 中看不到工具？
1. 完全重启 Claude Desktop（macOS 上 Cmd+Q）
2. 检查配置文件是否为有效 JSON
3. 确认已安装 Node.js 18+
4. 查看 MCP 日志：
参见 MCP 故障排查。
如何切换到另一个 Mind？
在 MCP 配置中修改 并重启客户端。
若要同时使用多个 Mind，可用不同的 Mind Key 运行多个 MCP Server 实例。
能限制暴露的工具吗？
可以，使用 工具配置文件：
- ：8 个组合工具（约 500 tokens）
- ：25 个工具（约 2,500 tokens）
- ：119 个工具（约 8,250 tokens，默认）
通过 环境变量或 头设置。
如何调试 MCP 问题？
1. 手动运行 MCP Server：
2. 查看客户端日志（因客户端而异）
3. 验证 Mind Key 是否有效：
4. 检查 Synapse 健康：
参见 MCP 故障排查。
MCP Server 是免费的吗？
是的。npm 包 是开源的。托管在 的 MCP Server 供公众免费使用。
可以自托管 MCP Server 吗？
可以：
[CODE BLOCK]
MCP 与直接 API 调用有何不同？
| 方面 | 直接 API | MCP |
|--------|-----------|-----|
| LLM 需要知道 | URL、请求头、认证 | 仅工具名 |
| 认证处理 | 手动 | 自动（环境变量） |
| 工具发现 | 读 /endpoints | 通过 MCP 协议自动 |
| 错误处理 | 手动 | 标准化 |
| 适合场景 | 自定义集成 | LLM Agent |
可以构建自己的 MCP 客户端吗？
可以。使用官方 MCP SDK：
- TypeScript：
- Python：
参见 自定义 MCP 客户端。
如何报告 MCP Bug？
提交 issue：
请包含：
- MCP Server 版本
- 客户端名称与版本
- 操作系统
- 相关日志
- 复现步骤
下一步
- MCP 是什么？
- Claude Desktop 配置
- MCP 故障排查
────────────────────────────────────────────────────────────
# 故障排查常见问题
SUMMARY: Synapse 常见问题的解决方案 — 认证、网络、数据、部署。
故障排查常见问题
Synapse 常见问题的解决方案。
无法登录
症状
- 返回 401
- "Invalid email or password"
解决方案
1. 确认邮箱正确 — 区分大小写
2. 检查密码 — 至少 6 个字符
3. 若无账户请先注册：
4. （如已配置 SMTP）通过 Web UI 重置密码
丢失了 Mind Key
症状
- 无法访问记忆
- Mind Key 已删除或丢失
解决方案
Mind Key 无法找回。你必须：
1. 登录获取 JWT：
2. 列出 Mind：（用 JWT）
3. 创建新 Mind：
4. 保存新的 Mind Key
5. （可选）删除旧 Mind：
旧 Mind 中的数据将丢失，除非你能找到 Mind Key。
API 调用返回 401
症状
- 所有 API 调用返回 401 Unauthorized
- "Mind Key fehlt oder ungültig"
解决方案
1. 确认请求头格式：
2. 检查 Mind Key 是否以 开头（不是 ，那是 JWT）
3. 直接测试：
[CODE BLOCK]
4. Mind Key 可能已被吊销 — 创建新 Mind
参见 Authentication。
API 调用返回 404
症状
- 404 Not Found
- "Route not found"
解决方案
> [!CRITICAL]
> 不要猜测端点路径。只有 中列出的路径才存在。
1. 检查有效端点：
2. 逐字符对比 URL — 区分大小写，无尾斜杠
3. 检查 HTTP 方法 — 与 是不同的
API 调用返回 429
症状
- 429 Too Many Requests
- "Rate limit exceeded"
解决方案
1. 改用头部认证（无限制）：
[CODE BLOCK]
2. 如果必须用 ，请等待 秒
参见 限速。
记忆搜索返回零结果
症状
- 返回空
- 确知有记忆存在
解决方案
1. 确认记忆存在：
2. 检查搜索语法 — FTS5 有特定语法
3. 尝试更简单的查询 — 用 而非
4. 概念查询用语义搜索：
参见 FTS5 搜索。
记忆未持久化
症状
- POST /memory 返回成功
- GET /memory/recall 看不到它们
解决方案
1. 确认使用相同的 Mind Key — 不同 key = 不同 Mind
2. 检查响应 — POST 应返回
3. 改用 GET /memory（JSON 列表）代替 /memory/recall（文本）
4. 检查过滤条件 — 或 可能将它们隐藏
Claude Desktop 中看不到工具
症状
- Claude Desktop 显示 0 个工具
- 没有 🔌 图标
解决方案
1. 完全重启 Claude Desktop（Cmd+Q）
2. 确认配置文件为有效 JSON
3. 检查已安装 Node.js 18+
4. 手动运行 MCP：
5. 查看日志：
参见 MCP 故障排查。
Synapse 离线
症状
- 无法访问 synapse.schaefer.zone
- curl 超时
解决方案
1. 检查你的网络 — 试试其他网站
2. 检查 Synapse 健康：
3. 等待 — 可能是临时故障或部署中
4. 查看状态页（如有）
自托管请检查 Docker 容器状态与数据库连接。
数据库错误
症状
- 500 Internal Server Error
- "Database connection failed"
解决方案
自托管：
1. 检查 PostgreSQL 是否运行：
2. 检查环境变量 DATABASEURL
3. 检查迁移：
4. 检查磁盘空间：
托管版本：联系支持。
Webhook 未触发
症状
- 已注册 Webhook 但未收到回调
- URL 没有 POST 请求到达
解决方案
1. 确认 URL 可达：
2. 检查事件过滤 — 匹配所有记忆事件
3. 测试 Webhook：
4. 检查 Webhook 是否启用：
5. 验证 SSL — Synapse 要求 Webhook URL 使用有效 HTTPS
参见 Webhooks API。
Cron 任务未运行
症状
- 已创建 Cron 任务但不触发
- 不更新
解决方案
1. 检查调度语法 — 必须是有效的 5 字段 cron 或整数秒
2. 确认端点被允许 — 必须是 http(s)，无私有 IP
3. 检查任务是否启用：
4. 等待下一个计划时间 — cron 不是即时的
参见 Cron 与调度器。
需要更多帮助？
1. 查看现有文档：
2. 搜索文档：
3. 提交 issue：
4. 联系：参见 页面
下一步
- 错误与错误处理
- API 常见问题
- MCP 故障排查