Mem0 Platform 高级功能实战指南：混合检索、实体链接、自定义分类、导出、Webhook 与多模态

本文基于仓库中的 Mem0 Platform 功能参考文档 features.md 展开，系统讲解 Mem0 Platform 在核心 CRUD 之外的九大能力：v3 混合检索与 Rerank、实体链接、自定义分类与自定义指令、反馈机制、结构化记忆导出、群聊归属、MCP 集成、Webhook 与多模态支持。读完后你可以直接复制文档中的 Python/TypeScript 示例完成生产配置，并结合 Python 客户端 与 TypeScript 客户端 的源码实现核对每个 API 的真实端点、参数校验与默认值。

一、功能全景与适用前提

Mem0 Platform 是一个托管式记忆层（managed memory layer），应用只调用 add() / search()，提取、去重、冲突消解与语义检索由平台完成。核心 CRUD（add、search、get、update、delete）之外，Platform 提供以下增强能力：

能力	关键 API / 参数	是否需要配置
混合检索（v3 默认）	search() 自动启用	否
Rerank 重排序	rerank=True	是（默认 False）
实体链接	add() 时自动提取	否
自定义分类	custom_categories（项目级/调用级）	是
自定义指令	custom_instructions	是
反馈机制	feedback()	否
记忆导出	create_memory_export() / get_memory_export()	是（schema）
群聊归属	消息中的 name 字段 + run_id	否
MCP 集成	https://mcp.mem0.ai/mcp	是（客户端配置）
Webhooks	create_webhook() 等	是
多模态	image_url / mdx_url / pdf_url 消息	否

适用前提（来自技能定义文件 SKILL.md）：Python 3.10+ 或 Node.js 18+，安装 mem0ai 包并设置 MEM0_API_KEY 环境变量（密钥以 m0- 开头），使用 Mem0 v3 API。

二、高级检索（Advanced Retrieval）

v3 默认的多信号混合检索

v3 的 search() 默认使用多信号混合检索，无需任何配置：

• 语义检索（向量相似度）
• BM25 关键词检索（归一化词项匹配）
• 实体匹配（实体图加权，见下文实体链接）

从参考文档 architecture.md 的检索管线图可以看到完整流程：查询先经过预处理（关键词词形还原、实体抽取），然后并行执行三路打分，最后做分数融合（score fusion），产出每条记忆上唯一的组合 score。v3 的搜索默认参数为 top_k=20（v2 为 100）、threshold=0.1（v2 为 None）、rerank=False（v2 为 True）。

这一默认值在 Python 客户端的类型定义中有直接印证：SearchMemoryOptions 模型声明了 filters、top_k、rerank、threshold、categories、show_expired、reference_date、latest_only、keyword_search 等字段，且文档字符串明确说明身份字段（user_id、agent_id、app_id、run_id）必须放进 filters 字典——v3 API 不接受顶层身份参数。

Rerank 深度重排序

rerank=True 会对混合检索结果做深度语义重排，把最相关的记忆排到最前：

• 延迟开销：约 +150–200ms（与 architecture.md 中「Hybrid search ~100–150ms，+ reranking +150–200ms」的延迟表一致）
• 默认值：False（v2 中为 True）
• 适用场景：面向用户展示的结果、对 top-N 精度敏感的场景

results = client.search(query, filters={"user_id": "user123"}, rerank=True)

const results = await client.search(query, {
    filters: { user_id: 'user123' },
    rerank: true,
});

源码印证：Python 端 search() 会先校验顶层参数（出现 ENTITY_PARAMS 中的身份字段直接抛 ValueError 提示改用 filters），随后把 {query, filters, top_k, rerank, ...} 组装成 payload 发送到 POST /v3/memories/search/。TypeScript 端 SearchPayload 同样定义了可选的 rerank 字段（见 mem0.types.ts）。

检索过滤的两个常见陷阱

来自参考文档 SKILL.md 的「Common edge cases」：

1. 跨实体 AND 过滤返回空：{"AND": [{"user_id": "alice"}, {"agent_id": "bot"}]} 不会命中任何记忆，因为 user 与 agent 作用域的记忆是分开存储的；应改用 OR 或分两次查询。
2. 隐式 null 作用域：仅传 filters={"user_id": "alice"} 时，只返回 agent_id、app_id、run_id 全为 null 的记忆；要包含带作用域字段的记忆需写 {"OR": [{"user_id": "alice"}]}。

