为 Claude 与 AI Agent 接入 Mem0 持久记忆：mem0 Skill 的安装配置与实战指南

Mem0 是面向 AI Agent 的记忆层（Memory Layer），而本仓库中的 skills/mem0 是一个打包成 Claude Skill 的技能包：安装后，Claude（以及 Claude Code、OpenCode 等支持 Skills 的 Agent 工具）可以直接帮助你在 Python 或 TypeScript 项目中完成 Mem0 的初始化、记忆读写与框架集成，并生成基于真实 API 文档的可运行代码。读完本文，你将掌握 mem0 Skill 的三种安装方式、触发方式、目录内每个参考文件的作用，以及如何用它快速搭建“检索 → 生成 → 存储”的持久记忆应用，并了解其 Platform 与 OSS 两条技术路径的差异。

---

mem0 Skill 是什么：把“加记忆”变成一句自然语言

skills/mem0/SKILL.md 是真正的技能定义文件，其元信息（front-matter）明确了技能名称、版本（3.0.0）、授权（Apache-2.0）与触发规则：

• 触发场景：当用户提到 “mem0”“MemoryClient”“memory layer”“remember user preferences”“persistent context”“personalization”，或需要在聊天机器人、Agent、AI 应用中添加长期记忆时触发；
• 能力范围：覆盖 Python SDK（mem0ai）、TypeScript SDK（mem0ai），以及 LangChain、CrewAI、OpenAI Agents SDK、Pipecat、LlamaIndex、AutoGen、LangGraph 等框架集成，同时覆盖开源自托管的 Memory 类；
• 默认技能：对于模糊的 memory 相关提问，它被标记为 DEFAULT mem0 skill；
• 不触发场景：CLI 终端用法（交给 mem0-cli skill）、Vercel AI SDK 的 @mem0/vercel-ai-provider / createMem0（交给 mem0-vercel-ai-sdk skill）。

也就是说，本 Skill 是“SDK 集成型”技能，它与 mem0-cli（终端型）和 mem0-vercel-ai-sdk（框架型）共同构成 Mem0 Skill Graph，分别覆盖 Agent 集成的三个侧面。

在项目说明文档中，技能被定义为“用几分钟为任意 AI 应用添加持久记忆”——记忆可以是托管在 Mem0 Platform 上的（通过 API Key 调用 api.mem0.ai），也可以基于开源自托管 SDK 本地运行。

安装后 Claude 能做什么

按 skills/mem0/README.md 的说明，技能安装成功后，Claude 可以替你完成四类工作：

1. 搭建 Mem0：在你的 Python 或 TypeScript 项目中初始化 Mem0（Platform 模式或 OSS 模式）；
2. 集成记忆：把记忆能力接入已有 AI 应用（LangChain、CrewAI、OpenAI Agents、LangGraph、LlamaIndex 等）；
3. 生成可运行代码：基于真实的 API 参考与经过测试的代码范式生成代码；
4. 按需检索官方文档：通过内置脚本实时搜索 Mem0 最新文档。

这背后是 Mem0 的托管式设计：Mem0 在服务端负责信息抽取（extraction）、去重（deduplication）、冲突消解（conflict resolution）与语义检索，应用侧只需调用 search() 与 add() 即可，正如 架构参考 中概括的核心循环：

User Input → Retrieve relevant memories → Enrich LLM prompt → Generate response → Store new memories

安装：三种方式与前置条件

方式一：CLI（Claude Code、OpenCode、OpenClaw 或任何支持 Skills 的工具）

npx skills add <mem0仓库地址> --skill mem0

说明：此命令从 Mem0 官方仓库拉取 skills/mem0 目录并注册为 skill（原安装命令中仓库地址为 Mem0 的官方 GitHub 仓库路径）。在当前镜像仓库中，技能源码已直接保存在 skills/mem0 目录下，可直接阅读。

方式二：Claude.ai（网页版）

