Synap Memory

synap-mcp-server

托管的远程 MCP 服务（Streamable HTTP），将现有的 Synap 公共 REST 操作重新封装为 MCP 工具，让无代码平台（Gumloop、n8n）只需粘贴 MCP URL 和 Bearer token，即可为其 Agent 提供持久记忆。

这是一个无状态适配器——不引入新的后端、存储或流水线。每次工具调用都映射到一个现有的 REST 操作，传入的 Bearer synap_<key> token 会原样转发给负责身份验证的 synap-cloud。

• 公共端点（生产环境）：https://synap-mcp.maximem.ai/mcp
• 健康检查：https://synap-mcp.maximem.ai/health

工具

工具	REST 操作	说明
log_exchange	POST /api/v1/memories/create（mode=long-range）	转发每一轮对话；由提取逻辑决定保留哪些内容。user_id 用于按最终用户划分范围，customer_id 仅适用于 B2B（参见“范围划分”）；conversation_id 可选。
recall_context	POST /v1/context/{client|user|customer}/fetch（mode=fast）	热路径；不传 ID ⇒ 客户端范围。customer 范围仅适用于 B2B。
list_recent_memories	广泛的 /v1/context/.../fetch（不带查询）	调试 /“测试我的记忆”。范围划分规则相同。
check_memory_status	GET /api/v1/memories/status/{id}	不接受范围 ID：ingestion_id 已标识该次写入。

范围划分：一份约定，两种模式

REST API 会强制执行此规则。这不是建议；该规则自 2026-08-26 07:07 UTC 起已在生产环境生效。

实例模式（user_context_isolation）	应传入的内容	否则会发生什么
equals_customer（B2C）	仅传入 user_id。用户 ID 就是完整身份标识。	任何 customer_id 都会被拒绝，并返回 HTTP 400。/v1/context/customer/fetch 完全不可用。
strict（B2B）	必须传入 customer_id，并同时传入 user_id。	仅传入 user_id 会报错。此约定不会改变这一点。

GET /api/v1/auth/whoami 会通过 user_context_isolation 报告模式。此服务会针对每个 token 读取一次该值，并在 B2C 实例上本地拒绝 customer_id，让模型收到告知其应传入内容的说明，而不是无法处理的状态码。如果无法读取模式，则不会拒绝请求，仍以 API 为准。

完全不传 ID ⇒ 客户端范围（凭据间共享），两种模式下均有效。注意：客户端范围的写入不会显示在仪表板的 Memories 页面上（关系型），因此在需要仪表板可见性时，建议按用户划分范围。从 n8n 表达式 / Gumloop 输入中填入 user_id，并在 log_exchange 和 recall_context 中传入相同的值，确保写入和读取对应同一个人。

**Host 标头。**服务器禁用了 MCP 传输的 DNS 重绑定检查（它位于代理之后，并通过 Bearer 身份验证），因此任何反向代理都可以转发实际的 Host——无需使用修改 Host 的变通方案。

本地运行

pip install -e ".[dev]"
SYNAP_API_URL=http://localhost:8000 uvicorn synap_mcp_server.server:app --port 8090
curl http://localhost:8090/health        # {"status":"ok",...}

向预期 Agent 报告轮次

MCP 服务不是 Agent。它会向其他人的 Agent 提供工具，并且每次只接收一个无状态 HTTP 调用，因此 Agent 执行的大部分操作在这里都不可见：调用方的工具调用、工具结果和推理都不会传到此进程，也没有任何信息会告知无状态服务对话已经结束。这些内容不会被报告，因为无事可报。

轮次确实存在。log_exchange 会将用户消息和助手回复作为参数传入。设置 MCP_STREAM_EVENTS=true 后，每次记录的交互也会作为对话轮次，通过 POST /v1/events/batch 报告；这是通往同一监听路径的 HTTP 入口，gRPC 流也会向该路径发送数据，因此预期 Agent 看到的是轮次，而不仅仅是从中提取出的记忆。与其他集成不同，此服务不使用 SDK 的 gRPC 流：它不持有 SDK，在请求之间不保留状态，而且每个请求都可能携带不同租户的密钥，因此每个密钥对应一个流会形成无上限的连接池，没有任何机制会关闭这些连接。将它迁移到 SDK 上，就得为一个用不到该流所返回内容的调用方重写传输层。

它也不会取代 Synap 的任何压缩机制：调用方的 Agent 会保留自己的历史记录，这里的工具不会返回对话内容。

此功能默认关闭，这是有意为之。启用后，每次 log_exchange 都会额外调用一次后端，将轮次写入对话历史（除长期文档外），并运行预期 Agent，这会产生模型调用费用。

它默认关闭还有第二个原因。Synap 会在对话被压缩时提取内容，这会在记录十条消息后开始。如果改为将每次交互记录为轮次，而不再写入长期文档，记忆就会一直延迟到那时才生成（下一次 recall_context 会找不到任何内容，而且也没有 ingestion_id 可供检查）；如果同时记录轮次和长期文档，则每次交互都会被提取两次。

无论是否启用此功能，以下行为都不会改变：log_exchange 仍会将长期文档加入队列，并仍会返回 check_memory_status 和 wait_for_processing 所依赖的 ingestion_id。轮次报告尽力而为，绝不会改变工具的响应。若轮次缺少 user_id 或 conversation_id，则完全不会报告，因为 events 路由要求两者都存在。

测试

pip install -e ".[dev]"
pytest -q

配置（env）

变量	默认值	含义
SYNAP_API_URL	http://synap-cloud:8000	后端 REST API 基础 URL（生产环境中的内部 Docker 主机名）。
MCP_PORT	8090	监听端口。
MCP_RECALL_TIMEOUT_S	10	召回（读取）超时时间。
MCP_INGEST_TIMEOUT_S	8	记录/摄取（写入）超时时间。
MCP_DEFAULT_MAX_RESULTS	10	默认召回结果数量。
MCP_STREAM_EVENTS	false	同时将记录的交互作为对话轮次报告给预期 Agent。启用前请先阅读上文。
MCP_EVENTS_TIMEOUT_S	4	轮次报告超时时间。尽力而为；报告失败绝不会改变工具的响应。
LOG_LEVEL	INFO	日志级别。
ENVIRONMENT	production	在 /health 中报告的环境。

服务端未配置 Synap API 密钥——最终用户的密钥会随每个请求以 Bearer 令牌的形式传入。

有关平台设置指南（Gumloop、n8n）和部署详情，请参阅 Synap MCP 文档。