mem0 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

mem0 项目

面向 AI Agent 的通用记忆层，为智能体提供跨会话、跨应用的记忆能力。

项目概览

mem0 是一个面向 AI Agent 的生产级长期记忆层（Memory Layer），通过可插拔的 LLM、嵌入模型与向量存储后端，为对话式应用提供"事实抽取—冲突解决—检索增强"全流程能力。项目主仓库同时托管 Python 与 TypeScript 两条 SDK 主线、OpenMemory 自托管套件、Mem0 Plugin、官方 Skills 资源以及 LoCoMo ...

章节 相关页面

继续阅读本节完整说明和来源证据。

项目定位与核心能力

主仓库顶层 README.md 将 mem0 描述为"the memory layer for AI Agents"，强调其为个性化 AI 系统提供的可扩展长期记忆基础设施。Python SDK 与 TypeScript SDK（mem0-ts）并列发布，TS OSS 子包 mem0-ts/src/oss/README.md 进一步说明其内置 OpenAI 嵌入与补全、SQLite 历史、可选图谱关系、TypeScript 类型安全与可扩展接口。

仓库结构与子项目

mem0 仓库采用 monorepo 风格组织，主要子目录各自承担不同职能：

子目录/包	角色	关键证据
`mem0-ts/src/oss`	TS 版 OSS 核心（事实抽取、检索、混合打分）	`mem0-ts/src/oss/README.md` 列出向量存储、嵌入、LLM 等可插拔点
`mem0-ts/src/client`	面向 Mem0 Platform 的 REST 客户端	`mem0-ts/src/client/mem0.types.ts` 定义 `WebhookCreatePayload`、`CreateMemoryExportPayload` 等类型
`mem0-ts/src/community`	社区扩展（LangChain 集成等）	`mem0-ts/src/community/package.json` 暴露 `./langchain` 子入口
`openmemory/`	自托管 OpenMemory MCP 服务	`openmemory/README.md` 描述其面向本地优先的部署
`mem0-plugin/`	跨编辑器插件（Claude Code、Cursor、Codex 等）	`mem0-plugin/README.md` 列出 `Lifecycle Hooks`、`MCP Server`、`Mem0 SDK Skill` 三类能力
`skills/mem0/`	官方 Skill 资源，供 AI 编程助手按需加载	`skills/mem0/README.md` 给出 `references/` 文档树
`server/dashboard/`	Web 控制台，含引导式 Onboarding	`server/dashboard/src/app/setup/page.tsx` 展示按 `use_case` 生成 `custom_instructions` 的流程
`evaluation/`	LoCoMo 等基准的可复现实验	`evaluation/README.md` 提供 `make run-mem0-add` 等 Make 目标
`examples/`	端到端样例（多模态、Vercel AI SDK Chat）	`examples/vercel-ai-sdk-chat-app/package.json` 依赖 `mem0ai: 2.1.2`

核心架构概览

mem0 的处理流水线可概括为"消息输入 → 事实抽取 → 记忆合并 → 向量存储 → 检索重排"。mem0-ts/src/oss/src/prompts/index.ts 中的 FactRetrievalSchema 与 MemoryUpdateSchema 驱动 LLM 完成事实抽取与去重；entity_extraction.ts 负责基于词性、专有名词与正则回退的实体识别；scoring.ts 提供 BM25 Sigmoid 归一化、查询长度自适应参数与"语义 + BM25 + 实体加权"的混合打分（ENTITY_BOOST_WEIGHT = 0.5）。LLM 层通过 langchain.ts 适配 LangChain BaseLanguageModel，允许传入任意 invoke 兼容模型。

flowchart LR
  A[Messages] --> B[Fact Extraction<br/>FactRetrievalSchema]
  B --> C[Entity Extraction<br/>entity_extraction.ts]
  C --> D[Memory Update<br/>MemoryUpdateSchema]
  D --> E[Vector Store<br/>Qdrant / PGVector / ...]
  E --> F[Hybrid Scoring<br/>scoring.ts]
  F --> G[Results]
  H[LangChain LLM] --> B
  H --> D

社区关注与已知问题

从近期社区讨论与 Issue 可归纳出三类高频关注点，对评估"项目概览"中的能力边界尤为关键：