1. 下载本仓库 skills/mem0 文件夹为 ZIP 压缩包；
2. 进入 Settings > Capabilities > Skills；
3. 点击 Upload skill 并选择该 ZIP 即可上传启用。

方式三：Claude API（Skills API）

curl -X POST https://api.anthropic.com/v1/skills \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mem0", "source": "<mem0仓库的skills/mem0目录地址>"}'

前置条件

在让 Claude 开始写记忆集成代码前，你需要准备：

• 一个 Mem0 Platform API Key（在 Mem0 Platform 控制台的 API Keys 页面获取，形如 m0-xxx）；
• Python 3.10+ 或 Node.js 18+ 运行环境；
• 设置环境变量，让 SDK 免显式传 Key：

export MEM0_API_KEY="m0-your-api-key"

Python 与 TypeScript 两个版本的 SDK 都会在未显式传入 api_key/apiKey 时自动读取该环境变量，找不到时会抛出 ValueError（Python）。

快速开始：直接“开口要”

安装完成并配置好 MEM0_API_KEY 后，无需记忆任何 SDK 细节，直接用自然语言向 Claude 下达指令即可，例如：

• “Set up mem0 in my project”
• “Add memory to my chatbot”
• “Help me search user memories with filters”
• “Integrate mem0 with my LangChain app”
• “Add graph memory to track entity relationships”

Claude 会根据 SKILL.md 中记录的 Step 1 安装认证 → Step 2 初始化客户端 → Step 3 核心操作 流程替你生成完整代码。以最核心的 Python 流程为例：

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

from mem0 import MemoryClient

client = MemoryClient(api_key="m0-xxx")

# 写入记忆
messages = [
    {"role": "user", "content": "I'm a vegetarian and allergic to nuts."},
    {"role": "assistant", "content": "Got it! I'll remember that."}
]
client.add(messages, user_id="alice")

# 语义检索
results = client.search("dietary preferences", filters={"user_id": "alice"})
for mem in results.get("results", []):
    print(mem["memory"])

# 列举与更新删除
all_memories = client.get_all(filters={"user_id": "alice"})
client.update("memory-uuid", text="Updated: vegetarian, nut allergy, prefers organic")
client.delete("memory-uuid")
client.delete_all(user_id="alice")  # 删除某用户全部记忆

TypeScript 侧使用相同的三步模式（import MemoryClient from 'mem0ai'），所有方法均返回 Promise。需要异步时，Python 使用 AsyncMemoryClient。

通用集成范式：检索 → 生成 → 存储

Skill 的核心价值在于让 Claude 直接产出“带记忆”的完整对话闭环。SKILL.md 内置了不依赖任何框架的通用参考实现：

from mem0 import MemoryClient
from openai import OpenAI

mem0 = MemoryClient()
openai = OpenAI()

def chat(user_input: str, user_id: str) -> str:
    # 1. 检索相关记忆
    memories = mem0.search(user_input, filters={"user_id": user_id})
    context = "\n".join([m["memory"] for m in memories.get("results", [])])

    # 2. 携带记忆上下文生成回复
    response = openai.chat.completions.create(
        model="gpt-5-mini",
        messages=[
            {"role": "system", "content": f"User context:\n{context}"},
            {"role": "user", "content": user_input},
        ]
    )
    reply = response.choices[0].message.content

    # 3. 把本轮交互存回记忆，供下次使用
    mem0.add(
        [{"role": "user", "content": user_input}, {"role": "assistant", "content": reply}],
        user_id=user_id
    )
    return reply

这个 retrieve → generate → store 三段循环是所有 Mem0 集成（无论 LangChain、CrewAI、OpenAI Agents 还是 LangGraph）的共同骨架，集成模式参考 中对其有完整归纳。

目录内容全解析：Skill 到底内置了什么

skills/mem0/README.md 给出了技能的完整目录结构（以下为原样保留，目录起点即 skills/mem0/）：

