企业官网建设流程全解析

mem0-mcp 是一个把 Mem0 官方记忆 API 封装成 Model Context Protocol（MCP）服务的开源项目，让 Claude Desktop、Cursor 等客户端都能对 AI 进行长期记忆管理。本文重点讲进阶用法：如何用好 user_id、agent_id、app_id、run_id 四级实体作用域来组织记忆，以及如何安全地完成实体级清理（delete_all_memories 与 delete_entities 的区别与正确姿势）。

快速认识 mem0-mcp 的工具箱

mem0-mcp 把 Mem0 的记忆能力暴露为 9 个 MCP 工具，核心工具一览：

工具定义位于 server.py，参数模型统一声明在 schemas.py。

user/agent/app/run 四级作用域：给记忆打上"坐标系"

Mem0 用四个可选标识符来定位一条记忆属于谁，它们可以自由组合，就像给记忆打上坐标系：

add_memory写入时，四个字段都是可选参数，但至少要有一个（user_id 若未显式给出且也没指定 agent_id/run_id，会自动使用服务端默认值）。

一个常见的分层设计：

user_id = alice # 人的维度 app_id = mem0-mcp-demo # 应用的维度 agent_id = support-bot # 智能体的维度 run_id = session-2024-01 # 单次会话

这样查询时可以只过滤其中一两层，比如"alice 在 support-bot 下所有的记忆"，而无需关心具体是哪次 run。

写入记忆：add_memory 的作用域用法

调用add_memory时，把目标作用域一并传入即可。服务端会自动处理一个细节：当只给了text没给messages时，text会被转换成一条role=user的对话再入库（见 server.py 中add_memory的实现）。

{ "text": "用户偏好深色模式，回复要简短", "user_id": "alice", "agent_id": "support-bot", "app_id": "mem0-mcp-demo", "run_id": "session-2024-01" }

💡 若配置了MEM0_DEFAULT_USER_ID环境变量，则user_id可省略，服务端会自动补上默认值（默认mem0-mcp）。

检索记忆：filters 是作用域管理的核心

search_memories与get_memories都支持结构化filters，且服务端会自动注入user_id（未显式提供时），防止跨用户读取。常用过滤器写法（摘自 server.py 中的工具描述）：

{"AND": [{"user_id": "john"}]} {"AND": [{"agent_id": "agent_name"}]} {"AND": [{"user_id": "john"}, {"created_at": {"gte": "2024-01-01"}}]} {"AND": [{"user_id": {"in": ["john", "jane"]}}]} {"OR": [{"user_id": "john"}, {"agent_id": "agent_name"}]}

• 单实体过滤：{"AND": [{"user_id": "john"}]}
• 时间范围：created_at支持gte/lte等操作符
• 跨实体查询：用OR组合不同维度
• 还可使用"*"通配符匹配任意非空值

get_memories额外支持page/page_size分页浏览，适合"列出某用户全部记忆"的场景。

实体清理进阶：delete_all_memories 与 delete_entities 别搞混

这是新手最容易踩坑的地方。两个删除工具的语义完全不同：

delete_all_memories的作用域参数（user_id / agent_id / app_id / run_id）与写入时一致，user_id缺省为服务端默认用户，参数模型见 schemas.py 中的DeleteAllArgs。

而delete_entities要求至少显式提供一个user_id、agent_id、app_id 或 run_id，否则会直接返回scope_missing错误，防止误删——这是一个值得学习的防护设计。

推荐的操作顺序（三步走）

1. 先盘点：用list_entities看看当前都有哪些用户/智能体/应用/运行；
2. 再抽查：用get_memories或search_memories确认该作用域下要删的内容；
3. 后清理：按需选择"清内容保实体"（delete_all_memories）或"连实体一起删"（delete_entities）。

⚠️ 两个工具都不可逆，且delete_entities是级联删除。生产环境建议先备份或在小范围作用域上验证。

配置与本地联调

环境变量与配置方式见 config.json，关键项：

• MEM0_API_KEY：Mem0 平台 API Key（必填）
• MEM0_DEFAULT_USER_ID：默认 user_id，缺省为mem0-mcp
• MEM0_ENABLE_GRAPH_DEFAULT：是否默认启用图记忆（默认关闭，查询更快）

项目自带一个 Pydantic AI 交互式示例 pydantic_ai_repl.py，可以直观体验"记住我喜欢提拉米苏"→"搜索我的饮食偏好"→"删除某作用域记忆"的完整流程，示例说明见 example/README.md。

小结

• 写：add_memory支持 user/agent/app/run 四级作用域任意组合，构建清晰的记忆坐标系
• 查：search_memories/get_memories用AND/OR/NOT结构化过滤器精确圈定范围，user_id会自动注入
• 删：清内容用delete_all_memories，连实体一起删用delete_entities（强制要求显式指定作用域）
• 习惯：先list_entities盘点、再抽查确认、最后执行删除

掌握这套"四级作用域 + 双删除策略"的组合，你的 AI 应用就能在多用户、多智能体环境下保持记忆既清晰又可控。