限速与配额

Synapse 采用简单、可预测的限速策略，既能防止滥用，又不妨碍正常使用。

限速策略

限速响应头

当你使用 ?key= 认证时，响应会包含限速头：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1782567840

当你超过限制时：

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42
Content-Type: application/json

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Use Authorization header for unlimited access."
}

当你触发限速时

如果收到 429：

1. 改用 Authorization 头（推荐）：

   # 不要这样做：?key=YOUR_MIND_KEY（60 次/分钟限制）
   curl ".../memory/recall?key=YOUR_MIND_KEY"
   
   # 推荐做法：Authorization 头（无限制）
   curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

2. 或等待 Retry-After 秒后重试。

为什么存在 ?key= 限制

?key= 查询参数对于只能使用 URL 的工具（浏览器、open 命令）很方便，但带来安全与性能影响：

• 安全：查询参数会出现在服务器访问日志、浏览器历史和 Referer 头中。限制使用可以降低泄露面。
• 性能：基于查询参数的认证需要基于 IP 的限速器（每次请求都查询 Redis），会增加延迟。基于头的认证可以跳过这一步。
• 防滥用：泄露的 ?key= URL 可能被分享并被疯狂调用。IP 限制可以减小爆炸半径。

推荐模式

LLM Agent

# 始终使用头部认证
headers = {"Authorization": f"Bearer {MIND_KEY}"}
response = requests.get(f"{URL}/memory/recall", headers=headers)

基于浏览器的工具

如果你的工具只能打开 URL：

# 偶尔使用尚可（保持在 60 次/分钟以内）
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# 频繁使用时，请改用支持请求头的工具
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

MCP Server

MCP Server 始终通过 SYNAPSE_MIND_KEY 环境变量使用头部认证 — 不受限速影响。

批量导入

对于批量操作（例如导入 1000 条记忆），请始终使用头部认证。通过 ?key= 进行批量导入会在 1 分钟内触发限速。

配额（Mind 级别）

目前没有针对存储大小或记忆数量的 Mind 级配额。所有限制都在认证/IP 层，不在数据层。未来为多租户公平性可能会调整此策略。

监控你的使用情况

# 查看当前限速状态（使用 ?key= 认证）
curl -i "https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY" | grep -i ratelimit

# 输出：
# X-RateLimit-Limit: 60
# X-RateLimit-Remaining: 58
# X-RateLimit-Reset: 1782567840

下一步

• Authentication
• 错误与错误处理