三、实体链接（Entity Linking）

v3 用内建实体链接取代了 v2 的图记忆。专有名词、引号内的文本、复合名词短语会在 add() 时被自动抽取，并在记忆之间建立跨记忆链接。

工作机制

1. 抽取：add() 时从记忆文本中自动抽取实体；
2. 存储：实体存入平行集合（{collection}_entities）；
3. 检索：search() 时查询中的实体被匹配，命中的记忆获得加权，加成直接折算进每条结果的组合 score。

实体链接完全自动，无需配置。architecture.md 也把存储架构描述为两部分：向量存储（语义相似度）+ 实体存储（关系感知的检索加权）。

v2 迁移注意事项

如果你在 v2 中用过 enable_graph=True，迁移到 v3 需要：

• 从所有 API 调用中移除 enable_graph；
• 从 OSS 配置中移除 graph_store；
• 实体关系不再以独立的 relations 数组暴露，而是通过检索排序体现。

官方 v2→v3 平台迁移文档在仓库内对应 migration/platform-v2-to-v3.mdx，SDK 侧的变更说明见 migration/oss-v2-to-v3.mdx。

四、自定义分类（Custom Categories）

Mem0 默认用 15 个标签自动为记忆打类，你可以用领域专属分类完全替换这套默认标签，系统会自动把记忆打到最接近的分类上。

默认分类（15 个）

personal_details、family、professional_details、sports、travel、food、music、health、technology、hobbies、fashion、entertainment、milestones、user_preferences、misc

配置方式

设置项目级分类（Python）：

new_categories = [
    {"lifestyle_management": "Tracks daily routines, habits, wellness activities"},
    {"seeking_structure": "Documents goals around creating routines and systems"},
    {"personal_information": "Basic information about the user"}
]
client.project.update(custom_categories=new_categories)

TypeScript（注意 v3 下 TypeScript 统一使用 camelCase 参数）：

await client.updateProject({ customCategories: newCategories });

读取当前生效分类：

categories = client.project.get(fields=["custom_categories"])

单次 add 调用覆盖分类：

client.add(messages, user_id="alice", custom_categories=per_call_categories)

await client.add(messages, { userId: "alice", customCategories: perCallCategories });

解析优先级（Resolution Order）

1. add 调用上传入的 custom_categories
2. 项目上设置的 custom_categories
3. 内建默认分类表

关键约束

• 单次调用传入的分类列表会整体替换该次调用的项目级列表，两个列表不做合并；
• 分类在**摄入时（ingestion time）**生效——事后修改分类列表不会重新标注已有记忆。

主要用途

通过调用级列表，你可以在同一个项目里为不同用户或实体使用各自的词汇表，而不必把它们拆分到多个项目。

源码印证：Python 客户端的 AddMemoryOptions（mem0/client/types.py）把 custom_categories 声明为 Optional[List[Dict[str, Any]]]，即「分类名 → 说明」的字典列表，与上文示例结构一致；项目级更新走 client.project.update()（旧的 client.update_project() 已标记为将在 v1.0 弃用，见 mem0/client/main.py 中的弃用警告）。

五、自定义指令（Custom Instructions）

自定义指令是自然语言过滤器，控制 Mem0 在创建记忆时提取哪些信息。

设置指令

client.project.update(custom_instructions="Your guidelines here...")

await client.updateProject({ customInstructions: "Your guidelines here..." });

指令模板结构

推荐的指令分四段：

1. 任务描述——提取任务的简要概述；
2. 信息类别——编号小节，写明要捕捉的具体细节；
3. 处理规则——质量与处理方式要求；
4. 排除清单——需要过滤掉的敏感/无关数据。

领域示例

• 电商：捕捉商品问题、偏好、服务体验；排除支付数据；
• 教育：提取学习进度、学生偏好、表现模式；排除具体分数；
• 金融：跟踪财务目标、人生事件、投资兴趣；排除账号号码与社保号（SSN）。

最佳实践

• 从简单指令起步，用样例消息测试，根据结果迭代；
• 避免过长的指令；
• 对「要包含什么」和「要排除什么」都要写明确。

