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托管 APIMemoryClient与OSS SDK本地运行Memory。两条产品线在两种语言中的导入方式与构造约定如下方面PythonTypeScript导入Platformfrom mem0 import MemoryClientimport MemoryClient from mem0ai导入OSSfrom mem0 import Memoryimport { Memory } from mem0ai/oss构造MemoryClient(api_keym0-xxx)new MemoryClient({ apiKey: m0-xxx })必选参数api_key位置参数或关键字参数均可apiKey放在 options 对象中两种 SDK 在未显式传入 key 时都会回退读取MEM0_API_KEY环境变量。这一点在 Python 侧源码中可以确认MemoryClient 构造函数 中self.api_key api_key or os.getenv(MEM0_API_KEY)取不到时直接抛出ValueError(Mem0 API Key not provided...)。构造行为上的几个源码细节值得注意默认 hostPython 的MemoryClient默认host为https://api.mem0.aimain.pyTypeScript 侧同样在构造函数中回退到https://api.mem0.ai。初始化即鉴权Python 客户端在构造时同步调用_validate_api_key()向/v1/ping/发起验证请求main.py并从中解析出org_id与project_idTypeScript 客户端则采用非阻塞策略——构造函数中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 与导出接口操作PythonTypeScript添加记忆add()add()搜索search()search()获取单条get()get()获取全部get_all()getAll()更新update()update()删除delete()delete()删除全部delete_all()deleteAll()历史记录history()history()批量更新batch_update()batchUpdate()批量删除batch_delete()batchDelete()用户列表users()users()删除用户delete_users()deleteUsers()获取项目project.get()getProject()更新项目project.update()updateProject()创建 Webhookcreate_webhook()createWebhook()获取 Webhooksget_webhooks()getWebhooks()更新 Webhookupdate_webhook()updateWebhook()删除 Webhookdelete_webhook()deleteWebhook()创建导出create_memory_export()createMemoryExport()获取导出get_memory_export()getMemoryExport()反馈feedback()feedback()规则Python 一律使用snake_caseTypeScript 一律使用camelCase。上表每一行都能在两侧源码中找到对应实现例如 Python 侧的 batch_update/batch_delete、create_webhook、create_memory_export/get_memory_exportTypeScript 侧的 batchUpdate/batchDelete、createWebhook/updateWebhook/deleteWebhook、createMemoryExport/getMemoryExport 以及 getProject/updateProject。参数传递kwargs 与 options 对象的约定差异两套 SDK 传参风格不同这是迁移时最易踩坑的地方# Python: kwargs client.add(messages, user_idalice, metadata{source: chat}) client.search(query, filters{user_id: alice}, top_k5, rerankTrue)// 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_caseTypeScript 的顶层方法参数使用camelCaseuserId、topK而过滤器键保留snake_caseuser_id、agent_id。从源码结构看Python 侧的方法签名同时接受类型化 options 与**kwargs如 add、get_all 的options: Optional[...] None, **kwargs类型定义位于 mem0/client/types.pyAddMemoryOptions、SearchMemoryOptions等因此在 Python 中user_id、top_k这类参数统一走snake_case关键字。TypeScript 侧则通过类型化的 options 对象收敛参数例如GetAllMemoryOptions、SearchMemoryOptionsmem0.types.ts方法签名如 getAll(options?: GetAllMemoryOptions)。v3 实体 ID 传递顶层参数与 filters 的边界Mem0 v3 对实体标识user_id/agent_id/app_id/run_id在不同方法上的传递位置有严格约定方法PythonTypeScriptadd()顶层user_idalice顶层{ userId: alice }search()放入 filtersfilters{user_id: alice}放入 filters{ filters: { user_id: alice } }get_all()放入 filtersfilters{user_id: alice}放入 filters{ filters: { user_id: alice } }这条规则在两套 SDK 中都有强制校验而非仅靠文档约定Python 在 main.py 定义了ENTITY_PARAMS frozenset({user_id, agent_id, app_id, run_id})用于在search/get_all等接口中拒绝以顶层参数形式传入实体 IDTypeScript 在 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 库、超时与同步/异步模型方面PythonTypeScriptHTTP 库httpxaxios默认超时300 秒60 秒同步支持是MemoryClient否全部异步异步支持是AsyncMemoryClient所有方法均为 async项目管理client.project.*独立类client.getProject()/client.updateProject()上下文管理器支持async with AsyncMemoryClient()不支持以上各项均与源码一致超时Python 默认 httpx 客户端timeout300main.pyTypeScript 的 axios 实例timeout: 60000mem0.ts。如果你的批量写入在 Python 侧能跑通而迁移到 TS 后偶发超时应首先怀疑这个 60s/300s 的差异。异步双客户端Python 同时提供同步MemoryClientmain.py与AsyncMemoryClientmain.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.projectTypeScript 则把项目操作平铺为实例方法getProject()与updateProject()mem0.ts没有project子对象这一层。Python 独占的 Platform 功能以下方法只存在于 Python SDK均已在 mem0/client/main.py 与 mem0/client/project.py 中确认方法说明源码位置get_summary(filters)获取记忆摘要main.pyreset()删除全部数据用户 记忆main.pyproject.create(name)创建新项目project.pyproject.delete()删除当前项目project.pyproject.get_members()列出项目成员project.pyproject.add_member(email, role)添加项目成员role默认READERproject.pyproject.update_member(email, role)变更成员角色project.pyproject.remove_member(email)移除成员project.py需要注意reset()是删除所有用户与记忆的破坏性操作且它只是 Python 客户端方法TypeScript 侧没有对应封装同理项目成员的增删改查在 TS 侧没有客户端方法需要走 REST API可参考 docs/api-reference/ 下的组织与项目管理接口文档。TypeScript 独占的 Platform 功能方法说明源码位置deleteUser(data)单实体删除的便捷方法mem0.tsping()健康检查端点mem0.ts补充一个容易被忽略的实现细节TypeScript 的ping()不仅是对外暴露的健康检查方法还承担客户端初始化职责——构造函数 通过它解析telemetryId、organizationId、projectId并在进程内按凭据缓存默认上限 50 组identityCacheMax可调。Python 侧的等价逻辑是构造时的同步_validate_api_key()对使用者透明。OSS 配置与范围参数的命名差异使用 OSS SDK本地向量库 本地/自托管 LLM时配置键与范围参数同样遵循同一套命名规则配置键对照Python 配置键TypeScript 配置键vector_storevectorStorehistory_db_pathhistoryDbPathcustom_instructionscustomInstructionsTypeScript 侧的 OSS 示例basic.ts中可以直接看到实际写法例如historyDbPath: memory.db对应本地记忆历史 SQLite 文件的落盘路径。范围参数scope对照PythonTypeScriptuser_idaliceuserId: aliceagent_idbotagentId: botrun_idsessionrunId: session这里再次强调边界OSS 顶层方法参数用 camelCasePlatform filters 内部的键用 snake_case。两个语境不要混用。常见坑filter 键永远是 snake_case跨语言迁移中最频繁的错误是把camelCase习惯带入过滤器。速查文档给出的正确姿势是无论 Python 还是 TypeScript搜索与过滤条件中的键一律snake_caseTypeScript 只在顶层方法参数上使用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显式报错。迁移自查清单可以概括为三条顶层方法参数Pythonsnake_case→ TypeScriptcamelCaseuser_id→userIdtop_k→topKfilters内部键两种语言都保持snake_case实体 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考