V3 Add 流水线的静默失败：Memory.add() 在批嵌入部分失败时仅记录 WARNING，不会向上抛异常，调用方可能误以为所有事实已落库（参考 Issue #5245）。
自托管与可插拔后端：社区呼吁将 OSS 存储层完全插件化，以便对接外部云原生后端；与之相关，Qdrant 在仅配置 host/port/api_key 时被错误地以 HTTPS 连接自托管实例（Issue #5378、#5354）。
SDK 一致性与安全卫生：TS 版 OpenAIEmbedder 默认 encoding_format="base64"，部分 OpenAI 兼容代理无法解析（Issue #5168）；近期多个发布（ts-v3.0.6、vercel-ai-v2.0.6、openclaw-v1.0.12、cli-node-v0.2.8）集中修复了 axios、jws、tar-fs、minimatch、picomatch 等多个高危 CVE。

此外，Platform v3 /v3/memories/add/ 接口曾出现 user_id/agent_id 入参被接受却未落库的问题（Issue #5224），npm 上亦出现过仿冒 mem0-mcp-server 的恶意包（Issue #5274），自托管用户应通过官方 @mem0/mcp-server 名称安装。

Lib 模块

server/dashboard/src/lib/ 是 Mem0 自托管 Web 控制台（server/dashboard）前端代码库中的共享工具与基础设施层。该目录集中放置了与具体业务页面（app/）和 UI 组件（components/）解耦的横切关注点，包括身份认证、错误处理、服务端地址解析、通用工具函数与输入校验。lib/ 下的文件被大量业务页面和 UI 组件通过 ...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 1. utils.ts —— 通用工具

继续阅读本节完整说明和来源证据。

章节 2. error-message.ts —— 错误信息归一化

继续阅读本节完整说明和来源证据。

章节 3. auth.tsx —— 认证上下文

继续阅读本节完整说明和来源证据。

概述与定位

server/dashboard/src/lib/ 是 Mem0 自托管 Web 控制台（server/dashboard）前端代码库中的共享工具与基础设施层。该目录集中放置了与具体业务页面（app/）和 UI 组件（components/）解耦的横切关注点，包括身份认证、错误处理、服务端地址解析、通用工具函数与输入校验。lib/ 下的文件被大量业务页面和 UI 组件通过 @/lib/... 路径导入，避免在多个页面中重复实现相同的逻辑。

资料来源：server/dashboard/src/lib/auth.tsx:1-1、server/dashboard/src/lib/utils.ts:1-1

子模块组成

lib/ 目录包含 5 个核心文件，每个文件承担一个明确的职责：

文件	主要职责	关键导出（基于使用点推断）
`auth.tsx`	用户身份认证上下文与路由守卫	Auth Provider / `useAuth` 等 React Context 钩子
`error-message.ts`	统一从异常对象中提取可展示的错误文本	`getErrorMessage(err, fallback)`
`server-api-url.ts`	解析后端 API 的基础 URL（处理相对路径、环境变量等）	`getServerApiUrl()`
`utils.ts`	通用前端工具（如 className 合并）	`cn(...)`
`validators.ts`	表单与请求体校验	表单/字段级校验函数

资料来源：server/dashboard/src/lib/auth.tsx:1-1、server/dashboard/src/lib/error-message.ts:1-1、server/dashboard/src/lib/server-api-url.ts:1-1、server/dashboard/src/lib/utils.ts:1-1、server/dashboard/src/lib/validators.ts:1-1

各子模块说明

1. `utils.ts` —— 通用工具

utils.ts 导出了最常用的 cn 工具函数，用于在 Tailwind CSS 场景下安全地合并多个 className 字符串并去除冲突类。components/ui/skeleton.tsx 在其组件实现中直接依赖 cn：

import { cn } from "@/lib/utils";

function Skeleton({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
  return (
    <div
      className={cn("animate-pulse rounded-md bg-primary/10", className)}
      {...props}
    />
  );
}

该模式（cn(基础类, 外部传入的 className)）是 components/ui/ 下所有基础组件的通用约定，依赖统一的工具函数避免在每个组件中重复实现条件拼接逻辑。

资料来源：server/dashboard/src/components/ui/skeleton.tsx:1-9、server/dashboard/src/lib/utils.ts:1-1

2. `error-message.ts` —— 错误信息归一化

getErrorMessage(err, fallback) 是业务页面在捕获到异步异常后，将任意错误对象转换为面向用户的可读字符串的统一入口。它接受两个参数：原始错误对象与降级提示文案。当错误是 Error 实例时返回其 message；否则返回 fallback。app/setup/page.tsx 在多处 try/catch 末尾调用它：

} catch (err) {
  setError(getErrorMessage(err, "Failed to save instructions"));
} finally {
  setIsLoading(false);
}

同类调用也出现在「生成自定义抽取指令」流程中：

} catch (err) {
  setError(getErrorMessage(err, "Failed to generate instructions"));
} finally {
  setIsGeneratingInstructions(false);
}

通过这一约定，所有页面在异常分支展示给用户的错误信息保持一致风格，避免直接打印 [object Object] 或栈信息。