源码印证：除项目级 custom_instructions 外，ProjectUpdateOptions 与 AddMemoryOptions 还都支持 agent_custom_instructions 字段，用于单独控制 agent 作用域记忆的提取指令；AddMemoryOptions 也带 custom_instructions，意味着指令同样支持调用级覆盖。

六、反馈机制（Feedback）

对已抽取的记忆提交反馈，帮助系统随时间提升质量。

反馈类型

类型	含义
POSITIVE	记忆有用且准确
NEGATIVE	记忆没有用处
VERY_NEGATIVE	记忆有害或完全错误
None	清除已有反馈

用法

Python：

client.feedback(
    memory_id="mem-123",
    feedback="POSITIVE",
    feedback_reason="Accurately captured dietary preference"
)

# 批量反馈
for item in feedback_data:
    client.feedback(**item)

TypeScript：

await client.feedback('mem-123', {
    feedback: 'POSITIVE',
    feedbackReason: 'Accurately captured dietary preference',
});

源码印证：Python 端 feedback() 实现里做了两层校验——反馈值自动转大写，且只允许 POSITIVE / NEGATIVE / VERY_NEGATIVE（传其他值直接抛 ValueError），None 用于清除反馈；请求以 JSON 发送到 POST /v1/feedback/。TypeScript 端 feedback() 使用 Feedback 枚举并发送同样的 payload，测试 memoryClient.project.test.ts 验证了请求体中 feedback_reason 字段的存在。

七、记忆导出（Memory Export）

用自定义 schema 对记忆做结构化导出，支持过滤，适合数据分析、用户画像生成、合规审计、CRM 同步等场景。

用法

import json

# 定义导出 schema
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "preferences": {"type": "array", "items": {"type": "string"}},
        "health_info": {"type": "string"},
    }
}

# 创建导出
response = client.create_memory_export(
    schema=json.dumps(schema),
    filters={"user_id": "alice"},
    export_instructions="Create comprehensive profile based on all memories"
)

# 获取导出结果（处理可能需要一点时间）
result = client.get_memory_export(memory_export_id=response["id"])

源码印证：create_memory_export() 把 schema（JSON Schema 字符串）与过滤条件一起 POST /v1/exports/，get_memory_export() 则 POST /v1/exports/get/ 按 memory_export_id 取回结果；两个方法均有对应的异步版本 AsyncMemoryClient.create_memory_export / get_memory_export。TypeScript 端测试（memoryClient.exports.test.ts）还验证了缺少 filters 或 schema 时客户端会抛错，即这两个参数实际是必填的。

八、群聊（Group Chat）

处理多参与者对话，并把记忆自动归属到具体说话人。

用法

messages = [
    {"role": "user", "name": "Alice", "content": "I think we should use React for the frontend"},
    {"role": "user", "name": "Bob", "content": "I prefer Vue.js, it's simpler for our use case"},
    {"role": "assistant", "content": "Both are great choices. Let me note your preferences."},
]

# Mem0 自动把记忆归属到每位说话人
response = client.add(messages, run_id="team_meeting_1")

# 取出 Alice 在该次会话中的记忆
alice_mems = client.get_all(
    filters={"AND": [{"user_id": "alice"}, {"run_id": "team_meeting_1"}]}
)

用消息里的 name 字段标识说话人，Mem0 会把名字自动映射到实体作用域（user_id）。配合 run_id 可以按会话聚合——这正是 architecture.md 中「会话层记忆」推荐模式：短期上下文用 run_id 隔离，会话结束可用 client.delete_all(run_id=...) 清理。

九、MCP 集成

Model Context Protocol 集成让 AI 客户端（Claude、Claude Code、Cursor、Windsurf、VS Code、OpenCode）自主管理 Mem0 记忆。

接入方式

一条命令把 Mem0 MCP 加入客户端：

npx mcp-add \
  --name mem0-mcp \
  --type http \
  --url "https://mcp.mem0.ai/mcp" \
  --clients "claude,claude code,cursor,windsurf,vscode,opencode"

仓库中 mem0-plugin 自身也声明了该 MCP 服务，见 mcp_config.json：serverUrl 指向 https://mcp.mem0.ai/mcp/，请求头携带 Authorization: Token ${MEM0_API_KEY}。

可用工具

