Mem0 Platform 两分钟上手：用 MemoryClient 为 AI Agent 接入持久化记忆-平芜编程栈

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/embedchain

Mem0 定位于 "AI Agent 的记忆层"：它把聊天中产生的偏好、事实、约束等信息抽取为结构化记忆，并持久化存储，让 Agent 在后续会话中具备持续上下文。本指南基于 skills/mem0/references/quickstart.md 展开，讲解如何在本项目中用 Python（MemoryClient/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_KEY="m0-your-api-key"

MEM0_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_key="your-api-key") # Add a memory messages = [ {"role": "user", "content": "I'm a vegetarian and allergic to nuts."}, {"role": "assistant", "content": "Got it! I'll remember your dietary preferences."} ] client.add(messages, user_id="user123") # Search memories results = client.search("What are my dietary restrictions?", user_id="user123") 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()要求把实体 ID（user_id、agent_id、app_id、run_id）放进filters对象中——顶层传参会直接抛出ValueError。详见下文「检索记忆」一节。

异步客户端

在高并发、IO 密集的 Agent 服务中推荐使用异步版本。API 完全对齐同步版，仅需把方法调用改为await：

from mem0 import AsyncMemoryClient client = AsyncMemoryClient(api_key="your-api-key") await client.add(messages, user_id="user123") results = await client.search("query", user_id="user123")

从源码看，AsyncMemoryClient（mem0/client/main.py）与MemoryClient共用相同的初始化逻辑，只是底层从httpx.Client换成httpx.AsyncClient，并提供对应的一套async方法。同步、异步两种客户端可以各自独立实例化使用。

TypeScript / JavaScript 快速接入

安装与配置

npm install mem0ai export MEM0_API_KEY="m0-your-api-key"

写入与检索

import MemoryClient from 'mem0ai'; const client = new MemoryClient({ apiKey: 'your-api-key' }); // Add a memory const messages = [ {"role": "user", "content": "I'm a vegetarian and allergic to nuts."}, {"role": "assistant", "content": "Got it! I'll 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 API：

export MEM0_API_KEY="m0-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()时建议等待 2～3 秒，给后台抽取留出处理时间。

解读检索结果

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`、`finance`）
`score`	相关性得分，取值`[0, 1]`，越高越相关
`expiration_date`	过期日期，未设置时为`null`；过期后默认在检索中隐藏
`created_at`/`updated_at`	记忆创建与更新时间

可以观察到两条关键事实：记忆文本（memory）≠ 原始对话——Mem0 会在写入时通过 LLM 抽取语义事实（把"I'm a vegetarian and allergic to nuts."提炼成 "Allergic to nuts" 并入health分类）；而score代表语义检索相关度，而非关键词匹配。

search 的默认参数

参数	默认值	说明
`top_k`	`10`	返回结果数量上限（合法范围 1～1000）
`threshold`	`0.1`	最低相似度阈值，传`0.0`可关闭过滤
`rerank`	`false`	是否启用重排（会进一步提升相关性）
`show_expired`	`false`	是否把已过期的记忆一并返回

filters 高级筛选

filters对象支持逻辑运算符（AND/OR/NOT）与比较运算符（in、gte、lte、gt、lt、ne、icontains，以及通配符*）。例如按类别做部分匹配：

results = client.search( query="dietary 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`与`content`
`user_id`/`agent_id`/`app_id`/`run_id`	实体 ID，至少提供一个，用于把记忆归属到某个用户、Agent、应用或运行会话
`metadata`	自定义键值对（如`{"source": "onboarding_form"}`），用于后续过滤或溯源
`infer`	布尔值，默认`true`；置`false`时跳过 LLM 推理、按原文直接存储
`expiration_date`	`YYYY-MM-DD`格式的时间记忆；该日期之后默认隐藏（Python 参数名`expiration_date`，TypeScript 为`expirationDate`）

检索：多信号混合召回

search()使用混合检索：语义向量 + BM25 关键词 + 实体匹配三种信号并行打分后融合，最终输出一个统一的[0,1]相关性得分（见 docs/api-reference/memory/search-memories.mdx）。

易踩的坑

实体跨筛选（AND 连接user_id与agent_id）会静默返回空——不同实体类型的记忆不共享，需改用OR；
SQL 运算符不被接受——用gte/lt，不要用>=/<；
metadata 过滤能力有限——仅支持顶层键的eq/contains/ne；
通配符*排除空值——它只匹配非 null 值；
默认阈值 0.1 偏低——需要更严格匹配时调大threshold；
写入是异步的——add()后立即检索可能查不到，等待 2～3 秒再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.py，TypeScript 客户端位于 mem0-ts/src/client/mem0.ts，对应的端点规范见 docs/api-reference/memory/add-memories.mdx 与 docs/api-reference/memory/search-memories.mdx。无论你是要在 Agent 中补充长期记忆、为聊天机器人记住用户偏好，还是搭建可复用的记忆服务，这条「写入 → 检索 → 引用」的最小闭环都是你迈向生产环境的第一步。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考