skills/mem0/
├── SKILL.md                    # Skill definition and instructions
├── README.md                   # This file
├── LICENSE                     # Apache-2.0
├── client/                     # Language-specific SDK references (Platform + OSS)
│   ├── python.md               # Python SDK (MemoryClient + Memory OSS)
│   ├── node.md                 # TypeScript SDK (MemoryClient + Memory OSS)
│   └── differences.md          # Python vs TypeScript comparison
├── scripts/
│   └── mem0_doc_search.py      # Search live Mem0 docs on demand
└── references/                 # Documentation (loaded on demand)
    ├── quickstart.md           # Full quickstart (Python, TS, cURL)
    ├── sdk-guide.md            # All SDK methods (Python + TypeScript)
    ├── api-reference.md        # REST endpoints, filters, memory object
    ├── architecture.md         # Processing pipeline, lifecycle, scoping, performance
    ├── features.md             # Retrieval, graph, categories, MCP, webhooks, multimodal
    ├── integration-patterns.md # LangChain, CrewAI, OpenAI Agents, LangGraph, LlamaIndex, etc.
    └── use-cases.md            # 7 real-world patterns with Python + TypeScript code

Claude 在设计上并不会一次性加载全部内容，而是按需读取对应文件（load on demand），避免撑爆上下文。下表把每个文件对应到仓库根目录路径，方便你在本仓库中直接打开研读：

Skill 内文件	仓库根目录相对路径	内容定位
技能定义	skills/mem0/SKILL.md	触发规则、三步上手、边界情形、v2 兼容说明
客户端 SDK 参考（Python）	skills/mem0/client/python.md	MemoryClient/AsyncMemoryClient 全部方法与 OSS Memory
客户端 SDK 参考（Node/TS）	skills/mem0/client/node.md	mem0ai 包全部方法、类型定义与 OSS Memory
Python/TS 差异速查	skills/mem0/client/differences.md	命名规范、参数风格、平台独有能力
文档检索脚本	skills/mem0/scripts/mem0_doc_search.py	按需搜索官方文档，无需 API Key
快速上手	skills/mem0/references/quickstart.md	Python / TS / cURL 三端 2 分钟上手与样例响应
SDK 指南	skills/mem0/references/sdk-guide.md	全部 SDK 方法、过滤器范式、v2→v3 迁移
API 参考	skills/mem0/references/api-reference.md	REST 端点、过滤器、memory 对象结构
架构说明	skills/mem0/references/architecture.md	处理管线、生命周期、作用域、性能特征
平台特性	skills/mem0/references/features.md	混合检索、实体链接、分类、MCP、Webhooks、多模态
集成模式	skills/mem0/references/integration-patterns.md	LangChain、CrewAI、OpenAI Agents 等框架代码
真实用例	skills/mem0/references/use-cases.md	7 个场景，Python + TypeScript 双端实现

SDK 参考文件的价值：方法族全景

Python SDK 参考 与 Node SDK 参考 是 Claude 生成代码时的“语法字典”。它们不仅覆盖 CRUD，还覆盖批量操作与平台管理能力：

• 核心记忆方法：add()、search()、get()、get_all()、update()、delete()、delete_all()、history()；
• 批量方法：batch_update() / batch_delete()，单次请求最多操作 1000 条记忆；
• 实体管理：users()、delete_users()、reset()（清空全部数据）；
• 导出与摘要：create_memory_export()、get_memory_export()、get_summary()（Python 独有）；
• 质量反馈：feedback()，支持 POSITIVE / NEGATIVE / VERY_NEGATIVE 三档评价与 feedback_reason；
• Webhooks：create_webhook()、get_webhooks()、update_webhook()、delete_webhook()；
• 项目管理：Python 走 client.project.*，TypeScript 走 getProject() / updateProject()。

这些参考文件在仓库的 Python 包源码中可以一一印证：例如 MemoryClient 定义于 mem0/client/main.py，其 add（第 184 行）、get_all（第 249 行）、search（第 297 行）、reset（第 548 行）等核心方法与 Skill 文档描述的签名一致；AsyncMemoryClient 定义于同一文件的第 977 行，方法一一对应；开源自托管模式下的 Memory 类则位于 mem0/memory/main.py，异步版本 AsyncMemory 位于该文件第 2172 行。

