---
title: API 开发指南 (Component & Handler 架构)
desc: MemOS v2.0 采用了更加模块化和解耦的架构。旧版的 MOS 类已被弃用，现在推荐使用 Components (组件) + Handlers (处理器) 的模式进行开发。
---


这种架构将“系统的元件”（Components）与“业务逻辑的执行”（Handlers）分离开来，使得系统更易于扩展、测试和维护。

## 1. 核心概念

### 1.1 Components (核心组件)

Components 是 MemOS 的各个“器官”，它们在服务器启动时被初始化（通过 `init_server()`），并在整个生命周期中复用。

核心组件包括：

#### 核心记忆组件

1. **MemCube**: 记忆容器, 用于隔离不同用户/不同应用场景的记忆, 并统一管理多种记忆模块.
2. **MemReader**: 记忆加工器, 把用户输入的各类素材（聊天, 文档, 图片）解析为系统可写入的记忆片段.
3. **MemScheduler**: 后台调度器, 负责管理后台任务队列，将记忆的存储、索引、组织等耗时操作异步处理，支持多任务的并发执行.
4. **MemChat**: 对话控制器, 负责在对话过程中自动进行“记忆检索 -> 上下文管理 -> LLM 调度 -> 记忆更新”的对话闭环.
5. **MemFeedback**: 记忆纠错器，自动理解用户的自然语言反馈，精准定位冲突记忆并执行原子级修正（纠错/补充/替换）.

### 1.2 Handlers (业务处理器)

Handlers 是 MemOS 的“大脑”，它们封装了具体的业务逻辑（如添加、搜索、对话），通过调用和协调 Components （器官）的各项能力来完成具体的用户任务。

#### 核心 Handler 概览

| Handler | 作用 | 核心方法 |
| :--- | :--- | :--- |
| **AddHandler** | 添加记忆 (对话/文档/文本) | `handle_add_memories` |
| **SearchHandler** | 搜索记忆 (语义检索) | `handle_search_memories` |
| **ChatHandler** | 对话 (带记忆增强) | `handle_chat_complete`, `handle_chat_stream` |
| **FeedbackHandler** | 反馈 (修正记忆/人工干预) | `handle_feedback_memories` |
| **MemoryHandler** | 管理 (获取详情/删除) | `handle_get_memory`, `handle_delete_memories` |
| **SchedulerHandler** | 调度 (查询异步任务状态) | `handle_scheduler_status`, `handle_scheduler_wait` |
| **SuggestionHandler** | 建议 (生成推荐问题) | `handle_get_suggestion_queries` |

## 2. API 详解

### 2.1 初始化 (Initialization)
初始化是系统启动的基石。所有 Handler 的运行都依赖于统一的组件注册与依赖注入机制。

- 组件加载 ( init_server ) : 系统启动时会初始化所有核心组件，包括 LLM（大语言模型）、存储层（向量数据库、图数据库）、调度器（Scheduler）以及各类 Memory Cube。
- 依赖注入 ( HandlerDependencies ) : 为了保证代码的解耦与可测试性，所有组件被统一封装到一个依赖容器（`HandlerDependencies`）中。当 Handler 启动时，只需接收这个容器，就能获取所需的 `naive_mem_cube`、`mem_reader`、`feedback_server` 等资源，而无需各自重复创建这些组件。

### 2.2 添加记忆 (AddHandler)
AddHandler 是大脑的"记忆接纳指令"，负责将外部信息转化并写入系统记忆。它不仅负责接纳和转化各类信息，还能自动识别反馈并路由到专门的反馈处理流程。

- 核心功能 :
  - 多模态支持 : 能够处理用户对话、文档、图片等多种输入形式，统一转化为系统内部的记忆对象。
  - 同步与异步模式 : 通过 `async_mode` 参数控制处理方式。**同步模式**（"sync"）：立即处理，调用者阻塞等待结果，适合调试；**异步模式**（"async"）：任务推入后台队列由 MemScheduler 并发处理，API 立即返回任务 ID，适合生产环境提升响应速度。
  - 自动反馈路由 : 如果请求中标记了 `is_feedback=True`，Handler 会自动提取对话中的最后一条用户消息作为反馈内容，将其转发到 MemFeedback 处理，而不是作为普通新记忆添加。
  - 多目标写入 : 支持向多个 MemCube 同时写入记忆。当指定多个目标 Cube 时，系统会并行处理所有写入任务；当仅有一个目标时，则使用轻量级的处理方式。

### 2.3 搜索记忆 (SearchHandler)
SearchHandler 是大脑的"记忆检索指令"，提供基于语义的智能记忆查询能力，是实现 RAG（检索增强生成）的关键组件。