资料来源：server/dashboard/src/app/setup/page.tsx:96-105, 165-175、server/dashboard/src/lib/error-message.ts:1-1

3. `auth.tsx` —— 认证上下文

auth.tsx 提供了用户身份认证的 React 上下文与相关钩子，供 app/ 下的受保护页面（如 app/setup/page.tsx 中的多步骤配置向导）使用。该文件以 .tsx 扩展名表明它包含 JSX，用以提供 AuthProvider 包裹组件与 useAuth 之类的钩子。设置向导包含多步流程（选择用例 → 生成指令 → 保存 → 测试 → 进入 Dashboard），其访问权限与登录态绑定，因此依赖 auth.tsx 提供的会话信息。

资料来源：server/dashboard/src/lib/auth.tsx:1-1、server/dashboard/src/app/setup/page.tsx:1-200

4. `server-api-url.ts` —— 后端地址解析

该模块集中处理「前端如何定位后端 API」的逻辑。在本地开发、Docker 自托管、生产环境部署等不同场景下，后端基础 URL 可能来源于环境变量、相对路径或同源地址。server-api-url.ts 封装了这些分支判断，导出一个统一的 getServerApiUrl() 供 api 实例（如 api.post(MEMORY_ENDPOINTS.CONFIGURE, ...)、MEMORY_ENDPOINTS.GENERATE_INSTRUCTIONS）拼接完整请求地址使用。该抽象使得页面层只关心端点常量，而不必关心部署形态。

资料来源：server/dashboard/src/lib/server-api-url.ts:1-1、server/dashboard/src/app/setup/page.tsx:113-118, 180-188

5. `validators.ts` —— 输入校验

validators.ts 集中存放表单与请求体字段的校验规则，与 UI 组件解耦，从而既能在客户端表单提交前做即时反馈，也能在需要时复用于后端调用前的兜底校验。这与设置向导中出现的多个交互步骤（自定义指令、测试消息、保存配置）所需的字段级约束相吻合。

资料来源：server/dashboard/src/lib/validators.ts:1-1、server/dashboard/src/app/setup/page.tsx:1-200

模块关系图

flowchart LR
  Page["app/setup/page.tsx<br/>业务页面"] --> Auth["lib/auth.tsx<br/>认证上下文"]
  Page --> Err["lib/error-message.ts<br/>getErrorMessage"]
  Page --> Url["lib/server-api-url.ts<br/>getServerApiUrl"]
  Page --> Val["lib/validators.ts<br/>字段校验"]
  UI["components/ui/*.tsx<br/>如 skeleton.tsx"] --> Utils["lib/utils.ts<br/>cn 合并类名"]
  Url --> Api[("后端 API<br/>CONFIGURE / GENERATE_INSTRUCTIONS")]

lib/ 下的模块互相独立、被上层自由组合：utils.ts 服务于通用 UI 组件；auth.tsx、error-message.ts、server-api-url.ts、validators.ts 则服务于业务页面。

资料来源：server/dashboard/src/app/setup/page.tsx:1-200、server/dashboard/src/components/ui/skeleton.tsx:1-9

常见使用模式

统一错误处理：所有 try/catch 末尾统一调用 getErrorMessage(err, "语义化降级文案")，再通过 setError(...) 反馈给用户。
统一类名合并：UI 组件统一使用 cn(基础类, props.className) 来安全扩展样式。
统一后端寻址：所有 API 调用均通过 getServerApiUrl() 与 MEMORY_ENDPOINTS.* 常量拼接，避免硬编码 URL。
受保护页面：依赖 auth.tsx 提供的会话状态决定是否渲染设置向导等敏感界面。

资料来源：server/dashboard/src/app/setup/page.tsx:96-105, 165-175, 113-118, 180-188、server/dashboard/src/components/ui/skeleton.tsx:1-9

社区相关讨论

关于自托管（self-host）相关流程，社群反馈 server/ 下的 make bootstrap 在部分环境（如缺少 node:sqlite）会失败（#5291），而前端控制台能否正常初始化又取决于 lib/auth.tsx、lib/server-api-url.ts 所读取的运行时配置，因此部署侧修复同样影响本模块的可用性。
关于「OpenMemory + Claude Desktop 对齐」问题（#2712），CLI 客户端与自托管控制台共享后端，前端 lib/server-api-url.ts 的解析结果决定了客户端能否正确联通。

Src 模块

Src 模块是 mem0 仓库内多个子项目源码根目录的统称，主要涵盖 TypeScript 实现（mem0-ts/src/oss/src、mem0-ts/src/client、mem0-ts/src/community）、自托管看板（server/dashboard/src）、技能包（skills/mem0）以及若干示例工程。该模块负责把"记忆提取、嵌入、检索、LLM 适配...