Platform 与 OSS：一条文档，两条路径

Skill 的客户端参考刻意把两种使用方式写在同一份文档里，并提供了对照表。核心差异概括如下：

维度	Platform（MemoryClient）	OSS（Memory）
Python 导入	from mem0 import MemoryClient	from mem0 import Memory
TypeScript 导入	import MemoryClient from 'mem0ai'	import { Memory } from 'mem0ai/oss'
认证	需要 MEM0_API_KEY	无需 Key，改为配置驱动
执行位置	API 调用 api.mem0.ai	本地执行
基础设施	全托管（向量库、Embedder、LLM 均托管）	自行管理向量库、Embedder 与 LLM
批量/Webhook/导出/反馈/项目管理	全部支持	不支持（本地无这些托管能力）
变更历史	平台托管	SQLite 本地存储（可配置 history_db_path）
异步形态	AsyncMemoryClient	AsyncMemory

OSS 模式通过 Memory.from_config(config) 传入字典配置即可运行，例如 Python 端可配置：

config = {
    "llm": {
        "provider": "openai",   # openai, groq, azure, ollama, lmstudio, google, anthropic, mistral
        "config": {"model": "gpt-5-mini", "api_key": "sk-xxx"},
    },
    "embedder": {
        "provider": "openai",   # openai, ollama, azure, lmstudio, google, huggingface
        "config": {"model": "text-embedding-3-small", "api_key": "sk-xxx"},
    },
    "vector_store": {
        "provider": "qdrant",   # faiss, qdrant, pgvector, redis, supabase, azure_ai_search, memory
        "config": {"collection_name": "my_memories", "host": "localhost", "port": 6333},
    },
    "history_db_path": "history.db",
}
m = Memory.from_config(config)

TypeScript 侧配置键使用驼峰（vectorStore、historyDbPath、customInstructions），二者差异可查 client/differences.md。这些 provider 列表在仓库中同样有真实实现佐证：LLM 与 Embedder 的 provider 目录分别位于 mem0/configs/llms 与 mem0/configs/embeddings，向量库目录位于 mem0/configs/vector_stores。

架构参考：add 与 search 的底层发生了什么

架构参考 解释了两个关键管线，这也是 Claude 写代码时需要理解的行为边界：

写入管线（client.add()）：

1. 抽取：默认 infer=True 时由单次 LLM 调用抽取全部独立新事实；infer=False 时原样存储文本（此时仅 user 角色的消息会被存储）；
2. 去重：基于哈希（MD5）阻止完全重复，v3 采用 ADD-only 语义，不再自动产生 UPDATE/DELETE；
3. 存储：批量嵌入写入向量库，实体抽取后写入实体库（{collection}_entities 并行集合）。

检索管线（client.search()）：

1. 预处理：关键词词形还原、实体抽取；
2. 并行打分：语义检索（向量相似度）+ BM25 关键词匹配 + 实体匹配加权；
3. 分数融合：融合为单一相关性分数，可选 rerank=True 做深度重排。

v3 默认值是实践中最容易踩坑的点：top_k=20、threshold=0.1、rerank=False（v2 分别为 100、无阈值、True）。另外，v3 的 add() 是异步处理的——API 立即返回 {"status": "PENDING", "event_id": "evt-..."}，因此 add() 之后立刻 search() 可能查不到结果，通常需要等待 2～3 秒。

平台特性：不止增删改查

features.md 汇总了 CRUD 之外的能力，值得在提问时让 Claude 帮你组合使用：

