MemoryOS 2.0.16__tar.gz → 2.0.19__tar.gz

{memoryos-2.0.16 → memoryos-2.0.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MemoryOS
-Version: 2.0.16
+Version: 2.0.19
 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.16 → memoryos-2.0.19}/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.16 → memoryos-2.0.19}/pyproject.toml

@@ -4,7 +4,7 @@
 ##############################################################################
 
 name = "MemoryOS"
-version = "2.0.16"
+version = "2.0.19"
 description = "Intelligence Begins with Memory"
 license = {text = "Apache-2.0"}
 readme = "README.md"
@@ -62,6 +62,9 @@ issues = "https://github.com/MemTensor/MemOS/issues"
 [project.scripts]
 memos = "memos.cli:main"
 
+[project.entry-points."memos.plugins"]
+dream = "memos.dream:CommunityDreamPlugin"
+
 [project.optional-dependencies]
 # These are optional dependencies for various features of MemoryOS.
 # Developers install: `poetry install --extras <feature>`. e.g., `poetry install --extras general-mem`

{memoryos-2.0.16 → memoryos-2.0.19}/src/memos/__init__.py

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

{memoryos-2.0.16 → memoryos-2.0.19}/src/memos/api/handlers/chat_handler.py

@@ -60,6 +60,7 @@ class ChatHandler(BaseHandler):
         self,
         dependencies: HandlerDependencies,
         chat_llms: dict[str, Any],
+        playground_chat_llms: dict[str, Any] | None = None,
         search_handler=None,
         add_handler=None,
         online_bot=None,
@@ -70,6 +71,7 @@ class ChatHandler(BaseHandler):
         Args:
             dependencies: HandlerDependencies instance
             chat_llms: Dictionary mapping model names to LLM instances
+            playground_chat_llms: Optional model map for /chat/stream/playground
             search_handler: Optional SearchHandler instance (created if not provided)
             add_handler: Optional AddHandler instance (created if not provided)
             online_bot: Optional DingDing bot function for notifications
@@ -89,6 +91,7 @@ class ChatHandler(BaseHandler):
             add_handler = AddHandler(dependencies)
 
         self.chat_llms = chat_llms
+        self.playground_chat_llms = playground_chat_llms or chat_llms
         self.search_handler = search_handler
         self.add_handler = add_handler
         self.online_bot = online_bot
@@ -630,10 +633,11 @@ class ChatHandler(BaseHandler):
 
                     # Step 3: Generate streaming response from LLM
                     try:
-                        model = next(iter(self.chat_llms.keys()))
+                        chat_llms = self.playground_chat_llms
+                        model = next(iter(chat_llms.keys()))
                         self.logger.info(f"[PLAYGROUND CHAT] Chat Playground Stream Model: {model}")
                         start = time.time()
-                        response_stream = self.chat_llms[model].generate_stream(
+                        response_stream = chat_llms[model].generate_stream(
                             current_messages, model_name_or_path=model
                         )
 

{memoryos-2.0.16 → memoryos-2.0.19}/src/memos/api/handlers/component_init.py

@@ -157,6 +157,7 @@ def init_server() -> dict[str, Any]:
     graph_db_config = build_graph_db_config()
     llm_config = build_llm_config()
     chat_llm_config = build_chat_llm_config()
+    playground_chat_llm_config = build_chat_llm_config("PLAYGROUND_CHAT_MODEL_LIST")
     embedder_config = build_embedder_config()
     nli_client_config = build_nli_client_config()
     mem_reader_config = build_mem_reader_config()
@@ -174,6 +175,11 @@ def init_server() -> dict[str, Any]:
         if os.getenv("ENABLE_CHAT_API", "false") == "true"
         else None
     )
+    playground_chat_llms = (
+        _init_chat_llms(playground_chat_llm_config)
+        if os.getenv("ENABLE_CHAT_API", "false") == "true" and playground_chat_llm_config
+        else chat_llms
+    )
     embedder = EmbedderFactory.from_config(embedder_config)
 
     plugin_context = build_plugin_context(
@@ -317,6 +323,7 @@ def init_server() -> dict[str, Any]:
         "mem_reader": mem_reader,
         "llm": llm,
         "chat_llms": chat_llms,
+        "playground_chat_llms": playground_chat_llms,
         "embedder": embedder,
         "reranker": reranker,
         "internet_retriever": internet_retriever,

{memoryos-2.0.16 → memoryos-2.0.19}/src/memos/api/handlers/config_builders.py

@@ -85,14 +85,17 @@ def build_llm_config() -> dict[str, Any]:
     )
 
 
-def build_chat_llm_config() -> list[dict[str, Any]]:
+def build_chat_llm_config(env_name: str = "CHAT_MODEL_LIST") -> list[dict[str, Any]]:
     """
     Build chat LLM configuration.
 
     Returns:
         Validated chat LLM configuration dictionary
+    Args:
+        env_name: Environment variable that contains the JSON chat model list.
+
     """
