synap

Maximem Synap — Agent 记忆技能

Synap 是面向 AI Agent 的托管记忆层。借助 Synap，Agent 可以跨会话、用户和租户记住事实、偏好、经历和实体，不必每次对话都从头开始。无需运维向量数据库、构建提取管线或调整检索排序器——这些都由产品负责。

这项技能可帮助你：(a) 判断 Synap 是否适合用户；(b) 将其接入用户正在使用的 Agent 框架。只阅读实际需要的参考文件。

适用场景

用户出现以下任一情况时，立即启用这项技能：

• 构建或搭建 AI Agent，并提到记忆、个性化或“跨会话记住信息”
• 调试会忘记上下文、反复提问或每轮都像冷启动的 Agent
• 评估记忆服务商（Mem0、Zep、Letta、SuperMemory、Cognee）——Synap 是另一种选择
• 询问如何将记忆集成到特定框架（reference/frameworks/ 中列出的 19 种框架中的任何一种）
• 迁移离开自建的记忆方案（存储在 Postgres 中的聊天记录、原始向量数据库、循环摘要）

如果用户只在调用单轮 LLM，没有 Agent 循环，也不需要跨会话状态，Synap 就用得太重了——请如实说明。决策标准见 reference/discovery.md。

流程——按以下顺序执行

没有 CLI。必须手动在控制面板中进行配置；SDK 只会使用已有密钥。请按以下步骤操作，不要跳过暂停步骤。

1. 识别技术栈。 确定用户使用的框架（或“自定义”）。据此选择要遵循的 reference/frameworks/<name>.md——参见 reference/frameworks/_index.md。
2. 在控制面板中配置（手动）。 引导用户参照 reference/dashboard-setup.md：注册 → 创建 Client → 创建 Instance（并上传用例 .md，参见 reference/use-case-markdown.md）→ 设置 B2C/B2B → 生成 API key。
3. ⏸ 暂停。 请用户粘贴其 synap_... 密钥（或自行设置），然后运行 export SYNAP_API_KEY=synap_...。设置好密钥前，不要编写集成代码。
4. 安装。 安装 SDK 和框架包——参见 reference/sdk-setup.md 和所选框架的文件。（沙盒中的 Agent 需要获得网络和文件写入权限。）
5. 集成。 按照框架示例（或自定义技术栈对应的 reference/ingestion.md + reference/context-fetch.md），在用户的实际代码仓库中编写代码。
6. 验证。 运行 python scripts/verify_synap.py。运行结果未通过前，绝不要声称已完成。

渐进式披露——按需加载

不要阅读所有参考文件。根据具体情况选择所需文件。