• 混合检索与重排：v3 默认即混合检索（语义 + BM25 + 实体），无需配置；rerank=True 增加 150-200ms 延迟换取 Top-N 精度；
• 实体链接：v3 以内置实体链接取代 v2 的 graph memory，add() 时自动抽取实体并在检索时加权，不再返回独立的 relations 数组；
• 自定义分类（Custom Categories）：默认内置 15 个分类标签（personal_details、family、health、user_preferences 等），可通过 client.project.update(custom_categories=[...]) 按业务域替换；注意“按次传入会整体替换项目级列表、不会合并”，且分类在摄入时生效，事后修改不会重新打标旧记忆；
• 自定义指令（Custom Instructions）：用自然语言控制抽取内容，模板含任务描述、信息类别、处理准则、排除清单四部分，适合电商、教育、金融等敏感域过滤；
• 反馈机制：对记忆标注 POSITIVE / NEGATIVE / VERY_NEGATIVE，帮助系统持续优化抽取质量；
• 记忆导出：按 JSON Schema 导出结构化记忆，适合数据分析、合规审计、CRM 同步；
• 群聊归属：消息带 name 字段时自动按说话人归属记忆（Group Chat）；
• MCP 集成：Mem0 MCP Server（HTTP 端点）向 Claude、Cursor、Windsurf、VS Code、OpenCode 等客户端暴露 9 个记忆工具，让 Agent 自主管理记忆；
• Webhooks：memory_add / memory_update / memory_delete / memory_categorize 四类事件实时通知；
• 多模态：支持图片（URL 或 Base64）与 MDX/TXT/PDF 文档作为消息内容写入记忆。

集成模式与用例：让 Claude 按框架生成

集成模式参考 提供了针对各 AI 框架的完整代码，例如：

• LangChain：在提示模板中插入 MessagesPlaceholder 承载检索到的记忆上下文；
• CrewAI：通过 Crew 的 memory_config={"provider": "mem0", "config": {"user_id": "..."}} 原生接入；
• OpenAI Agents SDK：把 search_memory / save_memory 封装为 function_tool，支持多 Agent + Handoffs 场景；
• LangGraph：在状态图中以记忆检索结果构造 system message；
• LlamaIndex：Mem0Memory.from_client(context=...) 原生记忆，配套 llama-index-memory-mem0 包；
• AutoGen、Pipecat（语音）：分别以“检索增强 prompt”和 Mem0MemoryService 流水线节点的方式接入。

仓库的 docs/integrations 目录为这些框架维护了对应的完整集成文档（如 langchain.mdx、openai-agents-sdk.mdx、crewai.mdx、langgraph.mdx、llama-index.mdx），需要更细实现时可进一步查阅。

而 use-cases.md 给出了 7 个端到端可运行场景（Python + TypeScript 双实现），包括个性化 AI 伴侣、带分类的客户支持、健康教练（高 threshold=0.7 保障安全检索）、内容创作工作流、多 Agent / 多租户隔离、个性化搜索、邮件智能。从中可以提炼出四条跨场景的通用模式：

1. Retrieve → Generate → Store：检索记忆拼装上下文 → LLM 生成 → 回存交互；
2. 用实体标识符做作用域隔离：user_id（用户级持久）、run_id（会话级临时）、agent_id + app_id（Agent/应用级）；
3. 富 metadata 支持多维过滤：写入时打 priority、source、sender 等标签，检索时按类别与元数据组合过滤；
4. custom_instructions 控制领域化抽取：只提取业务关心的信息并排除敏感字段。

避坑清单：Skill 内置的常见边界情形

SKILL.md 与 sdk-guide.md 都整理了高频踩坑点，这些会直接影响 Claude 生成代码的正确性：

1. 检索为空：记忆是异步处理的，add() 后等 2～3 秒再搜；同时确认 user_id 大小写完全一致，并严格使用 filters={"user_id": "..."} 语法；
2. AND 同时过滤 user_id + agent_id 返回空：实体分开存储，跨实体查询必须改用 OR 或分开查询；
3. 重复记忆：同一份数据不要混用 infer=True（默认）与 infer=False，否则同一事实会存两份；
4. 导入错误：Platform 一律 from mem0 import MemoryClient（异步用 AsyncMemoryClient），不要把 OSS 的 from mem0 import Memory 混进来；
5. 运算符与默认值：过滤器只接受 gte/lt/ne 等写法（SQL 风格 >=、!= 会被拒绝）；threshold 默认 0.1，需要高精度时调大；通配符 * 只匹配非空值；
6. metadata 过滤有限制：仅支持顶层 key，且只有 eq、contains、ne 三个算子；
7. get_all 必须有实体过滤：filters 中至少要包含 user_id / agent_id / app_id / run_id 之一。