-    configs = json.loads(os.getenv("CHAT_MODEL_LIST", "[]"))
+    configs = json.loads(os.getenv(env_name, "[]"))
     return [
         {
             "config_class": LLMConfigFactory.model_validate(

memoryos-2.0.19/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.16 → memoryos-2.0.19}/src/memos/api/handlers/search_handler.py

@@ -7,12 +7,15 @@ using dependency injection for better modularity and testability.
 
 import copy
 import math
+import os
 
+from contextlib import suppress
 from typing import Any
 
 from memos.api.handlers.base_handler import BaseHandler, HandlerDependencies
 from memos.api.handlers.formatters_handler import rerank_knowledge_mem
 from memos.api.product_models import APISearchRequest, SearchResponse
+from memos.dream.contextualization import CONTEXT_MEMORY_TYPE
 from memos.log import get_logger
 from memos.memories.textual.tree_text_memory.retrieve.retrieve_utils import (
     cosine_similarity_matrix,
@@ -20,11 +23,26 @@ from memos.memories.textual.tree_text_memory.retrieve.retrieve_utils import (
 from memos.multi_mem_cube.composite_cube import CompositeCubeView
 from memos.multi_mem_cube.single_cube import SingleCubeView
 from memos.multi_mem_cube.views import MemCubeView
-from memos.plugins.hooks import hookable
+from memos.plugins.hook_defs import H
+from memos.plugins.hooks import hookable, trigger_hook
 
 
 logger = get_logger(__name__)
 
+_ENV_CONTEXT_RECALL = "MEMOS_DREAM_CONTEXT_RECALL"
+_ENV_CONTEXT_RECALL_TOP_K = "MEMOS_DREAM_CONTEXT_RECALL_TOP_K"
+_DEFAULT_CONTEXT_RECALL_TOP_K = 2
+
+
+def _env_enabled(name: str, default: str = "off") -> bool:
+    return os.getenv(name, default).strip().lower() not in {"0", "false", "no", "off"}
+
+
+def _env_int(name: str, default: int) -> int:
+    with suppress(TypeError, ValueError):
+        return int(os.getenv(name, str(default)))
+    return default
+
 
 class SearchHandler(BaseHandler):
     """
@@ -71,6 +89,14 @@ class SearchHandler(BaseHandler):
         # Search and deduplicate
         cube_view = self._build_cube_view(search_req_local)
         results = cube_view.search_memories(search_req_local)
+        hooked_results = trigger_hook(
+            H.SEARCH_MEMORY_RESULTS,
+            handler=self,
+            search_req=search_req_local,
+            results=results,
+        )
+        if hooked_results is not None:
+            results = hooked_results
         if not search_req_local.relativity:
             search_req_local.relativity = 0
         self.logger.info(f"[SearchHandler] Relativity filter: {search_req_local.relativity}")
@@ -102,6 +128,105 @@ class SearchHandler(BaseHandler):
             data=results,
         )
 
+    def _merge_context_recall(
+        self, *, results: dict[str, Any], search_req: APISearchRequest
+    ) -> None:
+        if not _env_enabled(_ENV_CONTEXT_RECALL, "off"):
+            return
+
+        top_k = max(0, _env_int(_ENV_CONTEXT_RECALL_TOP_K, _DEFAULT_CONTEXT_RECALL_TOP_K))
+        if top_k <= 0:
+            return
+
+        context_buckets = self._recall_context_buckets(search_req=search_req, top_k=top_k)
+        if not context_buckets:
+            return
+
+        results.setdefault("text_mem", []).extend(context_buckets)
+
+    def _recall_context_buckets(
+        self, *, search_req: APISearchRequest, top_k: int
+    ) -> list[dict[str, Any]]:
+        graph_db = self.graph_db or getattr(self.searcher, "graph_store", None)
+        embedder = self.embedder or getattr(self.searcher, "embedder", None)
+        if graph_db is None or embedder is None:
+            self.logger.info(
+                "[SearchHandler] Context recall skipped: graph_db or embedder unavailable."
+            )
+            return []
+
+        try:
+            query_embedding = embedder.embed([search_req.query])[0]
+        except Exception:
+            self.logger.warning("[SearchHandler] Context recall embedding failed.", exc_info=True)
+            return []
+
+        buckets: list[dict[str, Any]] = []
+        for cube_id in self._resolve_cube_ids(search_req):
+            try:
+                hits = graph_db.search_by_embedding(
+                    query_embedding,
+                    top_k=top_k,
+                    scope=CONTEXT_MEMORY_TYPE,
+                    status="activated",
+                    user_name=cube_id,
+                    return_fields=[
+                        "memory",
+                        "key",
+                        "created_at",
+                        "updated_at",
+                        "source",
+                        "internal_info",
+                    ],
+                )
+            except Exception:
+                self.logger.warning(
+                    "[SearchHandler] Context recall search failed for cube=%s.",
+                    cube_id,
+                    exc_info=True,
+                )
+                continue
+
+            memories = [self._format_context_hit(hit) for hit in hits or [] if hit.get("memory")]
+            if not memories:
+                continue
+            buckets.append(
+                {
+                    "cube_id": cube_id,
+                    "memories": memories,
+                    "total_nodes": len(memories),
+                }
+            )
+        return buckets
+
+    @staticmethod
+    def _format_context_hit(hit: dict[str, Any]) -> dict[str, Any]:
+        context_id = str(hit.get("id", ""))
+        score = float(hit.get("score", 0.0) or 0.0)
+        metadata = {
+            "id": context_id,
+            "memory": hit.get("memory", ""),
+            "memory_type": CONTEXT_MEMORY_TYPE,
+            "source": hit.get("source") or "dream",
+            "key": hit.get("key", ""),
+            "relativity": score,
+            "score": score,
+            "embedding": [],
+            "sources": [],
+            "usage": [],
+            "ref_id": f"[{context_id.split('-')[0]}]" if context_id else "[context]",
+        }
+        for field in ("created_at", "updated_at", "internal_info"):
+            if hit.get(field) is not None:
+                metadata[field] = hit[field]
+
+        return {
+            "id": context_id,
+            "memory": hit.get("memory", ""),
+            "metadata": metadata,
+            "ref_id": metadata["ref_id"],
+        }
+
     @staticmethod
     def _apply_relativity_threshold(results: dict[str, Any], relativity: float) -> dict[str, Any]:
         if relativity <= 0: