API 开发指南 (Component & Handler 架构)

这种架构将“系统的元件”（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 概览

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 个相关的推荐问题。
    • 基于用户画像的建议 : 当没有对话上下文时，系统从用户的近期记忆中推断其兴趣和状态，生成与用户最近生活或工作相关的推荐问题。这适合在对话开始或话题转换时使用。
  • 多语言支持 : 推荐问题自动适配用户语言设置，支持中英文等多种语言，提升不同用户的体验。