## 项目概述

MemOS 是一个面向大语言模型（LLM）与 AI 智能体的记忆操作系统，旨在为智能体提供持久化、可演进的长时记忆能力。它统一了记忆的存储、检索与管理，支持多模态记忆（文本、图像、工具轨迹、用户画像）、多知识库（MemCube）管理、异步记忆调度（MemScheduler）以及基于自然语言反馈的记忆修正。MemOS 宣称在多个基准测试上表现优异，并实现了显著的 token 节省（35.24%）。项目采用 Apache-2.0 许可证，主要开发语言为 TypeScript（仓库元数据），但核心服务与文档示例以 Python 为主。

## 核心功能

- **统一记忆 API**：提供单一的 API 用于添加、检索、编辑和删除记忆，记忆以图结构组织，可检查、可编辑，而非黑盒嵌入存储。
- **多模态记忆**：原生支持文本、图像、工具调用轨迹和用户画像，在同一记忆系统中统一检索与推理。
- **多 Cube 知识库管理**：将多个知识库作为可组合的记忆立方体（MemCube）管理，支持隔离、受控共享和动态组合，适用于多用户、多项目和多智能体场景。
- **异步记忆调度（MemScheduler）**：通过异步方式执行记忆操作，具备毫秒级延迟，保障高并发下的生产稳定性。
- **记忆反馈与修正**：支持通过自然语言反馈对已有记忆进行修正、补充或替换，实现记忆的持续优化。
- **混合检索**：结合向量相似性检索与图遍历算法，实现稳健且上下文感知的混合搜索。
- **技能复用与自我进化**：支持跨任务技能复用，记忆系统可自我演进（L1 痕迹、L2 策略、L3 世界模型、结晶技能）。
- **多智能体协作**：支持多智能体间的记忆共享或隔离，促进协作。

## 适用与不适用场景

**适用场景：**
- AI 助手：需要一致、上下文丰富的多轮对话。
- 客户支持：需要回忆过往工单和用户历史。
- 个性化智能体：需要适应个体偏好。
- 多智能体协作：需要共享或隔离记忆。
- 知识管理：需要结构化、可追溯的知识库。

**不适用场景：**
- 对记忆延迟要求极高的实时系统（异步模式可能引入延迟）。
- 完全离线且无法连接任何 LLM API 的环境（记忆提取依赖 LLM）。
- 需要强实时一致性的场景（异步处理可能导致短暂不一致）。
- 对数据隐私要求极高且不愿使用云服务的场景（需自托管，但自托管仍需外部 LLM/嵌入服务）。

## 技术架构与依赖

MemOS 采用模块化架构，核心组件包括：
- **MOS（Memory Operating System）**：编排层，管理多用户、多会话记忆工作流。
- **MemCube**：模块化记忆容器，支持多 Cube 组合视图。
- **MemReader**：从对话、文档、图像等提取结构化记忆。
- **MemScheduler**：异步任务调度器。
- **MemFeedback**：记忆反馈与修正模块。

**主要依赖：**
- **图数据库**：Neo4j（社区版/企业版）、PolarDB（用于树形明文记忆）。
- **向量数据库**：Qdrant、Milvus（用于通用明文记忆和偏好记忆）。
- **LLM 后端**：OpenAI、Ollama、HuggingFace、百炼（DashScope）等。
- **嵌入模型**：如 text-embedding-v4、nomic-embed-text、bge-m3 等。
- **重排序器**：如 bge-reranker-base、cosine_local。
- **其他**：Redis（可选，用于调度队列）、Python 3.9+、Poetry、Docker。

## 安装与快速开始

MemOS 提供多种部署方式：

**1. 云 API（托管服务）**
- 在 [MemOS dashboard](https://memos-dashboard.openmem.net/cn/quickstart/?source=landing) 注册并获取 API Key（以 `mpg-` 开头）。
- 使用 REST API 添加和搜索记忆。

**2. 自托管（Docker 推荐）**
```bash
git clone https://github.com/MemTensor/MemOS.git
cd MemOS
cp docker/.env.example .env  # 填写 API 密钥等配置
cd docker
docker compose up  # 启动 MemOS API + Neo4j + Qdrant
```
API 服务运行在 `http://localhost:8000`。

**3. 从源码安装**
```bash
git clone https://github.com/MemTensor/MemOS.git
cd MemOS
pip install -e .
pip install --no-cache-dir -r ./docker/requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
export PYTHONPATH=/path/to/MemOS/src
uvicorn memos.api.server_api:app --host 0.0.0.0 --port 8000 --workers 1
```

**4. 通过 pip 安装**
```bash
pip install -U "MemoryOS[all]"
```

**5. 插件安装（OpenClaw/Hermes）**
- 云插件：`openclaw plugins install @memtensor/memos-cloud-openclaw-plugin@latest`
- 本地插件：运行安装脚本（macOS/Linux 或 Windows PowerShell）。

## 典型使用方法

**添加记忆（REST API）**
```bash
curl -X POST 'http://localhost:8000/product/add' \
-H 'Content-Type: application/json' \
-d '{
  "user_id": "alice",
  "writable_cube_ids": ["alice_cube"],
  "messages": [{"role": "user", "content": "I like strawberry"}],
  "async_mode": "sync"
}'
```

**搜索记忆**
```bash
curl -X POST 'http://localhost:8000/product/search' \
-H 'Content-Type: application/json' \
-d '{
  "query": "What do I like?",
  "user_id": "alice",
  "readable_cube_ids": ["alice_cube"]
}'
```

**Python 示例（使用 SDK）**
```python
from memos.api.routers.server_router import add_memories, search_memories
from memos.api.product_models import APIADDRequest, APISearchRequest

add_req = APIADDRequest(
    user_id="alice",
    writable_cube_ids=["alice_cube"],
    messages=[{"role": "user", "content": "I like strawberry"}],
    async_mode="sync"
)
add_memories(add_req)

search_req = APISearchRequest(
    user_id="alice",
    readable_cube_ids=["alice_cube"],
    query="What do I like?"
)
results = search_memories(search_req)
print(results)
```

## 配置与部署要点

- **环境变量配置**：在项目根目录创建 `.env` 文件，配置 LLM API 密钥、嵌入模型、数据库连接等。参考 `docker/.env.example`。
- **数据库依赖**：
  - 树形明文记忆（`tree_text`）需要图数据库（Neo4j 或 PolarDB）。
  - 通用明文记忆（`general_text`）需要向量数据库（Qdrant）。
  - 偏好记忆（`pref`）需要 Milvus。
  - 简单记忆（`naive_text`）无需数据库。
- **向量维度一致性**：更换嵌入模型时，需确保向量维度与 Qdrant Collection 一致，否则会报错。可修改 `collection_name` 或删除旧 Collection。
- **异步调度**：可通过 `DEFAULT_USE_REDIS_QUEUE` 配置是否使用 Redis 队列。
- **性能调优**：可调整 `top_k`、`thread_pool_max_workers`、`consume_interval_seconds` 等参数。
- **HTTPS 部署**：若需在 Coze 等平台集成 MCP，需配置 HTTPS 反向代理（如 Nginx）。
- **网络问题**：在中国大陆可配置 HF 镜像（`HF_ENDPOINT=https://hf-mirror.com`）和 Poetry 镜像源。

## 限制、风险与许可证

**限制：**
- 参数化记忆（Parametric Memory）标注为“即将推出”，尚未完全可用。
- 基于 API 的 LLM 无法使用激活记忆和参数记忆。
- 自托管需要外部 LLM 和嵌入服务，无法完全离线运行。
- 部分功能（如 LongMemEval 评估）在云服务上可能因不支持问题日期而得分有差异。

**风险：**
- 数据隐私：云服务将数据存储在 MemOS Cloud，自托管需自行保障数据安全。
- 依赖风险：依赖 Neo4j、Qdrant 等第三方服务，需确保其稳定运行。
- 记忆准确性：自动提取的记忆可能存在错误，需通过反馈机制修正。

**许可证：**
- 项目采用 Apache-2.0 许可证。

## 官方链接

- GitHub 仓库: [https://github.com/MemTensor/MemOS](https://github.com/MemTensor/MemOS)
- 官方文档: [https://memos-docs.openmem.net/](https://memos-docs.openmem.net/)
- 项目主页: [https://memos.openmem.net/](https://memos.openmem.net/)
- ArXiv 论文: [https://arxiv.org/abs/2507.03724](https://arxiv.org/abs/2507.03724)
- Discord: [https://discord.gg/Txbx3gebZR](https://discord.gg/Txbx3gebZR)
- X (Twitter): [https://x.com/MemOS_dev](https://x.com/MemOS_dev)
- 评估框架: [https://github.com/MemTensor/OmniMemEval](https://github.com/MemTensor/OmniMemEval)

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、文档目录（docs/cn/）、贡献指南、安装指南、示例代码、评估文档等。
- 分析时间：2026-08-01（基于仓库最新 Release v2.0.27 的发布时间 2026-07-31）。