- 核心功能 :
  - 语义检索 : 利用向量嵌入（Embedding）技术，根据查询语句的语义相似度召回相关记忆，相比简单的关键词匹配，能更准确地理解用户意图。
  - 灵活的搜索范围 : 支持指定检索的目标数据范围。例如，可以仅在特定用户的记忆库中搜索，也可以跨多个用户搜索共享的公开记忆，满足不同的隐私和业务需求。
  - 多种检索模式 : 根据应用场景在速度和准确率之间灵活选择。**快速模式**适合实时性要求高的场景，**精细模式**适合追求高记忆精准度的场景，**混合模式**兼顾两者。
  - 多步推理检索 : 对于复杂问题，支持引入深度推理能力，通过多轮理解和检索逐步逼近最相关的记忆。

### 2.4 对话 (ChatHandler)
ChatHandler 是大脑的"对话协调指令"，负责将用户的对话需求转化为完整的业务流程。它不直接存储数据，而是通过协调其他 Handler 来完成端到端的对话任务。

- 核心功能 :
  - 流程编排 : 自动执行"记忆检索 → LLM 生成 → 记忆保存"的完整对话闭环。用户每次提问都能基于历史记忆获得更智能的回复，同时每一次对话都被沉淀为新的记忆，实现对话即学习。
  - 上下文管理 : 负责处理 history （历史对话）与 query （当前问题）的拼接，确保 LLM 理解完整的对话语境，避免信息丢失。
  - 多种交互模式 : 支持标准请求-响应模式（ APIChatCompleteRequest ）和流式响应（Stream）模式，标准模式适合简单问题，流式模式适合长文本回复，满足不同的前端交互需求。
  - 消息推送（可选） : 支持在生成回复后自动将结果推送到第三方平台（如钉钉），实现多渠道集成。

### 2.5 反馈与修正 (FeedbackHandler)
FeedbackHandler 是大脑的"反馈纠正指令"，负责理解用户对 AI 表现的自然语言反馈，自动精准定位并修正相关的记忆内容。

- 核心功能 :
  - 记忆修正 : 当用户指出 AI 的错误（如"会议地点不是北京是上海"）时，Handler 会自动更新或标记相关的旧记忆。系统采用版本管理而非直接删除，保持修改历史的可追溯性。
  - 正负反馈 : 支持用户通过点赞或点踩的方式标记特定记忆的质量。系统据此调整该记忆的权重和可信度，使后续检索更加准确。
  - 精准定位 : 支持两种反馈方式。一种是基于对话历史自动定位冲突信息，另一种是用户直接指定具体的记忆来修正，提高反馈的有效性和准确度。

### 2.6 记忆管理 (MemoryHandler)
MemoryHandler 是大脑的"记忆管理指令"，提供了对记忆数据的底层 CRUD（增删改查）能力，主要用于系统管理后台或数据清理等运维场景。

- 核心功能 :
  - 精细化管理 : 不同于 AddHandler 的业务级写入，此 Handler 允许通过记忆 ID 直接获取单条记忆的详细信息或执行物理删除。这种直接操作方式绕过了业务逻辑的包装，主要用于调试、审计或系统清理。
  - 底层直通 : 某些管理操作需要直接与底层的记忆器官（naive_mem_cube）交互，以提供最高效和最低延迟的数据操作能力，满足系统运维的需求。

### 2.7 任务调度状态 (SchedulerHandler)
SchedulerHandler 是大脑的"任务监控指令"，负责追踪系统中所有异步任务的实时执行状态，让用户能够了解后台任务的进度和结果。

- 核心功能 :
  - 状态追踪 : 配合 Redis 后端，追踪任务的实时状态（Queued 排队中, Running 执行中, Completed 已完成, Failed 已失败）。
  - 结果获取 : 提供任务结果查询接口。当异步任务完成后，用户可以通过此接口获取最终的执行结果或错误信息，从而了解操作是否成功以及失败的原因。
  - 同步等待（调试工具） : 在测试和集成测试时，提供将异步任务强制转为同步等待的工具，使开发者能够像调试同步代码一样调试异步流程，提高开发效率。

### 2.8 猜你想问 (SuggestionHandler)
SuggestionHandler 是大脑的"建议生成指令"，通过预测用户的潜在需求，主动推荐相关问题，帮助用户探索系统能力和发现感兴趣的话题。

- 核心功能 :
  - 双模式生成 :
    - 基于对话的建议 : 当用户提供了最近的对话记录时，系统分析对话上下文，推断用户可能感兴趣的后续话题，生成 3 个相关的推荐问题。
    - 基于用户画像的建议 : 当没有对话上下文时，系统从用户的近期记忆中推断其兴趣和状态，生成与用户最近生活或工作相关的推荐问题。这适合在对话开始或话题转换时使用。
  - 多语言支持 : 推荐问题自动适配用户语言设置，支持中英文等多种语言，提升不同用户的体验。
