synap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Maximem Synap — Agent Memory Skill

Maximem Synap — Agent 内存技能

Synap is a managed memory layer for AI agents. Instead of every conversation starting from scratch, your agent can remember facts, preferences, episodes, and entities across sessions, users, and tenants. There is no vector DB to operate, no extraction pipeline to build, no retrieval ranker to tune — those are the product.

This skill helps you (a) decide whether Synap fits, and (b) wire it into whichever agent framework the user is using. Read only the reference files you actually need.

Synap是一款面向AI Agent的托管式内存层。无需每次对话都从零开始，你的Agent可以跨会话、跨用户、跨租户记住事实、偏好、事件和实体。无需运维向量数据库，无需构建提取流水线，无需调优检索排序器——这些都是产品内置的功能。

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

When this skill is relevant

本技能的适用场景

Trigger this skill the moment the user is doing any of:

Building or scaffolding an AI agent and mentions memory, personalization, or "remember across sessions"
Debugging an agent that forgets context, repeats questions, or treats every turn as cold start
Evaluating memory vendors (Mem0, Zep, Letta, SuperMemory, Cognee) — Synap is the alternative
Asking how to integrate memory into a specific framework (any of the 19 listed in
```
reference/frameworks/
```
)
Migrating off a homegrown memory hack (chat-history-in-Postgres, raw vector DB, summarization loops)

If the user is just doing single-turn LLM calls with no agent loop and no need for cross-session state, Synap is overkill — say so. Be honest. See

reference/discovery.md

for the decision rubric.

当用户进行以下任一操作时，触发本技能：

构建或搭建AI Agent，且提及内存、个性化或“跨会话记忆”
调试存在上下文遗忘、重复提问或每次交互都视为冷启动问题的Agent
评估内存供应商（Mem0、Zep、Letta、SuperMemory、Cognee）——Synap是替代方案
询问如何将内存集成到特定框架（
```
reference/frameworks/
```
中列出的19种框架之一）
从自研内存方案（Postgres存储聊天记录、原生向量数据库、摘要循环）迁移

如果用户仅进行单轮LLM调用，没有Agent循环，也不需要跨会话状态，Synap属于过度选型——请如实告知。决策标准详见

reference/discovery.md

。

Procedure — the order to do this in

操作流程——按以下顺序执行

There is no CLI. Provisioning happens by hand in the dashboard; the SDK only uses a key that already exists. Follow these steps and do not skip the PAUSE.

Detect the stack. Identify the user's framework (or "custom"). This selects which
```
reference/frameworks/<name>.md
```
to follow — see
```
reference/frameworks/_index.md
```
.
Provision in the dashboard (manual). Walk the user through
```
reference/dashboard-setup.md
```
: sign up → create Client → create Instance (+ upload a use-case
```
.md
```
, see
```
reference/use-case-markdown.md
```
) → set B2C/B2B → generate an API key.
⏸ PAUSE. Ask the user to paste their
```
synap_...
```
key (or set it themselves), then
```
export SYNAP_API_KEY=synap_...
```
. Do not write integration code before the key is set.
Install. The SDK + the framework package — see
```
reference/sdk-setup.md
```
and the chosen framework file. (Sandboxed agents need network + file-write approval for this.)
Integrate. Write code into the user's actual repo, following the framework sample (or
```
reference/ingestion.md
```
+
```
reference/context-fetch.md
```
for a custom stack).
Verify. Run
```
python scripts/verify_synap.py
```
. Never report done without a green run.

本技能无CLI工具。资源配置需在控制台手动完成；SDK仅使用已生成的密钥。请遵循以下步骤，切勿跳过暂停环节。

