企业官网建设流程全解析

Mem0 Python 与 TypeScript SDK 差异详解：方法命名、参数传递与架构行为对照指南

【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain

本文基于 Mem0 仓库中维护的 Python/TypeScript SDK 对照速查文档（differences.md），系统梳理两套 Mem0 Platform SDK 在导入方式、构造参数、方法命名、参数传递约定、底层 HTTP 行为与独占功能上的全部差异，并结合仓库源码验证这些差异的真实实现。读完后，你可以在 Python 与 TypeScript 之间无损迁移 Mem0 代码，避免"方法找不到、参数传错位置、过滤器不生效"这类跨语言迁移时的典型错误。

导入与构造：两套 SDK 的入口差异

Mem0 提供两条产品线：Platform SDK（托管 API，MemoryClient）与OSS SDK（本地运行，Memory）。两条产品线在两种语言中的导入方式与构造约定如下：

两种 SDK 在未显式传入 key 时都会回退读取MEM0_API_KEY环境变量。这一点在 Python 侧源码中可以确认：MemoryClient 构造函数 中self.api_key = api_key or os.getenv("MEM0_API_KEY")，取不到时直接抛出ValueError("Mem0 API Key not provided...")。

构造行为上的几个源码细节值得注意：

• 默认 host：Python 的MemoryClient默认host为https://api.mem0.ai（main.py），TypeScript 侧同样在构造函数中回退到https://api.mem0.ai。
• 初始化即鉴权：Python 客户端在构造时同步调用_validate_api_key()向/v1/ping/发起验证请求（main.py），并从中解析出org_id与project_id；TypeScript 客户端则采用非阻塞策略——构造函数中this.initialized = this._resolveIdentity()异步解析身份信息，记忆读写请求不会等待 ping 完成，且同一组 (host, apiKey) 凭据在同一进程内共享一次 ping 结果（mem0.ts）。这是两套实现中"同步急切初始化"与"异步惰性初始化"的显著架构差异。
• Project 子对象的注入：Python 客户端在构造末尾直接挂载self.project = Project(...)（main.py），这正是后文client.project.*用法的来源；TypeScript 没有这个子对象，项目管理是平铺的实例方法。

方法命名：snake_case 对 camelCase 的完整对照

下表完整继承自仓库速查文档，覆盖了 Platform SDK 的全部记忆操作、项目管理、Webhook 与导出接口：

规则：Python 一律使用snake_case，TypeScript 一律使用camelCase。上表每一行都能在两侧源码中找到对应实现，例如 Python 侧的 batch_update/batch_delete、create_webhook、create_memory_export/get_memory_export；TypeScript 侧的 batchUpdate/batchDelete、createWebhook/updateWebhook/deleteWebhook、createMemoryExport/getMemoryExport 以及 getProject/updateProject。

参数传递：kwargs 与 options 对象的约定差异

两套 SDK 传参风格不同，这是迁移时最易踩坑的地方：

# Python: kwargs client.add(messages, user_id="alice", metadata={"source": "chat"}) client.search("query", filters={"user_id": "alice"}, top_k=5, rerank=True)

// TypeScript: options object with camelCase for top-level params, snake_case for filter keys await client.add(messages, { userId: 'alice', metadata: { source: 'chat' } }); await client.search('query', { filters: { user_id: 'alice' }, topK: 5, rerank: true });

v3 命名规则：Python 全程使用snake_case；TypeScript 的顶层方法参数使用camelCase（userId、topK），而过滤器键保留snake_case（user_id、agent_id）。

从源码结构看，Python 侧的方法签名同时接受类型化 options 与**kwargs（如 add、get_all 的options: Optional[...] = None, **kwargs），类型定义位于 mem0/client/types.py（AddMemoryOptions、SearchMemoryOptions等），因此在 Python 中user_id、top_k这类参数统一走snake_case关键字。TypeScript 侧则通过类型化的 options 对象收敛参数，例如GetAllMemoryOptions、SearchMemoryOptions（mem0.types.ts），方法签名如 getAll(options?: GetAllMemoryOptions)。

v3 实体 ID 传递：顶层参数与 filters 的边界

Mem0 v3 对实体标识（user_id/agent_id/app_id/run_id）在不同方法上的传递位置有严格约定：

这条规则在两套 SDK 中都有强制校验，而非仅靠文档约定：