MCP 服务暴露 9 个记忆工具，供 AI Agent 自主调用：

• 添加、搜索、获取、更新、删除记忆；
• 获取历史、列出用户、删除用户；
• 搜索 Mem0 官方文档。

工作方式

1. 用上述命令把 MCP 加入 AI 客户端；
2. Agent 自主决定何时存储/检索记忆；
3. 无需手工 API 调用——记忆管理成为 Agent 推理过程的一部分。

一句话概括：一个协议打通所有 AI 客户端的通用集成。

十、Webhooks：记忆操作实时通知

Webhook 对记忆操作提供实时事件通知。

支持的事件

事件	触发条件
memory_add	记忆创建
memory_update	记忆修改
memory_delete	记忆删除
memory_categorize	记忆被打上分类标签

创建 Webhook

注意：这里的 project_id 指 Mem0 Dashboard 中 Webhook 所属的项目范围，不是已弃用的客户端初始化参数。

webhook = client.create_webhook(
    url="https://your-app.com/webhook",
    name="Memory Logger",
    project_id="proj_123",
    event_types=["memory_add", "memory_categorize"]
)

管理 Webhook

# 查询
webhooks = client.get_webhooks(project_id="proj_123")

# 更新
client.update_webhook(
    name="Updated Logger",
    url="https://your-app.com/new-webhook",
    event_types=["memory_update", "memory_add"],
    webhook_id="wh_123"
)

# 删除
client.delete_webhook(webhook_id="wh_123")

Payload 结构

• 记忆事件包含：记忆 ID、带记忆内容的 data 对象、事件类型（ADD / UPDATE / DELETE）；
• 分类事件包含：记忆 ID、事件类型（CATEGORIZE）、被赋予的分类标签。

源码印证：Python 客户端中 create_webhook 把 {url, name, event_types} 发送到 POST api/v1/webhooks/projects/{project_id}/，update_webhook 发 PUT api/v1/webhooks/{webhook_id}/（仅提交非 None 字段），get_webhooks / delete_webhook 分别走 GET / DELETE；TS 端行为有专门的集成测试（memoryClient.webhooks.test.ts）。另外，architecture.md 提到 v3 的 add() 是异步处理（立即返回 event_id），Webhook 正是处理完成通知的配套机制。

十一、多模态支持

Mem0 可以处理图片与文档（伴随文本一起）。

支持的媒体类型

• 图片：JPG、PNG
• 文档：MDX、TXT、PDF

图片（URL 方式）

image_message = {
    "role": "user",
    "content": {
        "type": "image_url",
        "image_url": {"url": "https://example.com/image.jpg"}
    }
}
client.add([image_message], user_id="alice")

图片（Base64 方式）

import base64
with open("photo.jpg", "rb") as f:
    base64_image = base64.b64encode(f.read()).decode("utf-8")

image_message = {
    "role": "user",
    "content": {
        "type": "image_url",
        "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}
    }
}
client.add([image_message], user_id="alice")

文档（MDX / TXT）

doc_message = {
    "role": "user",
    "content": {"type": "mdx_url", "mdx_url": {"url": document_url}}
}
client.add([doc_message], user_id="alice")

文档（PDF）

pdf_message = {
    "role": "user",
    "content": {"type": "pdf_url", "pdf_url": {"url": pdf_url}}
}
client.add([pdf_message], user_id="alice")

实现上，多模态消息最终都通过 client.add() 的 messages 参数传入；Python 客户端的 add() 会把字符串/单条字典归一化为消息列表后 POST /v3/memories/add/，content 的复合结构（image_url / mdx_url / pdf_url）原样进入 payload 交给平台解析。

十二、小结：v3 关键默认值速查

项	v3 值	v2 对照
top_k	20	100
threshold	0.1	None
rerank	False	True
图记忆	内建实体链接（自动）	enable_graph + graph_store
add 响应	异步，返回 event_id	同步
提取模式	单遍 ADD-only 提取	UPDATE/DELETE 合并

以上默认值在 SKILL.md 的 v3 API 章节与 architecture.md 的「v3 Search Defaults」表中互相印证。完整的平台 API 端点与对象结构可继续参考同目录的 api-reference.md、sdk-guide.md 与 use-cases.md；双语言 SDK 差异见 client/differences.md。