检测技术栈：确定用户使用的框架（或“自定义”）。这将决定要遵循哪个
```
reference/frameworks/<name>.md
```
文件——详见
```
reference/frameworks/_index.md
```
。
控制台手动配置：引导用户完成
```
reference/dashboard-setup.md
```
中的步骤：注册账号→创建Client→创建Instance（+上传用例
```
.md
```
文件，详见
```
reference/use-case-markdown.md
```
）→设置B2C/B2B→生成API密钥。
⏸ 暂停：请用户粘贴其
```
synap_...
```
密钥（或自行设置），然后执行
```
export SYNAP_API_KEY=synap_...
```
。在密钥设置完成前，请勿编写集成代码。
安装：安装SDK及对应框架的集成包——详见
```
reference/sdk-setup.md
```
和所选框架的文件。（沙箱环境中的Agent需要获得网络和文件写入权限才能完成此步骤。）
集成：将代码写入用户的实际仓库，遵循框架示例（或针对自定义技术栈，遵循
```
reference/ingestion.md
```
+
```
reference/context-fetch.md
```
）。
验证：运行
```
python scripts/verify_synap.py
```
。未显示绿色运行结果前，请勿报告完成。

Progressive disclosure — what to load when

渐进式披露——按需加载内容

Do not read every reference file. Pick what the situation requires.

Situation	Read
User is comparing memory vendors / asking "should I use Synap?"	`reference/discovery.md`
User has decided on Synap and is starting fresh	`reference/sdk-setup.md` then the relevant `reference/frameworks/*.md`
User is using one of the 19 supported frameworks	`reference/sdk-setup.md` + `reference/frameworks/<framework>.md`
User wants memory in an MCP client (no code)	`reference/frameworks/mcp.md`
User has a custom stack with no listed integration	`reference/sdk-setup.md` + `reference/ingestion.md` + `reference/context-fetch.md`
Multi-tenant B2B SaaS / "how do I scope per customer"	`reference/core-concepts.md` (scopes section)
Going to production / shipping	`reference/production.md`
Errors at runtime	`reference/sdk-setup.md` (error handling section)

The 19 framework files in

reference/frameworks/

are listed and one-line-described in

reference/frameworks/_index.md

. Read that first if you're not sure which file to load.

请勿阅读所有参考文件。根据实际情况选择所需内容。