按需检索最新文档：内置脚本用法

当 Skill 内置参考不足以覆盖最新 API 时，可让 Claude 调用随技能附带的文档搜索脚本 mem0_doc_search.py。该脚本基于 Mintlify 文档结构实现即时检索，不需要 API Key，直接访问官方文档站：

python ${CLAUDE_SKILL_DIR}/scripts/mem0_doc_search.py --query "topic"
python ${CLAUDE_SKILL_DIR}/scripts/mem0_doc_search.py --page "/platform/features/graph-memory"
python ${CLAUDE_SKILL_DIR}/scripts/mem0_doc_search.py --index
python ${CLAUDE_SKILL_DIR}/scripts/mem0_doc_search.py --query "webhook events" --section platform

它支持关键词搜索（--query）、整页拉取（--page）、站点索引（--index）以及按 section 定向检索，且内置了 platform、api、open-source 等分节页面清单，能显著减少无关内容对上下文的占用。

v2 兼容提示

如果目标项目还在使用 SDK v2.x，需要让 Claude 注意（详见 SDK 参考文件中的迁移小节，当前仓库的 docs/migration/oss-v2-to-v3.mdx 也有对应说明）：

• 实体 ID 传参位置变化：v2 中 user_id 作为 search() 顶层参数，v3 必须放入 filters（如 filters={"user_id": "alice"}）；
• 默认值变化：top_k 由 100 → 20、threshold 由无 → 0.1、rerank 由 True → False；
• 命名变化（TS）：顶层参数改驼峰（topK、userId），但 filter 内的 key 仍为 snake_case（user_id）；
• 已移除参数：enable_graph、async_mode、output_format、immutable、expiration_date、keyword_search、filter_memories 等均不再支持；图记忆能力由 v3 内置的实体链接取代。

与其他 Mem0 Skill 的协作边界

Skill Graph 明确了使用边界，避免多个技能互相抢答：

Skill	适用场景	仓库位置
mem0（本文）	Platform Client SDK + OSS（Python + TypeScript），为应用/AI 应用加记忆	skills/mem0/SKILL.md
mem0-cli	终端命令、脚本、CI/CD、Agent 工具循环（含 mem0 init 等认证引导）	skills/mem0-cli/SKILL.md
mem0-vercel-ai-sdk	Vercel AI SDK provider，包一层模型即自动获得记忆	skills/mem0-vercel-ai-sdk/SKILL.md

特别地，如果你还没有 MEM0_API_KEY，Skill 会引导你先装 mem0-cli，然后通过 mem0 init --agent --agent-caller <你的Agent身份> --json 完成平台侧 Agent 身份注册，再由人工通过 mem0 init --email <邮箱> 认领，之后再回到本 Skill 使用 MemoryClient——两条路径衔接清晰。

授权与结论

skills/mem0/LICENSE 表明该 Skill 以 Apache-2.0 协议发布，与仓库其他模块一致。对本仓库的使用者而言，即使不通过远程安装命令，也可以直接读取 skills/mem0 目录下的源码级参考，配合 mem0/client/main.py 与 mem0/memory/main.py 的 Python 实现，逐行理解 Platform 与 OSS 的记忆读写逻辑。总结下来，这套 Skill 的实际价值在于：把“持久记忆 + 框架集成”这一原本需要查阅多份文档的任务，压缩成一句自然语言指令，让 Claude 依据随包携带的真实 API 参考与架构细节，稳定地产出可运行、可迁移、符合 v3 语义的记忆集成代码。