Merge remote-tracking branch 'upstream/main' into agent/resolve-pr-1774-conflict

Author: hijzy

.github/workflows/hermes-plugin-publish.yml

@@ -0,0 +1,39 @@
+# MemOS Examples
+
+This directory contains runnable examples for MemOS modules, memory types, API
+usage, and integrations. Run examples from the repository root so relative
+configuration and data paths resolve correctly.
+
+## Running Examples
+
+Install the project dependencies first, then run a script directly:
+
+```bash
+python examples/mem_cube/load_cube.py
+```
+
+Some examples require extra services or credentials, such as Neo4j, Redis,
+model provider API keys, or local model backends. Check the script and matching
+documentation before running those examples.
+
+For guided walkthroughs, see the [examples guide](../docs/en/open_source/getting_started/examples.md)
+and the module documentation under [docs/en/open_source/modules](../docs/en/open_source/modules).
+
+## Directory Overview
+
+| Directory | Purpose |
+| --- | --- |
+| `api` | Server router and product API usage examples. |
+| `basic_modules` | Focused examples for embedders, LLMs, chunkers, rerankers, graph databases, and textual memory helpers. |
+| `core_memories` | Examples for core memory backends such as general, naive, preference, tree textual, KV cache, and vLLM KV cache memory. |
+| `data` | Shared sample configs, memory cube data, and input assets used by other examples. |
+| `dream` | End-to-end dream pipeline example. |
+| `extras` | Additional standalone demos that do not fit the main module categories. |
+| `mem_agent` | Agent-oriented examples, including deep search usage. |
+| `mem_chat` | Chat examples that combine generated cubes and explicit memory. |
+| `mem_cube` | MemCube load, dump, and legacy remote or lazy loading examples. |
+| `mem_feedback` | Examples for memory feedback workflows. |
+| `mem_mcp` | FastMCP server and client examples for MemOS integrations. |
+| `mem_reader` | MemReader parser, builder, sample, and runner demos for text, files, images, and messages. |
+| `mem_scheduler` | Scheduler examples for Redis-backed asynchronous memory workflows. |
+

examples/README.md

@@ -4,7 +4,7 @@
 ##############################################################################
 
 name = "MemoryOS"
-version = "2.0.15"
+version = "2.0.16"
 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`

pyproject.toml

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

src/memos/__init__.py

@@ -7,12 +7,15 @@
 
 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,
@@ -25,6 +28,20 @@
 
 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 +88,7 @@ def handle_search_memories(self, search_req: APISearchRequest) -> SearchResponse
         # Search and deduplicate
         cube_view = self._build_cube_view(search_req_local)
         results = cube_view.search_memories(search_req_local)
+        self._merge_context_recall(results=results, search_req=search_req_local)
         if not search_req_local.relativity:
             search_req_local.relativity = 0
         self.logger.info(f"[SearchHandler] Relativity filter: {search_req_local.relativity}")
@@ -102,6 +120,105 @@ def handle_search_memories(self, search_req: APISearchRequest) -> SearchResponse
             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: