[{"data":1,"prerenderedAt":495},["ShallowReactive",2],{"\u002Fcn\u002Fopen_source\u002Fmodules\u002Fmos\u002Foverview":3,"surround-\u002Fcn\u002Fopen_source\u002Fmodules\u002Fmos\u002Foverview":479},{"id":4,"title":5,"avatar":6,"banner":6,"body":7,"category":6,"desc":472,"description":13,"extension":473,"links":6,"meta":474,"navigation":6,"path":475,"seo":476,"stem":477,"__hash__":478},"docs\u002Fcn\u002Fopen_source\u002Fmodules\u002Fmos\u002Foverview.md","API 开发指南 (Component & Handler 架构)",null,{"type":8,"value":9,"toc":453},"minimark",[10,14,19,24,32,35,39,74,78,81,85,224,228,232,235,259,263,266,301,305,308,338,342,345,363,367,370,385,389,392,404,408,411,426,430,433],[11,12,13],"p",{},"这种架构将“系统的元件”（Components）与“业务逻辑的执行”（Handlers）分离开来，使得系统更易于扩展、测试和维护。",[15,16,18],"h2",{"id":17},"_1-核心概念","1. 核心概念",[20,21,23],"h3",{"id":22},"_11-components-核心组件","1.1 Components (核心组件)",[11,25,26,27,31],{},"Components 是 MemOS 的各个“器官”，它们在服务器启动时被初始化（通过 ",[28,29,30],"code",{},"init_server()","），并在整个生命周期中复用。",[11,33,34],{},"核心组件包括：",[36,37,38],"h4",{"id":38},"核心记忆组件",[40,41,42,50,56,62,68],"ol",{},[43,44,45,49],"li",{},[46,47,48],"strong",{},"MemCube",": 记忆容器, 用于隔离不同用户\u002F不同应用场景的记忆, 并统一管理多种记忆模块.",[43,51,52,55],{},[46,53,54],{},"MemReader",": 记忆加工器, 把用户输入的各类素材（聊天, 文档, 图片）解析为系统可写入的记忆片段.",[43,57,58,61],{},[46,59,60],{},"MemScheduler",": 后台调度器, 负责管理后台任务队列，将记忆的存储、索引、组织等耗时操作异步处理，支持多任务的并发执行.",[43,63,64,67],{},[46,65,66],{},"MemChat",": 对话控制器, 负责在对话过程中自动进行“记忆检索 -> 上下文管理 -> LLM 调度 -> 记忆更新”的对话闭环.",[43,69,70,73],{},[46,71,72],{},"MemFeedback",": 记忆纠错器，自动理解用户的自然语言反馈，精准定位冲突记忆并执行原子级修正（纠错\u002F补充\u002F替换）.",[20,75,77],{"id":76},"_12-handlers-业务处理器","1.2 Handlers (业务处理器)",[11,79,80],{},"Handlers 是 MemOS 的“大脑”，它们封装了具体的业务逻辑（如添加、搜索、对话），通过调用和协调 Components （器官）的各项能力来完成具体的用户任务。",[36,82,84],{"id":83},"核心-handler-概览","核心 Handler 概览",[86,87,88,105],"table",{},[89,90,91],"thead",{},[92,93,94,99,102],"tr",{},[95,96,98],"th",{"align":97},"left","Handler",[95,100,101],{"align":97},"作用",[95,103,104],{"align":97},"核心方法",[106,107,108,124,139,158,173,191,209],"tbody",{},[92,109,110,116,119],{},[111,112,113],"td",{"align":97},[46,114,115],{},"AddHandler",[111,117,118],{"align":97},"添加记忆 (对话\u002F文档\u002F文本)",[111,120,121],{"align":97},[28,122,123],{},"handle_add_memories",[92,125,126,131,134],{},[111,127,128],{"align":97},[46,129,130],{},"SearchHandler",[111,132,133],{"align":97},"搜索记忆 (语义检索)",[111,135,136],{"align":97},[28,137,138],{},"handle_search_memories",[92,140,141,146,149],{},[111,142,143],{"align":97},[46,144,145],{},"ChatHandler",[111,147,148],{"align":97},"对话 (带记忆增强)",[111,150,151,154,155],{"align":97},[28,152,153],{},"handle_chat_complete",", ",[28,156,157],{},"handle_chat_stream",[92,159,160,165,168],{},[111,161,162],{"align":97},[46,163,164],{},"FeedbackHandler",[111,166,167],{"align":97},"反馈 (修正记忆\u002F人工干预)",[111,169,170],{"align":97},[28,171,172],{},"handle_feedback_memories",[92,174,175,180,183],{},[111,176,177],{"align":97},[46,178,179],{},"MemoryHandler",[111,181,182],{"align":97},"管理 (获取详情\u002F删除)",[111,184,185,154,188],{"align":97},[28,186,187],{},"handle_get_memory",[28,189,190],{},"handle_delete_memories",[92,192,193,198,201],{},[111,194,195],{"align":97},[46,196,197],{},"SchedulerHandler",[111,199,200],{"align":97},"调度 (查询异步任务状态)",[111,202,203,154,206],{"align":97},[28,204,205],{},"handle_scheduler_status",[28,207,208],{},"handle_scheduler_wait",[92,210,211,216,219],{},[111,212,213],{"align":97},[46,214,215],{},"SuggestionHandler",[111,217,218],{"align":97},"建议 (生成推荐问题)",[111,220,221],{"align":97},[28,222,223],{},"handle_get_suggestion_queries",[15,225,227],{"id":226},"_2-api-详解","2. API 详解",[20,229,231],{"id":230},"_21-初始化-initialization","2.1 初始化 (Initialization)",[11,233,234],{},"初始化是系统启动的基石。所有 Handler 的运行都依赖于统一的组件注册与依赖注入机制。",[236,237,238,241],"ul",{},[43,239,240],{},"组件加载 ( init_server ) : 系统启动时会初始化所有核心组件，包括 LLM（大语言模型）、存储层（向量数据库、图数据库）、调度器（Scheduler）以及各类 Memory Cube。",[43,242,243,244,247,248,251,252,251,255,258],{},"依赖注入 ( HandlerDependencies ) : 为了保证代码的解耦与可测试性，所有组件被统一封装到一个依赖容器（",[28,245,246],{},"HandlerDependencies","）中。当 Handler 启动时，只需接收这个容器，就能获取所需的 ",[28,249,250],{},"naive_mem_cube","、",[28,253,254],{},"mem_reader",[28,256,257],{},"feedback_server"," 等资源，而无需各自重复创建这些组件。",[20,260,262],{"id":261},"_22-添加记忆-addhandler","2.2 添加记忆 (AddHandler)",[11,264,265],{},"AddHandler 是大脑的\"记忆接纳指令\"，负责将外部信息转化并写入系统记忆。它不仅负责接纳和转化各类信息，还能自动识别反馈并路由到专门的反馈处理流程。",[236,267,268],{},[43,269,270,271],{},"核心功能 :\n",[236,272,273,276,291,298],{},[43,274,275],{},"多模态支持 : 能够处理用户对话、文档、图片等多种输入形式，统一转化为系统内部的记忆对象。",[43,277,278,279,282,283,286,287,290],{},"同步与异步模式 : 通过 ",[28,280,281],{},"async_mode"," 参数控制处理方式。",[46,284,285],{},"同步模式","（\"sync\"）：立即处理，调用者阻塞等待结果，适合调试；",[46,288,289],{},"异步模式","（\"async\"）：任务推入后台队列由 MemScheduler 并发处理，API 立即返回任务 ID，适合生产环境提升响应速度。",[43,292,293,294,297],{},"自动反馈路由 : 如果请求中标记了 ",[28,295,296],{},"is_feedback=True","，Handler 会自动提取对话中的最后一条用户消息作为反馈内容，将其转发到 MemFeedback 处理，而不是作为普通新记忆添加。",[43,299,300],{},"多目标写入 : 支持向多个 MemCube 同时写入记忆。当指定多个目标 Cube 时，系统会并行处理所有写入任务；当仅有一个目标时，则使用轻量级的处理方式。",[20,302,304],{"id":303},"_23-搜索记忆-searchhandler","2.3 搜索记忆 (SearchHandler)",[11,306,307],{},"SearchHandler 是大脑的\"记忆检索指令\"，提供基于语义的智能记忆查询能力，是实现 RAG（检索增强生成）的关键组件。",[236,309,310],{},[43,311,270,312],{},[236,313,314,317,320,335],{},[43,315,316],{},"语义检索 : 利用向量嵌入（Embedding）技术，根据查询语句的语义相似度召回相关记忆，相比简单的关键词匹配，能更准确地理解用户意图。",[43,318,319],{},"灵活的搜索范围 : 支持指定检索的目标数据范围。例如，可以仅在特定用户的记忆库中搜索，也可以跨多个用户搜索共享的公开记忆，满足不同的隐私和业务需求。",[43,321,322,323,326,327,330,331,334],{},"多种检索模式 : 根据应用场景在速度和准确率之间灵活选择。",[46,324,325],{},"快速模式","适合实时性要求高的场景，",[46,328,329],{},"精细模式","适合追求高记忆精准度的场景，",[46,332,333],{},"混合模式","兼顾两者。",[43,336,337],{},"多步推理检索 : 对于复杂问题，支持引入深度推理能力，通过多轮理解和检索逐步逼近最相关的记忆。",[20,339,341],{"id":340},"_24-对话-chathandler","2.4 对话 (ChatHandler)",[11,343,344],{},"ChatHandler 是大脑的\"对话协调指令\"，负责将用户的对话需求转化为完整的业务流程。它不直接存储数据，而是通过协调其他 Handler 来完成端到端的对话任务。",[236,346,347],{},[43,348,270,349],{},[236,350,351,354,357,360],{},[43,352,353],{},"流程编排 : 自动执行\"记忆检索 → LLM 生成 → 记忆保存\"的完整对话闭环。用户每次提问都能基于历史记忆获得更智能的回复，同时每一次对话都被沉淀为新的记忆，实现对话即学习。",[43,355,356],{},"上下文管理 : 负责处理 history （历史对话）与 query （当前问题）的拼接，确保 LLM 理解完整的对话语境，避免信息丢失。",[43,358,359],{},"多种交互模式 : 支持标准请求-响应模式（ APIChatCompleteRequest ）和流式响应（Stream）模式，标准模式适合简单问题，流式模式适合长文本回复，满足不同的前端交互需求。",[43,361,362],{},"消息推送（可选） : 支持在生成回复后自动将结果推送到第三方平台（如钉钉），实现多渠道集成。",[20,364,366],{"id":365},"_25-反馈与修正-feedbackhandler","2.5 反馈与修正 (FeedbackHandler)",[11,368,369],{},"FeedbackHandler 是大脑的\"反馈纠正指令\"，负责理解用户对 AI 表现的自然语言反馈，自动精准定位并修正相关的记忆内容。",[236,371,372],{},[43,373,270,374],{},[236,375,376,379,382],{},[43,377,378],{},"记忆修正 : 当用户指出 AI 的错误（如\"会议地点不是北京是上海\"）时，Handler 会自动更新或标记相关的旧记忆。系统采用版本管理而非直接删除，保持修改历史的可追溯性。",[43,380,381],{},"正负反馈 : 支持用户通过点赞或点踩的方式标记特定记忆的质量。系统据此调整该记忆的权重和可信度，使后续检索更加准确。",[43,383,384],{},"精准定位 : 支持两种反馈方式。一种是基于对话历史自动定位冲突信息，另一种是用户直接指定具体的记忆来修正，提高反馈的有效性和准确度。",[20,386,388],{"id":387},"_26-记忆管理-memoryhandler","2.6 记忆管理 (MemoryHandler)",[11,390,391],{},"MemoryHandler 是大脑的\"记忆管理指令\"，提供了对记忆数据的底层 CRUD（增删改查）能力，主要用于系统管理后台或数据清理等运维场景。",[236,393,394],{},[43,395,270,396],{},[236,397,398,401],{},[43,399,400],{},"精细化管理 : 不同于 AddHandler 的业务级写入，此 Handler 允许通过记忆 ID 直接获取单条记忆的详细信息或执行物理删除。这种直接操作方式绕过了业务逻辑的包装，主要用于调试、审计或系统清理。",[43,402,403],{},"底层直通 : 某些管理操作需要直接与底层的记忆器官（naive_mem_cube）交互，以提供最高效和最低延迟的数据操作能力，满足系统运维的需求。",[20,405,407],{"id":406},"_27-任务调度状态-schedulerhandler","2.7 任务调度状态 (SchedulerHandler)",[11,409,410],{},"SchedulerHandler 是大脑的\"任务监控指令\"，负责追踪系统中所有异步任务的实时执行状态，让用户能够了解后台任务的进度和结果。",[236,412,413],{},[43,414,270,415],{},[236,416,417,420,423],{},[43,418,419],{},"状态追踪 : 配合 Redis 后端，追踪任务的实时状态（Queued 排队中, Running 执行中, Completed 已完成, Failed 已失败）。",[43,421,422],{},"结果获取 : 提供任务结果查询接口。当异步任务完成后，用户可以通过此接口获取最终的执行结果或错误信息，从而了解操作是否成功以及失败的原因。",[43,424,425],{},"同步等待（调试工具） : 在测试和集成测试时，提供将异步任务强制转为同步等待的工具，使开发者能够像调试同步代码一样调试异步流程，提高开发效率。",[20,427,429],{"id":428},"_28-猜你想问-suggestionhandler","2.8 猜你想问 (SuggestionHandler)",[11,431,432],{},"SuggestionHandler 是大脑的\"建议生成指令\"，通过预测用户的潜在需求，主动推荐相关问题，帮助用户探索系统能力和发现感兴趣的话题。",[236,434,435],{},[43,436,270,437],{},[236,438,439,450],{},[43,440,441,442],{},"双模式生成 :\n",[236,443,444,447],{},[43,445,446],{},"基于对话的建议 : 当用户提供了最近的对话记录时，系统分析对话上下文，推断用户可能感兴趣的后续话题，生成 3 个相关的推荐问题。",[43,448,449],{},"基于用户画像的建议 : 当没有对话上下文时，系统从用户的近期记忆中推断其兴趣和状态，生成与用户最近生活或工作相关的推荐问题。这适合在对话开始或话题转换时使用。",[43,451,452],{},"多语言支持 : 推荐问题自动适配用户语言设置，支持中英文等多种语言，提升不同用户的体验。",{"title":454,"searchDepth":455,"depth":455,"links":456},"",2,[457,462],{"id":17,"depth":455,"text":18,"children":458},[459,461],{"id":22,"depth":460,"text":23},3,{"id":76,"depth":460,"text":77},{"id":226,"depth":455,"text":227,"children":463},[464,465,466,467,468,469,470,471],{"id":230,"depth":460,"text":231},{"id":261,"depth":460,"text":262},{"id":303,"depth":460,"text":304},{"id":340,"depth":460,"text":341},{"id":365,"depth":460,"text":366},{"id":387,"depth":460,"text":388},{"id":406,"depth":460,"text":407},{"id":428,"depth":460,"text":429},"MemOS v2.0 采用了更加模块化和解耦的架构。旧版的 MOS 类已被弃用，现在推荐使用 Components (组件) + Handlers (处理器) 的模式进行开发。","md",{},"\u002Fcn\u002Fopen_source\u002Fmodules\u002Fmos\u002Foverview",{"title":5,"description":13},"cn\u002Fopen_source\u002Fmodules\u002Fmos\u002Foverview","QKAgqiCjGiMR4VYuGUJszjcPTwWWte6WFQpbV9-urk8",[480,488],{"title":481,"path":482,"stem":483,"icon":484,"framework":6,"module":6,"class":485,"target":-1,"active":486,"defaultOpen":486,"children":-1,"description":487},"MemOS 示例","\u002Fcn\u002Fopen_source\u002Fgetting_started\u002Fexamples","open_source\u002Fgetting_started\u002Fexamples","i-ri-code-line",[],false,"恭喜你——你已经掌握了快速入门并构建了第一个可用的记忆！现在是时候通过结合不同的记忆类型和功能，看看 MemOS 可以实现多大的可能性。使用这些精选示例来激发你自己的智能体、聊天机器人或知识系统的灵感。",{"title":489,"path":490,"stem":491,"icon":492,"framework":6,"module":6,"class":493,"target":-1,"active":486,"defaultOpen":486,"children":-1,"description":494},"MemCube记忆立方","\u002Fcn\u002Fopen_source\u002Fmodules\u002Fmem_cube","open_source\u002Fmodules\u002Fmem_cube","i-ri-checkbox-multiple-blank-line",[],"MemCube 是你的“记忆收纳箱”，统一管理三种类型的记忆：明文记忆、激活记忆和参数化记忆。它提供简洁的接口，方便加载、保存和操作多个记忆模块，让开发者轻松构建、保存和共享记忆增强应用。",1774339750479]