情况	阅读
用户正在比较记忆服务商／询问“我该使用 Synap 吗？”	reference/discovery.md
用户已决定使用 Synap，并准备从头开始	reference/sdk-setup.md，然后阅读相关的 reference/frameworks/*.md
用户正在使用 19 种受支持框架之一	reference/sdk-setup.md + reference/frameworks/<framework>.md
用户希望在 MCP 客户端中使用记忆（无需编写代码）	reference/frameworks/mcp.md
用户使用的自定义技术栈没有列出的集成	reference/sdk-setup.md + reference/ingestion.md + reference/context-fetch.md
多租户 B2B SaaS／“如何按客户划分范围”	reference/core-concepts.md（scopes 部分）
准备投入生产／发布	reference/production.md
运行时出错	reference/sdk-setup.md（错误处理部分）

reference/frameworks/ 中列出的 19 个框架文件及其单行说明，见 reference/frameworks/_index.md。不确定要加载哪个文件时，请先阅读该文件。

最简心智模型

理解任何框架指南都需要了解以下内容。

三个标识符——从用户的 Synap 仪表板 synap.maximem.ai 中复制：

• instance_id——格式类似 inst_a1b2c3d4e5f67890。每个 Agent 部署一个。
• api_key——格式类似 synap_...。每个实例生成一个，且只显示一次。
• 组织级别的 client_id（cli_...），但 SDK 无需直接使用它。

两个操作——每种集成都只是围绕它们构建的轻量封装：

# Write side: ingest a conversation or document
await sdk.memories.create(
    document="User: I prefer dark mode.\nAssistant: Noted.",
    document_type="ai-chat-conversation",
    user_id="alice",
    customer_id="acme",          # optional, scopes to org
    mode="long-range",           # "fast" or "long-range"
)

# Read side: fetch context before the next LLM call.
# Match the retrieval interface to the scope you wrote at — we wrote with user_id,
# so we read at user scope. (For per-conversation memory, register turns with
# sdk.conversation.record_message(...) first, then use sdk.conversation.context.fetch.)
context = await sdk.user.context.fetch(
    user_id="alice",
    search_query=["user preferences"],
    max_results=10,
    mode="fast",                 # "fast" (~50-100ms) or "accurate" (~200-500ms)
)

四个作用域级别——较宽的作用域对较窄的作用域可见，反之则不然：

USER   →  CUSTOMER  →  CLIENT  →  WORLD
private    org-wide      app-wide   global

在摄取时，通过传入哪些 *_id 来决定作用域。仅传入 user_id → 用户作用域。传入 user_id + customer_id → 两者兼有。仅传入 customer_id → 组织共享。什么都不传 → 客户端作用域。

每个维度有两种模式——任选其一：

	fast	accurate / long-range
摄取	轻量提取，耗时数秒	完整流水线 + 图谱，耗时数秒到数分钟
检索	仅向量，约 50-100ms	向量 + 图谱 + 多信号排序，约 200-500ms

检索默认使用 fast（它位于 Agent 的热路径中），摄取默认使用 long-range（提取质量会持续累积）。

SDK 生命周期

每种 Python 集成都假定你已在进程启动时执行过一次以下操作：

import os
from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK(
    instance_id=os.environ["SYNAP_INSTANCE_ID"],
    api_key=os.environ["SYNAP_API_KEY"],
)
await sdk.initialize()      # validates key, opens connection
# ... use sdk ...
await sdk.shutdown()        # flush telemetry, close connections

TypeScript 使用不同且更扁平的 API——包名为 @maximem/synap-js-sdk：

import { createClient } from "@maximem/synap-js-sdk";

const sdk = createClient({ apiKey: process.env.SYNAP_API_KEY! });
await sdk.init();                 // note: init(), not initialize()
// write: await sdk.addMemory({ userId, customerId, messages, mode })
// read:  await sdk.fetchUserContext({ userId, searchQuery, mode })
await sdk.shutdown();

JS SDK 会将 Python SDK 作为子进程启动——宿主机上需要安装 Python 3.11+，且不能在 Edge/Workers/Bun/Deno/仅支持 Node 的 Lambda 上运行。JS 中没有 MaximemSynapSDK 类，也没有 sdk.memories / sdk.conversation 命名空间。

Python SDK 对每个 instance_id 采用单例模式——使用同一 ID 构造两次会返回同一个实例。这是有意设计的；不要绕过它。测试时请使用 _force_new=True。

**重要：**每次 SDK 调用都是异步的。忘记使用 await 是最常见的错误。

支持的 19 个框架一览

框架	包	语言	风格
LangChain	synap-langchain	Python	历史记录 + 回调 + 检索器 + 工具
LangGraph	synap-langgraph	Python	检查点保存器 + 跨线程 Store
LlamaIndex	synap-llamaindex	Python	BaseMemory + 检索器
OpenAI Agents SDK	synap-openai-agents	Python	函数工具
Pydantic AI	synap-pydantic-ai	Python	依赖项 + 自动注册的工具
CrewAI	synap-crewai	Python	StorageBackend
AutoGen	synap-autogen	Python	BaseTool
Google ADK	synap-google-adk	Python	FunctionTool 工厂
Haystack	synap-haystack	Python	流水线组件
Agno	synap-agno	Python	InMemoryDb 子类
Semantic Kernel	synap-semantic-kernel	Python	Kernel 插件
Microsoft Agent Framework	synap-microsoft-agent	Python	上下文 + 历史记录提供程序
NVIDIA NeMo Agent Toolkit	synap-nemo-agent-toolkit	Python	MemoryEditor
LiveKit Agents	synap-livekit-agents	Python	预加载 + 录制 + 工具
Pipecat	synap-pipecat	Python	帧处理器
Claude Agent SDK	synap-claude-agent / @maximem/synap-claude-agent	Py + TS	Hooks + MCP 服务
Mastra	@maximem/synap-mastra	TypeScript	SynapMemory + 工具
Vercel AI SDK	@maximem/synap-vercel-adk	TypeScript	模型中间件

使用上述任一框架时，请跳转到 reference/frameworks/<name>.md。它们遵循相同的约定：

• 读取失败时优雅降级——上下文获取错误会返回空结果并记录日志；Agent 会继续运行。
• 写入失败时明确报错——摄取错误会抛出 SynapIntegrationError（或框架中的等效异常）。
• 作用域模型相同——每个辅助函数都接受 user_id、可选的 customer_id 和可选的 conversation_id。

自定义技术栈（无集成包）

如果用户使用的框架不在列表中（较少见），则直接接入 sdk.memories.create() 和 sdk.conversation.context.fetch()。请参阅 reference/ingestion.md 和 reference/context-fetch.md。

除非另有说明，否则使用以下默认值

生成代码时，默认：

• 读取环境变量 SYNAP_INSTANCE_ID 和 SYNAP_API_KEY。切勿硬编码。
• 摄取使用 mode="long-range"、document_type="ai-chat-conversation"。
• 检索使用 mode="fast"、max_results=10。
• 始终传入 user_id。只有用户提到多租户、B2B 或组织时，才添加 customer_id。
• conversation_id 必须是有效的 UUID——如果用户传入会话字符串，则将其包装为：str(uuid5(NAMESPACE_URL, session_str))。

此技能不做什么

• 配置 MACA（Memory Architecture Configuration）。这是仪表板中的 YAML 文件。请说明此功能存在，并引导用户前往 https://docs.maximem.ai/concepts/customized-memory-architectures 自行配置。
• 创建实例或 API 密钥。用户必须前往 https://synap.maximem.ai 自行创建。此技能绝不可尝试配置资源。
• 从其他记忆服务商迁移数据。请引导用户前往 https://docs.maximem.ai/migration/overview。

权威来源

此技能中的所有说法均以 https://docs.maximem.ai 为依据。如果此处内容与在线文档冲突，以在线文档为准。如有疑问，请获取相关的 https://docs.maximem.ai/<path>.md URL——Mintlify 会为每个页面提供纯净的 Markdown 版本。

https://docs.maximem.ai/llms.txt 是所有页面的规范机器可读索引。

---

截至 maximem-synap 0.2.6（Python）· @maximem/synap-js-sdk 0.3.0（JS），内容已于 2026-06-20 验证。信息源： https://docs.maximem.ai（在任意页面后追加 .md）。