MemoryOS 2.0.17__tar.gz → 2.0.20__tar.gz

{memoryos-2.0.17 → memoryos-2.0.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MemoryOS
-Version: 2.0.17
+Version: 2.0.20
 Summary: Intelligence Begins with Memory
 License: Apache-2.0
 License-File: LICENSE
@@ -134,6 +134,8 @@ Your lobsters and Hermes Agents now have **the best** memory system — choose *
 | 🧠 [**memos-local-plugin 2.0**](https://github.com/hijzy/MemOS/tree/main/apps/memos-local-plugin) | <ul><li>One local-first memory core for **Hermes Agent** and **OpenClaw**.</li><li>Self-evolving memory: L1 trace, L2 policy, L3 world model,<br>and crystallized Skills driven by feedback.</li></ul> | 🌐 [Website](https://memos-claw.openmem.net/) · 📖 [Docs](https://memos-docs.openmem.net/cn/openclaw/local_plugin) · 🐙 [GitHub](https://github.com/hijzy/MemOS/tree/main/apps/memos-local-plugin) · 📦 [NPM](https://www.npmjs.com/package/@memtensor/memos-local-plugin) |
 | ☁️ [**OpenClaw Cloud Plugin**](https://x.com/MemOS_dev/status/2019254160919769171?s=20) | <ul><li>[Reduces token usage by 72%.](https://x.com/MemOS_dev/status/2020854044583924111)</li><li>[Multi-agent memory sharing by `user_id`.](https://x.com/MemOS_dev/status/2020538135487062094)</li></ul> | 🖥️ [MemOS Dashboard](https://memos-dashboard.openmem.net/login/) · 📖 [Full Tutorial](https://memos-docs.openmem.net/openclaw/guide#_4-update-plugin) |
 
+> **🐳 Docker Deployment Note**: When running memos-local-plugin in Docker containers, you must specify the config location using `MEMOS_HOME` environment variable or `--home` CLI flag. See [Docker Configuration Guide](./apps/memos-local-plugin/README.md#docker-deployment) for details.
+
 </div>
 <br>
 
@@ -346,6 +348,126 @@ Your lobsters and Hermes Agents now have **the best** memory system — choose *
     
 <br>
 
+
+## FAQ
+
+### What is MemOS?
+
+MemOS is a **Memory Operating System** for LLMs and AI agents that unifies store/retrieve/manage for long-term memory. It enables context-aware and personalized interactions with knowledge base (KB), multi-modal memory, tool memory, and enterprise-grade optimizations built in.
+
+### What are the benchmark results?
+
+| Benchmark | MemOS Result | Improvement |
+|-----------|--------------|-------------|
+| LoCoMo | 75.80 | - |
+| LongMemEval | +40.43% vs baseline | - |
+| PrefEval-10 | +2568% | - |
+| PersonaMem | +40.75% | - |
+| **vs OpenAI Memory** | +43.70% Accuracy | - |
+| **Token Savings** | 35.24% | - |
+
+### How does MemOS compare to other memory solutions?
+
+| Feature | MemOS | mem0 | LangChain Memory | Letta |
+|---------|-------|------|------------------|-------|
+| Multi-Modal Memory | ✅ Text/Images/Tools | ❌ Text only | ❌ Text only | ❌ Text only |
+| Knowledge Base | ✅ Multi-Cube KB | ❌ No KB | ⚠️ RAG only | ❌ No KB |
+| Memory Feedback | ✅ Natural language | ❌ No | ❌ No | ❌ No |
+| Graph Memory | ✅ Inspectable/Editable | ❌ Black-box | ❌ Black-box | ❌ Limited |
+| Async Ingestion | ✅ MemScheduler | ❌ No | ❌ No | ❌ No |
+| Open Source | ✅ Apache 2.0 | ✅ MIT | ✅ Apache | ✅ MIT |
+| ArXiv Paper | ✅ 2507.03724 | ❌ No | ❌ No | ❌ No |
+
+### What are the key features?
+
+| Feature | Description |
+|---------|-------------|
+| **Unified Memory API** | Single API for add/retrieve/edit/delete, graph-structured, inspectable |
+| **Multi-Modal Memory** | Text, images, tool traces, personas retrieved together |
+| **Multi-Cube KB** | Composable memory cubes for users/projects/agents |
+| **Async Ingestion** | MemScheduler with millisecond latency |
+| **Memory Feedback** | Natural-language correction/supplement/replacement |
+| **Self-evolving Memory** | L1 traces, L2 policies, L3 world model, crystallized Skills |
+
+### What deployment options are available?
+
+| Option | Description |
+|--------|-------------|
+| **Cloud API** | Hosted service at memos.openmem.net |
+| **Self-Hosted** | Local/private deployment via Docker |
+| **Quick Mode** | Lightweight deployment |
+| **Full Mode** | Complete deployment |
+
+### How do I get started with Cloud API?
+
+1. Sign up at [MemOS dashboard](https://memos-dashboard.openmem.net/)
+2. Go to **API Keys** and copy your key
+3. Use the Cloud API for memory operations
+
+See [Cloud Getting Started](https://memos-docs.openmem.net/memos_cloud/quick_start/).
+
+### How do I self-host MemOS?
+
+```bash
+# Clone
+git clone https://github.com/MemTensor/MemOS.git
+cd MemOS
+
+# Install dependencies
+pip install -r ./docker/requirements.txt
+
+# Configure .env (OPENAI_API_KEY, etc.)
+cp docker/.env.example MemOS/.env
+
+# Start service
+# See docs for full setup
+```
+
+### What LLM providers are supported?
+
+| Provider | Setting |
+|----------|---------|
+| OpenAI | `MOS_CHAT_MODEL_PROVIDER=openai` |
+| Azure OpenAI | `MOS_CHAT_MODEL_PROVIDER=azure` |
+| Qwen (DashScope) | `MOS_CHAT_MODEL_PROVIDER=qwen` |
+| DeepSeek | `MOS_CHAT_MODEL_PROVIDER=deepseek` |
+| MiniMax | `MOS_CHAT_MODEL_PROVIDER=minimax` |
+| Ollama | `MOS_CHAT_MODEL_PROVIDER=ollama` |
+| HuggingFace | `MOS_CHAT_MODEL_PROVIDER=huggingface` |
+| vLLM | `MOS_CHAT_MODEL_PROVIDER=vllm` |
+
+### What plugins are available?
+
+| Plugin | Purpose |
+|--------|---------|
+| **memos-local-plugin 2.0** | Local-first memory for Hermes Agent & OpenClaw |
+| **OpenClaw Cloud Plugin** | Hosted memory service, 72% token reduction |
+| **OpenClaw Local Plugin** | 100% on-device SQLite memory |
+
+### What is the memory architecture?
+
+| Layer | Purpose |
+|-------|---------|
+| **L1 Traces** | Raw interaction history |
+| **L2 Policies** | Learned preferences/behaviors |
+| **L3 World Model** | User understanding |
+| **Crystallized Skills** | Reusable patterns |
+
+### What license does MemOS use?
+
+Apache 2.0 License (see [LICENSE](./LICENSE)).
+
+### Where can I get help?
+
+| Resource | Link |
+|----------|------|
+| Documentation | [memos-docs.openmem.net](https://memos-docs.openmem.net/home/overview/) |
+| ArXiv Paper | [2507.03724](https://arxiv.org/abs/2507.03724) |
+| Discord | [Join Server](https://discord.gg/Txbx3gebZR) |
+| X/Twitter | [@MemOS_dev](https://x.com/MemOS_dev) |
+| GitHub Issues | [Submit issues](https://github.com/MemTensor/MemOS/issues) |
+| Awesome-AI-Memory | [IAAR-Shanghai/Awesome-AI-Memory](https://github.com/IAAR-Shanghai/Awesome-AI-Memory) |
+
 ## 📚 Resources
 
 - **Awesome-AI-Memory**

{memoryos-2.0.17 → memoryos-2.0.20}/README.md

@@ -50,6 +50,8 @@ Your lobsters and Hermes Agents now have **the best** memory system — choose *
 | 🧠 [**memos-local-plugin 2.0**](https://github.com/hijzy/MemOS/tree/main/apps/memos-local-plugin) | <ul><li>One local-first memory core for **Hermes Agent** and **OpenClaw**.</li><li>Self-evolving memory: L1 trace, L2 policy, L3 world model,<br>and crystallized Skills driven by feedback.</li></ul> | 🌐 [Website](https://memos-claw.openmem.net/) · 📖 [Docs](https://memos-docs.openmem.net/cn/openclaw/local_plugin) · 🐙 [GitHub](https://github.com/hijzy/MemOS/tree/main/apps/memos-local-plugin) · 📦 [NPM](https://www.npmjs.com/package/@memtensor/memos-local-plugin) |
 | ☁️ [**OpenClaw Cloud Plugin**](https://x.com/MemOS_dev/status/2019254160919769171?s=20) | <ul><li>[Reduces token usage by 72%.](https://x.com/MemOS_dev/status/2020854044583924111)</li><li>[Multi-agent memory sharing by `user_id`.](https://x.com/MemOS_dev/status/2020538135487062094)</li></ul> | 🖥️ [MemOS Dashboard](https://memos-dashboard.openmem.net/login/) · 📖 [Full Tutorial](https://memos-docs.openmem.net/openclaw/guide#_4-update-plugin) |
 
+> **🐳 Docker Deployment Note**: When running memos-local-plugin in Docker containers, you must specify the config location using `MEMOS_HOME` environment variable or `--home` CLI flag. See [Docker Configuration Guide](./apps/memos-local-plugin/README.md#docker-deployment) for details.
+
 </div>
 <br>
 
@@ -262,6 +264,126 @@ Your lobsters and Hermes Agents now have **the best** memory system — choose *
     
 <br>
 
+
+## FAQ
+
+### What is MemOS?
+
+MemOS is a **Memory Operating System** for LLMs and AI agents that unifies store/retrieve/manage for long-term memory. It enables context-aware and personalized interactions with knowledge base (KB), multi-modal memory, tool memory, and enterprise-grade optimizations built in.
+
+### What are the benchmark results?
+
+| Benchmark | MemOS Result | Improvement |
+|-----------|--------------|-------------|
+| LoCoMo | 75.80 | - |
+| LongMemEval | +40.43% vs baseline | - |
+| PrefEval-10 | +2568% | - |
+| PersonaMem | +40.75% | - |
+| **vs OpenAI Memory** | +43.70% Accuracy | - |
+| **Token Savings** | 35.24% | - |
+
+### How does MemOS compare to other memory solutions?
+
+| Feature | MemOS | mem0 | LangChain Memory | Letta |
+|---------|-------|------|------------------|-------|
+| Multi-Modal Memory | ✅ Text/Images/Tools | ❌ Text only | ❌ Text only | ❌ Text only |
+| Knowledge Base | ✅ Multi-Cube KB | ❌ No KB | ⚠️ RAG only | ❌ No KB |
+| Memory Feedback | ✅ Natural language | ❌ No | ❌ No | ❌ No |
+| Graph Memory | ✅ Inspectable/Editable | ❌ Black-box | ❌ Black-box | ❌ Limited |
+| Async Ingestion | ✅ MemScheduler | ❌ No | ❌ No | ❌ No |
+| Open Source | ✅ Apache 2.0 | ✅ MIT | ✅ Apache | ✅ MIT |
+| ArXiv Paper | ✅ 2507.03724 | ❌ No | ❌ No | ❌ No |
+
+### What are the key features?
+
+| Feature | Description |
+|---------|-------------|
+| **Unified Memory API** | Single API for add/retrieve/edit/delete, graph-structured, inspectable |
+| **Multi-Modal Memory** | Text, images, tool traces, personas retrieved together |
+| **Multi-Cube KB** | Composable memory cubes for users/projects/agents |
+| **Async Ingestion** | MemScheduler with millisecond latency |
+| **Memory Feedback** | Natural-language correction/supplement/replacement |
+| **Self-evolving Memory** | L1 traces, L2 policies, L3 world model, crystallized Skills |
+
+### What deployment options are available?
+
+| Option | Description |
+|--------|-------------|
+| **Cloud API** | Hosted service at memos.openmem.net |
+| **Self-Hosted** | Local/private deployment via Docker |
+| **Quick Mode** | Lightweight deployment |
+| **Full Mode** | Complete deployment |
+
+### How do I get started with Cloud API?
+
+1. Sign up at [MemOS dashboard](https://memos-dashboard.openmem.net/)
+2. Go to **API Keys** and copy your key
+3. Use the Cloud API for memory operations
+
+See [Cloud Getting Started](https://memos-docs.openmem.net/memos_cloud/quick_start/).
+
+### How do I self-host MemOS?
+
+```bash
+# Clone
+git clone https://github.com/MemTensor/MemOS.git
+cd MemOS
+
+# Install dependencies
+pip install -r ./docker/requirements.txt
+
+# Configure .env (OPENAI_API_KEY, etc.)
+cp docker/.env.example MemOS/.env
+
+# Start service
+# See docs for full setup
+```
+
+### What LLM providers are supported?
+
+| Provider | Setting |
+|----------|---------|
+| OpenAI | `MOS_CHAT_MODEL_PROVIDER=openai` |
+| Azure OpenAI | `MOS_CHAT_MODEL_PROVIDER=azure` |
+| Qwen (DashScope) | `MOS_CHAT_MODEL_PROVIDER=qwen` |
+| DeepSeek | `MOS_CHAT_MODEL_PROVIDER=deepseek` |
+| MiniMax | `MOS_CHAT_MODEL_PROVIDER=minimax` |
+| Ollama | `MOS_CHAT_MODEL_PROVIDER=ollama` |
+| HuggingFace | `MOS_CHAT_MODEL_PROVIDER=huggingface` |
+| vLLM | `MOS_CHAT_MODEL_PROVIDER=vllm` |
+
+### What plugins are available?
+
+| Plugin | Purpose |
+|--------|---------|
+| **memos-local-plugin 2.0** | Local-first memory for Hermes Agent & OpenClaw |
+| **OpenClaw Cloud Plugin** | Hosted memory service, 72% token reduction |
+| **OpenClaw Local Plugin** | 100% on-device SQLite memory |
+
+### What is the memory architecture?
+
+| Layer | Purpose |
+|-------|---------|
+| **L1 Traces** | Raw interaction history |
+| **L2 Policies** | Learned preferences/behaviors |
+| **L3 World Model** | User understanding |
+| **Crystallized Skills** | Reusable patterns |
+
+### What license does MemOS use?
+
+Apache 2.0 License (see [LICENSE](./LICENSE)).
+
+### Where can I get help?
+
+| Resource | Link |
+|----------|------|
+| Documentation | [memos-docs.openmem.net](https://memos-docs.openmem.net/home/overview/) |
+| ArXiv Paper | [2507.03724](https://arxiv.org/abs/2507.03724) |
+| Discord | [Join Server](https://discord.gg/Txbx3gebZR) |
+| X/Twitter | [@MemOS_dev](https://x.com/MemOS_dev) |
+| GitHub Issues | [Submit issues](https://github.com/MemTensor/MemOS/issues) |
+| Awesome-AI-Memory | [IAAR-Shanghai/Awesome-AI-Memory](https://github.com/IAAR-Shanghai/Awesome-AI-Memory) |
+
 ## 📚 Resources
 
 - **Awesome-AI-Memory**

{memoryos-2.0.17 → memoryos-2.0.20}/pyproject.toml

@@ -4,7 +4,7 @@
 ##############################################################################
 
 name = "MemoryOS"
-version = "2.0.17"
+version = "2.0.20"
 description = "Intelligence Begins with Memory"
 license = {text = "Apache-2.0"}
 readme = "README.md"

{memoryos-2.0.17 → memoryos-2.0.20}/src/memos/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.0.17"
+__version__ = "2.0.20"
 
 from memos.configs.mem_cube import GeneralMemCubeConfig
 from memos.configs.mem_os import MOSConfig

memoryos-2.0.20/src/memos/api/handlers/cube_handler.py

@@ -0,0 +1,128 @@
+"""
+Cube handler for memory cube management operations.
+
+This module handles cube creation and registration through the HTTP API.
+"""
+
+from fastapi import HTTPException
+
+from memos.api.handlers.base_handler import BaseHandler
+from memos.api.product_models import (
+    CreateCubeRequest,
+    CreateCubeResponse,
+    CreateCubeResponseData,
+    RegisterCubeRequest,
+    RegisterCubeResponse,
+    RegisterCubeResponseData,
+)
+from memos.log import get_logger
+from memos.mem_user.user_manager import UserManager
+
+
+logger = get_logger(__name__)
+
+
+class CubeHandler(BaseHandler):
+    """Handler for memory cube management operations."""
+
+    def __init__(self, *args, **kwargs):
+        """Initialize CubeHandler with dependencies."""
+        super().__init__(*args, **kwargs)
+        # Initialize UserManager for cube operations
+        # Use graph_db as the backend for user/cube management
+        self.user_manager = UserManager()
+
+    async def create_cube(self, request: CreateCubeRequest) -> CreateCubeResponse:
+        """Create a new memory cube for a user.
+
+        Args:
+            request: Cube creation request
+
+        Returns:
+            CreateCubeResponse with created cube details
+
+        Raises:
+            HTTPException: If cube creation fails
+        """
+        try:
+            # Validate owner exists
+            if not self.user_manager.validate_user(request.owner_id):
+                raise ValueError(f"Owner user '{request.owner_id}' does not exist or is inactive")
+
+            # Create cube via UserManager
+            created_cube_id = self.user_manager.create_cube(
+                cube_name=request.cube_name,
+                owner_id=request.owner_id,
+                cube_path=request.cube_path,
+                cube_id=request.cube_id,
+            )
+
+            logger.info(f"Created cube: {created_cube_id} for owner: {request.owner_id}")
+
+            return CreateCubeResponse(
+                code=200,
+                message="Cube created successfully",
+                data=CreateCubeResponseData(
+                    cube_id=created_cube_id,
+                    cube_name=request.cube_name,
+                    owner_id=request.owner_id,
+                ),
+            )
+
+        except ValueError as e:
+            logger.error(f"Validation error creating cube: {e}")
+            raise HTTPException(status_code=400, detail=str(e)) from e
+        except Exception as e:
+            logger.error(f"Failed to create cube: {e}", exc_info=True)
+            raise HTTPException(status_code=500, detail=f"Failed to create cube: {e!s}") from e
+
+    async def register_cube(self, request: RegisterCubeRequest) -> RegisterCubeResponse:
+        """Register an existing memory cube with the system.
+
+        Note: This endpoint currently validates the request but the actual registration
+        logic requires integration with MOSCore.register_mem_cube(), which is not
+        directly available in the API server context. This is a placeholder that
+        validates inputs and could be enhanced when the architecture supports it.
+
+        Args:
+            request: Cube registration request
+
+        Returns:
+            RegisterCubeResponse with registration details
+
+        Raises:
+            HTTPException: If registration fails
+        """
+        try:
+            # Validate user exists if provided
+            if request.user_id and not self.user_manager.validate_user(request.user_id):
+                raise ValueError(f"User '{request.user_id}' does not exist or is inactive")
+
+            # Note: Full registration logic requires MOSCore which isn't available
+            # in the current API architecture. This validates the request.
+            # Future work: integrate with MOSCore.register_mem_cube()
+
+            # Use provided cube_id or fall back to name_or_path as identifier
+            final_cube_id = request.mem_cube_id or request.mem_cube_name_or_path
+
+            logger.info(f"Cube registration validated: {final_cube_id}")
+            logger.warning(
+                "register_cube endpoint validates inputs but full registration "
+                "requires MOSCore integration (not yet available in API context)"
+            )
+
+            return RegisterCubeResponse(
+                code=200,
+                message="Cube registration request validated (full registration pending architecture support)",
+                data=RegisterCubeResponseData(
+                    cube_id=final_cube_id,
+                    cube_name_or_path=request.mem_cube_name_or_path,
+                ),
+            )
+
+        except ValueError as e:
+            logger.error(f"Validation error registering cube: {e}")
+            raise HTTPException(status_code=400, detail=str(e)) from e
+        except Exception as e:
+            logger.error(f"Failed to register cube: {e}", exc_info=True)
+            raise HTTPException(status_code=500, detail=f"Failed to register cube: {e!s}") from e

{memoryos-2.0.17 → memoryos-2.0.20}/src/memos/api/handlers/formatters_handler.py

@@ -13,6 +13,13 @@ from memos.templates.instruction_completion import instruct_completion
 
 logger = get_logger(__name__)
 
+__all__ = [
+    "format_memory_item",
+    "post_process_textual_mem",
+    "rerank_knowledge_mem",
+    "to_iter",
+]
+
 
 def to_iter(running: Any) -> list[Any]:
     """
@@ -164,6 +171,7 @@ def rerank_knowledge_mem(
     text_mem: list[dict[str, Any]],
     top_k: int,
     file_mem_proportion: float = 0.5,
+    strip_conversation_sources: bool = False,
 ) -> list[dict[str, Any]]:
     """
     Rerank knowledge memories and keep conversation memories.
@@ -193,8 +201,9 @@ def rerank_knowledge_mem(
         item["memory"] = item["metadata"]["sources"][0]["content"]
         item["metadata"]["sources"] = []
 
-    for item in conversation_mem:
-        item.setdefault("metadata", {})["sources"] = []
+    if strip_conversation_sources:
+        for item in conversation_mem:
+            item.setdefault("metadata", {})["sources"] = []
 
     # deduplicate: remove items with duplicate memory content
     original_count = len(reranked_knowledge_mem)

{memoryos-2.0.17 → memoryos-2.0.20}/src/memos/api/handlers/search_handler.py

@@ -118,6 +118,23 @@ class SearchHandler(BaseHandler):
             top_k=search_req_local.top_k,
             file_mem_proportion=0.5,
         )
+        hooked_results = trigger_hook(
+            H.SEARCH_RESULTS_AFTER_RERANK,
+            handler=self,
+            search_req=search_req_local,
+            results=results,
+        )
+        if hooked_results is not None:
+            results = hooked_results
+
+        hooked_results = trigger_hook(
+            H.SEARCH_CONTEXT_RENDER,
+            handler=self,
+            search_req=search_req_local,
+            results=results,
+        )
+        if hooked_results is not None:
+            results = hooked_results
 
         self.logger.info(
             f"[SearchHandler] Final search results: count={len(results)} results={results}"

{memoryos-2.0.17 → memoryos-2.0.20}/src/memos/api/mcp_serve.py

@@ -270,7 +270,10 @@ class MOSMCPServer:
 
         @self.mcp.tool()
         async def search_memories(
-            query: str, user_id: str | None = None, cube_ids: list[str] | None = None
+            query: str,
+            user_id: str | None = None,
+            cube_ids: list[str] | None = None,
+            filter: dict[str, Any] | None = None,
         ) -> dict[str, Any]:
             """
             Search for memories across user's accessible memory cubes.
@@ -282,11 +285,15 @@ class MOSMCPServer:
                 query (str): Search query to find relevant memories
                 user_id (str, optional): User ID whose cubes to search. If not provided, uses default user
                 cube_ids (list[str], optional): Specific cube IDs to search. If not provided, searches all user's cubes
+                filter (dict, optional): Filter conditions for the search. An empty dict is treated as no filter.
 
             Returns:
                 dict: Search results containing text_mem, act_mem, and para_mem categories with relevant memories
             """
             try:
+                # Some MCP clients always send filter:{} in conversation mode; treat it as no filter
+                if not filter:
+                    filter = None
                 result = self.mos_core.search(query, user_id, cube_ids)
                 return result
             except Exception as e:

{memoryos-2.0.17 → memoryos-2.0.20}/src/memos/api/product_models.py

@@ -68,6 +68,71 @@ class MemCubeRegister(BaseRequest):
     mem_cube_id: str | None = Field(None, description="ID for the MemCube")
 
 
+class CreateCubeRequest(BaseRequest):
+    """Request model for creating a new memory cube."""
+
+    cube_name: str = Field(..., description="Human-readable name for the memory cube")
+    owner_id: str = Field(..., description="User ID of the cube owner")
+    cube_path: str | None = Field(
+        None, description="File system path where cube data will be stored"
+    )
+    cube_id: str | None = Field(
+        None,
+        description=(
+            "Custom unique identifier for the cube. If not provided, one will be generated. "
+            "Note: cube_id is also referred to as mem_cube_id throughout the API."
+        ),
+    )
+
+
+class CreateCubeResponseData(BaseModel):
+    """Data model for cube creation response."""
+
+    cube_id: str = Field(..., description="The created cube ID (also called mem_cube_id)")
+    cube_name: str = Field(..., description="Name of the created cube")
+    owner_id: str = Field(..., description="Owner user ID")
+
+
+class CreateCubeResponse(BaseResponse[CreateCubeResponseData]):
+    """Response model for cube creation."""
+
+    message: str = "Cube created successfully"
+
+
+class RegisterCubeRequest(BaseRequest):
+    """Request model for registering an existing memory cube.
+
+    This allows loading a cube from disk or creating a new one if the path doesn't exist.
+    """
+
+    mem_cube_name_or_path: str = Field(
+        ..., description="File path to the memory cube or name for a new cube"
+    )
+    mem_cube_id: str | None = Field(
+        None,
+        description=(
+            "Custom identifier for the cube (also called cube_id). "
+            "If not provided, one will be generated."
+        ),
+    )
+    user_id: str | None = Field(
+        None, description="User ID to associate with the cube. If not provided, uses default user"
+    )
+
+
+class RegisterCubeResponseData(BaseModel):
+    """Data model for cube registration response."""
+
+    cube_id: str = Field(..., description="The registered cube ID (also called mem_cube_id)")
+    cube_name_or_path: str = Field(..., description="Name or path of the registered cube")
+
+
+class RegisterCubeResponse(BaseResponse[RegisterCubeResponseData]):
+    """Response model for cube registration."""
+
+    message: str = "Cube registered successfully"
+
+
 class ChatRequest(BaseRequest):
     """Request model for chat operations.
 
@@ -357,6 +422,14 @@ class APISearchRequest(BaseRequest):
         ),
     )
 
+    rerank: bool = Field(
+        True,
+        description=(
+            "Whether to apply the textual memory reranker during search. "
+            "Set false to return retrieval-order candidates before post-search dedup/formatting."
+        ),
+    )
+
     pref_top_k: int = Field(
         6,
         ge=0,
@@ -399,6 +472,11 @@ class APISearchRequest(BaseRequest):
         description="Number of skill memories to retrieve (top-K). Default: 3.",
     )
 
+    context_format: str = Field(
+        "memory",
+        description="Optional search context format passed through to installed plugins.",
+    )
+
     # ==== Filter conditions ====
     # TODO: maybe add detailed description later
     filter: dict[str, Any] | None = Field(