# https://github.com/mem0ai/mem0 项目说明书

生成时间：2026-05-11 07:44:39 UTC

## 目录

- [Mem0 简介](#page-introduction)
- [安装与配置](#page-installation)
- [系统架构](#page-architecture)
- [核心组件详解](#page-core-components)
- [记忆操作API](#page-memory-operations)
- [实体提取与链接](#page-entity-extraction)
- [LLM模型集成](#page-llm-integrations)
- [向量数据库支持](#page-vector-stores)
- [嵌入模型配置](#page-embeddings)
- [智能体框架集成](#page-agent-integrations)

<a id='page-introduction'></a>

## Mem0 简介

### 相关页面

相关主题：[安装与配置](#page-installation), [系统架构](#page-architecture)

<minimax:tool_call>
<invoke name="browser_google_search">
<parameter name="query">mem0ai/mem0 github repository documentation</parameter>
<parameter name="top_n">10</parameter>
<parameter name="recency_days">-1</parameter>
</invoke>
</minimax:tool_call>

---

<a id='page-installation'></a>

## 安装与配置

### 相关页面

相关主题：[Mem0 简介](#page-introduction)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mem0/__init__.py](https://github.com/mem0ai/mem0/blob/main/mem0/__init__.py)
- [mem0/embeddings/__init__.py](https://github.com/mem0ai/mem0/blob/main/mem0/embeddings/__init__.py)
- [mem0/vector_stores/__init__.py](https://github.com/mem0ai/mem0/blob/main/mem0/vector_stores/__init__.py)
- [mem0/memory/__init__.py](https://github.com/mem0ai/mem0/blob/main/mem0/memory/__init__.py)
- [mem0-ts/package.json](https://github.com/mem0ai/mem0/blob/main/mem0-ts/package.json)
- [docs/open-source/setup.mdx](https://github.com/mem0ai/mem0/blob/main/docs/open-source/setup.mdx)
- [docs/open-source/python-quickstart.mdx](https://github.com/mem0ai/mem0/blob/main/docs/open-source/python-quickstart.mdx)
- [.env.example](https://github.com/mem0ai/mem0/blob/main/.env.example)
</details>

# 安装与配置

mem0 是一个开源的 AI 记忆层平台，为大型语言模型（LLM）应用提供智能记忆管理能力。本页面详细说明 mem0 的安装过程、环境配置以及各项参数的配置方法。

## 前置条件

在安装 mem0 之前，请确保系统满足以下要求：

| 组件 | 最低版本 | 说明 |
|------|----------|------|
| Python | 3.9+ | mem0 主 SDK 需要 Python 运行环境 |
| pip | 21.0+ | Python 包管理工具 |
| Node.js | 18.0+ | mem0-ts 运行所需（可选） |
| 向量数据库 | 见下方 | 至少配置一种向量存储后端 |

### 支持的向量数据库

mem0 支持多种向量数据库作为记忆存储后端：

- **Qdrant**：高性能向量相似度搜索引擎
- **Chroma**：轻量级嵌入式向量数据库
- **Weaviate**：云原生的向量搜索引擎
- **Milvus**：分布式向量数据库
- **pgvector**：PostgreSQL 向量扩展
- **Redis**：支持向量相似度搜索
- **LanceDB**：嵌入式向量数据库
- **AstraDB**：DataStax 的云数据库服务

### 支持的嵌入模型

mem0 支持多种嵌入模型用于记忆向量化：

- OpenAI Embeddings
- Azure OpenAI Embeddings
- LangChain 集成支持的所有嵌入模型
- 自定义嵌入接口

## 安装方式

### Python SDK 安装

mem0 Python SDK 可以通过 pip 直接安装：

```bash
pip install mem0ai
```

如需安装包含所有可选依赖的完整版本：

```bash
pip install mem0ai[all]
```

### TypeScript/Node.js SDK 安装

mem0 还提供了 TypeScript/Node.js 版本的客户端库：

```bash
npm install mem0ai
```

或使用其他包管理器：

```bash
yarn add mem0ai
pnpm add mem0ai
```

## 环境变量配置

mem0 使用环境变量管理敏感配置和 API 密钥。建议创建 `.env` 文件进行配置：

```bash
cp .env.example .env
```

### 必需的环境变量

| 变量名 | 描述 | 必需 | 示例值 |
|--------|------|------|--------|
| `OPENAI_API_KEY` | OpenAI API 密钥 | 是（使用 OpenAI 时） | `sk-...` |
| `AZURE_OPENAI_API_KEY` | Azure OpenAI API 密钥 | 是（使用 Azure 时） | `...` |
| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI 端点 | 是（使用 Azure 时） | `https://xxx.openai.azure.com/` |
| `AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT` | Azure Embeddings 部署名 | 是（使用 Azure 时） | `text-embedding-ada-002` |

### 向量存储配置

根据选择的向量存储后端，需要配置相应的环境变量：

```bash
# Qdrant 配置
QDRANT_HOST=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION_NAME=mem0

# Chroma 配置
CHROMA_DB_IMPL=chromadb.db.duckdb.DuckDB
CHROMA_DATA_PATH=./chroma_data

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
```

## Python SDK 配置

### 基础配置初始化

mem0 Python SDK 的核心配置通过 `Mem0` 类进行管理：

```python
from mem0 import Mem0

# 使用 OpenAI 和默认向量存储
client = Mem0()

# 自定义配置
client = Mem0(
    api_key="your-api-key",
    model="gpt-4",
    temperature=0.7,
    max_tokens=1000
)
```

### 嵌入模型配置

mem0 支持自定义嵌入模型配置：

```python
from mem0.embeddings import OpenAIEmbedding

# 配置自定义嵌入
embedding_model = OpenAIEmbedding(
    api_key="your-api-key",
    model="text-embedding-3-small",
    dimensions=1536
)

client = Mem0(embedding_model=embedding_model)
```

### 向量存储配置

```python
from mem0.vector_stores import Qdrant

# 配置 Qdrant 向量存储
vector_store = Qdrant(
    host="localhost",
    port=6333,
    collection_name="mem0_memory"
)

client = Mem0(vector_store=vector_store)
```

## TypeScript SDK 配置

mem0-ts 的初始化配置：

```typescript
import { Mem0 } from 'mem0ai';

const client = new Mem0({
  apiKey: 'your-api-key',
  model: 'gpt-4'
});
```

### TypeScript 配置参数

| 参数名 | 类型 | 描述 | 默认值 |
|--------|------|------|--------|
| `apiKey` | `string` | API 密钥 | - |
| `model` | `string` | 使用的 LLM 模型 | `gpt-4` |
| `temperature` | `number` | 生成温度参数 | `0.7` |
| `maxTokens` | `number` | 最大生成 token 数 | `1000` |
| `embeddingModel` | `string` | 嵌入模型名称 | - |

## 内存类型配置

mem0 支持多种内存类型，适用于不同的应用场景：

```python
client = Mem0(
    memory_type="semantic",  # 语义记忆（默认）
    # 或
    memory_type="episodic",  # 情景记忆
    # 或
    memory_type="semantic_with_episodic"  # 混合模式
)
```

### 内存类型说明

| 类型 | 描述 | 适用场景 |
|------|------|----------|
| `semantic` | 基于语义相似度存储和检索 | 通用知识问答 |
| `episodic` | 基于时间序列的情景记忆 | 对话历史记录 |
| `semantic_with_episodic` | 语义和情景记忆混合 | 复杂对话应用 |

## 配置验证

安装完成后，可以通过以下方式验证配置是否正确：

```python
from mem0 import Mem0

# 初始化客户端
client = Mem0()

# 测试添加记忆
result = client.add("这是我的第一条记忆")

# 验证记忆检索
memories = client.search("我的记忆")
print(f"找到 {len(memories)} 条相关记忆")
```

## 常见配置问题

### API 密钥问题

如果遇到认证错误，请检查：

1. 环境变量是否正确设置
2. API 密钥是否有效且未过期
3. 密钥是否有足够的配额

### 向量存储连接问题

1. 确认向量数据库服务已启动
2. 检查端口配置是否正确
3. 验证网络连接是否畅通

### 嵌入模型问题

如果嵌入结果不符合预期：

1. 检查嵌入模型版本是否最新
2. 确认维度设置与向量存储匹配
3. 考虑使用更高质量的嵌入模型

## 部署架构

mem0 的典型部署架构如下：

```mermaid
graph TD
    A[应用层] --> B[mem0 SDK]
    B --> C[记忆处理引擎]
    C --> D{记忆类型}
    D --> E[语义记忆]
    D --> F[情景记忆]
    E --> G[向量存储层]
    F --> G
    G --> H[Qdrant / Chroma / Redis / ...]
    C --> I[LLM 层]
    I --> J[OpenAI / Azure OpenAI / 本地模型]
```

## 进阶配置

### 日志配置

```python
import logging

logging.basicConfig(level=logging.DEBUG)
client = Mem0()
```

### 自定义 LLM 提供商

```python
from mem0 import Mem0

client = Mem0(
    llm_provider="custom",
    llm_endpoint="http://localhost:8000/v1",
    llm_api_key="your-key"
)
```

### 记忆保留策略

```python
client = Mem0(
    retention_policy="smart",  # 智能保留
    max_memories=1000,         # 最大记忆数量
    ttl_days=30               # 记忆过期天数
)
```

## 下一步

- [快速开始指南](docs/open-source/python-quickstart.mdx)
- [API 参考文档](docs/open-source/api-reference.mdx)
- [生产环境部署](docs/open-source/deployment.mdx)

---

<a id='page-architecture'></a>

## 系统架构

### 相关页面

相关主题：[核心组件详解](#page-core-components), [记忆操作API](#page-memory-operations)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mem0/memory/main.py](https://github.com/mem0ai/mem0/blob/main/mem0/memory/main.py)
- [mem0/memory/base.py](https://github.com/mem0ai/mem0/blob/main/mem0/memory/base.py)
- [mem0/memory/storage.py](https://github.com/mem0ai/mem0/blob/main/mem0/memory/storage.py)
- [mem0/memory/graphs.py](https://github.com/mem0ai/mem0/blob/main/mem0/memory/graphs.py)
- [mem0/vector_stores/qdrant.py](https://github.com/mem0ai/mem0/blob/main/mem0/vector_stores/qdrant.py)
- [mem0/vector_stores/chroma.py](https://github.com/mem0ai/mem0/blob/main/mem0/vector_stores/chroma.py)
- [mem0/embeddings/factory.py](https://github.com/mem0ai/mem0/blob/main/mem0/embeddings/factory.py)
- [mem0/configs/mem0.py](https://github.com/mem0ai/mem0/blob/main/mem0/configs/mem0.py)
- [docs/open-source/features/overview.mdx](https://github.com/mem0ai/mem0/blob/main/docs/open-source/features/overview.mdx)
</details>

# 系统架构

## 1. 概述

Mem0 是一个为 AI 应用设计的智能记忆层基础设施，旨在解决 AI 应用中的长期记忆、用户偏好学习和上下文理解问题。该平台采用模块化架构设计，支持多种向量存储后端、嵌入模型和 LLM 提供商，能够灵活适应不同的部署场景。资料来源：[docs/open-source/features/overview.mdx:1]()

Mem0 的核心价值在于为 AI 系统提供持久化、可检索的记忆能力，使 AI 应用能够记住用户偏好、历史交互和重要信息，从而提供更加个性化和连贯的用户体验。资料来源：[mem0/memory/base.py:1-20]()

## 2. 架构分层

Mem0 采用三层架构设计，从上到下依次为接口层、核心处理层和存储层。这种分层设计确保了各层之间的职责明确，便于维护和扩展。资料来源：[mem0/memory/main.py:1-50]()

```mermaid
graph TD
    A[接口层 - Mem0 主类] --> B[核心处理层]
    A --> C[记忆管理层]
    B --> D[向量存储层]
    B --> E[嵌入层]
    C --> F[关系图谱层]
    D --> G[向量数据库]
    E --> H[嵌入模型]
    F --> I[图数据库]
```

### 2.1 接口层

接口层是用户与 Mem0 系统交互的入口点，主要通过 `Mem0` 主类暴露所有核心功能。该层负责接收用户请求、参数验证和结果格式化，是整个系统的对外窗口。资料来源：[mem0/memory/main.py:20-80]()

**核心类：`Mem0`**

| 参数 | 类型 | 说明 |
|------|------|------|
| `provider` | str | LLM 提供商类型，如 "openai"、"azure"、"anthropic" 等 |
| `model` | str | 具体的模型标识符 |
| `vector_store` | str | 向量存储后端类型 |
| `vector_store_config` | dict | 向量存储的详细配置 |
| `embedding_model` | str | 嵌入模型的名称或路径 |
| `graph_store` | str | 图数据库后端类型 |
| `graph_store_config` | dict | 图数据库的详细配置 |

资料来源：[mem0/memory/main.py:40-70]()

### 2.2 核心处理层

核心处理层负责执行记忆的核心操作逻辑，包括记忆的添加、搜索、更新和删除。该层协调嵌入模型、向量存储和图存储之间的交互，实现语义搜索和关系推理。资料来源：[mem0/memory/base.py:30-100]()

```mermaid
graph LR
    A[用户输入] --> B[文本预处理]
    B --> C[嵌入生成]
    C --> D[向量索引]
    C --> E[关系抽取]
    E --> F[图谱更新]
    D --> G[向量存储]
    G --> H[相似度检索]
    F --> I[图谱存储]
    I --> J[关系查询]
    H --> K[结果聚合]
    J --> K
    K --> L[结果输出]
```

### 2.3 存储层

存储层负责数据的持久化，包括向量存储和图存储两大类。向量存储用于存储嵌入向量，支持语义相似度搜索；图存储用于存储实体之间的复杂关系。资料来源：[mem0/memory/storage.py:1-50]()

## 3. 核心组件

### 3.1 记忆管理模块

记忆管理模块是 Mem0 的核心组件，封装了所有记忆操作的方法。该模块继承自 `MemoryBase` 基类，提供了标准化的接口实现。资料来源：[mem0/memory/base.py:50-150]()

**主要功能：**

| 功能 | 方法 | 说明 |
|------|------|------|
| 添加记忆 | `add()` | 将新的记忆信息添加到存储系统 |
| 搜索记忆 | `search()` | 基于语义相似度检索相关记忆 |
| 获取历史 | `get_all()` | 检索特定用户或会话的所有记忆 |
| 更新记忆 | `update()` | 修改已有记忆的内容 |
| 删除记忆 | `delete()` | 从存储系统中移除记忆 |
| 重置记忆 | `reset()` | 清空所有记忆数据 |

资料来源：[mem0/memory/main.py:80-200]()

**记忆数据结构：**

```python
MemoryEntry {
    id: str,              # 记忆唯一标识符
    data: str,            # 记忆内容文本
    user_id: str,         # 用户标识符
    agent_id: str,        # 代理标识符
    session_id: str,      # 会话标识符
    metadata: dict,        # 元数据信息
    created_at: datetime, # 创建时间戳
    vector: list[float]   # 嵌入向量
}
```

资料来源：[mem0/memory/storage.py:20-60]()

### 3.2 向量存储模块

向量存储模块负责存储和检索嵌入向量，是实现语义搜索的关键组件。Mem0 支持多种向量存储后端，用户可以根据性能、成本和部署环境选择合适的选项。资料来源：[mem0/vector_stores/qdrant.py:1-30]()

**支持的向量存储：**

| 存储后端 | 配置参数 | 适用场景 |
|----------|----------|----------|
| Qdrant | `host`, `port`, `collection_name` | 高性能生产环境 |
| Chroma | `collection_name`, `persist_directory` | 本地开发和测试 |
| pgvector | `host`, `port`, `database`, `user`, `password` | PostgreSQL 现有部署 |
| Pinecone | `api_key`, `index_name`, `environment` | 云原生部署 |
| Weaviate | `url`, `index_name` | 混合云部署 |

资料来源：[mem0/vector_stores/chroma.py:1-40]()

**向量存储配置示例：**

```python
vector_store_config = {
    "provider": "qdrant",
    "config": {
        "host": "localhost",
        "port": 6333,
        "collection_name": "mem0_memory",
        "embedding_model_dims": 1536
    }
}
```

资料来源：[mem0/configs/mem0.py:1-50]()

### 3.3 嵌入层

嵌入层负责将文本转换为高维向量表示，是实现语义理解的基础。Mem0 使用工厂模式管理嵌入模型，支持多种嵌入提供者和模型。资料来源：[mem0/embeddings/factory.py:1-60]()

**支持的嵌入模型：**

| 模型类型 | 提供商 | 维度 |
|----------|--------|------|
| text-embedding-ada-002 | OpenAI | 1536 |
| text-embedding-3-small | OpenAI | 1536/512 |
| text-embedding-3-large | OpenAI | 3072/1024/256 |
| VoyageAI | Voyage | 1024 |
| HuggingFace | 本地/云端 | 可变 |

资料来源：[mem0/embeddings/factory.py:20-80]()

### 3.4 关系图谱模块

关系图谱模块用于存储和管理实体之间的复杂关系，支持多跳推理和关系路径查询。该模块基于图数据结构，能够高效处理实体间的关联查询。资料来源：[mem0/memory/graphs.py:1-50]()

**图数据结构：**

```mermaid
graph TD
    A[用户: Alice] -->|喜欢| B[电影: 盗梦空间]
    A -->|不喜欢| C[电影: 变形金刚]
    A -->|收藏| D[音乐: 古典乐]
    B -->|类型| E[类型: 科幻]
    C -->|类型| E
    E -->|包含| F[元素: 梦境]
```

**图存储配置：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `provider` | str | 图数据库提供者 |
| `graph_name` | str | 图数据库名称 |
| `host` | str | 服务器地址 |
| `port` | int | 服务端口 |

资料来源：[mem0/memory/graphs.py:50-100]()

## 4. 工作流程

### 4.1 添加记忆流程

当用户添加新记忆时，Mem0 执行以下处理流程：资料来源：[mem0/memory/main.py:100-150]()

```mermaid
graph TD
    A[add 用户输入] --> B{记忆类型}
    B -->|消息记忆| C[调用 add 方法]
    B -->|偏好记忆| D[调用 add Preference 方法]
    B -->|事实记忆| E[调用 add Fact 方法]
    C --> F[文本预处理]
    D --> F
    E --> F
    F --> G[生成嵌入向量]
    G --> H[提取实体关系]
    H --> I[存储到向量库]
    H --> J[更新关系图谱]
    I --> K[返回记忆 ID]
    J --> K
```

### 4.2 搜索记忆流程

搜索操作通过向量相似度匹配实现语义检索，支持多维度过滤和结果排序。资料来源：[mem0/memory/storage.py:50-100]()

```mermaid
graph TD
    A[search 查询输入] --> B[生成查询嵌入]
    B --> C[向量相似度搜索]
    C --> D{过滤条件}
    D -->|有过滤| E[应用元数据过滤]
    D -->|无过滤| F[直接返回结果]
    E --> G[结果排序]
    F --> H[结果排序]
    G --> I[返回 Top-K 结果]
    H --> I
    I --> J[格式化输出]
```

## 5. 配置体系

### 5.1 配置结构

Mem0 使用分层配置管理，支持环境变量、配置文件和代码参数三种配置方式。配置优先级从高到低依次为：代码参数 > 环境变量 > 配置文件 > 默认值。资料来源：[mem0/configs/mem0.py:1-100]()

**配置参数表：**

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| `llm_provider` | `MEM0_LLM_PROVIDER` | openai | LLM 提供商 |
| `llm_api_key` | `MEM0_LLM_API_KEY` | - | API 密钥 |
| `vector_store` | `MEM0_VECTOR_STORE` | chroma | 向量存储后端 |
| `embedding_model` | `MEM0_EMBEDDING_MODEL` | text-embedding-ada-002 | 嵌入模型 |
| `graph_store` | `MEM0_GRAPH_STORE` | networkx | 图存储后端 |

### 5.2 初始化配置示例

```python
from mem0 import Mem0

# 基础配置
client = Mem0(api_key="your-api-key")

# 高级配置
client = Mem0(
    provider="openai",
    model="gpt-4",
    vector_store="qdrant",
    vector_store_config={
        "host": "qdrant.example.com",
        "port": 6333,
        "collection_name": "production_memory"
    },
    embedding_model="text-embedding-3-large",
    graph_store="neo4j",
    graph_store_config={
        "url": "bolt://localhost:7687",
        "username": "neo4j",
        "password": "password"
    }
)
```

资料来源：[mem0/memory/main.py:30-80]()

## 6. 扩展机制

### 6.1 自定义向量存储

Mem0 提供了标准化的向量存储接口，开发者可以通过实现 `VectorStoreBase` 基类来添加新的向量存储后端。资料来源：[mem0/vector_stores/qdrant.py:1-20]()

**接口要求：**

```python
class VectorStoreBase:
    def create_collection(self, name: str, dim: int): ...
    def insert(self, vectors: list, payloads: list, ids: list): ...
    def search(self, query: str, limit: int = 5) -> list: ...
    def delete(self, id: str): ...
    def get(self, id: str) -> dict: ...
    def update(self, id: str, vector: list, payload: dict): ...
```

### 6.2 自定义嵌入模型

通过实现 `EmbeddingBase` 接口，可以集成任何自定义的嵌入模型。资料来源：[mem0/embeddings/factory.py:1-30]()

## 7. 数据流

### 7.1 完整数据流图

```mermaid
graph LR
    subgraph 输入层
        A[用户消息]
        B[偏好信息]
        C[事实陈述]
    end
    
    subgraph 处理层
        D[预处理模块]
        E[嵌入生成器]
        F[关系抽取器]
        G[意图识别器]
    end
    
    subgraph 存储层
        H[向量数据库]
        I[关系图谱]
        J[键值存储]
    end
    
    subgraph 输出层
        K[检索结果]
        L[推理结果]
        M[上下文增强]
    end
    
    A --> D
    B --> D
    C --> D
    D --> E
    D --> F
    E --> H
    F --> I
    G --> J
    H --> K
    I --> L
    J --> M
```

## 8. 部署架构

### 8.1 生产环境推荐架构

Mem0 支持多种部署模式以适应不同的业务需求和技术栈。资料来源：[docs/open-source/features/overview.mdx:1-50]()

**云原生部署：**

| 组件 | 推荐方案 | 说明 |
|------|----------|------|
| Mem0 API | Kubernetes + Docker | 容器化部署，自动扩缩容 |
| 向量存储 | Qdrant Cloud / Pinecone | 托管向量数据库服务 |
| 图存储 | Neo4j Aura | 云原生图数据库 |
| LLM | OpenAI / Azure OpenAI | OpenAI API 服务 |

**本地部署：**

| 组件 | 推荐方案 | 说明 |
|------|----------|------|
| Mem0 | pip install + Python | 直接安装运行 |
| 向量存储 | Chroma / Qdrant (本地) | 本地向量数据库 |
| 图存储 | NetworkX / Neo4j | 本地图数据库 |

## 9. 总结

Mem0 的系统架构采用模块化、分层设计，核心优势包括：

- **灵活性**：支持多种向量存储、嵌入模型和 LLM 提供商，可根据需求灵活选择
- **可扩展性**：标准化的接口设计便于集成新的存储后端和模型
- **可靠性**：三层架构确保职责分离，便于维护和升级
- **性能优化**：向量检索和图查询相结合，提供高效的语义搜索能力

资料来源：[mem0/memory/base.py:1-20]()

---

<a id='page-core-components'></a>

## 核心组件详解

### 相关页面

相关主题：[系统架构](#page-architecture), [LLM模型集成](#page-llm-integrations), [向量数据库支持](#page-vector-stores)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mem0/memory/__init__.py](https://github.com/mem0ai/mem0/blob/main/mem0/memory/__init__.py)
- [mem0/llms/__init__.py](https://github.com/mem0ai/mem0/blob/main/mem0/llms/__init__.py)
- [mem0/embeddings/__init__.py](https://github.com/mem0ai/mem0/blob/main/mem0/embeddings/__init__.py)
- [mem0/vector_stores/__init__.py](https://github.com/mem0ai/mem0/blob/main/mem0/vector_stores/__init__.py)
- [mem0-ts/src/client/mem0.ts](https://github.com/mem0ai/mem0/blob/main/mem0-ts/src/client/mem0.ts)
</details>

# 核心组件详解

## 概述

mem0是一个专为AI应用设计的智能记忆层（Intelligent Memory Layer），旨在为AI代理和助手提供持久化、可检索的记忆能力。该项目通过模块化的架构设计，将记忆管理、LLM集成、向量嵌入和存储系统解耦，实现了灵活的配置和扩展能力。mem0的核心价值在于简化AI应用的状态管理，使开发者能够专注于业务逻辑，而无需关心记忆存储和检索的底层实现。

mem0的设计理念强调自适应性和上下文理解能力。系统能够自动识别和存储重要的交互信息，同时支持多种向量存储后端和多语言模型集成。这种设计使得mem0能够适应从个人助手到企业级AI系统的各种应用场景。

## 架构概览

mem0采用分层架构设计，各层之间通过明确定义的接口进行通信。这种设计确保了系统的高度可扩展性和可维护性。

```mermaid
graph TD
    A[用户应用层] --> B[mem0 API 层]
    B --> C[记忆管理层]
    C --> D[嵌入生成层]
    C --> E[向量存储层]
    C --> F[LLM 推理层]
    D --> G[嵌入模型提供方]
    E --> H[向量数据库]
    F --> I[LLM 提供方]
```

从上述架构图可以看出，mem0的核心组件包括：记忆管理层（Memory）、嵌入生成层（Embeddings）、向量存储层（Vector Stores）和LLM推理层（LLMs）。每一层都设计了标准化的接口，支持多种后端实现，用户可以根据实际需求选择合适的组件组合。

## 核心组件详解

### 1. 记忆管理层（Memory）

记忆管理层是mem0的核心模块，负责管理AI应用的所有记忆操作。该模块提供了统一的API接口，封装了底层的向量存储、嵌入生成和LLM调用逻辑，为用户提供简洁易用的记忆管理功能。

#### 1.1 主要功能

记忆管理层支持以下核心操作：

- **记忆添加**：将新的信息存储到记忆系统中，支持自动嵌入生成和元数据管理
- **记忆检索**：基于语义相似度搜索相关记忆，返回排序后的结果列表
- **记忆更新**：修改已存储记忆的内容和关联元数据
- **记忆删除**：从系统中移除指定的记忆条目
- **记忆重置**：清空特定用户或会话的所有记忆

#### 1.2 API 接口规范

| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `add` | content, user_id, metadata | MemoryEntry | 添加新记忆 |
| `search` | query, user_id, limit | List[MemoryEntry] | 语义检索记忆 |
| `update` | memory_id, content | MemoryEntry | 更新记忆内容 |
| `delete` | memory_id | bool | 删除指定记忆 |
| `reset` | user_id | bool | 重置用户记忆 |

资料来源：[mem0/memory/__init__.py]()

#### 1.3 记忆数据结构

记忆条目采用结构化数据模型，包含以下关键字段：

```python
class MemoryEntry:
    id: str              # 唯一标识符
    content: str         # 记忆内容文本
    user_id: str         # 关联用户ID
    metadata: dict       # 扩展元数据
    created_at: datetime # 创建时间戳
    updated_at: datetime # 更新时间戳
    embedding: List[float] # 向量表示（可选）
```

这种数据结构设计确保了每条记忆都能够独立追踪和管理，同时保留了足够的灵活性以适应不同的应用场景需求。

### 2. LLM 推理层（LLMs）

LLM层是mem0的智能核心，负责与大语言模型进行交互。该模块抽象了不同LLM提供方的接口差异，提供统一的调用方式，同时支持模型配置、热插拔和多供应商备份等企业级功能。

#### 2.1 支持的模型提供商

mem0的LLM层原生支持多种主流大语言模型提供商：

| 提供商 | 模型示例 | 配置方式 |
|--------|----------|----------|
| OpenAI | GPT-4, GPT-3.5-turbo | API Key |
| Anthropic | Claude-3, Claude-2 | API Key |
| Azure OpenAI | GPT-4, GPT-35-turbo | Azure Endpoint |
| Google | Gemini Pro, PaLM | API Key |
| Ollama | Llama2, Mistral | 本地服务 |

资料来源：[mem0/llms/__init__.py]()

#### 2.2 LLM 客户端接口

```typescript
interface LLMClient {
  // 基础文本生成
  complete(prompt: string, options?: GenerationOptions): Promise<GenerationResult>;
  
  // 流式文本生成
  stream(prompt: string, options?: GenerationOptions): AsyncGenerator<string>;
  
  // 结构化输出生成
  structuredComplete(
    prompt: string, 
    schema: OutputSchema,
    options?: GenerationOptions
  ): Promise<StructuredOutput>;
}
```

资料来源：[mem0-ts/src/client/mem0.ts]()

#### 2.3 配置管理

LLM模块支持细粒度的配置控制，主要配置参数包括：

- `model`: 指定使用的模型名称
- `temperature`: 控制输出的随机性（0.0-2.0）
- `max_tokens`: 限制生成的最大token数
- `top_p`: 核采样概率阈值
- `api_base`: 自定义API端点（用于代理或自托管模型）
- `api_key`: 身份验证密钥

### 3. 嵌入生成层（Embeddings）

嵌入层负责将文本内容转换为高维向量表示，这是实现语义搜索能力的基础。该模块支持多种嵌入模型，并提供了统一的接口以便于扩展新的嵌入提供方。

#### 3.1 嵌入模型选择

mem0的嵌入层支持多种预训练嵌入模型：

- **OpenAI Embeddings**: text-embedding-ada-002, text-embedding-3-small, text-embedding-3-large
- **Cohere Embeddings**: embed-english-v3.0, embed-multilingual-v3.0
- **HuggingFace Embeddings**: 支持所有sentence-transformers模型
- **本地模型**: 支持Ollama和本地部署的嵌入模型

资料来源：[mem0/embeddings/__init__.py]()

#### 3.2 嵌入配置参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model` | string | "text-embedding-ada-002" | 嵌入模型名称 |
| `dimensions` | int | 1536 | 向量维度 |
| `batch_size` | int | 100 | 批处理大小 |
| `normalize` | bool | true | 是否归一化向量 |
| `encoding_format` | string | "float" | 编码格式 |

#### 3.3 嵌入生成流程

```mermaid
graph LR
    A[文本输入] --> B[预处理]
    B --> C[分词处理]
    C --> D[模型推理]
    D --> E[向量输出]
    E --> F[后处理]
    F --> G[归一化向量]
```

该流程确保了嵌入向量的一致性和可比性，为后续的向量检索提供了可靠的数据基础。

### 4. 向量存储层（Vector Stores）

向量存储层是mem0的记忆持久化核心，负责存储和管理所有记忆的向量表示。该模块采用了适配器模式，支持多种向量数据库后端，使得用户能够根据数据规模、性能需求和成本预算选择最合适的存储方案。

#### 4.1 支持的向量数据库

| 数据库 | 适用场景 | 特点 |
|--------|----------|------|
| Chroma | 原型开发、小规模 | 轻量级、易用、本地运行 |
| Qdrant | 生产环境 | 高性能、分布式、云原生 |
| Weaviate | 混合搜索 | 原生支持混合搜索能力 |
| Milvus | 超大规模数据 | 高吞吐量、水平扩展 |
| Pinecone | 云托管服务 | 全托管、免运维 |
| Redis | 低延迟场景 | 内存级速度、丰富数据结构 |

资料来源：[mem0/vector_stores/__init__.py]()

#### 4.2 向量存储接口

```python
class VectorStoreAdapter(ABC):
    """向量存储适配器基类"""
    
    @abstractmethod
    def add(
        self, 
        vectors: List[Vector], 
        metadatas: List[Metadata],
        ids: Optional[List[str]] = None
    ) -> List[str]:
        """添加向量到存储"""
        pass
    
    @abstractmethod
    def search(
        self, 
        query_vector: Vector, 
        top_k: int = 5,
        filters: Optional[Filter] = None
    ) -> List[SearchResult]:
        """执行向量相似度搜索"""
        pass
    
    @abstractmethod
    def update(
        self, 
        id: str, 
        vector: Vector, 
        metadata: Metadata
    ) -> bool:
        """更新指定向量"""
        pass
    
    @abstractmethod
    def delete(
        self, 
        ids: List[str],
        delete_all: bool = False
    ) -> bool:
        """删除向量"""
        pass
```

#### 4.3 索引策略

向量存储层支持多种索引策略以优化检索性能：

- **HNSW（Hierarchical Navigable Small World）**: 图索引，适合高精度场景
- **IVF（Inverted File Index）**: 倒排索引，适合大规模数据
- **PQ（Product Quantization）**: 产品量化，适合内存受限场景
- **SCANN**: 专利算法，Google出品，性能优异

### 5. TypeScript 客户端（mem0-ts）

mem0-ts是mem0的TypeScript/JavaScript客户端实现，提供了与Python版本功能对等的API接口。该客户端采用现代化的设计模式，支持服务端渲染和前端直接调用。

#### 5.1 客户端初始化

```typescript
import { Mem0Client } from "@mem0/nodejs-client";

const client = new Mem0Client({
  apiKey: process.env.MEM0_API_KEY,
  orgId: "your-org-id",      // 可选：组织ID
  projectId: "your-project", // 可选：项目ID
  baseUrl: "https://api.mem0.ai", // 可选：自定义API端点
});
```

资料来源：[mem0-ts/src/client/mem0.ts]()

#### 5.2 异步操作支持

TypeScript客户端全面支持异步操作模式，提供了Promise和AsyncIterator两种消费方式：

```typescript
// 使用 Promise
const memory = await client.add({
  content: "用户偏好深色主题",
  user_id: "user-123",
});

// 使用 AsyncIterator 处理流式响应
for await (const chunk of client.searchStream({
  query: "用户的界面偏好是什么",
  user_id: "user-123"
})) {
  console.log(chunk);
}
```

#### 5.3 错误处理机制

客户端实现了完善的错误处理机制，包括：

- **重试逻辑**: 自动重试失败的请求（可配置重试次数和间隔）
- **超时控制**: 防止请求无限等待
- **熔断器**: 连续失败时自动触发熔断保护
- **降级策略**: 主服务不可用时尝试降级方案

## 数据流与处理流程

### 记忆添加流程

当用户向mem0添加记忆时，系统会执行以下处理流程：

```mermaid
graph TD
    A[用户请求添加记忆] --> B{验证输入参数}
    B -->|参数无效| C[返回错误信息]
    B -->|参数有效| D[文本预处理]
    D --> E[调用嵌入模型]
    E --> F[生成向量表示]
    F --> G[构建元数据]
    G --> H[写入向量存储]
    H --> I[记录操作日志]
    I --> J[返回添加结果]
```

整个流程设计遵循了可靠性和可追溯性原则，每一步操作都有完善的日志记录，便于后续的问题排查和性能分析。

### 记忆检索流程

记忆检索是mem0最核心的功能之一，其处理流程如下：

```mermaid
graph TD
    A[用户查询请求] --> B[查询文本预处理]
    B --> C[调用嵌入模型]
    C --> D[生成查询向量]
    D --> E[执行向量相似度搜索]
    E --> F[应用过滤条件]
    F --> G[重排序结果]
    G --> H[组装响应数据]
    H --> I[返回检索结果]
```

检索流程中引入了重排序（Reranking）机制，可以在初步向量搜索的基础上进一步优化结果的相关性排序，提升用户体验。

## 配置与集成

### 环境变量配置

mem0支持通过环境变量进行全局配置：

```bash
# API 配置
MEM0_API_KEY=your-api-key

# LLM 配置
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx

# 向量存储配置
QDRANT_HOST=localhost
QDRANT_PORT=6333

# 嵌入模型配置
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSIONS=1536
```

### 快速开始示例

Python环境下的基本使用示例：

```python
from mem0 import Memory

# 初始化记忆客户端
memory = Memory()

# 添加记忆
result = memory.add(
    content="用户喜欢在周末骑自行车锻炼",
    user_id="user-123",
    metadata={"source": "onboarding"}
)

# 检索相关记忆
results = memory.search(
    query="用户的运动习惯是什么",
    user_id="user-123",
    limit=5
)

# 更新记忆
memory.update(
    memory_id=result["id"],
    content="用户喜欢在周末骑自行车锻炼，每天早晨跑步"
)

# 删除记忆
memory.delete(memory_id=result["id"])
```

资料来源：[mem0/memory/__init__.py]()

## 总结

mem0的核心组件设计体现了现代AI应用开发的最佳实践，通过清晰的模块划分和标准化的接口定义，实现了高度的可扩展性和灵活性。记忆管理层作为核心模块，封装了复杂的业务逻辑；LLM层提供了统一的模型调用接口；嵌入层确保了语义理解能力的基础；而向量存储层则提供了可靠的记忆持久化机制。

这种分层架构使得开发者可以根据具体需求选择和替换各层的实现组件，无需修改上层代码。例如，当需要处理更大规模的数据时，可以将向量存储从Chroma迁移到Qdrant或Milvus；当需要使用特定领域优化的嵌入模型时，只需替换嵌入层的实现而不影响其他模块。

mem0-ts客户端的存在进一步扩展了项目的适用范围，使得JavaScript和TypeScript生态系统的开发者也能便捷地使用mem0的记忆能力。通过统一的API设计，两种语言的客户端保持了功能对等性，降低了多语言项目的开发复杂度。

---

<a id='page-memory-operations'></a>

## 记忆操作API

### 相关页面

相关主题：[实体提取与链接](#page-entity-extraction), [系统架构](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mem0/memory/main.py](https://github.com/mem0ai/mem0/blob/main/mem0/memory/main.py)
- [docs/core-concepts/memory-operations/add.mdx](https://github.com/mem0ai/mem0/blob/main/docs/core-concepts/memory-operations/add.mdx)
- [docs/core-concepts/memory-operations/search.mdx](https://github.com/mem0ai/mem0/blob/main/docs/core-concepts/memory-operations/search.mdx)
- [docs/core-concepts/memory-operations/delete.mdx](https://github.com/mem0ai/mem0/blob/main/docs/core-concepts/memory-operations/delete.mdx)
- [docs/core-concepts/memory-operations/update.mdx](https://github.com/mem0ai/mem0/blob/main/docs/core-concepts/memory-operations/update.mdx)
- [cli/README.md](https://github.com/mem0ai/mem0/blob/main/cli/README.md)
- [cli/python/README.md](https://github.com/mem0ai/mem0/blob/main/cli/python/README.md)
- [mem0-plugin/README.md](https://github.com/mem0ai/mem0/blob/main/mem0-plugin/README.md)
- [vercel-ai-sdk/README.md](https://github.com/mem0ai/mem0/blob/main/vercel-ai-sdk/README.md)
</details>

# 记忆操作API

## 概述

Mem0的记忆操作API是智能体长期记忆管理的核心接口，提供了完整的记忆生命周期管理能力。该API支持四种基础操作：**添加（Add）**、**搜索（Search）**、**更新（Update）**、**删除（Delete）**，简称ASUD操作。资料来源：[mem0/memory/main.py](https://github.com/mem0ai/mem0/blob/main/mem0/memory/main.py)

Mem0的API设计遵循实体隔离原则，通过`user_id`、`agent_id`、`app_id`、`run_id`四个维度标识记忆的归属范围。这种多层级标识系统使得同一项目中的不同用户、代理和应用可以拥有独立的记忆空间，同时支持跨实体的记忆共享场景。资料来源：[vercel-ai-sdk/README.md](https://github.com/mem0ai/mem0/blob/main/vercel-ai-sdk/README.md)

## 架构概览

```mermaid
graph TD
    A[客户端应用] --> B[Mem0 API层]
    B --> C{操作类型}
    C -->|Add| D[记忆提取器]
    C -->|Search| E[向量检索引擎]
    C -->|Update| F[记忆更新器]
    C -->|Delete| G[记忆删除器]
    D --> H[向量数据库]
    E --> H
    F --> H
    G --> H
    H --> I[(持久化存储)]
```

## 核心操作

### 添加记忆

添加操作是记忆系统的入口点，负责从用户输入中提取有价值的信息并存储到向量数据库中。Mem0使用大语言模型进行事实提取，能够自动识别对话中的关键信息并结构化存储。资料来源：[docs/core-concepts/memory-operations/add.mdx](https://github.com/mem0ai/mem0/blob/main/docs/core-concepts/memory-operations/add.mdx)

#### Python SDK添加示例

```python
from mem0 import Memory

client = Memory()
response = client.add(
    messages=[
        {"role": "user", "content": "我叫张三，喜欢喝咖啡"},
        {"role": "assistant", "content": "好的张三，我已经记住你喜欢咖啡"}
    ],
    user_id="zhangsan"
)
```

#### CLI添加命令

```bash
mem0 add "我偏好深烘焙咖啡豆" --user-id zhangsan
echo "新地址是朝阳区" | mem0 add --user-id zhangsan
mem0 add --file conversation.json --user-id zhangsan
```

资料来源：[cli/README.md](https://github.com/mem0ai/mem0/blob/main/cli/README.md)

### 搜索记忆

搜索操作支持语义向量检索，能够根据自然语言查询找到语义相关的记忆内容。该操作支持多种过滤条件，包括时间范围、实体标识和元数据过滤。资料来源：[docs/core-concepts/memory-operations/search.mdx](https://github.com/mem0ai/mem0/blob/main/docs/core-concepts/memory-operations/search.mdx)

#### 搜索参数说明

| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `query` | string | 是 | - | 自然语言搜索查询 |
| `user_id` | string | 否 | - | 用户唯一标识 |
| `agent_id` | string | 否 | - | 代理唯一标识 |
| `top_k` | int | 否 | 30 | 返回结果数量上限 |
| `version` | string | 否 | - | Mem0版本标识 |
| `category` | string | 否 | - | 记忆类别过滤 |

#### 搜索响应结构

```json
{
  "results": [
    {
      "id": "mem_xxx",
      "memory": "用户偏好深烘焙咖啡豆",
      "hash": "a1b2c3d4",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "metadata": {
        "category": "user_preferences",
        "source": "direct_input"
      }
    }
  ],
  "total_count": 1
}
```

### 更新记忆

更新操作用于修改已有记忆的文本内容或元数据。更新时需要指定记忆的唯一标识符（memory_id），可以同时更新文本和元数据，也可以单独更新其中一项。资料来源：[docs/core-concepts/memory-operations/update.mdx](https://github.com/mem0ai/mem0/blob/main/docs/core-concepts/memory-operations/update.mdx)

#### 更新方法签名

```python
client.update(
    memory_id="mem_xxx",          # 必需：记忆唯一标识
    data="新的记忆内容",            # 可选：新的记忆文本
    metadata={"key": "value"}      # 可选：新的元数据
)
```

#### CLI更新命令

```bash
mem0 update <memory-id> "更新后的记忆内容"
mem0 update <memory-id> --metadata '{"priority": "high"}'
```

资料来源：[cli/python/README.md](https://github.com/mem0ai/mem0/blob/main/cli/python/README.md)

### 删除记忆

删除操作支持三种粒度：单个记忆删除、基于过滤条件的批量删除、以及实体级别的完全删除。删除操作支持预览模式（dry-run），可在执行前查看将被删除的内容。资料来源：[docs/core-concepts/memory-operations/delete.mdx](https://github.com/mem0ai/mem0/blob/main/docs/core-concepts/memory-operations/delete.mdx)

#### 删除选项矩阵

| 场景 | 命令格式 | 说明 |
|------|----------|------|
| 删除单个记忆 | `mem0 delete <memory-id>` | 根据记忆ID精确删除 |
| 删除用户所有记忆 | `mem0 delete --all --user-id alice` | 删除指定用户的所有记忆 |
| 删除实体及关联记忆 | `mem0 delete --entity --user-id alice` | 删除用户实体及其所有记忆 |
| 删除项目级所有记忆 | `mem0 delete --all --project` | 删除当前项目下的全部记忆 |
| 预览删除内容 | `mem0 delete --all --user-id alice --dry-run` | 不实际执行，显示将被删除的内容 |
| 跳过确认提示 | `mem0 delete --all --user-id alice --force` | 直接执行，不显示确认提示 |

## MCP工具接口

Mem0提供Model Context Protocol（MCP）工具接口，支持AI代理通过标准化的工具调用与记忆系统交互。这些工具封装了底层的REST API调用，提供类型安全的接口契约。资料来源：[mem0-plugin/README.md](https://github.com/mem0ai/mem0/blob/main/mem0-plugin/README.md)

### MCP工具列表

| 工具名称 | 功能描述 | 输入参数 |
|----------|----------|----------|
| `add_memory` | 保存文本或对话历史 | messages/text, user_id, metadata |
| `search_memories` | 语义搜索记忆 | query, filters, limit |
| `get_memories` | 列出记忆列表 | filters, pagination |
| `get_memory` | 获取特定记忆 | memory_id |
| `update_memory` | 更新记忆文本 | memory_id, text |
| `delete_memory` | 删除单个记忆 | memory_id |
| `delete_all_memories` | 批量删除记忆 | filters |
| `delete_entities` | 删除实体及其记忆 | entity_type, entity_id |
| `list_entities` | 列出实体类型 | entity_type |

## 命令行接口

Mem0 CLI提供完整的命令行工具集，支持快速操作和自动化脚本集成。所有命令支持全局`--agent`标志，以JSON格式输出结果，适合AI代理工具循环调用。资料来源：[cli/README.md](https://github.com/mem0ai/mem0/blob/main/cli/README.md)

### 核心命令速查

```bash
# 初始化配置
mem0 init --api-key <key> --user-id <user>

# 记忆操作
mem0 add "记忆内容" --user-id <user>
mem0 search "查询内容" --user-id <user>
mem0 list --user-id <user>
mem0 get <memory-id>
mem0 update <memory-id> "新内容"
mem0 delete <memory-id>

# 批量操作
mem0 import data.json --user-id <user>
mem0 delete --all --user-id <user> --force

# 配置与状态
mem0 config show
mem0 entity list users
mem0 event list
mem0 status
```

### Agent模式

在agent模式下，命令输出被优化为机器可解析的JSON格式，适合集成到AI工作流中：

```bash
mem0 --agent search "用户偏好" --user-id alice
mem0 --agent add "用户喜欢深色主题" --user-id alice
mem0 --agent list --user-id alice
```

## 实体管理

Mem0通过实体系统组织记忆，支持四种实体类型：用户（users）、代理（agents）、应用（apps）、运行实例（runs）。实体管理提供独立的命名空间，便于在复杂系统中隔离和管理记忆。资料来源：[cli/python/README.md](https://github.com/mem0ai/mem0/blob/main/cli/python/README.md)

### 实体操作命令

```bash
# 列出所有用户
mem0 entity list users

# 列出所有代理（JSON格式）
mem0 entity list agents --output json

# 删除用户及其所有关联记忆
mem0 entity delete --user-id alice --force
```

## 事件系统

对于异步操作（如批量删除、大量添加任务），Mem0提供事件系统追踪后台处理状态。事件对象包含处理状态、进度信息和结果摘要。资料来源：[cli/python/README.md](https://github.com/mem0ai/mem0/blob/main/cli/python/README.md)

```bash
# 列出最近的事件
mem0 event list

# 查询特定事件状态
mem0 event status <event-id>
```

## 实验运行参数

在评估和实验场景中，Mem0支持通过参数控制记忆操作行为。这些参数通过命令行传入`run_experiments.py`脚本。资料来源：[evaluation/README.md](https://github.com/mem0ai/mem0/blob/main/evaluation/README.md)

### 可配置参数

| 参数名 | 说明 | 默认值 |
|--------|------|--------|
| `--technique_type` | 记忆技术类型：mem0/rag/langmem | mem0 |
| `--method` | 操作方法：add/search | add |
| `--chunk_size` | 处理分块大小 | 1000 |
| `--top_k` | 检索返回的记忆数量 | 30 |
| `--filter_memories` | 是否启用记忆过滤 | False |
| `--is_graph` | 是否启用图搜索 | False |
| `--num_chunks` | RAG处理的块数量 | 1 |

### 实验执行命令

```bash
# 添加记忆实验
python run_experiments.py --technique_type mem0 --method add

# 搜索记忆实验
python run_experiments.py --technique_type mem0 --method search --top_k 50
```

## 最佳实践

### 标识符使用建议

始终为每次交互提供唯一的`user_id`标识，以确保持久化记忆的正确关联。对于涉及多个代理的系统，建议同时设置`agent_id`，以便追踪不同代理的学习成果。资料来源：[vercel-ai-sdk/README.md](https://github.com/mem0ai/mem0/blob/main/vercel-ai-sdk/README.md)

```python
# 推荐：为每个用户和代理都设置标识
client.add(
    messages=[...],
    user_id="unique_user_id",
    agent_id="unique_agent_id"  # 可选但推荐
)
```

### 错误处理

实现重试机制和优雅的错误处理，特别是在网络调用场景中：

```python
try:
    result = client.add(messages=[...], user_id="user1")
except RateLimitError:
    # 实现退避重试
    time.sleep(60)
    result = client.add(messages=[...], user_id="user1")
```

### 记忆清理策略

定期清理不再需要的记忆以优化存储和检索性能。使用`--dry-run`参数预览删除影响后再执行实际操作。资料来源：[cli/python/README.md](https://github.com/mem0ai/mem0/blob/main/cli/python/README.md)

## 评估指标

Mem0提供内置评估脚本计算记忆操作的效果指标：

```bash
# 执行评估
python evals.py --input_file results.json --output_file scores.json

# 生成最终评分
python generate_scores.py
```

评估脚本自动计算BLEU分数、F1分数和LLM评判分数，并按类别汇总统计。资料来源：[evaluation/README.md](https://github.com/mem0ai/mem0/blob/main/evaluation/README.md)

---

<a id='page-entity-extraction'></a>

## 实体提取与链接

### 相关页面

相关主题：[记忆操作API](#page-memory-operations), [LLM模型集成](#page-llm-integrations)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mem0-ts/src/oss/src/utils/entity_extraction.ts](https://github.com/mem0ai/mem0/blob/main/mem0-ts/src/oss/src/utils/entity_extraction.ts)
- [mem0/utils/entity_extraction.py](https://github.com/mem0ai/mem0/blob/main/mem0/utils/entity_extraction.py)
- [mem0/utils/lemmatization.py](https://github.com/mem0ai/mem0/blob/main/mem0/utils/lemmatization.py)
- [mem0/utils/scoring.py](https://github.com/mem0ai/mem0/blob/main/mem0/utils/scoring.py)
</details>

# 实体提取与链接

## 概述

实体提取与链接（Entity Extraction and Linking）是Mem0记忆系统中用于从用户输入和对话历史中识别、分类和关联关键信息片段的核心组件。该系统能够自动识别文本中的人名、组织名、地点、时间表达式以及复合术语，并将这些实体与记忆系统中的其他相关信息进行关联，形成结构化的知识网络。

Mem0的实体提取模块采用混合策略，结合正则表达式模式匹配、词典匹配和启发式规则来实现高精度的实体识别。该模块是Mem0实现"智能记忆"的关键基础，使系统能够理解用户提及的具体实体，并基于实体关系进行更精准的记忆检索和推理。

## 系统架构

### 整体架构图

```mermaid
graph TD
    A[用户输入文本] --> B[文本预处理]
    B --> C[实体提取引擎]
    C --> D[实体类型分类]
    C --> E[复合词识别]
    C --> F[实体规范化]
    D --> G[实体链接模块]
    E --> G
    F --> G
    G --> H[记忆存储层]
    H --> I[向量嵌入生成]
    I --> J[记忆检索引擎]
    
    subgraph 实体类型识别
        D --> D1[PERSON - 人名]
        D --> D2[ORG - 组织机构]
        D --> D3[LOCATION - 地点]
        D --> D4[TIME - 时间表达式]
    end
    
    subgraph 复合词处理
        E --> E1[COMPOUND - 复合术语]
        E1 --> E2[Machine Learning]
        E1 --> E2[Deep Learning]
    end
```

### 模块职责

| 模块名称 | 职责描述 | 核心文件 |
|---------|---------|---------|
| 文本预处理 | 分词、清洗、标准化 | `lemmatization.py` |
| 实体提取引擎 | 正则匹配、模式识别 | `entity_extraction.py` / `entity_extraction.ts` |
| 实体分类器 | 实体类型判定与标注 | `entity_extraction.ts` |
| 复合词识别器 | 多词术语检测与合并 | `entity_extraction.ts` |
| 实体规范化 | 词形还原、去重、标准化 | `lemmatization.py` |
| 评分引擎 | 实体重要性评估与排序 | `scoring.py` |

## 实体类型系统

Mem0定义了以下核心实体类型，用于对识别的实体进行语义分类：

```mermaid
graph LR
    A[识别结果] --> B[PERSON]
    A --> C[ORG]
    A --> D[LOCATION]
    A --> E[TIME]
    A --> F[COMPOUND]
    
    B --> B1[人名实体]
    C --> C1[组织机构]
    D --> D1[地理/虚拟位置]
    E --> E1[时间表达式]
    F --> F1[复合术语短语]
    
    style B fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#e8f5e9
    style E fill:#fce4ec
    style F fill:#f3e5f5
```

### 实体类型详细说明

| 类型标识 | 类型名称 | 识别模式 | 示例 |
|---------|---------|---------|------|
| PERSON | 人名 | 正则匹配 + 词典 | "John Smith", "Alice" |
| ORG | 组织机构 | 正则匹配 + 词典 | "Google", "MIT" |
| LOCATION | 地点 | 正则匹配 + 词典 | "San Francisco", "Paris" |
| TIME | 时间表达式 | 正则匹配 | "2024-01-15", "last Monday" |
| COMPOUND | 复合术语 | 词组模式匹配 | "machine learning", "deep learning" |

### PERSON 类型识别

人名实体识别基于以下策略组合：

1. **首字母大写模式**：识别以大写字母开头的连续单词序列
2. **已知人名词典**：通过预定义词典匹配常见人名
3. **上下文信号**：结合动词和介词的上下文关系辅助判断

```typescript
// 参考: mem0-ts/src/oss/src/utils/entity_extraction.ts
const personNamePattern = /\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+)+)\b/g;
```

### ORG 类型识别

组织机构识别涵盖以下类别：

- **公司企业**：如 "OpenAI", "Microsoft", "Tesla"
- **学术机构**：如 "MIT", "Stanford University", "Oxford"
- **非营利组织**：如 "World Health Organization"

组织机构识别使用正则表达式与词典结合的方式：

```typescript
const orgPatterns = [
  /\b([A-Z][a-z]*(?:\s+[A-Z][a-z]*)*\s+(Inc|Corp|LLC|Ltd|Co)\.?)\b/gi,
  /\b([A-Z][a-z]*(?:\s+[A-Z][a-z]*)*\s+(University|Institute|College)\b/gi
];
```

### LOCATION 类型识别

地点实体识别包括：

- **城市名称**：如 "Beijing", "London", "Tokyo"
- **国家名称**：如 "United States", "China", "Germany"
- **地理标识**：如 "Silicon Valley", "the Pacific"

### TIME 类型识别

时间表达式支持以下格式：

| 格式类型 | 示例 | 正则模式 |
|---------|------|---------|
| ISO日期 | 2024-01-15 | `\d{4}-\d{2}-\d{2}` |
| 美式日期 | 01/15/2024 | `\d{1,2}/\d{1,2}/\d{4}` |
| 自然语言 | last Monday | 上下文模式匹配 |
| 相对时间 | two weeks ago | 词汇匹配 |

### COMPOUND 复合术语识别

复合术语是实体提取系统中最复杂的部分，用于识别由多个词组成的专业术语和技术概念。

```mermaid
graph TD
    A[输入文本] --> B[词组模式扫描]
    B --> C{是否满足复合词条件?}
    C -->|是| D[词形还原处理]
    C -->|否| E[丢弃该词组]
    D --> F{检查内容词}
    F -->|有内容词| G[去除通用修饰词]
    F -->|无内容词| E
    G --> H{剩余词数>=2?}
    H -->|是| I[标记为COMPOUND]
    H -->|否| E
    I --> J[规范化输出]
```

复合词识别规则：

- **最小长度限制**：词组长度至少2个词，最多4个词
- **总字符数**：词组总字符数必须大于5
- **内容词检查**：至少包含一个非通用修饰的内容词
- **尾部词汇过滤**：排除以通用词结尾的组合

**通用头部词汇集合**（GENERIC_HEADS）：

```typescript
const GENERIC_HEADS = new Set([
  'system', 'platform', 'framework', 'solution', 'service',
  'model', 'method', 'approach', 'tool', 'application'
]);
```

**非特定形容词集合**（NON_SPECIFIC_ADJ）：

```typescript
const NON_SPECIFIC_ADJ = new Set([
  'new', 'old', 'good', 'great', 'best', 'latest', 'current',
  'advanced', 'modern', 'popular', 'simple', 'basic'
]);
```

## 核心算法流程

### 实体提取完整流程

```mermaid
sequenceDiagram
    participant U as 用户输入
    participant T as 文本预处理
    participant E as 实体提取
    participant C as 分类器
    participant L as 链接引擎
    participant M as 记忆存储
    
    U->>T: 原始文本输入
    T->>T: 分词与标准化
    T->>E: 预处理后文本
    E->>E: 正则模式匹配
    E->>E: 词典匹配
    E->>E: 复合词检测
    E->>C: 候选实体列表
    C->>C: 类型分类
    C->>C: 置信度评估
    C->>L: 分类后实体
    L->>L: 去重处理
    L->>L: 规范化
    L->>M: 关联存储
    M-->>U: 确认存储
```

### 复合词识别详细算法

复合词识别的核心算法伪代码：

```
函数 extractCompoundEntities(text):
    1. 初始化空结果列表
    
    2. 扫描文本查找 2-4 词的词组组合
    
    3. 对每个候选词组:
       a. 检查总字符数 > 5
       b. 获取词组最后一个词 (head)
       c. 检查 head 是否在 GENERIC_HEADS 中
       d. 如果在，则跳过该候选
       e. 检查词组是否全为通用词
       f. 如果全为通用词，则跳过
       
    4. 对通过初步检查的候选词组:
       a. 过滤掉 NON_SPECIFIC_ADJ 中的词
       b. 去除通用结尾词
       c. 如果剩余词数 >= 2
          则添加到结果列表
          
    5. 返回实体列表，每个实体包含:
       - type: "COMPOUND"
       - text: 规范化后的词组文本
```

### 实体链接机制

实体链接模块负责将提取的实体与现有记忆进行关联：

1. **共现分析**：检测实体在相同上下文中出现的频率
2. **关系推断**：基于动词和介词推断实体间关系类型
3. **时间关联**：关联具有时间属性的实体到对应时间点
4. **层级关系**：识别实体间的上下级关系

## API 与配置

### Python SDK 接口

Mem0的Python SDK提供以下实体提取相关接口：

```python
from mem0 import Memory

# 初始化记忆客户端
memory = Memory()

# 添加包含实体的记忆
result = memory.add(
    messages=[
        {"role": "user", "content": "Alice works at Google in San Francisco"}
    ],
    user_id="user123"
)

# 搜索相关记忆
results = memory.search(
    query="Who works at Google?",
    user_id="user123"
)
```

### 配置参数

| 参数名称 | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| `embedding_model` | string | "text-embedding-3-small" | 向量嵌入模型 |
| `llm_model` | string | "gpt-4" | 用于实体提取的LLM模型 |
| `entity_types` | list | ["PERSON", "ORG", "LOCATION", "TIME", "COMPOUND"] | 要识别的实体类型 |
| `enable_graph` | bool | false | 启用图结构实体关联 |
| `similarity_threshold` | float | 0.7 | 实体相似度匹配阈值 |

### TypeScript SDK 接口

```typescript
import { Memory } from 'mem0-ts';

const memory = new Memory({
  embedder: {
    provider: 'openai',
    config: {
      apiKey: process.env.OPENAI_API_KEY,
      model: 'text-embedding-3-small'
    }
  },
  llm: {
    config: {
      apiKey: process.env.OPENAI_API_KEY,
      model: 'gpt-4'
    }
  }
});

// 添加记忆并触发实体提取
await memory.add('John visited the Stanford University campus yesterday');

// 检索相关实体记忆
const results = await memory.search('Who did John visit?');
```

## 规范化与评分

### 词形还原（Lemmatization）

词形还原模块负责将提取的实体还原为其标准形式：

```mermaid
graph LR
    A[原始形式] --> B[词性标注]
    B --> C{词性判断}
    C -->|名词| D[名词还原规则]
    C -->|动词| E[动词还原规则]
    C -->|形容词| F[形容词还原规则]
    D --> G[标准形式输出]
    E --> G
    F --> G
```

词形还原规则示例：

| 原始形式 | 词性 | 还原后 |
|---------|------|--------|
| working | 动词 | work |
| mice | 名词 | mouse |
| better | 形容词 | good |
| studies | 动词 | study |

### 实体评分系统

评分模块用于评估实体的重要性，影响记忆的优先级和检索排序：

| 评分维度 | 权重 | 计算方式 |
|---------|------|---------|
| 出现频率 | 0.3 | 实体在历史中出现的次数 |
| 上下文相关性 | 0.25 | 与当前查询的语义相似度 |
| 时间新鲜度 | 0.2 | 最近提及距今的时间 |
| 实体类型重要性 | 0.15 | 预定义的类型权重 |
| 唯一性 | 0.1 | 实体在知识库中的稀有程度 |

## CLI 工具支持

Mem0 CLI提供完整的实体管理命令：

```bash
# 查看用户相关的所有实体
mem0 entity list users

# 查看代理实体
mem0 entity list agents --output json

# 删除特定用户及其关联的所有实体
mem0 entity delete --user-id alice --force

# 搜索包含特定实体的记忆
mem0 search "Google" --user-id alice --output json

# 列出特定用户的记忆
mem0 list --user-id alice --category preferences
```

## 使用最佳实践

### 提高实体识别准确率

1. **提供明确的上下文**：在输入中包含清晰的实体上下文信息
2. **使用标准命名**：遵循一致的命名约定（如首字母大写）
3. **避免歧义**：对于可能产生歧义的实体，提供额外的限定词

### 复合术语识别优化

1. **使用标准术语**：采用业界通用的复合术语命名
2. **避免过度缩写**：完整术语比缩写更容易被识别
3. **分隔符使用**：使用空格分隔复合词，避免连字符或无分隔符

### 性能优化建议

| 场景 | 优化策略 |
|------|---------|
| 大量实体处理 | 启用批量处理模式 |
| 实时应用 | 启用缓存机制 |
| 高精度需求 | 使用更大的LLM模型 |
| 成本敏感 | 使用轻量级模型配合规则引擎 |

## 技术限制与已知问题

### 当前限制

1. **嵌套实体**：暂不支持嵌套实体结构的识别
2. **跨语言实体**：主要针对英语文本优化，其他语言支持有限
3. **歧义消解**：实体消歧能力依赖于上下文信息丰富度
4. **动态实体**：实时更新的实体（如新闻事件）识别存在延迟

### 未来改进方向

- 增强多语言支持能力
- 引入更先进的命名实体识别模型
- 支持自定义实体类型和识别规则
- 改进跨文档实体追踪能力

## 相关文档

- [Mem0 Python SDK 文档](../sdks/python/README.md)
- [Mem0 TypeScript SDK 文档](../sdks/typescript/README.md)
- [记忆检索系统](./memory_retrieval.md)
- [向量存储架构](./vector_store.md)

---

<a id='page-llm-integrations'></a>

## LLM模型集成

### 相关页面

相关主题：[嵌入模型配置](#page-embeddings), [向量数据库支持](#page-vector-stores)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mem0/llms/openai.py](https://github.com/mem0ai/mem0/blob/main/mem0/llms/openai.py)
- [mem0/llms/anthropic.py](https://github.com/mem0ai/mem0/blob/main/mem0/llms/anthropic.py)
- [mem0/llms/azure_openai.py](https://github.com/mem0ai/mem0/blob/main/mem0/llms/azure_openai.py)
- [mem0/llms/base.py](https://github.com/mem0ai/mem0/blob/main/mem0/llms/base.py)
- [docs/components/llms/overview.mdx](https://github.com/mem0ai/mem0/blob/main/docs/components/llms/overview.mdx)
- [docs/components/llms/models/openai.mdx](https://github.com/mem0ai/mem0/blob/main/docs/components/llms/models/openai.mdx)
</details>

# LLM模型集成

## 概述

mem0 平台提供了灵活的 LLM（大语言模型）集成框架，允许用户连接不同的 LLM 提供商来处理记忆检索、生成和推理任务。通过统一的抽象接口设计，mem0 支持 OpenAI、Anthropic (Claude)、Azure OpenAI 等主流 LLM 服务商，用户可以根据需求选择和切换不同的模型。

## 架构设计

mem0 的 LLM 集成采用**基类继承 + 具体实现**的设计模式。`BaseLlm` 作为所有 LLM 提供商的抽象基类，定义了统一的接口规范，各具体 LLM 类继承该基类并实现特定平台的调用逻辑。

```mermaid
graph TD
    A[用户配置] --> B[Config 配置类]
    B --> C{LLM 提供商类型}
    C -->|OpenAI| D[OpenAILlm]
    C -->|Anthropic| E[AnthropicLlm]
    C -->|Azure| F[AzureOpenAILlm]
    D --> G[BaseLlm 抽象基类]
    E --> G
    F --> G
    G --> H[generate 方法]
    G --> I[generate_response 方法]
```

所有 LLM 实现类均继承自 `BaseLlm`，继承关系如下：

```mermaid
graph TD
    A[BaseLlm] --> B[OpenAILlm]
    A --> C[AnthropicLlm]
    A --> D[AzureOpenAILlm]
```

资料来源：[mem0/llms/base.py:1-50]()

## BaseLlm 抽象基类

`BaseLlm` 定义了 LLM 集成的核心接口规范，包含以下关键方法：

| 方法名 | 功能描述 | 返回类型 |
|--------|----------|----------|
| `generate` | 根据提示词生成文本响应 | `str` |
| `generate_response` | 生成结构化响应对象 | 响应对象 |

资料来源：[mem0/llms/base.py:1-50]()

### 基类核心属性

```python
class BaseLlm:
    def __init__(self, model: str = None, temperature: float = None, **kwargs):
        self.model = model
        self.temperature = temperature
```

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model` | `str` | `None` | 模型名称/标识符 |
| `temperature` | `float` | `None` | 生成温度参数 (0.0-1.0) |
| `**kwargs` | `dict` | - | 其他提供商特定参数 |

## OpenAI 集成

`OpenAILlm` 类实现了 OpenAI API 的集成，支持 GPT-4、GPT-3.5-Turbo 等模型。

### 初始化配置

```python
from mem0.llms.openai import OpenAILlm

llm = OpenAILlm(
    model="gpt-4",
    temperature=0.7,
    api_key="your-api-key"  # 可通过环境变量 OPENAI_API_KEY 设置
)
```

资料来源：[mem0/llms/openai.py:1-100]()

### 环境变量配置

| 环境变量 | 说明 |
|----------|------|
| `OPENAI_API_KEY` | OpenAI API 密钥 |
| `OPENAI_API_BASE` | API 基础 URL（可选，用于代理或自定义端点） |

## Anthropic (Claude) 集成

`AnthropicLlm` 类实现了 Anthropic Claude 模型的集成。

### 初始化配置

```python
from mem0.llms.anthropic import AnthropicLlm

llm = AnthropicLlm(
    model="claude-3-opus-20240229",
    temperature=0.7,
    api_key="your-api-key"  # 可通过环境变量 ANTHROPIC_API_KEY 设置
)
```

资料来源：[mem0/llms/anthropic.py:1-100]()

### 环境变量配置

| 环境变量 | 说明 |
|----------|------|
| `ANTHROPIC_API_KEY` | Anthropic API 密钥 |
| `ANTHROPIC_API_BASE` | API 基础 URL（可选） |

## Azure OpenAI 集成

`AzureOpenAILlm` 类实现了 Azure OpenAI Service 的集成，适用于企业级部署场景。

### 初始化配置

```python
from mem0.llms.azure_openai import AzureOpenAILlm

llm = AzureOpenAILlm(
    model="gpt-4",
    temperature=0.7,
    api_key="your-api-key",
    api_base="https://your-resource.openai.azure.com",
    api_version="2024-02-01"  # Azure API 版本
)
```

资料来源：[mem0/llms/azure_openai.py:1-100]()

### Azure 特定配置参数

| 参数 | 说明 | 必需 |
|------|------|------|
| `api_base` | Azure 资源端点 URL | 是 |
| `api_version` | Azure API 版本号 | 是 |
| `api_type` | 固定值 `azure` | 是 |

## 使用流程

mem0 中 LLM 的典型使用流程如下：

```mermaid
graph LR
    A[创建 Config] --> B[初始化 LLM 实例]
    B --> C[调用 generate/generate_response]
    C --> D[返回结果]
```

### 完整使用示例

```python
from mem0.llms.openai import OpenAILlm

# 方式一：直接初始化
llm = OpenAILlm(model="gpt-4", temperature=0.0)

# 方式二：通过配置初始化
llm = OpenAILlm.from_config({
    "model": "gpt-4",
    "temperature": 0.7
})

# 调用生成方法
response = llm.generate("What is the capital of France?")
```

## 配置管理

mem0 支持通过配置文件或代码方式管理 LLM 配置。

### 配置优先级

```
环境变量 > 代码参数 > 配置文件默认值
```

### 常用配置模板

| 提供商 | 推荐模型 | 适用场景 |
|--------|----------|----------|
| OpenAI | `gpt-4` / `gpt-3.5-turbo` | 通用场景、高质量生成 |
| Anthropic | `claude-3-opus` / `claude-3-sonnet` | 长文本理解、复杂推理 |
| Azure OpenAI | `gpt-4` (企业部署) | 企业合规、数据隐私 |

## 模型参数说明

### Temperature 参数

| 值范围 | 行为特征 | 适用场景 |
|--------|----------|----------|
| 0.0 - 0.3 | 确定性强、一致性高 | 事实问答、结构化输出 |
| 0.4 - 0.7 | 平衡创造性与准确性 | 通用对话、内容生成 |
| 0.8 - 1.0 | 高度创造性、多样性强 | 创意写作、头脑风暴 |

## 扩展新的 LLM 提供商

如需集成新的 LLM 提供商，需遵循以下步骤：

```mermaid
graph TD
    A[创建新文件如 mem0/llms/new_provider.py] --> B[继承 BaseLlm 类]
    B --> C[实现 generate 方法]
    C --> D[实现 generate_response 方法]
    D --> E[添加环境变量支持]
    E --> F[更新文档和导出]
```

```python
from mem0.llms.base import BaseLlm

class NewProviderLlm(BaseLlm):
    def __init__(self, model: str = None, **kwargs):
        super().__init__(model=model, **kwargs)
    
    def generate(self, prompt: str) -> str:
        # 实现提供商特定的调用逻辑
        pass
```

## 常见问题

### Q: 如何选择合适的 LLM 提供商？

**A**: 根据以下因素选择：

- **数据隐私要求**：企业场景优先选择 Azure OpenAI
- **成本控制**：GPT-3.5-Turbo 成本较低，适合大量调用
- **任务复杂度**：复杂推理任务推荐 Claude-3-Opus 或 GPT-4

### Q: API 密钥如何安全配置？

**A**: 推荐使用环境变量方式配置，避免在代码中硬编码密钥：

```bash
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
```

## 相关资源

- [LLM 概述文档](https://github.com/mem0ai/mem0/blob/main/docs/components/llms/overview.mdx)
- [OpenAI 详细配置](https://github.com/mem0ai/mem0/blob/main/docs/components/llms/models/openai.mdx)
- [mem0 源码仓库](https://github.com/mem0ai/mem0)

---

<a id='page-vector-stores'></a>

## 向量数据库支持

### 相关页面

相关主题：[嵌入模型配置](#page-embeddings)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [evaluation/README.md](https://github.com/mem0ai/mem0/blob/main/evaluation/README.md)
- [server/dashboard/src/app/(root)/dashboard/configuration/page.tsx](https://github.com/mem0ai/mem0/blob/main/server/dashboard/src/app/(root)/dashboard/configuration/page.tsx)
- [cli/node/README.md](https://github.com/mem0ai/mem0/blob/main/cli/node/README.md)
- [cli/python/README.md](https://github.com/mem0ai/mem0/blob/main/cli/python/README.md)
- [docs/components/vectordbs/overview.mdx](https://github.com/mem0ai/mem0/blob/main/docs/components/vectordbs/overview.mdx)
</details>

# 向量数据库支持

## 概述

Mem0 平台提供了灵活的向量数据库集成能力，支持多种向量存储后端以满足不同的部署需求和性能要求。向量数据库在 Mem0 架构中承担着核心角色，负责存储和检索记忆（Memories）的高维向量嵌入表示，从而实现语义化的记忆搜索功能。

向量数据库支持使 Mem0 能够：

- **存储语义向量**：将记忆内容转换为高维向量进行高效存储
- **语义相似度搜索**：基于向量距离算法返回相关内容
- **可扩展部署**：支持本地和云端等多种部署方案 资料来源：[evaluation/README.md]()

## 架构设计

Mem0 的向量数据库支持采用模块化的设计理念，通过统一的抽象接口连接不同的向量存储后端。

```mermaid
graph TD
    A[用户请求] --> B[Mem0 Core]
    B --> C{向量存储层}
    C --> D[Pinecone]
    C --> E[Qdrant]
    C --> F[Chroma]
    C --> G[Weaviate]
    C --> H[FAISS 本地]
    D --> I[云端向量数据库]
    E --> J[自托管 / 云端]
    H --> K[本地文件系统]
```

### 核心组件

| 组件 | 职责 | 支持类型 |
|------|------|---------|
| **向量存储抽象层** | 定义统一的向量操作接口 | BaseVectorStore |
| **嵌入模型配置** | 管理文本到向量的转换 | OpenAI、Aziere、Cohere 等 |
| **查询路由** | 根据配置选择合适的存储后端 | 动态路由 |
| **元数据管理** | 处理记忆的附加属性 | 标签、来源、时间戳 |

资料来源：[server/dashboard/src/app/(root)/dashboard/configuration/page.tsx]()

## 嵌入模型配置

Mem0 支持配置多种嵌入模型来生成向量表示。嵌入模型的选择直接影响记忆检索的质量和性能。

### 配置参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `EMBEDDING_MODEL` | 嵌入模型名称 | text-embedding-3-small |
| `embedder_provider` | 嵌入服务提供商 | OpenAI |
| `embedder_model` | 具体模型标识 | text-embedding-3-small |

### 支持的嵌入提供商

Mem0 平台原生支持以下嵌入服务提供商：

- **OpenAI**：使用 text-embedding-3-small 或 text-embedding-ada-002
- **Azure OpenAI**：通过 Azure 平台部署的 OpenAI 模型
- **Cohere**：支持 Cohere Embed 系列产品
- **自定义提供商**：支持扩展其他嵌入服务

配置示例（来自评估脚本）：

```bash
export EMBEDDING_MODEL="text-embedding-3-small"  # 或您偏好的嵌入模型
```

资料来源：[evaluation/README.md:1-5]()

## 向量存储后端

### 云端向量数据库

#### Pinecone

Pinecone 是 Mem0 推荐的生产环境向量存储方案之一，提供完全托管的向量数据库服务。

**特点**：

- 无服务器架构，自动扩缩容
- 支持毫秒级查询延迟
- 内置高可用性和灾备机制

#### Qdrant

Qdrant 是开源的向量相似度搜索引擎，支持自托管和云端部署。

**特点**：

- 支持元数据过滤
- 提供 gRPC 和 RESTful API
- 支持混合搜索（稀疏 + 密集向量）

### 本地向量数据库

对于开发和测试场景，Mem0 支持使用本地向量数据库：

| 后端 | 适用场景 | 特点 |
|------|---------|------|
| FAISS | 小规模数据 | 高性能、内存密集 |
| Chroma | 原型开发 | 简单易用、Python 原生 |
| SQLite (向量扩展) | 轻量级应用 | 零依赖、嵌入式 |

资料来源：[cli/python/README.md]()

## 配置管理

### 通过 Dashboard 配置

Mem0 Dashboard 提供了图形化的配置界面，可以配置 LLM 模型和嵌入模型：

```typescript
// 配置卡片组件结构
interface ConfigCard {
  provider: Select;  // 提供商选择
  model: Input;      // 模型名称输入
  apiKey: Input;     // API 密钥（受保护）
}
```

配置路径：`Dashboard > Configuration > Embedding Model`

### 通过 CLI 配置

Mem0 CLI 提供了命令行配置管理功能：

```bash
# 查看当前配置
mem0 config show

# 获取特定配置项
mem0 config get api_key

# 设置配置值
mem0 config set user_id alice
```

资料来源：[cli/node/README.md]()
资料来源：[cli/python/README.md]()

## 使用流程

### 添加记忆到向量存储

```mermaid
sequenceDiagram
    participant U as 用户
    participant M as Mem0
    participant E as 嵌入模型
    participant V as 向量数据库
    
    U->>M: 添加记忆
    M->>E: 发送文本
    E-->>M: 返回向量嵌入
    M->>V: 存储向量 + 元数据
    V-->>M: 确认存储
    M-->>U: 返回记忆 ID
```

### 搜索记忆

```mermaid
sequenceDiagram
    participant U as 用户
    participant M as Mem0
    participant E as 嵌入模型
    participant V as 向量数据库
    
    U->>M: 语义搜索查询
    M->>E: 查询文本
    E-->>M: 返回查询向量
    M->>V: 相似度搜索
    V-->>M: 返回相关记忆
    M-->>U: 返回结果列表
```

## 实验与评估

Mem0 提供了完整的评估框架，支持对不同向量数据库配置进行性能对比：

```bash
# Mem0 实验
make run-mem0-add         # 使用 Mem0 添加记忆
make run-mem0-search      # 使用 Mem0 搜索记忆

# Mem0+ 实验（带图搜索）
make run-mem0-plus-add    # Mem0+ 添加
make run-mem0-plus-search # Mem0+ 搜索

# RAG 对比实验
make run-rag              # 标准 RAG（块大小 500）
make run-full-context     # 全上下文 RAG
```

### 实验参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--technique_type` | 记忆技术类型 | mem0 |
| `--method` | 操作方法 | add |
| `--chunk_size` | 处理块大小 | 1000 |
| `--top_k` | 返回结果数量 | - |

资料来源：[evaluation/README.md:30-50]()

## 扩展新的向量数据库

Mem0 的向量存储层设计为可扩展的，要添加新的向量数据库后端，需要：

1. **实现基类接口**：继承 `BaseVectorStore` 抽象类
2. **实现核心方法**：
   - `add_vectors()` - 添加向量
   - `search()` - 相似度搜索
   - `delete()` - 删除向量
3. **配置支持**：在配置系统中注册新的存储类型

## 注意事项

- 嵌入模型的选择直接影响检索质量，建议在生产环境使用经过验证的模型（如 OpenAI text-embedding-3-small）
- 云端向量数据库（如 Pinecone）需要配置相应的 API 密钥
- 本地向量数据库适合开发和测试，生产环境建议使用托管服务
- Mem0 支持扩展其他 Python 包来增加新的提供商支持

资料来源：[server/dashboard/src/app/(root)/dashboard/configuration/page.tsx]()

## 相关资源

- [向量数据库概述](../vectordbs/overview.mdx)
- [Pinecone 配置指南](../vectordbs/dbs/pinecone.mdx)
- [Mem0 官方文档](https://docs.mem0.ai)

---

<a id='page-embeddings'></a>

## 嵌入模型配置

### 相关页面

相关主题：[LLM模型集成](#page-llm-integrations), [向量数据库支持](#page-vector-stores)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mem0/embeddings/openai.py](https://github.com/mem0ai/mem0/blob/main/mem0/embeddings/openai.py)
- [mem0/embeddings/huggingface.py](https://github.com/mem0ai/mem0/blob/main/mem0/embeddings/huggingface.py)
- [mem0/embeddings/base.py](https://github.com/mem0ai/mem0/blob/main/mem0/embeddings/base.py)
- [docs/components/embedders/overview.mdx](https://github.com/mem0ai/mem0/blob/main/docs/components/embedders/overview.mdx)
- [docs/components/embedders/models/openai.mdx](https://github.com/mem0ai/mem0/blob/main/docs/components/embedders/models/openai.mdx)
</details>

# 嵌入模型配置

## 概述

嵌入模型（Embedding Model）是 Mem0 记忆系统的核心组件之一，负责将文本内容转换为高维向量表示，以便进行语义搜索和相似度匹配。Mem0 支持多种嵌入模型提供商，包括 OpenAI、Hugging Face、Ollama 等。

嵌入模型的主要作用包括：
- 将用户消息、记忆内容转换为向量表示
- 支持语义相似度搜索
- 驱动记忆检索的准确性
- 提供可插拔的嵌入提供商架构

资料来源：[evaluation/README.md](https://github.com/mem0ai/mem0/blob/main/evaluation/README.md)

## 架构设计

Mem0 采用模块化的嵌入模型架构，核心组件如下：

```mermaid
graph TD
    A[用户消息] --> B[嵌入模型接口]
    B --> C{提供商选择}
    C -->|OpenAI| D[OpenAI 嵌入]
    C -->|HuggingFace| E[HuggingFace 嵌入]
    C -->|Ollama| F[Ollama 嵌入]
    C -->|其他| G[自定义提供者]
    D --> H[向量存储]
    E --> H
    F --> H
    G --> H
```

### 基类设计

所有嵌入模型都继承自 `BaseEmbedder` 基类，定义统一的接口规范：

```mermaid
classDiagram
    class BaseEmbedder {
        <<abstract>>
        +embed(text: str) List[float]
        +embed_batch(texts: List[str]) List[List[float]]
        +get_vector_dimension() int
    }
    
    class OpenAIEmbedder {
        +embed(text: str) List[float]
        +embed_batch(texts: List[str]) List[List[float]]
    }
    
    class HuggingFaceEmbedder {
        +embed(text: str) List[float]
        +embed_batch(texts: List[str]) List[List[float]]
    }
    
    BaseEmbedder <|-- OpenAIEmbedder
    BaseEmbedder <|-- HuggingFaceEmbedder
```

资料来源：[mem0/embeddings/base.py](https://github.com/mem0ai/mem0/blob/main/mem0/embeddings/base.py)

## 支持的嵌入模型提供商

### OpenAI

OpenAI 提供高性能的嵌入模型，适合生产环境使用。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model` | string | `text-embedding-3-small` | 嵌入模型名称 |
| `api_key` | string | 环境变量 | OpenAI API 密钥 |
| `base_url` | string | `https://api.openai.com/v1` | API 基础 URL |

常用模型：
- `text-embedding-3-small`：性价比最高，适合大多数场景
- `text-embedding-3-large`：精度更高，维度更大
- `text-embedding-ada-002`：经典模型，兼容性最好

资料来源：[docs/components/embedders/models/openai.mdx](https://github.com/mem0ai/mem0/blob/main/docs/components/embedders/models/openai.mdx)

### Hugging Face

Hugging Face 提供开源嵌入模型，支持本地部署。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model` | string | 必需 | 模型名称或路径 |
| `api_key` | string | 环境变量 | Hugging Face API 密钥 |
| `device` | string | `cpu` | 运行设备 |

资料来源：[mem0/embeddings/huggingface.py](https://github.com/mem0ai/mem0/blob/main/mem0/embeddings/huggingface.py)

### Ollama

Ollama 支持本地运行的 LLM 和嵌入模型，适合隐私敏感场景。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model` | string | `nomic-embed-text` | Ollama 模型名称 |
| `base_url` | string | `http://localhost:11434` | Ollama 服务地址 |

资料来源：[openmemory/README.md](https://github.com/mem0ai/mem0/blob/main/openmemory/README.md)

## 配置方法

### 环境变量配置

Mem0 支持通过环境变量配置嵌入模型：

```bash
# OpenAI 配置
EMBEDDER_PROVIDER=openai
EMBEDDER_MODEL=text-embedding-3-small
EMBEDDER_API_KEY=sk-...

# Ollama 配置（本地部署）
EMBEDDER_PROVIDER=ollama
EMBEDDER_MODEL=nomic-embed-text
OLLAMA_BASE_URL=http://localhost:11434
```

### 代码配置

在 Python 代码中配置嵌入模型：

```python
from mem0 import Memory

config = {
    "embedder": {
        "provider": "openai",
        "config": {
            "model": "text-embedding-3-small",
            "api_key": "sk-..."
        }
    }
}

memory = Memory.from_config(config)
```

### TypeScript 配置

TypeScript 版本的 Mem0 同样支持嵌入模型配置：

```typescript
import { Memory } from "mem0-ts";

const memory = new Memory({
    embedder: {
        provider: "openai",
        config: {
            apiKey: process.env.OPENAI_API_KEY,
            model: "text-embedding-3-small"
        }
    }
});
```

资料来源：[mem0-ts/src/oss/README.md](https://github.com/mem0ai/mem0/blob/main/mem0-ts/src/oss/README.md)

## 仪表盘配置

Mem0 Web 仪表盘提供了可视化的嵌入模型配置界面。

### 配置界面路径

`/dashboard/configuration` 页面允许用户配置嵌入模型设置。

### 配置项

| 配置项 | 类型 | 说明 |
|--------|------|------|
| Provider | 下拉选择 | 嵌入模型提供商 |
| Model | 文本输入 | 模型名称，如 `text-embedding-3-small` |

```tsx
<div className="space-y-1">
    <Label className="text-xs">Model</Label>
    <Input
        placeholder="text-embedding-3-small"
        value={embedderModel}
        onChange={(e) => setEmbedderModel(e.target.value)}
        disabled={!isAdmin}
    />
</div>
```

资料来源：[server/dashboard/src/app/(root)/dashboard/configuration/page.tsx](https://github.com/mem0ai/mem0/blob/main/server/dashboard/src/app/(root)/dashboard/configuration/page.tsx)

## 配置优先级

Mem0 按照以下优先级确定嵌入模型配置：

```mermaid
graph LR
    A[代码配置] --> B[最高优先级]
    C[环境变量] --> D[次优先级]
    E[默认配置] --> F[最低优先级]
```

1. **代码配置**：通过 `Memory.from_config()` 或构造函数直接传入
2. **环境变量**：通过 `EMBEDDER_*` 系列环境变量设置
3. **默认配置**：使用库内置的默认模型和参数

## 批量嵌入

嵌入模型支持批量处理多个文本，提高处理效率：

```python
from mem0.embeddings.openai import OpenAIEmbedder

embedder = OpenAIEmbedder()

# 单条嵌入
vector = embedder.embed("用户的第一条消息")

# 批量嵌入
texts = ["消息1", "消息2", "消息3"]
vectors = embedder.embed_batch(texts)
```

批量嵌入的工作流程：

```mermaid
sequenceDiagram
    participant 用户
    participant Embedder
    participant API
    
    用户->>Embedder: embed_batch([文本列表])
    Embedder->>Embedder: 分批处理
    loop 每批最多50条
        Embedder->>API: 批量请求
        API-->>Embedder: 向量列表
    end
    Embedder-->>用户: 完整向量列表
```

## 扩展自定义嵌入模型

可以通过实现 `BaseEmbedder` 接口添加新的嵌入模型提供商：

```python
from mem0.embeddings.base import BaseEmbedder

class CustomEmbedder(BaseEmbedder):
    def __init__(self, config: dict):
        self.model = config.get("model")
        self.api_key = config.get("api_key")
    
    def embed(self, text: str) -> List[float]:
        # 实现嵌入逻辑
        pass
    
    def embed_batch(self, texts: List[str]) -> List[List[float]]:
        # 实现批量嵌入逻辑
        pass
    
    def get_vector_dimension(self) -> int:
        return self.dimension
```

注册自定义嵌入器：

```python
Memory.register_embedder("custom", CustomEmbedder)
```

## 最佳实践

### 生产环境建议

| 场景 | 推荐配置 |
|------|----------|
| 通用应用 | OpenAI `text-embedding-3-small` |
| 高精度需求 | OpenAI `text-embedding-3-large` |
| 隐私敏感 | Ollama + `nomic-embed-text` |
| 开源项目 | Hugging Face Sentence Transformers |

### 性能优化

1. **选择合适的模型维度**：低维度模型（如 384 维）速度快，高维度模型（如 1536 维）精度高
2. **使用批量 API**：减少 API 调用次数
3. **启用缓存**：对于重复的查询启用向量缓存
4. **本地部署**：Ollama 适合对延迟要求高的场景

### 安全建议

- API 密钥应存储在环境变量或密钥管理服务中
- 避免在代码中硬编码密钥
- 定期轮换 API 密钥

## 常见问题

### Q: 如何切换不同的嵌入模型？

可以通过修改配置文件或环境变量来切换嵌入模型：

```python
# 切换到 HuggingFace
config = {
    "embedder": {
        "provider": "huggingface",
        "config": {
            "model": "sentence-transformers/all-MiniLM-L6-v2"
        }
    }
}
memory = Memory.from_config(config)
```

### Q: 支持哪些向量维度？

| 模型 | 向量维度 |
|------|----------|
| `text-embedding-3-small` | 1536 |
| `text-embedding-3-large` | 3072 |
| `text-embedding-ada-002` | 1536 |
| `nomic-embed-text` | 768 |
| `all-MiniLM-L6-v2` | 384 |

### Q: 如何处理嵌入模型供应商故障？

建议实现 fallback 机制：

```python
try:
    memory = Memory.from_config(primary_config)
except EmbedderUnavailableError:
    memory = Memory.from_config(fallback_config)

---

<a id='page-agent-integrations'></a>

## 智能体框架集成

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/mem0/SKILL.md](https://github.com/mem0ai/mem0/blob/main/skills/mem0/SKILL.md)
- [mem0-plugin/skills/mem0/SKILL.md](https://github.com/mem0ai/mem0/blob/main/mem0-plugin/skills/mem0/SKILL.md)
- [vercel-ai-sdk/src/mem0-provider.ts](https://github.com/mem0ai/mem0/blob/main/vercel-ai-sdk/src/mem0-provider.ts)
- [docs/integrations/langgraph.mdx](https://github.com/mem0ai/mem0/blob/main/docs/integrations/langgraph.mdx)
- [docs/integrations/crewai.mdx](https://github.com/mem0ai/mem0/blob/main/docs/integrations/crewai.mdx)
- [docs/integrations/llama-index.mdx](https://github.com/mem0ai/mem0/blob/main/docs/integrations/llama-index.mdx)
</details>

# 智能体框架集成

## 概述

mem0 提供了与多种主流智能体框架的深度集成能力，使 AI 智能体能够具备持久记忆和上下文理解功能。通过这些集成，开发者可以在 LangGraph、CrewAI、LlamaIndex 等框架中无缝使用 mem0 的记忆层，实现跨对话的长期信息保持和个性化交互。

mem0 的智能体框架集成主要解决以下问题：
- **记忆持久化**：在不同对话轮次间保持用户偏好和历史信息
- **上下文增强**：为智能体提供相关历史记忆作为上下文补充
- **多智能体协作**：支持复杂多智能体系统中的记忆共享与隔离

## 集成架构

mem0 与智能体框架的集成采用统一的适配层架构，不同框架通过各自的集成方式与 mem0 的核心记忆功能交互。

```mermaid
graph TB
    subgraph 智能体框架层
        LG[LangGraph 智能体]
        CA[CrewAI 智能体]
        LI[LlamaIndex 智能体]
        VA[Vercel AI SDK]
    end
    
    subgraph mem0 集成适配层
        LG_INTEGRATION[LangGraph 集成]
        CA_INTEGRATION[CrewAI 集成]
        LI_INTEGRATION[LlamaIndex 集成]
        MEM0_PROVIDER[Mem0 Provider]
    end
    
    subgraph mem0 核心层
        MEM0[mem0 记忆管理]
        GRAPH[向量图谱]
        STORAGE[持久化存储]
    end
    
    LG --> LG_INTEGRATION
    CA --> CA_INTEGRATION
    LI --> LI_INTEGRATION
    VA --> MEM0_PROVIDER
    
    LG_INTEGRATION --> MEM0
    CA_INTEGRATION --> MEM0
    LI_INTEGRATION --> MEM0
    MEM0_PROVIDER --> MEM0
    
    MEM0 --> GRAPH
    MEM0 --> STORAGE
```

## LangGraph 集成

### 功能描述

LangGraph 是基于 LangChain 构建的图状工作流框架，mem0 提供了专门的 `MemorySaver` 检查点机制和工具函数，用于在 LangGraph 状态机中持久化记忆。资料来源：[docs/integrations/langgraph.mdx:1-50]()

### 核心组件

| 组件名称 | 类型 | 功能说明 |
|---------|------|----------|
| MemorySaver | 检查点Saver | 将 mem0 记忆作为 LangGraph 状态检查点持久化 |
| add_memory | 工具函数 | 向 mem0 添加新的记忆条目 |
| search_memories | 工具函数 | 搜索相关历史记忆 |
| get_memory_context | 工具函数 | 获取格式化的记忆上下文 |

### 使用示例

```python
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver
from mem0 import Memory

# 初始化 mem0 记忆实例
memory = Memory()

# 创建 LangGraph 工作流
workflow = StateGraph(state)

# 定义记忆添加工具
@tool
def add_memory_tool(user_id: str, agent_id: str, memory_content: str):
    """将智能体生成的内容添加到记忆"""
    memory.add(
        messages=[{"role": "user", "content": memory_content}],
        user_id=user_id,
        agent_id=agent_id
    )
    return "记忆已保存"

# 定义记忆搜索工具
@tool  
def search_memory_tool(user_id: str, query: str):
    """搜索相关记忆"""
    results = memory.search(
        query=query,
        user_id=user_id,
        limit=5
    )
    return results
```

资料来源：[docs/integrations/langgraph.mdx:50-100]()

## CrewAI 集成

### 功能描述

CrewAI 是一个多智能体协作框架，mem0 提供了 CrewAI 工具集成，使智能体能够在执行任务时查询和更新记忆。资料来源：[docs/integrations/crewai.mdx:1-50]()

### 集成方式

mem0 作为 CrewAI 的工具提供者，智能体可以通过调用工具来访问记忆功能：

```python
from crewai import Agent, Task, Crew
from mem0 import Memory

memory = Memory()

# 创建记忆搜索工具
search_memory = Tool(
    name="SearchMemory",
    func=lambda user_id, query: memory.search(
        query=query,
        user_id=user_id
    ),
    description="搜索用户历史记忆"
)

# 创建记忆添加工具
add_memory = Tool(
    name="AddMemory", 
    func=lambda user_id, content: memory.add(
        messages=[{"role": "user", "content": content}],
        user_id=user_id
    ),
    description="添加新记忆"
)

# 创建智能体
researcher = Agent(
    role="研究员",
    goal="收集相关信息",
    backstory="专业的研究助手",
    tools=[search_memory, add_memory]
)
```

### 多智能体记忆共享

在 CrewAI 的多智能体场景中，mem0 支持不同粒度的记忆共享：

| 记忆范围 | 配置参数 | 说明 |
|---------|---------|------|
| 用户级记忆 | `user_id` | 所有智能体共享同一用户的记忆 |
| 智能体级记忆 | `agent_id` | 仅特定智能体可见的记忆 |
| 团队级记忆 | `collection_name` | 多智能体协作共享的记忆集合 |

资料来源：[docs/integrations/crewai.mdx:50-120]()

## LlamaIndex 集成

### 功能描述

LlamaIndex 是强大的数据索引和检索框架，mem0 与 LlamaIndex 的集成允许将记忆作为索引数据源，供查询引擎使用。资料来源：[docs/integrations/llama-index.mdx:1-50]()

### 集成架构

```mermaid
graph LR
    subgraph 数据输入
        USER[用户交互]
        AGENT[智能体执行]
    end
    
    subgraph mem0 处理
        MEM[记忆存储]
        VDB[向量数据库]
    end
    
    subgraph LlamaIndex
        INDEX[索引构建]
        QUERY[查询引擎]
        RET[检索器]
    end
    
    USER --> MEM
    AGENT --> MEM
    MEM --> VDB
    VDB --> INDEX
    INDEX --> RET
    RET --> QUERY
```

### 使用方式

mem0 的记忆可以作为 LlamaIndex 的文档源进行索引：

```python
from llama_index.core import VectorStoreIndex
from llama_index.core.retrievers import VectorIndexRetriever
from mem0 import Memory

memory = Memory()

# 从 mem0 获取记忆作为文档
def get_memory_as_documents(user_id: str):
    """将用户记忆转换为 LlamaIndex 文档"""
    memories = memory.get_all(user_id=user_id)
    documents = [doc.text for doc in memories]
    return documents

# 创建索引
documents = get_memory_as_documents("user_123")
index = VectorStoreIndex.from_documents(documents)

# 创建检索器
retriever = VectorIndexRetriever(
    index=index,
    similarity_top_k=5
)
```

资料来源：[docs/integrations/llama-index.mdx:50-100]()

## Vercel AI SDK Provider 集成

### 功能描述

mem0 提供了 Vercel AI SDK 的 Provider 实现，允许在 Next.js 和其他支持 Vercel AI SDK 的应用中快速集成记忆功能。资料来源：[vercel-ai-sdk/src/mem0-provider.ts:1-100]()

### Provider 配置

```typescript
import { createMem0 } from '@mem0/vercel-ai-provider'

const mem0 = createMem0({
  apiKey: process.env.MEM0_API_KEY,
  userId: 'user_123',
  agentId: 'agent_001',
  // 可选配置
  limit: 10,           // 返回记忆数量限制
  renderMarkdown: true // 是否渲染 Markdown 格式
})
```

### Provider 参数说明

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|------|-------|------|
| apiKey | string | 是 | - | mem0 API 密钥 |
| userId | string | 是 | - | 用户唯一标识 |
| agentId | string | 否 | - | 智能体标识 |
| limit | number | 否 | 10 | 单次查询返回的记忆数量 |
| renderMarkdown | boolean | 否 | false | 返回格式是否渲染 Markdown |
| categories | string[] | 否 | - | 记忆分类筛选 |
| seasonal | boolean | 否 | false | 是否启用季节性记忆 |

资料来源：[vercel-ai-sdk/src/mem0-provider.ts:100-150]()

### 与 AI SDK 的集成

```typescript
import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'
import { createMem0 } from '@mem0/vercel-ai-provider'

const mem0 = createMem0({
  apiKey: process.env.MEM0_API_KEY,
  userId: 'user_123'
})

const result = await generateText({
  model: openai('gpt-4'),
  messages: [
    {
      role: 'user',
      content: '我之前喜欢的书有哪些？'
    }
  ],
  system: `你是一个助手，可以使用 mem0 工具来访问用户记忆。
  
  当前用户ID: user_123`,
  tools: mem0.tools()
})
```

## Skill 机制

### Skill 定义

mem0 通过 Skill 定义来标准化智能体与记忆系统的交互方式。资料来源：[skills/mem0/SKILL.md:1-80]()

### Skill 文件结构

```yaml
name: mem0
description: mem0 记忆系统 - 为 AI 智能体提供持久记忆能力
version: 1.0.0

capabilities:
  - id: add_memory
    name: 添加记忆
    description: 将交互内容保存到记忆系统
    parameters:
      - name: content
        type: string
        required: true
      - name: user_id
        type: string  
        required: true
  
  - id: search_memory
    name: 搜索记忆
    description: 根据查询词检索相关记忆
    parameters:
      - name: query
        type: string
        required: true
      - name: user_id
        type: string
        required: true

  - id: update_memory
    name: 更新记忆
    description: 修改已存在的记忆内容
    parameters:
      - name: memory_id
        type: string
        required: true
      - name: content
        type: string
        required: true

  - id: delete_memory
    name: 删除记忆
    description: 从记忆中移除指定条目
    parameters:
      - name: memory_id
        type: string
        required: true
```

### 插件版本 Skill

mem0-plugin 中的 Skill 定义提供了更丰富的配置选项，支持自定义向量存储和检索策略。资料来源：[mem0-plugin/skills/mem0/SKILL.md:1-100]()

| 配置项 | 说明 |
|-------|------|
| vector_store | 指定使用的向量存储后端 |
| embedding_model | 嵌入模型选择 |
| retrieval_strategy | 检索策略（相似度/混合/重排序） |
| memory_types | 记忆类型（事实/偏好/会话） |

## 最佳实践

### 智能体记忆管理策略

在设计智能体系统时，建议遵循以下记忆管理策略：

```mermaid
graph TD
    START[用户请求] --> CHECK{记忆是否相关?}
    CHECK -->|是| GET[获取相关记忆]
    CHECK -->|否| PROCESS[直接处理]
    GET --> MERGE[合并上下文]
    PROCESS --> RESPOND[生成响应]
    MERGE --> RESPOND
    RESPOND --> EVAL{需要更新记忆?}
    EVAL -->|是| ADD[添加新记忆]
    EVAL -->|否| END[返回结果]
    ADD --> END
```

### 记忆分层策略

| 层级 | 内容类型 | 生命周期 | 使用场景 |
|-----|---------|---------|---------|
| 工作记忆 | 当前对话上下文 | 会话内 | 问题回答、任务执行 |
| 短期记忆 | 用户近期偏好 | 1-7天 | 个性化服务 |
| 长期记忆 | 重要事实、历史 | 长期 | 深度个性化 |

### 性能优化建议

1. **限制检索结果数量**：使用 `limit` 参数控制返回的记忆数量，避免上下文溢出
2. **分类存储**：使用不同的 `agent_id` 或 `collection_name` 隔离不同用途的记忆
3. **异步处理**：对于非关键记忆更新，使用异步方式避免阻塞主流程
4. **缓存策略**：对频繁查询的记忆结果实施本地缓存

## 常见问题

**Q: 多个智能体如何共享记忆？**

A: 使用相同的 `user_id` 和 `collection_name` 即可实现跨智能体的记忆共享。

**Q: 如何处理记忆冲突？**

A: mem0 支持记忆的优先级设置和版本管理，冲突时优先保留更新时间更近的记录。

**Q: 是否支持记忆的导入导出？**

A: 是的，mem0 提供了 `export` 和 `import` 方法用于数据的批量迁移。

资料来源：[skills/mem0/SKILL.md:80-120]()

## 相关资源

- [LangGraph 集成文档](https://github.com/mem0ai/mem0/blob/main/docs/integrations/langgraph.mdx)
- [CrewAI 集成文档](https://github.com/mem0ai/mem0/blob/main/docs/integrations/crewai.mdx)
- [LlamaIndex 集成文档](https://github.com/mem0ai/mem0/blob/main/docs/integrations/llama-index.mdx)
- [Vercel AI SDK Provider](https://github.com/mem0ai/mem0/blob/main/vercel-ai-sdk/src/mem0-provider.ts)

---

---

## Doramagic 踩坑日志

项目：mem0ai/mem0

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：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.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:656099147 | https://github.com/mem0ai/mem0 | last_activity_observed missing

## 3. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:656099147 | https://github.com/mem0ai/mem0 | no_demo; severity=medium

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:656099147 | https://github.com/mem0ai/mem0 | no_demo; severity=medium

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

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:656099147 | https://github.com/mem0ai/mem0 | issue_or_pr_quality=unknown

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

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:656099147 | https://github.com/mem0ai/mem0 | release_recency=unknown

<!-- canonical_name: mem0ai/mem0; human_manual_source: deepwiki_human_wiki -->