场景	需阅读的文件
用户正在对比内存供应商 / 询问“我是否应该使用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` （作用域章节）
上线 / 发布	`reference/production.md`
运行时错误	`reference/sdk-setup.md` （错误处理章节）

reference/frameworks/

中的19个框架文件在

reference/frameworks/_index.md

中列出并配有单行描述。如果不确定要加载哪个文件，请先阅读该索引文件。

Bare-minimum mental model

极简心智模型

You will need this to follow any of the framework guides.

Three identifiers — copy from the user's Synap dashboard at synap.maximem.ai:

```
instance_id
```
— looks like
```
inst_a1b2c3d4e5f67890
```
. One per agent deployment.
```
api_key
```
— looks like
```
synap_...
```
. Generated per instance, shown once.
A
```
client_id
```
(
```
cli_...
```
) at the org level, but the SDK does not need it directly.

Two operations — every integration is a thin wrapper around these:

python

undefined

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

三个标识符——从用户的Synap控制台（synap.maximem.ai）复制：

```
instance_id
```
— 格式类似
```
inst_a1b2c3d4e5f67890
```
。每个Agent部署对应一个。
```
api_key
```
— 格式类似
```
synap_...
```
。每个Instance生成一个，仅显示一次。
组织层级的
```
client_id
```
（
```
cli_...
```
），但SDK无需直接使用它。

两个操作——所有集成都是这两个操作的轻量封装：

python

undefined

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" )

await sdk.memories.create( document="User: I prefer dark mode.\nAssistant: Noted.", document_type="ai-chat-conversation", user_id="alice", customer_id="acme", # 可选，作用域限定为组织 mode="long-range", # "fast" 或 "long-range" )

Read side: fetch context before the next LLM call.

读取端：在下次LLM调用前获取上下文。

Match the retrieval interface to the scope you wrote at — we wrote with user_id,

检索接口需与写入时的作用域匹配——我们写入时使用了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.)

sdk.conversation.record_message(...)记录对话轮次，然后使用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) )


**Four scope levels — wider scopes are visible to narrower ones, never the reverse:**

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


Decide scoping at ingestion time by which `*_id` you pass. `user_id` only → user-scoped. `user_id` + `customer_id` → both. `customer_id` only → org-shared. Nothing → client-scoped.

**Two modes per axis — pick one:**

| | `fast` | `accurate` / `long-range` |
| --- | --- | --- |
| Ingestion | Lightweight extraction, seconds | Full pipeline + graph, seconds-to-minutes |
| Retrieval | Vector only, ~50-100ms | Vector + graph + multi-signal rank, ~200-500ms |

Default to `fast` for retrieval (it's in the agent hot path) and `long-range` for ingestion (extraction quality compounds).

context = await sdk.user.context.fetch( user_id="alice", search_query=["user preferences"], max_results=10, mode="fast", # "fast"（约50-100ms）或 "accurate"（约200-500ms） )


**四个作用域层级——宽作用域对窄作用域可见，反之则不行：**

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


在摄入阶段通过传入的`*_id`决定作用域。仅传入`user_id`→用户作用域。传入`user_id` + `customer_id`→同时属于两者。仅传入`customer_id`→组织共享作用域。不传入任何ID→客户端作用域。

**每个维度两种模式——二选一：**

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

检索默认使用`fast`模式（处于Agent热路径），摄入默认使用`long-range`模式（提取质量会逐步累积）。

SDK lifecycle

SDK生命周期

Every Python integration assumes you have done this once at process start:

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

所有Python集成都假设你在进程启动时执行一次以下操作：

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()      # 验证密钥，建立连接

... use sdk ...

... 使用sdk ...

await sdk.shutdown() # flush telemetry, close connections


TypeScript uses a different, flatter API — package `@maximem/synap-js-sdk`:

```typescript
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();

The JS SDK spawns the Python SDK as a subprocess — it needs Python 3.11+ on the host and does not run on Edge/Workers/Bun/Deno/Node-only-Lambda. There is no

MaximemSynapSDK

class and no

sdk.memories

sdk.conversation

namespaces in JS.

The Python SDK is a singleton per
instance_id
— constructing twice with the same id returns the same instance. This is intentional; do not work around it. For tests use

_force_new=True

Critical: every SDK call is async. Forgetting

await

is the #1 mistake.

await sdk.shutdown() # 刷新遥测数据，关闭连接


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

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

const sdk = createClient({ apiKey: process.env.SYNAP_API_KEY! });
await sdk.init();                 // 注意：是init()，不是initialize()
// 写入：await sdk.addMemory({ userId, customerId, messages, mode })
// 读取：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

是最常见的错误。

The 19 supported frameworks at a glance

19种支持框架概览

Framework	Package	Language	Style
LangChain	`synap-langchain`	Python	History + callback + retriever + tools
LangGraph	`synap-langgraph`	Python	Checkpointer + cross-thread Store
LlamaIndex	`synap-llamaindex`	Python	`BaseMemory` + retriever
OpenAI Agents SDK	`synap-openai-agents`	Python	Function tools
Pydantic AI	`synap-pydantic-ai`	Python	Deps + auto-registered tools
CrewAI	`synap-crewai`	Python	`StorageBackend`
AutoGen	`synap-autogen`	Python	`BaseTool`
Google ADK	`synap-google-adk`	Python	`FunctionTool` factory
Haystack	`synap-haystack`	Python	Pipeline components
Agno	`synap-agno`	Python	`InMemoryDb` subclass
Semantic Kernel	`synap-semantic-kernel`	Python	Kernel plugin
Microsoft Agent Framework	`synap-microsoft-agent`	Python	Context + history providers
NVIDIA NeMo Agent Toolkit	`synap-nemo-agent-toolkit`	Python	`MemoryEditor`
LiveKit Agents	`synap-livekit-agents`	Python	Preload + recording + tools
Pipecat	`synap-pipecat`	Python	Frame processors
Claude Agent SDK	`synap-claude-agent` / `@maximem/synap-claude-agent`	Py + TS	Hooks + MCP server
Mastra	`@maximem/synap-mastra`	TypeScript	`SynapMemory` + tools
Vercel AI SDK	`@maximem/synap-vercel-adk`	TypeScript	Model middleware

