为 AI Agent 注入持久记忆mem0 SDKPlatform 客户端 OSS 自托管从接入到实战【免费下载链接】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本文是仓库内skills/mem0/SKILL.mdMem0 Platform Integration 技能文档的完整技术展开。该技能用于指导开发者或代码生成型 AI快速为聊天机器人、Agent 与 AI 应用接入 Mem0 记忆层包括 Python SDKmem0ai与 TypeScript SDKmem0ai的安装认证、MemoryClient核心记忆操作、通用的检索→生成→存储集成模式以及自托管开源版本Memory的本地化用法。读完本文你将能独立完成记忆层选型Platform vs OSS、端到端打通记忆的写入、召回、更新与删除并掌握 v2/v3 差异、常见踩坑点与深入学习的仓库路径。Mem0 的定位是 AI 应用的托管式记忆层它把记住用户偏好、携带持久上下文、实现个性化这类能力以 API 形式交付无需自建基础设施而仓库中的开源版本则允许你完全自托管同一套记忆能力。本技能文档的触发场景非常明确——当用户提到mem0、MemoryClient、memory layer、持久上下文、记住用户偏好、个性化或需要为 chatbot / Agent 添加长期记忆时它都会作为默认技能生效。需要特别注意的是它不覆盖命令行场景应使用 mem0-cli 技能与 Vercel AI SDK /mem0/vercel-ai-provider场景应使用 mem0-vercel-ai-sdk 技能。环境要求与技能范围速览根据 SKILL.md 的 frontmatter使用本技能需要满足以下前提Python 3.10或Node.js 18通过pip install mem0ai或npm install mem0ai安装 SDK使用 Platform托管版时需设置环境变量MEM0_API_KEY并保证可访问api.mem0.aiSDK v3 提供 v2 兼容模式存量 v2.x 用户可按文末的差异清单平滑迁移。技能覆盖面包括Python SDKmem0ai、TypeScript SDKmem0ai以及 LangChain、CrewAI、OpenAI Agents SDK、Pipecat、LlamaIndex、AutoGen、LangGraph 等框架集成同时涵盖开源自托管Memory类。在仓库中本技能与mem0-cli命令行、mem0-vercel-ai-sdkVercel AI SDK Provider共同构成 Mem0 技能图谱三个技能按使用场景互相分工。一、安装与认证Step 1SKILL.md 给出的第一步在任何语言下都是同构的安装 SDK然后提供 API Key。Pythonpip install mem0ai export MEM0_API_KEYm0-your-api-keyTypeScript / JavaScriptnpm install mem0ai export MEM0_API_KEYm0-your-api-key这里的认证机制可以从源码得到印证Platform 客户端入口 中MemoryClient.__init__通过self.api_key api_key or os.getenv(MEM0_API_KEY)读取密钥当两者都缺失时直接抛出ValueError(Mem0 API Key not provided. Please provide an API Key.)。此外在客户端构造阶段会发起一次GET /v1/ping/校验密钥有效性并从响应中取得org_id、project_id与user_email见_validate_api_key随后才会完成client.project管理器的初始化——也就是说先认证、后使用是 SDK 的硬性约束。没有现成的MEM0_API_KEY怎么办SKILL.md 推荐通过 Mem0 CLI 完成引导式初始化先pip install mem0-cli或npm install -g mem0/cli然后运行mem0 init --agent --agent-caller 你的标识 --json其中你的标识替换为你的 Agent 身份例如claude-code、cursor。若初始化时忘记传--agent-caller可事后用mem0 identify 你的标识补上。人类用户之后可用mem0 init --email 你的邮箱认领该账户。二、初始化客户端Step 2Python 同步客户端from mem0 import MemoryClient client MemoryClient(api_keym0-xxx)TypeScript 客户端import MemoryClient from mem0ai; const client new MemoryClient({ apiKey: m0-xxx });Python 异步客户端使用AsyncMemoryClient方法签名与同步版完全一致仅需awaitfrom mem0 import AsyncMemoryClient # 常规用法 client AsyncMemoryClient(api_keym0-xxx) # 或作为异步上下文管理器使用自动管理资源 async with AsyncMemoryClient(api_keym0-xxx) as client: results await client.search(query, filters{user_id: alice})结合源码可以补充若干对排障有价值的构造细节底层 HTTP 客户端采用httpxtimeout300秒默认base_url为https://api.mem0.ai认证头为Authorization: Token api_key见 mem0/client/main.py官方推荐同时设置MEM0_API_KEY环境变量这样MemoryClient()与AsyncMemoryClient()均可零参数构造也便于把密钥留在 CI / 环境配置中而不写进代码包导出层面mem0/init.py 统一导出了MemoryClient、AsyncMemoryClientPlatform与Memory、AsyncMemoryOSS所以务必使用from mem0 import ...的导入路径。三、核心记忆操作Step 3无论 Platform 还是 OSS任何 Mem0 集成都遵循同一个模式先检索retrieve→ 再生成generate→ 后存储store。在此模式之上SKILL.md 定义了五类最基本的记忆操作。3.1 写入记忆 add写入时传入一段或多段角色消息并指定记忆归属的实体用户 / Agentmessages [ {role: user, content: Im a vegetarian and allergic to nuts.}, {role: assistant, content: Got it! Ill remember that.} ] client.add(messages, user_idalice)从 client 类型定义 与 OSS add 实现 看add()的常用可选参数包括参数类型默认值说明messagesstr/dict/list[dict]必填消息内容字符串会被自动转换为 user 消息user_idstrNone用户标识agent_idstrNoneAgent 标识app_idstrNone应用标识Platformrun_idstrNone会话 / 运行标识metadatadictNone自定义键值元数据inferboolTrueFalse时跳过 LLM 事实抽取、按原文直接入库custom_categorieslistNone覆盖项目自定义分类Platformcustom_instructionsstrNone覆盖抽取指令Platformtimestampint/float/strNone自定义时间戳Unix epoch 或 ISO 8601expiration_datestrNoneYYYY-MM-DD过期时间过期记忆默认被隐藏写入结果形如[{id: ..., event: ADD, data: {memory: ...}}]v3 起统一为ADD事件v2 会区分 ADD / UPDATE / DELETE 三类事件。源码中 OSS add 对infer的注释明确说明为True默认时由 LLM 从消息中抽取关键事实并决定新增 / 更新 / 删除为False时消息作为原文直接入库。因此同一批数据不要在inferTrue与inferFalse之间混用否则可能产生重复记忆详见后文边界情况。3.2 语义检索 searchresults client.search(dietary preferences, filters{user_id: alice}) for mem in results.get(results, []): print(mem[memory])search()返回形如{results: [{id, memory, user_id, categories, score, created_at, ...}]}的结构每条命中都带有相似度得分score。检索参数与默认值如下参数类型默认值说明querystr必填自然语言检索语句filtersdictNone过滤条件含实体 ID 或AND/OR/NOT逻辑组合例如{user_id: alice}top_kint10Platform v3/ 20OSS返回结果条数rerankboolFalse是否开启深度语义重排约增加 150–200ms 延迟thresholdfloat0.1最低相似度阈值fieldslistNone仅返回指定字段categorieslistNone按分类过滤这些 v3 默认值在 OSS 源码中得到完全印证Memory.search 的签名即top_k: int 20, threshold: float 0.1, rerank: bool False。易错点源码硬约束search()/get_all()必须通过filters{user_id: ..., agent_id: ..., ...}传入实体 ID直接传顶层user_id会抛出ValueError。对应地客户端源码定义了ENTITY_PARAMS白名单见 mem0/client/main.py用于拒绝顶层实体参数。filters支持丰富的比较运算符eq、ne、in、nin、gt、gte、lt、lte、contains、not_contains以及AND/OR/NOT逻辑组合详见 OSS search docstring例如{AND: [{user_id: alice}, {categories: {contains: health}}]}。3.3 获取全部记忆 get_allall_memories client.get_all(filters{user_id: alice})get_all()至少要求提供一个实体标识user_id/agent_id/run_id之一否则 OSS 源码会抛出ValueError: filters must contain at least one of: user_id, agent_id, run_id见 mem0/memory/main.py。Platform 版还支持top_k、page、page_size分页参数以及复合过滤条件例如memories client.get_all(filters{AND: [{user_id: alice}, {categories: {contains: health}}]})3.4 更新与删除记忆 update / delete / delete_all# 更新单条记忆的内容 client.update(memory-uuid, textUpdated: vegetarian, nut allergy, prefers organic) # 删除单条记忆 client.delete(memory-uuid) # 删除某个用户的全部记忆不可恢复 client.delete_all(user_idalice)update(memory_id, textNone, metadataNone, timestampNone)至少需要提供text、metadata、timestamp中的一项delete_all()按过滤条件整批删除且不可逆生产环境中务必谨慎。单条记忆的变更历史可通过history(memory_id)获取返回[{previous_value, new_value, action, timestamps}]。3.5 Platform 专属高级能力若使用 PlatformMemoryClient还可使用以下 OSS 不具备的能力完整清单可参考本技能下的 Python 客户端深度参考 与 Node 客户端深度参考批量操作batch_update([...])、batch_delete([...])单请求最多 1000 条实体管理users()列出全部实体delete_users(user_id...)删除实体及其记忆reset()一键清空所有数据记忆导出与摘要create_memory_export(schemajson_schema, ...)按 JSON Schema 结构化导出、get_memory_export(memory_export_id...)拉取结果、get_summary(filters...)生成记忆摘要质量反馈feedback(memory_id, feedbackPOSITIVE, feedback_reason...)其中feedback取值POSITIVE/NEGATIVE/VERY_NEGATIVE/None清除Webhooksget_webhooks/create_webhook(url, name, project_id, event_types[...])/update_webhook/delete_webhook项目管理通过client.project.*获取 / 更新项目配置custom_instructions、custom_categories、multilingual等、创建删除项目、管理成员角色READER/OWNER。四、OSS 自托管 Memory 类开源版若不愿接入托管平台可直接使用仓库中的开源实现Memory。它镜像了 Platform 客户端的全部方法签名但在本地执行无需 API Key全部依赖通过配置文件指定。默认配置为 OpenAI 嵌入模型 内存向量库真实 vector store 目录见 mem0/vector_stores 与 mem0/embeddings。from mem0 import Memory m Memory() # 使用默认配置OpenAI embedder 内存向量库关键区别OSS 应from mem0 import Memory而不要误用from mem0 import MemoryClient那是 Platform 客户端。4.1 配置文件驱动 from_config自托管时通过配置字典接入你自己的 LLM、Embedder 与向量库config { llm: { provider: openai, # openai, groq, azure, ollama, lmstudio, google, anthropic, mistral config: { model: gpt-5-mini, api_key: sk-xxx, } }, embedder: { provider: openai, # openai, ollama, azure, lmstudio, google, huggingface config: { model: text-embedding-3-small, api_key: sk-xxx, } }, vector_store: { provider: qdrant, # faiss, qdrant, pgvector, redis, supabase, azure_ai_search, memory config: { collection_name: my_memories, host: localhost, port: 6333, } }, history_db_path: history.db, # 变更历史的 SQLite 路径 custom_instructions: ..., # 自定义抽取指令覆盖默认 LLM prompt } m Memory.from_config(config)from_config是 OSS 的类方法入口见 mem0/memory/main.py。向量库 provider 的可选值涵盖faiss、qdrant、pgvector、redis、supabase、azure_ai_search等与仓库 vector_stores 目录 一一对应。4.2 上下文管理器与本地化资源管理OSS 版本的历史记录写入本地 SQLite因此推荐用上下文管理器在退出时自动释放连接with Memory(config) as m: m.add(I prefer dark mode, user_idalice) results m.search(preferences, filters{user_id: alice}) # SQLite 连接自动释放也可以显式调用m.close()m.reset()会清空整个向量库集合与历史数据库并重建向量库。OSS 同样提供异步版本AsyncMemoryfrom mem0 import AsyncMemory并允许顶层传user_id的add()接口add(messages, *, user_id, agent_id, run_id, metadata, inferTrue)user_id/agent_id/run_id三者至少其一。4.3 Platform 与 OSS 能力对照维度PlatformMemoryClientOSSMemory导入from mem0 import MemoryClientfrom mem0 import Memory认证必须提供 API KeyMEM0_API_KEY无需 Key基于配置执行方式调用api.mem0.ai全部本地执行基础设施完全托管自管向量库 / Embedder / LLM实体过滤filters{user_id: ...}filters{user_id: ...}批量操作 / Webhooks / 导出 / 反馈 / 项目管理 / 实体列表支持不支持自定义抽取指令通过项目设置配置中custom_instructions变更历史平台托管SQLite可配置路径异步AsyncMemoryClientAsyncMemory五、通用集成模式检索 → 生成 → 存储这是 SKILL.md 给出的端到端参考实现——把记忆层接入任意聊天循环的最小完整代码。核心思想在生成响应前召回相关记忆作为 system context在生成响应后再把整轮对话写回记忆库从而让记忆随对话不断累积、可被下一轮检索from mem0 import MemoryClient from openai import OpenAI mem0 MemoryClient() openai OpenAI() def chat(user_input: str, user_id: str) - str: # 1. 检索相关记忆 memories mem0.search(user_input, filters{user_id: user_id}) context \n.join([m[memory] for m in memories.get(results, [])]) # 2. 携带记忆上下文生成回复 response openai.chat.completions.create( modelgpt-5-mini, messages[ {role: system, content: fUser context:\n{context}}, {role: user, content: user_input}, ] ) reply response.choices[0].message.content # 3. 将本轮交互写回记忆供后续使用 mem0.add( [{role: user, content: user_input}, {role: assistant, content: reply}], user_iduser_id ) return reply注意该示例把mem0与openai两个客户端都无参构造前提正是环境变量MEM0_API_KEY与OPENAI_API_KEY均已配置。同理这套三步模式也可以把MemoryClient替换为 OSSMemory本地执行或替换为AsyncMemoryClient的await版本。更多框架侧集成范式LangChain、CrewAI、OpenAI Agents SDK、LlamaIndex、AutoGen、LangGraph 等可进一步查阅本技能下的 框架集成参考 与 用例示例。六、常见边界情况与排查指南SKILL.md 汇总了真实项目中最高频的几类问题逐一说明成因与对策搜索返回空结果Search returns empty记忆是异步处理的add()之后需要等待 2–3 秒再做search()。同时确认user_id完全一致区分大小写并严格使用filters{user_id: ...}语法而非顶层参数。user_idagent_id的 AND 过滤返回空实体在存储中是分离的跨实体做AND交集天然为空。改用OR或对每个实体分别查询。重复记忆Duplicate memories不要对同一份数据混用inferTrue默认与inferFalse两种模式会走不同的抽取 / 入库路径混用易产生重复条目。全流程固定使用其中一种模式。错误的导入路径始终使用from mem0 import MemoryClient异步场景用AsyncMemoryClient。不要用from mem0 import Memory来对接 Platform——那是 OSS 自托管类。代码库中两者并存于 mem0/init.py 的顶层导出中混用接口会导致行为与预期不符。v3 默认参数不适合你的场景v3 默认top_k20、threshold0.1、rerankFalse。若你的应用需要更高召回或更强排序精度请显式调整这三个参数。七、v2 → v3 兼容性要点如果你在使用 SDK v2.x迁移到 v3 时请注意以下差异仓库内的迁移文档见 docs/migration/oss-v2-to-v3.mdx实体 ID 传参位置v2 把user_id作为顶层 kwarg 传给search()v3 必须放进filters字典里。# v2 results client.search(query, user_idalice) # v3 results client.search(query, filters{user_id: alice})默认值变化v2 为top_k100、无 threshold、rerankTruev3 为top_k20、threshold0.1、rerankFalse。图谱记忆v2 通过enable_graphTrue启用v3 中该开关与graph_store配置均已移除Platform 侧图谱能力改由平台功能配置参见 Platform 功能参考。v3 已移除的参数构造函数中的org_id、project_idadd()中的async_mode、output_format、enable_graph、immutable、expiration_date、filter_memories、batch_size、force_add_only、includes、excludes、keyword_searchsearch()/get_all()中的enable_graph以及配置项custom_fact_extraction_prompt更名为custom_instructions。八、继续深入文档检索脚本与参考文件索引SKILL.md 是整套skills/mem0技能树的根节点它按需加载更深的语言级与主题级参考。若需要比本地参考更新、更全的说明可直接运行技能自带的实时文档检索脚本无需 API Key直接查询 docs.mem0.aipython skills/mem0/scripts/mem0_doc_search.py --query topic python skills/mem0/scripts/mem0_doc_search.py --page /platform/features/graph-memory python skills/mem0/scripts/mem0_doc_search.py --index以下是本技能目录内的完整参考文件索引仓库根目录相对路径分类主题文件客户端深参考PythonMemoryClientAsyncMemoryClient OSSMemoryclient/python.md客户端深参考TypeScript / Node.jsMemoryClient OSSMemoryclient/node.md客户端深参考Python 与 TypeScript 差异client/differences.mdPlatform 参考快速上手Python、TS、cURLreferences/quickstart.mdPlatform 参考SDK 指南全方法双语言references/sdk-guide.mdPlatform 参考API 参考端点、过滤条件、对象 Schemareferences/api-reference.mdPlatform 参考架构处理管线、生命周期、作用域、性能references/architecture.mdPlatform 参考平台功能检索、图谱、分类、MCP 等references/features.mdPlatform 参考框架集成模式references/integration-patterns.mdPlatform 参考真实用例与示例代码references/use-cases.md相邻技能命令行 / 脚本 / CI 场景mem0-cli SKILL相邻技能Vercel AI SDK Provider自动记忆mem0-vercel-ai-sdk SKILL若想验证文中涉及的源码事实可直接阅读仓库内的 客户端实现Platform 同步 / 异步客户端、OSS Memory 主类Memory/AsyncMemory及search/get_all/add的默认值与过滤逻辑、类型定义AddMemoryOptions/SearchMemoryOptions等 Pydantic 模型与 顶层导出。完整的方法参数表、字段 Schema 与跨框架接入示例则以技能目录下的语言级参考文件为准。【免费下载链接】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），仅供参考