Mem0 Platform 两分钟上手用 MemoryClient 为 AI Agent 接入持久化记忆【免费下载链接】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 的记忆层它把聊天中产生的偏好、事实、约束等信息抽取为结构化记忆并持久化存储让 Agent 在后续会话中具备持续上下文。本指南基于 skills/mem0/references/quickstart.md 展开讲解如何在本项目中用 PythonMemoryClient/AsyncMemoryClient、TypeScript 与纯 HTTP cURL 快速接入 Mem0 Platform完成「写入记忆 → 检索记忆」的闭环。读完本文你将掌握 API Key 的配置方式、add()与search()的核心用法、记忆对象结构以及其背后 SDK 的实现细节。概述无需自建基础设施Mem0 Platform 是一个托管式记忆服务无需自行部署向量库与抽取管线只需一个 API Key即可使用。官方声称可以在约两分钟内跑通完整流程。整条使用链路非常简单注册账号并获取 API Key选择 Python / TypeScript / cURL 三种方式之一调用add写入对话调用search按自然语言检索记忆。前置条件Python 3.10或Node.js 18对应 Python SDK 与 TypeScript SDK 的运行时要求一个有效的 Mem0 Platform API Key在 Platform 控制台的 API Keys 页面创建以m0-开头。注意本文讨论的是 Mem0Platform托管云服务的用法。仓库中的纯 Python 客户端实现在 mem0/client/main.py其 API 能力与 Platform 的 v3 记忆端点一一对应。Python 快速接入安装与配置pip install mem0ai export MEM0_API_KEYm0-your-api-keyMEM0_API_KEY环境变量是 SDK 读取 API Key 的默认来源。查看 mem0/client/main.py 的MemoryClient.__init__可以看到若构造时未显式传入api_key会回退读取os.getenv(MEM0_API_KEY)两者都没有时会抛出ValueError。写入与检索第一条记忆from mem0 import MemoryClient client MemoryClient(api_keyyour-api-key) # Add a memory messages [ {role: user, content: Im a vegetarian and allergic to nuts.}, {role: assistant, content: Got it! Ill remember your dietary preferences.} ] client.add(messages, user_iduser123) # Search memories results client.search(What are my dietary restrictions?, user_iduser123) print(results)from mem0 import MemoryClient的导出路径可在 mem0/init.py 中找到实证该模块同时导出了AsyncMemoryClient与MemoryClient。这里有几个值得注意的 SDK 细节均可在源码中验证构造即校验MemoryClient.__init__在初始化时会发起一次GET /v1/ping/请求验证 Key 的有效性并将返回的org_id/project_id缓存在客户端上mem0/client/main.py。自动请求头客户端会为每个请求附带Authorization: Token api_key与Mem0-User-ID由 API Key 的 MD5 生成两个请求头这是服务端识别身份与做遥测的基础mem0/client/main.py。默认超时内置的httpx.Client默认超时 300 秒默认 host 为https://api.mem0.ai可通过构造参数host覆盖。add的输入宽容度add()的messages参数既可以是字符串自动包装成一条user消息、单个消息字典也可以是消息字典列表mem0/client/main.py。版本提示示例中的client.add(messages, user_id...)属于「顶层实体参数」的旧式写法。当前 v3 SDK 内部实际调用的是POST /v3/memories/add/与POST /v3/memories/search/并且search()/get_all()要求把实体 IDuser_id、agent_id、app_id、run_id放进filters对象中——顶层传参会直接抛出ValueError。详见下文「检索记忆」一节。异步客户端在高并发、IO 密集的 Agent 服务中推荐使用异步版本。API 完全对齐同步版仅需把方法调用改为awaitfrom mem0 import AsyncMemoryClient client AsyncMemoryClient(api_keyyour-api-key) await client.add(messages, user_iduser123) results await client.search(query, user_iduser123)从源码看AsyncMemoryClientmem0/client/main.py与MemoryClient共用相同的初始化逻辑只是底层从httpx.Client换成httpx.AsyncClient并提供对应的一套async方法。同步、异步两种客户端可以各自独立实例化使用。TypeScript / JavaScript 快速接入安装与配置npm install mem0ai export MEM0_API_KEYm0-your-api-key写入与检索import MemoryClient from mem0ai; const client new MemoryClient({ apiKey: your-api-key }); // Add a memory const messages [ {role: user, content: Im a vegetarian and allergic to nuts.}, {role: assistant, content: Got it! Ill remember your dietary preferences.} ]; await client.add(messages, { userId: user123 }); // Search memories const results await client.search(What are my dietary restrictions?, { filters: { user_id: user123 } }); console.log(results);TypeScript 客户端的类定义与async add()方法签名可在 mem0-ts/src/client/mem0.ts 中找到对应实现。注意其中体现的命名约定方法名与顶层参数使用camelCase如userId但filters对象内部的筛选键仍使用snake_case如user_id、agent_id这是为了与后端字段保持一致混用会导致筛选不生效。cURL 方式接入不想引入 SDK 时可以直接调用 HTTP APIexport MEM0_API_KEYm0-your-api-key # Add memory curl -X POST https://api.mem0.ai/v1/memories/ \ -H Authorization: Token $MEM0_API_KEY \ -H Content-Type: application/json \ -d { messages: [ {role: user, content: I am a vegetarian and allergic to nuts.}, {role: assistant, content: Got it! I will remember your dietary preferences.} ], user_id: user123 } # Search memories curl -X POST https://api.mem0.ai/v2/memories/search/ \ -H Authorization: Token $MEM0_API_KEY \ -H Content-Type: application/json \ -d { query: What are my dietary restrictions?, filters: {user_id: user123} }以上是官方 Quickstart 文档中的原始示例。若希望与当前仓库源码实现的端点保持一致SDK 实际写入的是POST /v3/memories/add/见 docs/api-reference/memory/add-memories.mdx检索是POST /v3/memories/search/见 docs/api-reference/memory/search-memories.mdx。对应的 v3 风格请求体大致为# Add memory (v3 endpoint) curl -X POST https://api.mem0.ai/v3/memories/add/ \ -H Authorization: Token $MEM0_API_KEY \ -H Content-Type: application/json \ -d { user_id: user123, messages: [ {role: user, content: I moved to Austin last month.} ], metadata: {source: onboarding_form} } # Search memories (v3 endpoint) curl -X POST https://api.mem0.ai/v3/memories/search/ \ -H Authorization: Token $MEM0_API_KEY \ -H Content-Type: application/json \ -d { query: Where does this user live?, filters: {user_id: user123} }异步处理的注意点v3 的写入与检索都是异步管线。POST /v3/memories/add/返回的响应体是{event_id: ..., status: PENDING}需要通过GET /v1/event/{event_id}/轮询最终状态SUCCEEDED/FAILED。因此在add()之后立即search()时建议等待 23 秒给后台抽取留出处理时间。解读检索结果search()的返回体遵循 v1.1 结构核心是results数组。每个记忆条目大致如下{ results: [ { id: 14e1b28a-2014-40ad-ac42-69c9ef42193d, memory: Allergic to nuts, user_id: user123, categories: [health], created_at: 2025-10-22T04:40:22.864647-07:00, score: 0.30 } ] }各字段含义结合 docs/api-reference/memory/search-memories.mdx 中的输出示例字段说明id该条记忆的唯一标识后续get/update/delete/history都以它作为入参memory抽取并规范化后的记忆文本注意与原始消息不同它是事实提炼的结果user_id记忆所属的用户实体metadata写入时携带的自定义键值对可选字段categories自动推理出的记忆类别如health、hobbies、financescore相关性得分取值[0, 1]越高越相关expiration_date过期日期未设置时为null过期后默认在检索中隐藏created_at/updated_at记忆创建与更新时间可以观察到两条关键事实记忆文本memory≠ 原始对话——Mem0 会在写入时通过 LLM 抽取语义事实把Im a vegetarian and allergic to nuts.提炼成 Allergic to nuts 并入health分类而score代表语义检索相关度而非关键词匹配。search 的默认参数参数默认值说明top_k10返回结果数量上限合法范围 11000threshold0.1最低相似度阈值传0.0可关闭过滤rerankfalse是否启用重排会进一步提升相关性show_expiredfalse是否把已过期的记忆一并返回filters 高级筛选filters对象支持逻辑运算符AND/OR/NOT与比较运算符in、gte、lte、gt、lt、ne、icontains以及通配符*。例如按类别做部分匹配results client.search( querydietary restrictions, filters{AND: [ {user_id: user123}, {categories: {contains: health}} ]}, )对应地SDK 在search()内部会校验查询串非空空白会被拒绝并抛出ValueError并拒绝user_id等实体参数以顶层 keyword 形式传入mem0/client/main.py。这些行为都被仓库测试所覆盖例如tests/test_client.py中的test_search_rejects_empty_query与test_search_rejects_user_id_kwarg见 tests/test_client.py。源码视角写入与检索是怎么工作的写入v3 additive 抽取管线在 v3 中add()走的是ADD-only 单遍抽取管线一次 LLM 调用只做新增抽取不做 UPDATE/DELETE。记忆随时间累积、互不覆盖详见 docs/api-reference/memory/add-memories.mdx 的说明。支持的重要字段包括字段说明messages对话轮次数组必填每条包含role与contentuser_id/agent_id/app_id/run_id实体 ID至少提供一个用于把记忆归属到某个用户、Agent、应用或运行会话metadata自定义键值对如{source: onboarding_form}用于后续过滤或溯源infer布尔值默认true置false时跳过 LLM 推理、按原文直接存储expiration_dateYYYY-MM-DD格式的时间记忆该日期之后默认隐藏Python 参数名expiration_dateTypeScript 为expirationDate检索多信号混合召回search()使用混合检索语义向量 BM25 关键词 实体匹配三种信号并行打分后融合最终输出一个统一的[0,1]相关性得分见 docs/api-reference/memory/search-memories.mdx。易踩的坑实体跨筛选AND 连接user_id与agent_id会静默返回空——不同实体类型的记忆不共享需改用ORSQL 运算符不被接受——用gte/lt不要用/metadata 过滤能力有限——仅支持顶层键的eq/contains/ne通配符*排除空值——它只匹配非 null 值默认阈值 0.1 偏低——需要更严格匹配时调大threshold写入是异步的——add()后立即检索可能查不到等待 23 秒再search()。下一步深入方向Quickstart 只是起点官方文档为你铺设了三条进阶路径SDK 指南Python 与 TypeScript 的完整方法参考涵盖add、search、get/get_all、update、delete/delete_all、history、批量操作与反馈等全部方法以及 v2 → v3 的迁移对照表API 参考REST 端点与记忆对象完整结构集成模式LangChain、CrewAI、Vercel AI 等主流 Agent 框架的接入范例。在仓库内部你还可以沿着这些路径继续深挖纯 Python 客户端完整实现位于 mem0/client/main.pyTypeScript 客户端位于 mem0-ts/src/client/mem0.ts对应的端点规范见 docs/api-reference/memory/add-memories.mdx 与 docs/api-reference/memory/search-memories.mdx。无论你是要在 Agent 中补充长期记忆、为聊天机器人记住用户偏好还是搭建可复用的记忆服务这条「写入 → 检索 → 引用」的最小闭环都是你迈向生产环境的第一步。【免费下载链接】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），仅供参考