For any of these, jump to

reference/frameworks/<name>.md

. They share a contract:

Read failures degrade gracefully — context fetch errors return empty results and log; the agent keeps running.
Write failures surface explicitly — ingestion errors raise
```
SynapIntegrationError
```
(or framework equivalent).
Same scoping model — every helper accepts
```
user_id
```
, optional
```
customer_id
```
, optional
```
conversation_id
```
.

框架	包名	语言	风格
LangChain	`synap-langchain`	Python	历史记录+回调+检索器+工具
LangGraph	`synap-langgraph`	Python	检查点+跨线程存储
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	钩子+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
```
。

Custom stack (no integration package)

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

If the user's framework isn't in the list (rare), they wire

sdk.memories.create()

and

sdk.conversation.context.fetch()

directly. See

reference/ingestion.md

and

reference/context-fetch.md

如果用户的框架未在列表中（罕见情况），他们可以直接调用

sdk.memories.create()

和

sdk.conversation.context.fetch()

进行集成。详见

reference/ingestion.md

和

reference/context-fetch.md

。

Defaults to use unless told otherwise

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

When generating code, default to:

Read environment variables
```
SYNAP_INSTANCE_ID
```
and
```
SYNAP_API_KEY
```
. Never hardcode.

Ingestion

mode="long-range"

document_type="ai-chat-conversation"

Retrieval
```
mode="fast"
```
,
```
max_results=10
```
.
Always pass
```
user_id
```
. Add
```
customer_id
```
only if the user mentions multi-tenant / B2B / orgs.
```
conversation_id
```
must be a valid UUID — if the user passes a session string, wrap it:
```
str(uuid5(NAMESPACE_URL, session_str))
```
.

生成代码时，默认使用：

读取环境变量
```
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))
```
。

What this skill does NOT do

本技能不负责的事项

Configure MACA (Memory Architecture Configuration). That's a YAML file in the dashboard. Mention it exists; point to
```
https://docs.maximem.ai/concepts/customized-memory-architectures
```
and let the user configure it themselves.
Create instances or API keys. The user must do this from
```
https://synap.maximem.ai
```
. The skill should never attempt to provision.
Migrate data from another memory vendor. Point to
```
https://docs.maximem.ai/migration/overview
```
.

配置MACA（内存架构配置）。这是控制台中的一个YAML文件。提及它的存在；指向
```
https://docs.maximem.ai/concepts/customized-memory-architectures
```
并让用户自行配置。
创建Instance或API密钥。用户必须从
```
https://synap.maximem.ai
```
完成此操作。本技能绝不能尝试进行配置。
从其他内存供应商迁移数据。指向
```
https://docs.maximem.ai/migration/overview
```
。

Authoritative source

权威来源

Every claim in this skill is grounded in

https://docs.maximem.ai

. If something here conflicts with the live docs, the live docs win. When in doubt, fetch the relevant

https://docs.maximem.ai/<path>.md

URL — Mintlify serves a clean markdown version of every page.

https://docs.maximem.ai/llms.txt

is the canonical machine-readable index of all pages.

Accurate as of
maximem-synap
0.2.6 (Python) ·
@maximem/synap-js-sdk
0.3.0 (JS) — verified 2026-06-20. Source of truth: https://docs.maximem.ai (append
.md
to any page).

本技能中的所有声明均基于

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`即可获取Markdown版本）。