Mem0 Platform v3 REST API 深度解析端点、记忆对象模型、过滤系统与异步处理模型【免费下载链接】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 插件技能包中的 API 参考文档 为核心系统梳理 Mem0 Platform v3 REST API 的全部端点、记忆对象字段结构、四级作用域标识、嵌套过滤系统与异步事件处理模型并结合本仓库中 Python/TypeScript 客户端的源码实现mem0/client/main.py、mem0-ts/src/client/mem0.ts验证文档描述与实际调用行为的一致性帮助你在直连https://api.mem0.ai或使用官方 SDK 时准确构造请求、正确编写过滤器并理解响应格式。一、API 总览Base URL、鉴权与端点清单Mem0 Platform 对外提供 REST APIBase URL 为https://api.mem0.ai。所有端点都要求携带同一鉴权头Authorization: Token MEM0_API_KEYAPI Key 以m0-前缀开头通常在客户端 SDK 中通过MEM0_API_KEY环境变量注入。Python 客户端构造函数 MemoryClient 的默认host正是https://api.mem0.ai并在 httpx 请求头 中注入Authorization: Token key与Mem0-User-ID两个头——后者是 API Key 的 MD5 哈希用于平台侧的用户识别。文档给出的核心端点清单如下操作方法URLAdd MemoriesPOST/v3/memories/add/Search MemoriesPOST/v3/memories/search/Get All MemoriesPOST/v3/memories/Get Single MemoryGET/v1/memories/{memory_id}/Update MemoryPUT/v1/memories/{memory_id}/Delete MemoryDELETE/v1/memories/{memory_id}/Delete All MemoriesDELETE/v1/memories/?user_idXapp_idYGet Event StatusGET/v1/event/{event_id}/注意版本混用的设计写入add/search/get-all走 v3 端点而单条记忆的增删改查与事件轮询仍保留在 v1 路径下。这与仓库源码完全对应——MemoryClient.add() 向/v3/memories/add/发 POSTsearch() 与 get_all() 分别 POST 到/v3/memories/search/和/v3/memories/而 get()/update()/delete() 均作用于/v1/memories/{memory_id}/。TypeScript 客户端 mem0.ts 同样在三个 v3 端点上发起请求并有 单元测试 逐条断言POST /v3/memories/add/等 URL 与方法可作为端点行为的独立佐证。不依赖 SDK 时也可以直接用 cURL 调用取自 quickstart.mdexport MEM0_API_KEYm0-your-api-key # Add memory curl -X POST https://api.mem0.ai/v3/memories/add/ \ -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/v3/memories/search/ \ -H Authorization: Token $MEM0_API_KEY \ -H Content-Type: application/json \ -d { query: What are my dietary restrictions?, filters: {user_id: user123} }二、Memory 对象结构每条记忆在服务端表现为一个统一结构的对象字段类型说明idstring (UUID)唯一记忆标识memorystring记忆的文本内容user_idstring关联用户agent_idstring (nullable)Agent 标识app_idstring (nullable)应用标识run_idstring (nullable)运行/会话标识metadataobject自定义键值对categoriesarray of strings自动分配的分类标签hashstring内容哈希created_atdatetime创建时间戳updated_atdatetime最后修改时间戳搜索Search结果在此结构之外额外附带score字段作为相关性度量值在 v3 中score是一个综合多信号的相关性得分combined multi-signal relevance score而非单一的向量相似度。一个真实的搜索响应形如{ results: [ { id: ea925981-..., memory: Is a vegetarian and allergic to nuts., user_id: user123, categories: [food, health], score: 0.89, created_at: 2024-07-26T10:29:36.630547-07:00 } ] }三、作用域标识符Scoping Identifiers与实体分区规则记忆可以在四个粒度上作用域隔离作用域参数使用场景Useruser_id按用户隔离记忆Agentagent_id按 Agent 划分记忆分区Applicationapp_id跨 Agent 的应用级记忆Run/Sessionrun_id会话级的临时记忆文档特别标注了一条关键Critical约束将user_id与agent_id放在同一个 AND 过滤块中会得到空结果因为实体是分开存储stored separately的——应改用OR逻辑或分别查询。这一约束在 SDK 层面有直接体现。mem0/client/main.py 定义了实体参数集合ENTITY_PARAMS frozenset({user_id, agent_id, app_id, run_id})并且 search() 与 get_all() 会在入口处主动拒绝这些顶层实体参数抛出ValueError提示改用filters{user_id: ...}。也就是说身份字段必须放进filters字典传递v3 API 不接受顶层实体参数——mem0/client/types.py 的模块 docstring 对此有明确声明AddMemoryOptions、SearchMemoryOptions等 Pydantic 模型也都把filters设计为承载user_id等身份字段的首选字段。[SKILL.md](https://link.gitcode.com/i/ec17316e7c60d058301b98e9e6deade0)还补充了一条容易踩坑的隐式 null 作用域规则filters{user_id: alice}只返回agent_id、app_id、run_id全部为 null 的记忆若想包含带其他作用域字段的记忆需要包一层{OR: [...]}。四、异步处理模型v3 默认文档的 Processing Model 一节说明了三条事实记忆的写入在v3 默认情况下是异步处理的Add 响应只返回已排队的ADD事件——v3 是 ADD-only 的不再有 UPDATE/DELETE 事件需通过GET /v1/event/{event_id}/轮询处理状态。对应到 SKILL.md 中关于 v3 相对 v2 的变更说明v3 采用单趟single-passADD-only 抽取记忆是累积式的accumulate而非归并式的consolidate实体链接entity linking取代了 v2 的图记忆graph memory在add()时自动抽取、无需配置org_id、project_id、enable_graph参数已从 SDK 移除。由此推出一个实用的工程事实add 之后立即 search 可能查不到刚写入的记忆[SKILL.md](https://link.gitcode.com/i/ec17316e7c60d058301b98e9e6deade0)建议等待 2-3 秒后再检索同时检查user_id是否大小写完全一致。v3 的检索默认值为top_k20、threshold0.1、rerankFalse。五、过滤系统嵌套 JSON、操作符与可过滤字段5.1 过滤器结构过滤条件使用嵌套 JSON根节点必须是一个逻辑操作符{ AND: [ {user_id: alice}, {categories: {contains: finance}}, {created_at: {gte: 2024-01-01}} ] }根节点只允许AND、OR、NOT三者之一同时也支持简写形式{user_id: alice}等价于单条件 AND。5.2 支持的操作符操作符说明eq相等默认ne不相等in匹配数组中任一值gt,gte大于 / 大于等于lt,lte小于 / 小于等于contains大小写敏感的包含icontains大小写不敏感的包含*通配——匹配任意非 null 值5.3 可过滤字段与各自合法操作符字段合法操作符user_id,agent_id,app_id,run_ideq,ne,in,*created_at,updated_at,timestampgt,gte,lt,lte,eq,necategorieseq,ne,in,containsmetadataeq,ne,contains仅顶层键keywordscontains,icontainsmemory_idsin5.4 六条过滤约束实体作用域分区user_id与agent_id同处一个AND块会得到空结果metadata 限制只能过滤顶层键且仅支持eq、contains、ne不支持in和gt操作符语法必须使用gte、lt、ne这类词法操作符SQL 风格写法、!会被拒绝get-all 必须携带实体过滤user_id、agent_id、app_id、run_id至少要提供一个通配符排除 null*只匹配非 null 值日期格式ISO 8601YYYY-MM-DDTHH:MM:SSZ不带时区的时间默认按 UTC 处理。六、响应格式详解6.1 Add 响应v3{ message: Memory processing has been queued for background execution, status: PENDING, event_id: evt-uuid }响应体印证了第四节的异步模型status为PENDINGevent_id用于后续经GET /v1/event/{event_id}/轮询。v3 下该事件流中只有 ADD 事件没有 UPDATE 或 DELETE。6.2 Get All 响应v3 分页信封{ count: 123, next: https://api.mem0.ai/v3/memories/?page2page_size50, previous: null, results: [...] }v3 的列表接口返回标准分页信封通过page与page_size查询参数翻页。这一点在 Python SDK 中同样成立get_all() 会把page、page_size从 body 参数中剥离出来改作为POST /v3/memories/的 query parameters 发送docstring 也承诺返回{count, next, previous, results}结构GetAllMemoryOptions 进一步暴露了start_date、end_date、categories、show_expired、latest_only等选项。6.3 Search 响应如第二节示例所示搜索返回{results: [...]}每条结果携带score。Python SDK 的 SearchMemoryOptions 提供了完整的检索调优面top_k返回条数、rerank是否重排、threshold最低相似度阈值、fields裁剪响应字段、categories、show_expired、reference_date相对时间查询的基准日期、latest_only、keyword_search与文档v3 默认top_k20、threshold0.1、rerankFalse的说明互为表里。七、源码级验证Python 与 TypeScript 客户端如何映射这些端点以 mem0/client/main.py 中的同步客户端为样本可以逐条确认 API 参考与实现的对应关系addL217self.client.post(/v3/memories/add/, jsonpayload)。入参messages支持字符串、单条 dict 或消息列表三种形态字符串会被自动包装为[{role: user, content: ...}]L208-L213searchL329self.client.post(/v3/memories/search/, jsonpayload)且 query 会先经过 非空校验与 trimget / update / delete均对/v1/memories/{memory_id}/发起 GET / PUT / DELETE其中delete额外支持delete_linked参数——为True时会沿 v3 的linked_memory_ids链传递性删除被当前记忆取代的旧版本get_all / search 的实体参数护栏两者都在方法开头用ENTITY_PARAMS set(kwargs.keys())拦截顶层实体参数并抛出ValueError这是身份字段必须走 filters这条 API 约束在客户端侧的防御性实现错误处理所有公开方法都挂api_error_handler装饰器来自 mem0/client/utils.py将 HTTP 错误归一化为AuthenticationError、RateLimitError、MemoryQuotaExceededError、MemoryNotFoundError等异常类型。TypeScript 侧mem0-ts/src/client/mem0.ts 在add、getAll、search三个方法中分别拼接${this.host}/v3/memories/add/、${this.host}/v3/memories/、${this.host}/v3/memories/search/并用 query string 承载分页参数。[SKILL.md](https://link.gitcode.com/i/ec17316e7c60d058301b98e9e6deade0)还特别指出 TypeScript 客户端只接受 camelCase 参数名userId、agentId、appId、topK与 Python 的 snake_case 形成对照——跨语言迁移代码时这是最容易出错的一点。测试目录 mem0-ts/src/client/tests/ 中的memoryClient.crud.test.ts、memoryClient.search.test.ts、memoryClient.identity.test.ts对三个 v3 端点的 URL、HTTP 方法与参数传递逐一做了断言可视为端点契约的活文档。八、常见问题与工程建议结合 SKILL.md 的Common edge cases清单与本文 API 参考逐条对照后可沉淀出五条实用建议搜索返回空先确认 add 的异步处理已完成等 2-3 秒或轮询GET /v1/event/{event_id}/再确认user_id大小写精确匹配同时警惕隐式 null 作用域——若目标记忆带有agent_id/app_id/run_id纯user_id过滤会命中不到需用{OR: [...]}组合条件AND 组合 user_id agent_id 得空结果实体分区存储所致改用OR或拆成两次独立查询即第五节约束 1 的复现重复记忆inferTrue默认会通过 LLM 抽取事实并去重inferFalse原样存储、同一文本可能存两次两者不要对同一批数据混用SDK 选择Platform 场景用from mem0 import MemoryClient打向api.mem0.ai自托管 OSS 场景用from mem0 import Memory本地运行两者不要混用v3 检索调参默认top_k20、threshold0.1、rerankFalse对召回精度有更高要求时通过SearchMemoryOptions显式上调threshold或开启rerank。总结Mem0 Platform v3 REST API 的核心特征可以概括为三点写入异步化add 返回PENDING事件并走事件轮询ADD-only 抽取模型、查询过滤体系化AND/OR/NOT 嵌套过滤器 词法操作符 严格的实体分区规则、版本路径分层v3 负责 add/search/get-allv1 保留单条记忆 CRUD 与事件查询。本仓库的 Python 客户端、类型化选项模型 与 TypeScript 客户端及其测试 与 API 参考文档 在端点、参数约束和响应结构上高度一致可以作为编写、调试或审计 Mem0 API 集成时的双份权威依据。【免费下载链接】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），仅供参考
