Mem0 SDK 指南：Python 与 TypeScript 的 MemoryClient 全方法实战参考-北京尧图网络

Mem0 SDK 指南Python 与 TypeScript 的 MemoryClient 全方法实战参考【免费下载链接】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/embedchainMem0 为 AI Agent 提供持久化的记忆层能力而面向 Platform API 的官方 SDK 入口统一为MemoryClient。本篇指南以 Mem0 官方技能文档 sdk-guide.md 为骨架系统覆盖记忆的写入add、检索search/get/getAll、更新update、删除delete/deleteAll、历史追踪history、批量操作与导出等全部方法并给出 v2 到 v3 的迁移对照。读完本篇你将能在 Python同步/异步与 TypeScript 中正确初始化客户端、掌握 filters 过滤语法与命名规范、避开高频踩坑点并把各方法对应的源码实现mem0/client/main.py、mem0-ts/src/client/mem0.ts与 REST 端点逐一对应起来。需要说明的前提本指南默认使用Platform API云端托管、零基础设施所有身份参数user_id、agent_id、run_id等在 v3 中都必须放进filters对象传递这一点在 SDK 源码与 API 文档中都有强制校验。若你使用 OSS 自托管方案可查阅仓库内更细分的语言级参考Python SDK 深度参考、Node.js SDK 深度参考与 Python 与 TypeScript 差异对照表。初始化Initialization三种语言的初始化方式完全对称构造参数仅两个api_key必填。除了显式传参Python 与 TypeScript SDK 都会在缺失时回退读取MEM0_API_KEY环境变量见 mem0/client/main.py 的__init__。host可选默认https://api.mem0.ai仅自建或代理场景需要覆盖。Python同步from mem0 import MemoryClient client MemoryClient(api_keym0-your-api-key)Python异步from mem0 import AsyncMemoryClient client AsyncMemoryClient(api_keym0-your-api-key)TypeScriptimport MemoryClient from mem0ai; const client new MemoryClient({ apiKey: m0-your-api-key });源码视角构造函数实际做了什么阅读 mem0/client/main.py 可以看到初始化并非只保存一个 key而是完成以下四件事解析凭证self.api_key api_key or os.getenv(MEM0_API_KEY)两者都为空时直接抛出ValueError(Mem0 API Key not provided...)。创建内部 HTTP 客户端Python 使用httpx.Clientbase_urlself.host并在请求头写入Authorization: Token {api_key}与Mem0-User-ID由 API key 的 MD5 计算而来超时默认 300 秒。校验 API key构造时同步请求GET /v1/ping/把响应中的org_id、project_id、user_email拉回客户端用于后续项目级调用。初始化项目管理器self.project Project(...)支持自定义指令、分类、成员管理等平台级能力。TypeScript 端mem0-ts/src/client/mem0.ts采用 axios全部方法均为async默认超时 60 秒无同步变体两种 SDK 的语言级差异详见 differences.md。add()写入记忆add()是记忆层的数据入口输入一段对话消息列表由 Mem0 负责用 LLM 做事实抽取、去重与沉淀。Pythonmessages [ {role: user, content: Im a vegetarian and allergic to nuts.}, {role: assistant, content: Got it! Ill remember that.} ] client.add(messages, user_idalice) # 附带元数据 client.add(messages, user_idalice, metadata{source: onboarding})TypeScriptawait client.add(messages, { userId: alice }); await client.add(messages, { userId: alice, metadata: { source: onboarding } });参数说明名称类型说明messagesarray对话消息形如[{role: user, content: ...}]user_idstring用户标识强烈建议提供agent_idstringAgent 标识run_idstring会话/运行标识metadataobject自定义键值对inferboolean设为false时跳过 LLM 推断直接存储原始文本默认true补充说明从 mem0/client/types.py 的AddMemoryOptions可以看出add()还支持custom_categories覆盖项目分类、custom_instructions/agent_custom_instructions覆盖抽取指令、timestampUnix 时间戳或 ISO 8601、expiration_dateYYYY-MM-DD 过期日期等可选字段消息格式方面源码 mem0/client/main.py 会自动把字符串转换成{role: user, content: ...}、把单个 dict 包装成列表三种入参形式都可接受。请求最终落在POST /v3/memories/add/端点。高级用法Agent 与会话双维度隔离、跳过推断# Agent session scoping三维身份隔离 client.add(messages, user_idalice, agent_idnutrition-agent, run_idsession-456) # 原始文本直存 —— 跳过 LLM 推断 client.add( [{role: user, content: User prefers dark mode.}], user_idalice, inferFalse, )要点虽然user_id、agent_id、run_id在add()中是作为顶层参数传入的但在search()、get_all()中则必须下沉到filters里后文详述这是 v3 最核心的 API 形态变化。search()语义检索记忆search()用自然语言查询做相关性召回。v3 采用混合检索——语义向量、BM25 关键词与实体匹配并行打分后融合返回结果里的score是融合后的[0, 1]置信度。详见仓库的 Search Memories 接口文档。Pythonresults client.search(dietary preferences?, filters{user_id: alice}) # 组合 filters 重排 results client.search( querywork experience, filters{AND: [{user_id: alice}, {categories: {contains: professional_details}}]}, top_k5, rerankTrue, threshold0.5 )TypeScriptconst results await client.search(dietary preferences, { filters: { user_id: alice } }); const results await client.search(work experience, { filters: { AND: [{ user_id: alice }, { categories: { contains: professional_details } }] }, topK: 5, rerank: true, });参数说明名称类型说明querystring自然语言检索查询filtersobject过滤对象支持 AND/OR 等逻辑运算符。用{user_id: ...}按用户过滤top_knumber返回条数Platform 默认 10取值范围 1–1000rerankboolean是否启用重排以提升相关性默认falsethresholdnumber最低相似度阈值默认 0.1接口文档还补充了两个常用参数show_expiredPython 端为show_expiredTypeScript 端为showExpired默认隐藏已过期记忆与latest_only仅返回同一记忆的最新版本。从源码 mem0/client/main.py 可见search()在发出POST /v3/memories/search/前会先做一次查询词校验空串或纯空白字符串直接抛ValueError且会先strip()去除首尾空白。filters 支持的运算符filters对象支持逻辑运算与比较运算的组合逻辑运算AND、OR、NOT比较运算符in匹配枚举值之一、gte大于等于、lte小于等于、gt大于、lt小于、ne不等于、icontains大小写不敏感的包含判断、contains包含通配符*匹配任意内容。常用过滤模式全集以下模式同时给出 Python 与 TypeScript 写法可直接复制使用。Python# 单用户过滤 filters{user_id: alice} # 跨多个 Agent 取并集OR filters{OR: [{user_id: alice}, {agent_id: {in: [travel-agent, sports-agent]}}]} # 分类过滤部分匹配 contains filters{AND: [{user_id: alice}, {categories: {contains: finance}}]} # 分类过滤精确匹配 in filters{AND: [{user_id: alice}, {categories: {in: [personal_information]}}]} # 通配符匹配任意非空 run_id filters{AND: [{user_id: alice}, {run_id: *}]} # 日期区间 filters{AND: [ {user_id: alice}, {created_at: {gte: 2024-01-01T00:00:00Z}}, {created_at: {lt: 2024-02-01T00:00:00Z}} ]} # 用 NOT 排除分类 filters{AND: [{user_id: user_123}, {NOT: {categories: {in: [spam, test]}}}]} # 多维查询用户关键词分类时间 filters{AND: [ {user_id: user_123}, {keywords: {icontains: invoice}}, {categories: {in: [finance]}}, {created_at: {gte: 2024-01-01T00:00:00Z}} ]}TypeScript// 单用户过滤 filters: { user_id: alice } // 跨 Agent 并集OR filters: { OR: [{ user_id: alice }, { agent_id: { in: [travel-agent, sports-agent] } }] } // 分类部分匹配 filters: { AND: [{ user_id: alice }, { categories: { contains: finance } }] } // 分类精确匹配 filters: { AND: [{ user_id: alice }, { categories: { in: [personal_information] } }] }注意一个高频误区过滤器内的键一律使用snake_caseuser_id、agent_id、categories、created_at即使你写的是 TypeScript——TypeScript 只在方法级参数上用 camelCasetopK、pageSize过滤器对象里的键名是两个 SDK 保持一致的。仓库测试对上述过滤语义有完整覆盖例如 tests/test_client.py 中的test_search_passes_and_filters、test_search_passes_or_filters、test_search_passes_not_filters、test_search_passes_complex_nested_filters可作回归验证参考。get() / getAll()按需读取记忆按 ID 读取单条记忆或按过滤器批量拉取记忆列表。Python# 按 ID 读取单条记忆 memory client.get(memory_idea925981-...) # 读取某用户的全部记忆 memories client.get_all(filters{user_id: alice}) # 附带日期区间过滤 memories client.get_all( filters{AND: [ {user_id: alex}, {created_at: {gte: 2024-07-01, lte: 2024-07-31}} ]} )TypeScriptconst memory await client.get(ea925981-...); const memories await client.getAll({ filters: { user_id: alice } });注意get_all()的filters中必须包含user_id、agent_id、app_id、run_id四者之一否则无法定位命名空间。同时v3 禁止把实体 ID 作为顶层参数传给get_all()——mem0/client/main.py 中通过ENTITY_PARAMS常量做了硬校验一旦检测到顶层出现user_id/agent_id/app_id/run_id会直接抛出ValueError提示改用filters。get_all()的分页支持通过page与page_size控制二者在源码中会被抽取成 URL 查询参数后提交到POST /v3/memories/返回值是{count: ..., next: ..., previous: ..., results: [...]}的分页结构page/page_size单独或同时传入的行为差异均有测试覆盖见 tests/test_client.py。此外get_all()还支持start_date/end_dateISO 8601、categories、show_expired、latest_only等选项见 mem0/client/types.py 的GetAllMemoryOptions。update()修改记忆按 memory ID 更新记忆文本或其元数据。Pythonclient.update(memory_idea925981-..., textUpdated: vegan since 2024) client.update(memory_idea925981-..., textUpdated, metadata{verified: True})TypeScriptawait client.update(ea925981-..., { text: Updated: vegan since 2024 });源码细节mem0/client/main.py 对update()做了两个值得注意的处理——其一会把None值字段过滤掉但expiration_date例外保留这意味着expiration_dateNone可用于清除过期时间对应测试test_update_preserves_null_expiration_date其二若最终 payload 为空会抛ValueError提示至少提供text、metadata、timestamp、expiration_date之一。请求走PUT /v1/memories/{memory_id}/。delete() / deleteAll()删除记忆Pythonclient.delete(memory_idea925981-...) client.delete_all(user_idalice) # 不可逆的批量删除TypeScriptawait client.delete(ea925981-...); await client.deleteAll({ userId: alice });两个方法语义差异明显务必分清delete()只删一条记忆可选参数delete_linked默认False设为True时会连带删除该记忆取代过superseded的更早版本链linked_memory_ids用于防止删除当前记忆后旧版本复活。源码见 mem0/client/main.py请求走DELETE /v1/memories/{memory_id}/。delete_all()是不可逆的批量删除通过filters或顶层user_id/agent_id/app_id圈定删除范围走DELETE /v1/memories/。批量场景请务必先在get_all()中核对过滤条件无误后再执行。history()追踪记忆变更历史查看某条记忆从创建以来的每次变更记录适合审计与调试。Pythonhistory client.history(memory_idea925981-...) # 返回形如: [{previous_value, new_value, action, timestamps}]TypeScriptconst history await client.history(ea925981-...);每条变更记录包含变更前值previous_value、变更后值new_value、操作类型action如 ADD/UPDATE/DELETE与时间戳源码路径为 mem0/client/main.py请求走GET /v1/memories/{memory_id}/history/。批量操作TypeScript 示例批量更新 / 删除在 Python 中对应batch_update()、batch_delete()走PUT /v1/batch/与DELETE /v1/batch/mem0/client/main.pyTypeScript 侧每个元素同样只需给memoryId与可选的text/metadata。// 批量更新 await client.batchUpdate([ { memoryId: uuid-1, text: Updated text }, { memoryId: uuid-2, text: Another updated text }, ]); // 批量删除 await client.batchDelete([uuid-1, uuid-2, uuid-3]);批量操作相比循环单条调用能显著减少 HTTP 往返适合记忆整理、数据迁移等场景。附加方法实体管理、反馈与导出Python# 列出所有已产生记忆的用户 / Agent / 会话 users client.users() # 删除某用户或 Agent实体及其全部记忆 client.delete_users(user_idalice) # 为一条记忆提交反馈用于改善抽取质量 client.feedback(memory_id..., feedbackPOSITIVE, feedback_reasonAccurate extraction) # 导出记忆先创建导出任务再按 ID 拉取数据 export client.create_memory_export(filters{AND: [{user_id: alice}]}) data client.get_memory_export(memory_export_idexport[id])对应源码与端点users()GET /v1/entities/返回所有存在记忆的实体用户/Agent/会话列表mem0/client/main.py。delete_users()DELETE /v2/entities/{type}/{name}/。只传一个身份时删对应实体什么都不传时则先枚举全部实体再逐一删除相当于全量清空同时它还支持agent_id、app_id、run_id维度mem0/client/main.py。feedback()枚举值必须是POSITIVE、NEGATIVE、VERY_NEGATIVE三者之一代码中用VALID_FEEDBACK_VALUES强制校验其余取值抛ValueError携带可选的feedback_reason请求走POST /v1/feedback/mem0/client/main.py。导出相关create_memory_export()/get_memory_export()对应POST /v1/exports/与POST /v1/exports/get/mem0/client/main.py。Python 独有、TypeScript 未覆盖的能力还包括get_summary()记忆摘要与reset()清空全部用户与记忆详见 differences.md。常见踩坑点Common Pitfalls官方技能文档总结的高频坑逐条给出规避建议实体跨维度过滤会静默返回空结果——AND组合user_idagent_id返回空集。跨实体检索请改用OR。SQL 风格运算符会被拒绝——必须用gte、lt等 Mem0 运算符而不是、。metadata 过滤能力有限——仅支持顶层键且运算符只有eq、contains、ne。通配符*排除空值——它只匹配非 null 的值想匹配任意 run需确认该字段确实有值。默认 threshold 是 0.1——需要更严格匹配时主动调高如 0.5接口文档说明传0.0可关闭阈值过滤。记忆处理是异步的——add()写入后后台需要一定时间完成推断与落库搜索前建议等待 2–3 秒文档与技能源码均如此提示否则可能查不到刚写入的内容。命名规范速查Python全程snake_case——user_id、memory_id、get_all()、batch_update()。TypeScript方法名与顶层参数用camelCasegetAll、deleteAll、batchUpdate、userId、topK、pageSize但filter 键名沿用snake_caseuser_id、agent_id、created_at。v2 到 v3 迁移指南如果你从 v2 升级下面四条是最关键的破坏性变更务必逐一核对调用点。1. search() 与 getAll() 中的实体 ID 必须移入 filtersv3 强制要求实体 IDuser_id、agent_id、run_id等放在filters对象内顶层传参会直接报错Python 端由ENTITY_PARAMS常量硬校验拦截见 mem0/client/main.py# v2已废弃 client.search(query, user_idalice) client.get_all(user_idalice) # v3 client.search(query, filters{user_id: alice}) client.get_all(filters{user_id: alice})// v2已废弃 await client.search(query, { user_id: alice }); await client.getAll({ user_id: alice }); // v3 await client.search(query, { filters: { user_id: alice } }); await client.getAll({ filters: { user_id: alice } });2. TypeScript 参数命名改为 camelCasev2v3user_iduserIdagent_idagentIdrun_idrunIdtop_ktopKpage_sizepageSize注意迁移时顶层参数按上表替换但filters 内部的键如{user_id: alice}继续使用snake_case不要一并改动。3. 默认值变化参数v2 默认v3 默认threshold0.30.1rerank未明确指定false默认阈值从 0.3 降到 0.1意味着同样的查询在 v3 下会返回更多低相关度结果迁移后若感觉结果变杂请显式调高threshold。4. 已移除的参数参数状态enable_graph从 add/search/getAll 中移除keyword_search从 search 中移除filter_memories移除immutable从 add 中移除expiration_date从 add 中移除includes从 add 中移除excludes从 add 中移除async_mode从 add 中移除代码中仍出现的对应用法都需要清理例如 mem0/client/types.py 中SearchMemoryOptions尚保留keyword_search字段注释但 v3 语义已不再接受该参数。建议迁移完成后用 tests/test_client.py 中的搜索/过滤相关用例作为行为基线对账号内数据进行一次端到端回归。延伸阅读Platform 快速上手2 分钟跑通 add search 的最小示例含 cURL。Python SDK 深度参考Python 端全部方法签名、参数表与 OSS 自托管用法。Node.js SDK 深度参考TypeScript 端方法与 OSS 配置命名。Python vs TypeScript 差异方法名、超时、HTTP 库、能力差异速查表。API 参考与 Search Memories 接口文档REST 端点、过滤器运算符与记忆对象结构。集成模式LangChain、CrewAI、Vercel AI 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），仅供参考

Mem0 SDK 指南：Python 与 TypeScript 的 MemoryClient 全方法实战参考

相关推荐

Puppeteer Page.setGeolocation() 方法详解：模拟浏览器地理定位

YOLOv5舰船检测实战：从数据集准备到训练调参全流程解析

基于MFC的扫雷游戏实战：从界面绘制到消息处理与状态机

更多资讯

高通Adreno GPU内置AI核心：端侧推理与开发者适配全解析

OpenClaw v3.1.0 部署指南，搞定本地 AI 自动化环境搭建

齿轮缺陷检测数据集：VOC+YOLO双格式，2978张图+YOLOv8实战

基于Python的微博舆情分析系统设计与实现全指南

Python实战图像超分辨率：从原理到部署全流程

STM32F103 AB分区OTA升级方案：从Bootloader到双分区回滚完整实战

今日更新

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？