章节 相关页面

继续阅读本节完整说明和来源证据。

Src 模块是 mem0 仓库内多个子项目源码根目录的统称，主要涵盖 TypeScript 实现（mem0-ts/src/oss/src、mem0-ts/src/client、mem0-ts/src/community）、自托管看板（server/dashboard/src）、技能包（skills/mem0）以及若干示例工程。该模块负责把"记忆提取、嵌入、检索、LLM 适配、UI 装配"等核心能力以可重用、可配置的形式对外提供，是 mem0 OSS + Platform 体系的实现底座。资料来源：mem0-ts/src/oss/README.md:1-15、mem0-ts/src/community/package.json:1-15。

一、模块组成与职责划分

Src 在仓库中并非单一目录，而是按子项目拆分到多个 src/ 入口。下表列出了最常被开发者访问的 src 入口及其职责：

路径	角色	关键产物
`mem0-ts/src/oss/src`	OSS 内存核心（事实抽取、检索、打分、LLM 适配）	`prompts/`、`utils/`、`llms/`
`mem0-ts/src/client`	对接 Mem0 Platform 的 REST 客户端	类型定义、Webhook、Export
`mem0-ts/src/community`	社区扩展包（含 LangChain 集成）	`@mem0/community` npm 包
`server/dashboard/src`	自托管看板的 Next.js 前端	页面、UI 组件、API 客户端
`skills/mem0`	面向 IDE/Agent 的技能定义	SKILL.md、references/*
`examples/*/src`	演示应用（Vercel AI SDK、Multimodal 等）	可运行 Demo

资料来源：mem0-ts/src/oss/README.md:1-18、mem0-ts/src/community/package.json:3-21、skills/mem0/README.md:9-25。

graph LR
  A[examples/*] --> B[mem0-ts/src/client]
  A --> C[mem0-ts/src/oss/src]
  C --> D[prompts]
  C --> E[utils]
  C --> F[llms]
  C --> G[Vector Store]
  E --> H[scoring.ts]
  E --> I[entity_extraction.ts]
  B --> J[Mem0 Platform REST API]
  K[server/dashboard/src] --> J
  L[skills/mem0] --> C
  L --> B

二、OSS 内核：提示工程与记忆抽取

mem0-ts/src/oss/src/prompts/index.ts 集中导出 FactRetrievalSchema 与 MemoryUpdateSchema 两类 Zod schema，定义 LLM 在"事实检索"和"记忆增改"阶段的输入/输出契约。提示工程层严格遵守"无上下文污染"原则：抽取新记忆时，绝不把 Existing Memories / Recent Memories 中的细节合并进 New Message，除非消息本身显式引用了这些细节。资料来源：mem0-ts/src/oss/src/prompts/index.ts:1-40。

同时，提示工程还规定了 Memory Linking 规则：当一条新事实涉及已存在的某条记忆（同实体、偏好更新、对话延续）时，应在 linked_memory_ids 字段中回填旧 ID，以支持后续的图谱化检索。资料来源：mem0-ts/src/oss/src/prompts/index.ts:42-58。

三、工具层：实体抽取与混合检索打分

utils/entity_extraction.ts 实现了一个可降级的实体抽取器，先尝试 compromise NLP 库（extractCompoundsWithNlp），失败时回退到正则方案（extractCompoundsRegex）；同时维护 NON_SPECIFIC_NOUN 与 NON_SPECIFIC_ADJ 两个停用集合，过滤诸如 "thing"、"new"、"many" 这类无语义区分度的词。资料来源：mem0-ts/src/oss/src/utils/entity_extraction.ts:1-60。

清洗阶段会剥离星号、冒号、序号等格式噪声，并按小写键去重；最终 extractEntities 返回去重后的 ExtractedEntity[]，供后续的 scoring.ts 使用。资料来源：mem0-ts/src/oss/src/utils/entity_extraction.ts:62-120。

utils/scoring.ts 实现了混合检索打分：先对原始 BM25 分做 Sigmoid 归一化至 [0,1]，再叠加语义相似度与 ENTITY_BOOST_WEIGHT（默认 0.5）实体加权。getBm25Params 根据查询词数自适应选择 sigmoid 中点与陡度：短查询取 [5.0, 0.7]，长查询放宽到 [12.0, 0.5]。资料来源：mem0-ts/src/oss/src/utils/scoring.ts:1-40。

四、LLM 适配层与客户端类型

llms/langchain.ts 把 LangChain 的 BaseLanguageModel 包成 mem0 的 LLM 接口：convertToLangchainMessages 将 role: "system" | "user" | "assistant" 映射为 SystemMessage / HumanMessage / AIMessage，未识别角色会以警告日志回退到 HumanMessage。构造时强制要求 config.model 必须是已初始化的 LangChain 实例，并校验 .invoke 方法存在，否则抛错。资料来源：mem0-ts/src/oss/src/llms/langchain.ts:1-60。

client/mem0.types.ts 描述了 Platform 客户端的全部 TS 类型，涵盖 WebhookCreatePayload、WebhookUpdatePayload、FeedbackPayload、CreateMemoryExportPayload 等，覆盖了社区里"导出/反馈/Webhook"等高频需求。资料来源：mem0-ts/src/client/mem0.types.ts:1-30。

五、自托管看板与生态集成

server/dashboard/src/app/setup/page.tsx 实现了"使用场景 → 生成自定义抽取指令 → 测试消息 → 进入 Dashboard"的引导流程，通过 MEMORY_ENDPOINTS.GENERATE_INSTRUCTIONS 与 CONFIGURE 两个后端接口完成配置写入。资料来源：server/dashboard/src/app/setup/page.tsx:1-60。

UI 层则由 components/ui/sidebar.tsx（可折叠侧边栏，使用 class-variance-authority 暴露 icon/default 两种变体）与 components/ui/skeleton.tsx（基于 bg-primary/10 的骨架屏）原子组件拼装而成。资料来源：server/dashboard/src/components/ui/sidebar.tsx:1-40、server/dashboard/src/components/ui/skeleton.tsx:1-12。

生态方面，mem0-plugin/README.md 表明插件同时支持 Claude Code、Cursor、Codex、OpenCode、Antigravity 等宿主，MCP Server 默认连接 mcp.mem0.ai；examples/vercel-ai-sdk-chat-app 与 examples/multimodal-demo 各自维护 package.json 并通过 pnpm（[email protected]）管理依赖。资料来源：mem0-plugin/README.md:1-20、examples/vercel-ai-sdk-chat-app/package.json:1-15。

六、常见问题与限制

批量嵌入静默丢失：社区反馈 Memory.add() 在 V3 管道里若 batch embedding 部分失败，仅以 WARNING 等级记录而不上抛，会导致记忆静默丢失（#5245）。建议在关键业务中对 add() 的返回值做非空校验。
OpenAI 兼容代理：mem0-ts 的 OpenAIEmbedder 默认 encoding_format="base64"，部分代理服务不支持，需手动覆盖（#5168）。
Qdrant HTTPS 误用：当仅配置 host + port + api_key 时，Qdrant 客户端可能误用 HTTPS，自托管 HTTP 实例需显式指定 scheme（#5378）。
Platform v3 元数据丢失：/v3/memories/add/ 接受 user_id/agent_id 但内部未持久化，导致 get_all() 返回空集（#5224）。
npm 仿冒包：社区出现 mem0-mcp-server 仿冒包，请仅从官方 @mem0/mcp-server 安装（#5274）。
自托管构建失败：make bootstrap 在缺少 node:sqlite 的环境会失败，需升级 Node 至 22.x+（#5291）。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Self-hosting build fail

可能增加新用户试用和生产接入成本。

high 来源证据：Silent memory loss when batch embedding partially fails in V3 add pipeline

可能增加新用户试用和生产接入成本。

high 来源证据：Workaround: Solving time-blindness, semantic conflicts, and missing CRUD in Mem0 OSS + Qdrant

可能增加新用户试用和生产接入成本。

high 来源证据：[Bug] Platform v3 API: add() accepts user_id/agent_id but doesn't store them — get_all returns empty

可能增加新用户试用和生产接入成本。

Pitfall Log / 踩坑日志

项目：mem0ai/mem0

摘要：发现 29 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：Self-hosting build fail。

1. 安装坑 · 来源证据：Self-hosting build fail

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Self-hosting build fail
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/mem0ai/mem0/issues/5291 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Silent memory loss when batch embedding partially fails in V3 add pipeline

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Silent memory loss when batch embedding partially fails in V3 add pipeline
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/mem0ai/mem0/issues/5245 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：Workaround: Solving time-blindness, semantic conflicts, and missing CRUD in Mem0 OSS + Qdrant

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Workaround: Solving time-blindness, semantic conflicts, and missing CRUD in Mem0 OSS + Qdrant
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/mem0ai/mem0/issues/5352 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：[Bug] Platform v3 API: add() accepts user_id/agent_id but doesn't store them — get_all returns empty

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] Platform v3 API: add() accepts user_id/agent_id but doesn't store them — get_all returns empty
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/mem0ai/mem0/issues/5224 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 安全/权限坑 · 来源证据：🚨 Malicious impersonator package 'mem0-mcp-server' on npm

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：🚨 Malicious impersonator package 'mem0-mcp-server' on npm
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/mem0ai/mem0/issues/5274 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

6. 安装坑 · 失败模式：installation: Bug: OpenAIEmbedder in mem0-ts fails with OpenAI-compatible proxies (encoding_format default...

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: Bug: OpenAIEmbedder in mem0-ts fails with OpenAI-compatible proxies (encoding_format default base64) — port #4058 to TS SDK
对用户的影响：Developers may fail before the first successful local run: Bug: OpenAIEmbedder in mem0-ts fails with OpenAI-compatible proxies (encoding_format default base64) — port #4058 to TS SDK
证据：failure_mode_cluster:github_issue | https://github.com/mem0ai/mem0/issues/5168 | Bug: OpenAIEmbedder in mem0-ts fails with OpenAI-compatible proxies (encoding_format default base64) — port #4058 to TS SDK

7. 安装坑 · 失败模式：installation: Mem0 Node CLI (v0.2.8)

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: Mem0 Node CLI (v0.2.8)
对用户的影响：Upgrade or migration may change expected behavior: Mem0 Node CLI (v0.2.8)
证据：failure_mode_cluster:github_release | https://github.com/mem0ai/mem0/releases/tag/cli-node-v0.2.8 | Mem0 Node CLI (v0.2.8)

8. 安装坑 · 失败模式：installation: Mem0 Node SDK (v3.0.6)

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: Mem0 Node SDK (v3.0.6)
对用户的影响：Upgrade or migration may change expected behavior: Mem0 Node SDK (v3.0.6)
证据：failure_mode_cluster:github_release | https://github.com/mem0ai/mem0/releases/tag/ts-v3.0.6 | Mem0 Node SDK (v3.0.6)

9. 安装坑 · 失败模式：installation: Mem0 OpenClaw Plugin (v1.0.12)

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: Mem0 OpenClaw Plugin (v1.0.12)
对用户的影响：Upgrade or migration may change expected behavior: Mem0 OpenClaw Plugin (v1.0.12)
证据：failure_mode_cluster:github_release | https://github.com/mem0ai/mem0/releases/tag/openclaw-v1.0.12 | Mem0 OpenClaw Plugin (v1.0.12)

10. 安装坑 · 失败模式：installation: Mem0 OpenCode Plugin (v0.1.1)

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: Mem0 OpenCode Plugin (v0.1.1)
对用户的影响：Upgrade or migration may change expected behavior: Mem0 OpenCode Plugin (v0.1.1)
证据：failure_mode_cluster:github_release | https://github.com/mem0ai/mem0/releases/tag/opencode-v0.1.1 | Mem0 OpenCode Plugin (v0.1.1)

11. 安装坑 · 失败模式：installation: Mem0 OpenCode Plugin (v0.1.2)

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: Mem0 OpenCode Plugin (v0.1.2)
对用户的影响：Upgrade or migration may change expected behavior: Mem0 OpenCode Plugin (v0.1.2)
证据：failure_mode_cluster:github_release | https://github.com/mem0ai/mem0/releases/tag/opencode-v0.1.2 | Mem0 OpenCode Plugin (v0.1.2)

12. 安装坑 · 失败模式：installation: Self-hosting build fail

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: Self-hosting build fail
对用户的影响：Developers may fail before the first successful local run: Self-hosting build fail
证据：failure_mode_cluster:github_issue | https://github.com/mem0ai/mem0/issues/5291 | Self-hosting build fail

13. 安装坑 · 失败模式：installation: Vercel AI SDK Provider (v2.4.6)

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: Vercel AI SDK Provider (v2.4.6)
对用户的影响：Upgrade or migration may change expected behavior: Vercel AI SDK Provider (v2.4.6)
证据：failure_mode_cluster:github_release | https://github.com/mem0ai/mem0/releases/tag/vercel-ai-v2.0.6 | Vercel AI SDK Provider (v2.4.6)

14. 安装坑 · 失败模式：installation: 🚨 Malicious impersonator package 'mem0-mcp-server' on npm

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: 🚨 Malicious impersonator package 'mem0-mcp-server' on npm
对用户的影响：Developers may fail before the first successful local run: 🚨 Malicious impersonator package 'mem0-mcp-server' on npm
证据：failure_mode_cluster:github_issue | https://github.com/mem0ai/mem0/issues/5274 | 🚨 Malicious impersonator package 'mem0-mcp-server' on npm

15. 安装坑 · 来源证据：Bug: OpenAIEmbedder in mem0-ts fails with OpenAI-compatible proxies (encoding_format default base64) — port #4058 to TS…

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: OpenAIEmbedder in mem0-ts fails with OpenAI-compatible proxies (encoding_format default base64) — port #4058 to TS SDK
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/mem0ai/mem0/issues/5168 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

16. 配置坑 · 失败模式：configuration: Proposal: Make Mem0 OSS Storage Fully Pluggable for Cloud-Native Backends

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: Proposal: Make Mem0 OSS Storage Fully Pluggable for Cloud-Native Backends
对用户的影响：Developers may misconfigure credentials, environment, or host setup: Proposal: Make Mem0 OSS Storage Fully Pluggable for Cloud-Native Backends
证据：failure_mode_cluster:github_issue | https://github.com/mem0ai/mem0/issues/5354 | Proposal: Make Mem0 OSS Storage Fully Pluggable for Cloud-Native Backends

17. 配置坑 · 失败模式：configuration: Qdrant vector store uses HTTPS unexpectedly with host/port/api_key for self-hosted HTTP Qdrant

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: Qdrant vector store uses HTTPS unexpectedly with host/port/api_key for self-hosted HTTP Qdrant
对用户的影响：Developers may misconfigure credentials, environment, or host setup: Qdrant vector store uses HTTPS unexpectedly with host/port/api_key for self-hosted HTTP Qdrant
证据：failure_mode_cluster:github_issue | https://github.com/mem0ai/mem0/issues/5378 | Qdrant vector store uses HTTPS unexpectedly with host/port/api_key for self-hosted HTTP Qdrant

18. 配置坑 · 失败模式：configuration: Silent memory loss when batch embedding partially fails in V3 add pipeline

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: Silent memory loss when batch embedding partially fails in V3 add pipeline
对用户的影响：Developers may misconfigure credentials, environment, or host setup: Silent memory loss when batch embedding partially fails in V3 add pipeline
证据：failure_mode_cluster:github_issue | https://github.com/mem0ai/mem0/issues/5245 | Silent memory loss when batch embedding partially fails in V3 add pipeline

19. 配置坑 · 失败模式：configuration: Workaround: Solving time-blindness, semantic conflicts, and missing CRUD in Mem0 OSS + Qdrant

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: Workaround: Solving time-blindness, semantic conflicts, and missing CRUD in Mem0 OSS + Qdrant
对用户的影响：Developers may misconfigure credentials, environment, or host setup: Workaround: Solving time-blindness, semantic conflicts, and missing CRUD in Mem0 OSS + Qdrant
证据：failure_mode_cluster:github_issue | https://github.com/mem0ai/mem0/issues/5352 | Workaround: Solving time-blindness, semantic conflicts, and missing CRUD in Mem0 OSS + Qdrant

20. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | github_repo:656099147 | https://github.com/mem0ai/mem0 | README/documentation is current enough for a first validation pass.

21. 维护坑 · 失败模式：migration: Mem0 Python SDK (v2.0.3)

严重度：medium
证据强度：source_linked
发现：Developers should check this migration risk before relying on the project: Mem0 Python SDK (v2.0.3)
对用户的影响：Upgrade or migration may change expected behavior: Mem0 Python SDK (v2.0.3)
证据：failure_mode_cluster:github_release | https://github.com/mem0ai/mem0/releases/tag/v2.0.3 | Mem0 Python SDK (v2.0.3)

22. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | github_repo:656099147 | https://github.com/mem0ai/mem0 | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | github_repo:656099147 | https://github.com/mem0ai/mem0 | no_demo; severity=medium

24. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | github_repo:656099147 | https://github.com/mem0ai/mem0 | no_demo; severity=medium

25. 安全/权限坑 · 来源证据：Qdrant vector store uses HTTPS unexpectedly with host/port/api_key for self-hosted HTTP Qdrant

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Qdrant vector store uses HTTPS unexpectedly with host/port/api_key for self-hosted HTTP Qdrant
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/mem0ai/mem0/issues/5378 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

26. 运行坑 · 失败模式：performance: Mem0 Python SDK (v2.0.4)

严重度：low
证据强度：source_linked
发现：Developers should check this performance risk before relying on the project: Mem0 Python SDK (v2.0.4)
对用户的影响：Upgrade or migration may change expected behavior: Mem0 Python SDK (v2.0.4)
证据：failure_mode_cluster:github_release | https://github.com/mem0ai/mem0/releases/tag/v2.0.4 | Mem0 Python SDK (v2.0.4)

27. 运行坑 · 失败模式：performance: [Bug] Platform v3 API: add() accepts user_id/agent_id but doesn't store them — get_all return...

严重度：low
证据强度：source_linked
发现：Developers should check this performance risk before relying on the project: [Bug] Platform v3 API: add() accepts user_id/agent_id but doesn't store them — get_all returns empty
对用户的影响：Developers may hit a documented source-backed failure mode: [Bug] Platform v3 API: add() accepts user_id/agent_id but doesn't store them — get_all returns empty
证据：failure_mode_cluster:github_issue | https://github.com/mem0ai/mem0/issues/5224 | [Bug] Platform v3 API: add() accepts user_id/agent_id but doesn't store them — get_all returns empty

28. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | github_repo:656099147 | https://github.com/mem0ai/mem0 | issue_or_pr_quality=unknown

29. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | github_repo:656099147 | https://github.com/mem0ai/mem0 | release_recency=unknown

来源：Doramagic 发现、验证与编译记录

mem0 项目

项目概览

项目定位与核心能力

仓库结构与子项目

核心架构概览

社区关注与已知问题

See Also

Lib 模块

概述与定位

子模块组成

各子模块说明

1. `utils.ts` —— 通用工具

2. `error-message.ts` —— 错误信息归一化

3. `auth.tsx` —— 认证上下文

4. `server-api-url.ts` —— 后端地址解析

5. `validators.ts` —— 输入校验

模块关系图

常见使用模式

社区相关讨论

See Also

Src 模块

一、模块组成与职责划分

二、OSS 内核：提示工程与记忆抽取

三、工具层：实体抽取与混合检索打分

四、LLM 适配层与客户端类型

五、自托管看板与生态集成

六、常见问题与限制

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 安装坑 · 来源证据：Self-hosting build fail

2. 安装坑 · 来源证据：Silent memory loss when batch embedding partially fails in V3 add pipeline

3. 安装坑 · 来源证据：Workaround: Solving time-blindness, semantic conflicts, and missing CRUD in Mem0 OSS + Qdrant

4. 安装坑 · 来源证据：[Bug] Platform v3 API: add() accepts user_id/agent_id but doesn't store them — get_all returns empty

5. 安全/权限坑 · 来源证据：🚨 Malicious impersonator package 'mem0-mcp-server' on npm

6. 安装坑 · 失败模式：installation: Bug: OpenAIEmbedder in mem0-ts fails with OpenAI-compatible proxies (encoding_format default...

7. 安装坑 · 失败模式：installation: Mem0 Node CLI (v0.2.8)

8. 安装坑 · 失败模式：installation: Mem0 Node SDK (v3.0.6)

9. 安装坑 · 失败模式：installation: Mem0 OpenClaw Plugin (v1.0.12)

10. 安装坑 · 失败模式：installation: Mem0 OpenCode Plugin (v0.1.1)

11. 安装坑 · 失败模式：installation: Mem0 OpenCode Plugin (v0.1.2)

12. 安装坑 · 失败模式：installation: Self-hosting build fail

13. 安装坑 · 失败模式：installation: Vercel AI SDK Provider (v2.4.6)

14. 安装坑 · 失败模式：installation: 🚨 Malicious impersonator package 'mem0-mcp-server' on npm

15. 安装坑 · 来源证据：Bug: OpenAIEmbedder in mem0-ts fails with OpenAI-compatible proxies (encoding_format default base64) — port #4058 to TS…

16. 配置坑 · 失败模式：configuration: Proposal: Make Mem0 OSS Storage Fully Pluggable for Cloud-Native Backends

17. 配置坑 · 失败模式：configuration: Qdrant vector store uses HTTPS unexpectedly with host/port/api_key for self-hosted HTTP Qdrant

18. 配置坑 · 失败模式：configuration: Silent memory loss when batch embedding partially fails in V3 add pipeline

19. 配置坑 · 失败模式：configuration: Workaround: Solving time-blindness, semantic conflicts, and missing CRUD in Mem0 OSS + Qdrant

20. 能力坑 · 能力判断依赖假设

21. 维护坑 · 失败模式：migration: Mem0 Python SDK (v2.0.3)

22. 维护坑 · 维护活跃度未知

24. 安全/权限坑 · 存在评分风险

25. 安全/权限坑 · 来源证据：Qdrant vector store uses HTTPS unexpectedly with host/port/api_key for self-hosted HTTP Qdrant

26. 运行坑 · 失败模式：performance: Mem0 Python SDK (v2.0.4)

27. 运行坑 · 失败模式：performance: [Bug] Platform v3 API: add() accepts user_id/agent_id but doesn't store them — get_all return...

28. 维护坑 · issue/PR 响应质量未知

29. 维护坑 · 发布节奏不明确