[{"data":1,"prerenderedAt":535},["ShallowReactive",2],{"/open_source/modules/mos/overview":3,"surround-/open_source/modules/mos/overview":520},{"id":4,"title":5,"avatar":6,"banner":6,"body":7,"category":6,"desc":513,"description":13,"extension":514,"links":6,"meta":515,"navigation":6,"path":516,"seo":517,"stem":518,"__hash__":519},"docs/en/open_source/modules/mos/overview.md","MemOS API Development Guide (Components & Handlers Architecture)",null,{"type":8,"value":9,"toc":493},"minimark",[10,14,19,24,32,35,40,75,79,82,85,89,228,232,236,239,270,274,277,308,312,315,341,345,348,378,382,385,404,408,411,430,434,437,455,459,462],[11,12,13],"p",{},"This architecture separates \"system construction\" (Components) from \"business logic execution\" (Handlers), making the system easier to extend, test, and maintain.",[15,16,18],"h2",{"id":17},"_1-core-concepts","1. Core Concepts",[20,21,23],"h3",{"id":22},"_11-components","1.1 Components",[11,25,26,27,31],{},"Components are the \"brain\" and \"infrastructure\" of MemOS. They are initialized when the server starts (via ",[28,29,30],"code",{},"init_server()",") and reused throughout the system lifecycle.",[11,33,34],{},"Core components include:",[36,37,39],"h4",{"id":38},"core-memory-components","Core Memory Components",[41,42,43,51,57,63,69],"ol",{},[44,45,46,50],"li",{},[47,48,49],"strong",{},"MemCube",": A memory container used to isolate memories across different users / different cubes, and to manage multiple memory modules in a unified way.",[44,52,53,56],{},[47,54,55],{},"MemReader",": A memory processor that parses user inputs (chat, documents, images) into memory items that the system can write.",[44,58,59,62],{},[47,60,61],{},"MemScheduler",": A scheduler that turns time-consuming tasks such as memory writes, index building, and memory organization into asynchronous and concurrent jobs.",[44,64,65,68],{},[47,66,67],{},"MemChat",": A conversation controller responsible for the dialogue loop of \"retrieve memory -> generate response -> write new memory\".",[44,70,71,74],{},[47,72,73],{},"MemFeedback",": Correction and feedback that converts users' natural-language feedback into safe updates to the memory store.",[20,76,78],{"id":77},"_12-handlers","1.2 Handlers",[11,80,81],{},"Handlers are the \"hands\" of MemOS. They encapsulate concrete business logic and complete tasks by calling Components.",[11,83,84],{},"Main Handlers include:",[15,86,88],{"id":87},"core-handlers-overview","Core Handlers Overview",[90,91,92,109],"table",{},[93,94,95],"thead",{},[96,97,98,103,106],"tr",{},[99,100,102],"th",{"align":101},"left","Handler",[99,104,105],{"align":101},"Purpose",[99,107,108],{"align":101},"Key Methods",[110,111,112,128,143,162,177,195,213],"tbody",{},[96,113,114,120,123],{},[115,116,117],"td",{"align":101},[47,118,119],{},"AddHandler",[115,121,122],{"align":101},"Add memories (chat / documents / text)",[115,124,125],{"align":101},[28,126,127],{},"handle_add_memories",[96,129,130,135,138],{},[115,131,132],{"align":101},[47,133,134],{},"SearchHandler",[115,136,137],{"align":101},"Search memories (semantic retrieval)",[115,139,140],{"align":101},[28,141,142],{},"handle_search_memories",[96,144,145,150,153],{},[115,146,147],{"align":101},[47,148,149],{},"ChatHandler",[115,151,152],{"align":101},"Chat (with memory augmentation)",[115,154,155,158,159],{"align":101},[28,156,157],{},"handle_chat_complete",", ",[28,160,161],{},"handle_chat_stream",[96,163,164,169,172],{},[115,165,166],{"align":101},[47,167,168],{},"FeedbackHandler",[115,170,171],{"align":101},"Feedback (correct memories / human-in-the-loop)",[115,173,174],{"align":101},[28,175,176],{},"handle_feedback_memories",[96,178,179,184,187],{},[115,180,181],{"align":101},[47,182,183],{},"MemoryHandler",[115,185,186],{"align":101},"Manage (get details / delete)",[115,188,189,158,192],{"align":101},[28,190,191],{},"handle_get_memory",[28,193,194],{},"handle_delete_memories",[96,196,197,202,205],{},[115,198,199],{"align":101},[47,200,201],{},"SchedulerHandler",[115,203,204],{"align":101},"Scheduling (query async task status)",[115,206,207,158,210],{"align":101},[28,208,209],{},"handle_scheduler_status",[28,211,212],{},"handle_scheduler_wait",[96,214,215,220,223],{},[115,216,217],{"align":101},[47,218,219],{},"SuggestionHandler",[115,221,222],{"align":101},"Suggestions (generate recommended questions)",[115,224,225],{"align":101},[28,226,227],{},"handle_get_suggestion_queries",[15,229,231],{"id":230},"_2-api-details","2. API Details",[20,233,235],{"id":234},"_21-initialization","2.1 Initialization",[11,237,238],{},"Initialization is the foundation of system startup. All Handlers rely on a unified component registry and dependency-injection mechanism.",[240,241,242,249],"ul",{},[44,243,244,245,248],{},"Component loading (",[28,246,247],{},"init_server","): The system first initializes all core components, including the LLM, storage layers (vector DB, graph DB), the scheduler, and various Memory Cubes.",[44,250,251,252,255,256,258,259,158,262,265,266,269],{},"Dependency injection (",[28,253,254],{},"HandlerDependencies","): To keep the code decoupled and testable, all components are wrapped into a ",[28,257,254],{}," object. Handlers receive this dependency container during instantiation, so they can access resources such as ",[28,260,261],{},"naive_mem_cube",[28,263,264],{},"mem_reader",", or ",[28,267,268],{},"feedback_server"," on demand, without hard-coding initialization logic inside the Handler.",[20,271,273],{"id":272},"_22-add-memories-addhandler","2.2 Add Memories (AddHandler)",[11,275,276],{},"AddHandler is the primary entry point that converts external information into system memories. It supports chats, file uploads, and plain text. Besides writing, it also takes on part of the feedback routing responsibility.",[240,278,279],{},[44,280,281,282],{},"Core capabilities:\n",[240,283,284,287,294,301],{},[44,285,286],{},"Multimodal support: Processes user message lists (Messages) and converts them into internal memory objects.",[44,288,289,290,293],{},"Sync and async modes: Controlled via ",[28,291,292],{},"async_mode",". In production, \"async\" is recommended: tasks are pushed to a background queue and executed by the Scheduler, and the API returns immediately with a task_id. For debugging, use \"sync\" to block until completion.",[44,295,296,297,300],{},"Automatic feedback routing: If the request sets ",[28,298,299],{},"is_feedback=True",", the Handler automatically takes the last user message as feedback content and routes it to the feedback logic, instead of adding it as a normal new memory.",[44,302,303,304,307],{},"Multi-target writes: You can specify multiple target cubes via ",[28,305,306],{},"writable_cube_ids",". If multiple targets are provided, the Handler builds a CompositeCubeView and fans out write tasks in parallel. If only one target is provided, it uses a lightweight SingleCubeView.",[20,309,311],{"id":310},"_23-search-memories-searchhandler","2.3 Search Memories (SearchHandler)",[11,313,314],{},"SearchHandler provides semantic memory retrieval and is a key component for RAG (Retrieval-Augmented Generation).",[240,316,317],{},[44,318,281,319],{},[240,320,321,324,331,334],{},[44,322,323],{},"Semantic retrieval: Uses embedding-based similarity to recall relevant memories by meaning rather than simple keyword matching.",[44,325,326,327,330],{},"Flexible search scope: With ",[28,328,329],{},"readable_cube_ids",", callers can precisely control the search context (for example, search only within a specific user's memory, or search across public memories).",[44,332,333],{},"Multi-strategy support: The underlying implementation supports multiple search strategies (such as fast, fine, or mixture) to balance latency and recall quality.",[44,335,336,337,340],{},"Deep search integration: Can integrate ",[28,338,339],{},"deepsearch_agent"," to handle more complex retrieval requests that require multi-step reasoning.",[20,342,344],{"id":343},"_24-chat-chathandler","2.4 Chat (ChatHandler)",[11,346,347],{},"ChatHandler is the orchestrator of upper-layer business logic. It does not store data directly; instead, it composes other Handlers to complete end-to-end chat tasks.",[240,349,350],{},[44,351,281,352],{},[240,353,354,357,368,371],{},[44,355,356],{},"Orchestration: Automatically chains the full process of \"retrieve -> generate -> store\". It calls SearchHandler for context, calls the LLM to generate a response, then calls AddHandler to save the newly produced dialogue as memory.",[44,358,359,360,363,364,367],{},"Context management: Assembles ",[28,361,362],{},"history"," (past conversation) and ",[28,365,366],{},"query"," (current question) to ensure the AI understands the complete context.",[44,369,370],{},"Streaming and non-streaming: Supports standard responses (APIChatCompleteRequest) and streaming responses (Stream) to match different frontend interaction needs.",[44,372,373,374,377],{},"Notification integration: Optionally integrates ",[28,375,376],{},"online_bot"," (for example, a DingTalk bot) to push notifications after responses are generated.",[20,379,381],{"id":380},"_25-feedback-and-correction-feedbackhandler","2.5 Feedback and Correction (FeedbackHandler)",[11,383,384],{},"FeedbackHandler is the system's \"self-correction\" mechanism. It allows users to intervene in the AI's behavior to improve future retrieval and generation.",[240,386,387],{},[44,388,281,389],{},[240,390,391,394,397],{},[44,392,393],{},"Memory correction: When users point out mistakes (for example, \"the meeting location is Shanghai, not Beijing\"), the Handler updates or marks the old memory nodes based on the feedback content.",[44,395,396],{},"Positive and negative feedback: Supports upvote and downvote signals to adjust the weight or credibility of specific memories.",[44,398,399,400,403],{},"Precise targeting: In addition to conversation-history-based feedback, it supports ",[28,401,402],{},"retrieved_memory_ids"," so you can correct specific retrieved items, improving feedback effectiveness.",[20,405,407],{"id":406},"_26-memory-management-memoryhandler","2.6 Memory Management (MemoryHandler)",[11,409,410],{},"MemoryHandler provides low-level CRUD capabilities for memory data. It is mainly used for admin backends or cleanup tools.",[240,412,413],{},[44,414,281,415],{},[240,416,417,424],{},[44,418,419,420,423],{},"Fine-grained management: Unlike AddHandler's business-level writes, this Handler can fetch a single memory by ",[28,421,422],{},"memory_id"," or perform physical deletion.",[44,425,426,427,429],{},"Direct dependency access: Some operations need to interact with the underlying ",[28,428,261],{}," component directly, bypassing business wrappers to provide the most efficient data operations.",[20,431,433],{"id":432},"_27-scheduler-status-schedulerhandler","2.7 Scheduler Status (SchedulerHandler)",[11,435,436],{},"SchedulerHandler monitors the lifecycle of all async tasks in the system and is an important part of system observability.",[240,438,439],{},[44,440,281,441],{},[240,442,443,446,449],{},[44,444,445],{},"Status tracking: With a Redis backend, it tracks real-time task states (Queued, Running, Completed, Failed).",[44,447,448],{},"Result fetching: For async tasks, clients can poll progress via this API and retrieve the final result or error when the task completes.",[44,450,451,452,454],{},"Debugging support: Provides utilities such as ",[28,453,212],{}," to force async flows into synchronous waits in test scripts, which is useful for integration tests.",[20,456,458],{"id":457},"_28-suggested-next-questions-suggestionhandler","2.8 Suggested Next Questions (SuggestionHandler)",[11,460,461],{},"SuggestionHandler improves interaction by predicting users' potential intent and generating \"recommended questions\" (Next Query Suggestion).",[240,463,464],{},[44,465,281,466],{},[240,467,468,486],{},[44,469,470,471],{},"Dual-mode generation:\n",[240,472,473,480],{},[44,474,475,476,479],{},"Conversation-based: If ",[28,477,478],{},"message"," (recent conversation records) is provided, the system analyzes the context and generates 3 follow-up questions closely related to the current topic.",[44,481,482,483,485],{},"Memory-based: If there is no conversation context, the system uses ",[28,484,261],{}," to quickly retrieve the user's \"recent memories\" and generates questions related to the user's recent life/work status.",[44,487,488,489,492],{},"Multi-language support: Built-in Chinese and English prompt templates switch the language style automatically based on the ",[28,490,491],{},"language"," parameter.",{"title":494,"searchDepth":495,"depth":495,"links":496},"",2,[497,502,503],{"id":17,"depth":495,"text":18,"children":498},[499,501],{"id":22,"depth":500,"text":23},3,{"id":77,"depth":500,"text":78},{"id":87,"depth":495,"text":88},{"id":230,"depth":495,"text":231,"children":504},[505,506,507,508,509,510,511,512],{"id":234,"depth":500,"text":235},{"id":272,"depth":500,"text":273},{"id":310,"depth":500,"text":311},{"id":343,"depth":500,"text":344},{"id":380,"depth":500,"text":381},{"id":406,"depth":500,"text":407},{"id":432,"depth":500,"text":433},{"id":457,"depth":500,"text":458},"MemOS v2.0 adopts a more modular and decoupled architecture. The legacy MOS class is deprecated; Components + Handlers is now recommended for development.","md",{},"/en/open_source/modules/mos/overview",{"title":5,"description":13},"en/open_source/modules/mos/overview","m5Rp8slTKclUSSg7cqIOpyqjLAROhKX_ouCues3uq9g",[521,529],{"title":522,"path":523,"stem":524,"icon":525,"framework":6,"module":6,"class":526,"target":-1,"active":527,"defaultOpen":527,"children":-1,"description":528},"MemOS Examples","/open_source/getting_started/examples","open_source/getting_started/examples","i-ri-code-line",[],false,"Congratulations - you've mastered the Quick Start and built your first working memory! Now it's time to see how far you can take MemOS by combining different memory types and features. Use these curated examples to inspire your own agents, chatbots, or knowledge systems.",{"title":49,"path":530,"stem":531,"icon":532,"framework":6,"module":6,"class":533,"target":-1,"active":527,"defaultOpen":527,"children":-1,"description":534},"/open_source/modules/mem_cube","open_source/modules/mem_cube","i-ri-checkbox-multiple-blank-line",[],"MemCube is the core organizational unit in MemOS, designed to encapsulate and manage all types of memory for a user or agent. It provides a unified interface for loading, saving, and operating on multiple memory modules, making it easy to build, share, and deploy memory-augmented applications.",1770372088085]