• Python 在 main.py 定义了ENTITY_PARAMS = frozenset({"user_id", "agent_id", "app_id", "run_id"})，用于在search/get_all等接口中拒绝以顶层参数形式传入实体 ID；
• TypeScript 在 mem0.ts 定义了同样的实体参数清单（同时包含 snake_case 与 camelCase 两种写法），rejectTopLevelEntityParams()一旦在search()/getAll()的 options 顶层发现这些键，会抛出明确错误：Top-level entity parameters [...] are not supported in xxx(). Use filters: { user_id: "..." } instead.。

也就是说，即便你在 TypeScript 中"顺手"写成client.search(q, { userId: 'alice' })，客户端也会立刻报错而不是静默失效——这是跨 SDK 迁移时行为可预期的重要保障。

架构差异：HTTP 库、超时与同步/异步模型

以上各项均与源码一致：

• 超时：Python 默认 httpx 客户端timeout=300（main.py）；TypeScript 的 axios 实例timeout: 60000（mem0.ts）。如果你的批量写入在 Python 侧能跑通而迁移到 TS 后偶发超时，应首先怀疑这个 60s/300s 的差异。
• 异步双客户端：Python 同时提供同步MemoryClient（main.py）与AsyncMemoryClient（main.py），后者实现了__aenter__/__aexit__（main.py），因此可以async with AsyncMemoryClient(api_key=...) as client:自动管理连接生命周期；TypeScript 的MemoryClient所有公开方法均为async，无同步版本，也无上下文管理器等价物，连接由 axios 实例自身管理。
• 项目管理的类结构差异：Python 将项目/成员操作封装为独立类，Project 基类与子类 定义在mem0/client/project.py中，并在MemoryClient.__init__中注入为client.project；TypeScript 则把项目操作平铺为实例方法getProject()与updateProject()（mem0.ts），没有project子对象这一层。

Python 独占的 Platform 功能

以下方法只存在于 Python SDK（均已在 mem0/client/main.py 与 mem0/client/project.py 中确认）：

需要注意：reset()是删除所有用户与记忆的破坏性操作，且它只是 Python 客户端方法，TypeScript 侧没有对应封装；同理，项目成员的增删改查在 TS 侧没有客户端方法，需要走 REST API（可参考 docs/api-reference/ 下的组织与项目管理接口文档）。

TypeScript 独占的 Platform 功能

补充一个容易被忽略的实现细节：TypeScript 的ping()不仅是对外暴露的健康检查方法，还承担客户端初始化职责——构造函数 通过它解析telemetryId、organizationId、projectId，并在进程内按凭据缓存（默认上限 50 组，identityCacheMax可调）。Python 侧的等价逻辑是构造时的同步_validate_api_key()，对使用者透明。

OSS 配置与范围参数的命名差异

使用 OSS SDK（本地向量库 + 本地/自托管 LLM）时，配置键与范围参数同样遵循同一套命名规则：

配置键对照：

TypeScript 侧的 OSS 示例（basic.ts）中可以直接看到实际写法，例如historyDbPath: "memory.db"，对应本地记忆历史 SQLite 文件的落盘路径。

范围参数（scope）对照：

这里再次强调边界：OSS 顶层方法参数用 camelCase，Platform filters 内部的键用 snake_case。两个语境不要混用。

常见坑：filter 键永远是 snake_case

跨语言迁移中最频繁的错误是把camelCase习惯带入过滤器。速查文档给出的正确姿势是：无论 Python 还是 TypeScript，搜索与过滤条件中的键一律snake_case；TypeScript 只在顶层方法参数上使用camelCase：

# Python - snake_case in filters results = client.search("query", filters={"user_id": "alice"})

// TypeScript - snake_case in filters, camelCase for top-level params const results = await client.search('query', { filters: { user_id: 'alice' }, topK: 20 });

如果你在 TypeScript 中误写filters: { userId: 'alice' }，过滤器不会报"键名错误"，但按用户过滤的语义会失效（查不到该用户的记忆）；而若在search()顶层误放userId，则会触发前文提到的rejectTopLevelEntityParams显式报错。迁移自查清单可以概括为三条：

1. 顶层方法参数：Pythonsnake_case→ TypeScriptcamelCase（user_id→userId，top_k→topK）；
2. filters内部键：两种语言都保持snake_case；
3. 实体 ID 在search()/get_all()中只能进filters，在add()中只能放顶层。

以上约定与 differences.md 速查表、mem0/client/main.py、mem0-ts/src/client/mem0.ts 的当前实现一致，可直接作为两套 SDK 并行维护或相互迁移时的对照基准。

【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain