MemoryOS 2.0.1__tar.gz → 2.0.2__tar.gz

{memoryos-2.0.1 → memoryos-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MemoryOS
-Version: 2.0.1
+Version: 2.0.2
 Summary: Intelligence Begins with Memory
 License: Apache-2.0
 License-File: LICENSE
@@ -289,6 +289,7 @@ Get Free API: [Try API](https://memos-dashboard.openmem.net/quickstart/?source=g
 - Launch via the uvicorn command line interface (CLI)
   ###### Tips: Please ensure that Neo4j and Qdrant are running before executing the following command.
   ```bash
+  cd src
   uvicorn memos.api.server_api:app --host 0.0.0.0 --port 8001 --workers 1
   ```
   ##### For detailed integration steps, see the [`CLI Reference`](https://docs.openmem.net/open_source/getting_started/rest_api_server/#method-3client-install-with-CLI).

{memoryos-2.0.1 → memoryos-2.0.2}/README.md

@@ -211,6 +211,7 @@ Get Free API: [Try API](https://memos-dashboard.openmem.net/quickstart/?source=g
 - Launch via the uvicorn command line interface (CLI)
   ###### Tips: Please ensure that Neo4j and Qdrant are running before executing the following command.
   ```bash
+  cd src
   uvicorn memos.api.server_api:app --host 0.0.0.0 --port 8001 --workers 1
   ```
   ##### For detailed integration steps, see the [`CLI Reference`](https://docs.openmem.net/open_source/getting_started/rest_api_server/#method-3client-install-with-CLI).

{memoryos-2.0.1 → memoryos-2.0.2}/pyproject.toml

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

{memoryos-2.0.1 → memoryos-2.0.2}/src/memos/__init__.py

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

{memoryos-2.0.1 → memoryos-2.0.2}/src/memos/api/handlers/component_init.py

@@ -183,7 +183,8 @@ def init_server() -> dict[str, Any]:
         else None
     )
     embedder = EmbedderFactory.from_config(embedder_config)
-    mem_reader = MemReaderFactory.from_config(mem_reader_config)
+    # Pass graph_db to mem_reader for recall operations (deduplication, conflict detection)
+    mem_reader = MemReaderFactory.from_config(mem_reader_config, graph_db=graph_db)
     reranker = RerankerFactory.from_config(reranker_config)
     feedback_reranker = RerankerFactory.from_config(feedback_reranker_config)
     internet_retriever = InternetRetrieverFactory.from_config(

memoryos-2.0.2/src/memos/api/handlers/formatters_handler.py

@@ -0,0 +1,237 @@
+"""
+Data formatting utilities for server handlers.
+
+This module provides utility functions for formatting and transforming data
+structures for API responses, including memory items and preferences.
+"""
+
+from typing import Any
+
+from memos.log import get_logger
+from memos.templates.instruction_completion import instruct_completion
+
+
+logger = get_logger(__name__)
+
+
+def to_iter(running: Any) -> list[Any]:
+    """
+    Normalize running tasks to a list of task objects.
+
+    Handles different input types and converts them to a consistent list format.
+
+    Args:
+        running: Running tasks, can be None, dict, or iterable
+
+    Returns:
+        List of task objects
+    """
+    if running is None:
+        return []
+    if isinstance(running, dict):
+        return list(running.values())
+    return list(running) if running else []
+
+
+def format_memory_item(
+    memory_data: Any, include_embedding: bool = False, save_sources: bool = True
+) -> dict[str, Any]:
+    """
+    Format a single memory item for API response.
+
+    Transforms a memory object into a dictionary with metadata properly
+    structured for API consumption.
+
+    Args:
+        memory_data: Memory object to format
+
+    Returns:
+        Formatted memory dictionary with ref_id and metadata
+    """
+    memory = memory_data.model_dump()
+    memory_id = memory["id"]
+    ref_id = f"[{memory_id.split('-')[0]}]"
+
+    memory["ref_id"] = ref_id
+    if not include_embedding:
+        memory["metadata"]["embedding"] = []
+    if not save_sources:
+        memory["metadata"]["sources"] = []
+    memory["metadata"]["usage"] = []
+    memory["metadata"]["ref_id"] = ref_id
+    memory["metadata"]["id"] = memory_id
+    memory["metadata"]["memory"] = memory["memory"]
+
+    return memory
+
+
+def post_process_pref_mem(
+    memories_result: dict[str, Any],
+    pref_formatted_mem: list[dict[str, Any]],
+    mem_cube_id: str,
+    include_preference: bool,
+) -> dict[str, Any]:
+    """
+    Post-process preference memory results.
+
+    Adds formatted preference memories to the result dictionary and generates
+    instruction completion strings if preferences are included.
+
+    Args:
+        memories_result: Result dictionary to update
+        pref_formatted_mem: List of formatted preference memories
+        mem_cube_id: Memory cube ID
+        include_preference: Whether to include preferences in result
+
+    Returns:
+        Updated memories_result dictionary
+    """
+    if include_preference:
+        memories_result["pref_mem"].append(
+            {
+                "cube_id": mem_cube_id,
+                "memories": pref_formatted_mem,
+                "total_nodes": len(pref_formatted_mem),
+            }
+        )
+        pref_instruction, pref_note = instruct_completion(pref_formatted_mem)
+        memories_result["pref_string"] = pref_instruction
+        memories_result["pref_note"] = pref_note
+
+    return memories_result
+
+
+def post_process_textual_mem(
+    memories_result: dict[str, Any],
+    text_formatted_mem: list[dict[str, Any]],
+    mem_cube_id: str,
+) -> dict[str, Any]:
+    """
+    Post-process text and tool memory results.
+    """
+    fact_mem = [
+        mem
+        for mem in text_formatted_mem
+        if mem["metadata"]["memory_type"] not in ["ToolSchemaMemory", "ToolTrajectoryMemory"]
+    ]
+    tool_mem = [
+        mem
+        for mem in text_formatted_mem
+        if mem["metadata"]["memory_type"] in ["ToolSchemaMemory", "ToolTrajectoryMemory"]
+    ]
+
+    memories_result["text_mem"].append(
+        {
+            "cube_id": mem_cube_id,
+            "memories": fact_mem,
+            "total_nodes": len(fact_mem),
+        }
+    )
+    memories_result["tool_mem"].append(
+        {
+            "cube_id": mem_cube_id,
+            "memories": tool_mem,
+            "total_nodes": len(tool_mem),
+        }
+    )
+    return memories_result
+
+
+def separate_knowledge_and_conversation_mem(memories: list[dict[str, Any]]):
+    """
+    Separate knowledge and conversation memories from retrieval results.
+    """
+    knowledge_mem = []
+    conversation_mem = []
+    for item in memories:
+        sources = item["metadata"]["sources"]
+        if (
+            len(sources) > 0
+            and "type" in sources[0]
+            and sources[0]["type"] == "file"
+            and "content" in sources[0]
+            and sources[0]["content"] != ""
+        ):  # TODO change to memory_type
+            knowledge_mem.append(item)
+        else:
+            conversation_mem.append(item)
+
+    logger.info(
+        f"Retrieval results number of knowledge_mem: {len(knowledge_mem)}, conversation_mem: {len(conversation_mem)}"
+    )
+    return knowledge_mem, conversation_mem
+
+
+def rerank_knowledge_mem(
+    reranker: Any,
+    query: str,
+    text_mem: list[dict[str, Any]],
+    top_k: int,
+    file_mem_proportion: float = 0.5,
+) -> list[dict[str, Any]]:
+    """
+    Rerank knowledge memories and keep conversation memories.
+    """
+    memid2cubeid = {}
+    memories_list = []
+    for memory_group in text_mem:
+        cube_id = memory_group["cube_id"]
+        memories = memory_group["memories"]
+        memories_list.extend(memories)
+        for memory in memories:
+            memid2cubeid[memory["id"]] = cube_id
+
+    knowledge_mem, conversation_mem = separate_knowledge_and_conversation_mem(memories_list)
+    knowledge_mem_top_k = max(int(top_k * file_mem_proportion), int(top_k - len(conversation_mem)))
+    # rerank set unuse
+    reranked_knowledge_mem = knowledge_mem
+
+    # Sort by relativity in descending order
+    reranked_knowledge_mem = sorted(
+        reranked_knowledge_mem,
+        key=lambda item: item.get("metadata", {}).get("relativity", 0.0),
+        reverse=True,
+    )
+
+    # TODO revoke sources replace memory value
+    for item in reranked_knowledge_mem:
+        item["memory"] = item["metadata"]["sources"][0]["content"]
+        item["metadata"]["sources"] = []
+
+    for item in conversation_mem:
+        item["metadata"]["sources"] = []
+
+    # deduplicate: remove items with duplicate memory content
+    original_count = len(reranked_knowledge_mem)
+    seen_memories = set[Any]()
+    deduplicated_knowledge_mem = []
+    for item in reranked_knowledge_mem:
+        memory_content = item.get("memory", "")
+        if memory_content and memory_content not in seen_memories:
+            seen_memories.add(memory_content)
+            deduplicated_knowledge_mem.append(item)
+    deduplicated_count = len(deduplicated_knowledge_mem)
+    logger.info(
+        f"After filtering duplicate knowledge base text from sources, count changed from {original_count} to {deduplicated_count}"
+    )
+
+    reranked_knowledge_mem = deduplicated_knowledge_mem[:knowledge_mem_top_k]
+    conversation_mem_top_k = top_k - len(reranked_knowledge_mem)
+    cubeid2memories = {}
+    text_mem_res = []
+
+    for memory in reranked_knowledge_mem + conversation_mem[:conversation_mem_top_k]:
+        cube_id = memid2cubeid[memory["id"]]
+        if cube_id not in cubeid2memories:
+            cubeid2memories[cube_id] = []
+        cubeid2memories[cube_id].append(memory)
+
+    for cube_id, memories in cubeid2memories.items():
+        text_mem_res.append(
+            {
+                "cube_id": cube_id,
+                "memories": memories,
+            }
+        )
+
+    return text_mem_res

{memoryos-2.0.1 → memoryos-2.0.2}/src/memos/api/handlers/memory_handler.py

@@ -6,7 +6,11 @@ This module handles retrieving all memories or specific subgraphs based on queri
 
 from typing import TYPE_CHECKING, Any, Literal
 
-from memos.api.handlers.formatters_handler import format_memory_item
+from memos.api.handlers.formatters_handler import (
+    format_memory_item,
+    post_process_pref_mem,
+    post_process_textual_mem,
+)
 from memos.api.product_models import (
     DeleteMemoryRequest,
     DeleteMemoryResponse,
@@ -209,54 +213,67 @@ def handle_get_memory(memory_id: str, naive_mem_cube: NaiveMemCube) -> GetMemory
 def handle_get_memories(
     get_mem_req: GetMemoryRequest, naive_mem_cube: NaiveMemCube
 ) -> GetMemoryResponse:
-    # TODO: Implement get memory with filter
+    results: dict[str, Any] = {"text_mem": [], "pref_mem": [], "tool_mem": []}
     memories = naive_mem_cube.text_mem.get_all(
         user_name=get_mem_req.mem_cube_id,
         user_id=get_mem_req.user_id,
         page=get_mem_req.page,
         page_size=get_mem_req.page_size,
-    )
-    total_nodes = memories["total_nodes"]
-    total_edges = memories["total_edges"]
-    del memories["total_nodes"]
-    del memories["total_edges"]
+        filter=get_mem_req.filter,
+    )["nodes"]
+
+    results = post_process_textual_mem(results, memories, get_mem_req.mem_cube_id)
+
+    if not get_mem_req.include_tool_memory:
+        results["tool_mem"] = []
 
     preferences: list[TextualMemoryItem] = []
-    total_pref = 0
 
+    format_preferences = []
     if get_mem_req.include_preference and naive_mem_cube.pref_mem is not None:
         filter_params: dict[str, Any] = {}
         if get_mem_req.user_id is not None:
             filter_params["user_id"] = get_mem_req.user_id
         if get_mem_req.mem_cube_id is not None:
             filter_params["mem_cube_id"] = get_mem_req.mem_cube_id
-
-        preferences, total_pref = naive_mem_cube.pref_mem.get_memory_by_filter(
+        if get_mem_req.filter is not None:
+            # Check and remove user_id/mem_cube_id from filter if present
+            filter_copy = get_mem_req.filter.copy()
+            removed_fields = []
+
+            if "user_id" in filter_copy:
+                filter_copy.pop("user_id")
+                removed_fields.append("user_id")
+            if "mem_cube_id" in filter_copy:
+                filter_copy.pop("mem_cube_id")
+                removed_fields.append("mem_cube_id")
+
+            if removed_fields:
+                logger.warning(
+                    f"Fields {removed_fields} found in filter will be ignored. "
+                    f"Use request-level user_id/mem_cube_id parameters instead."
+                )
+
+            filter_params.update(filter_copy)
+
+        preferences, _ = naive_mem_cube.pref_mem.get_memory_by_filter(
             filter_params, page=get_mem_req.page, page_size=get_mem_req.page_size
         )
-        format_preferences = [format_memory_item(item) for item in preferences]
+        format_preferences = [format_memory_item(item, save_sources=False) for item in preferences]
 
-    return GetMemoryResponse(
-        message="Memories retrieved successfully",
-        data={
-            "text_mem": [
-                {
-                    "cube_id": get_mem_req.mem_cube_id,
-                    "memories": memories,
-                    "total_nodes": total_nodes,
-                    "total_edges": total_edges,
-                }
-            ],
-            "pref_mem": [
-                {
-                    "cube_id": get_mem_req.mem_cube_id,
-                    "memories": format_preferences,
-                    "total_nodes": total_pref,
-                }
-            ],
-        },
+    results = post_process_pref_mem(
+        results, format_preferences, get_mem_req.mem_cube_id, get_mem_req.include_preference
     )
 
+    # Filter to only keep text_mem, pref_mem, tool_mem
+    filtered_results = {
+        "text_mem": results.get("text_mem", []),
+        "pref_mem": results.get("pref_mem", []),
+        "tool_mem": results.get("tool_mem", []),
+    }
+
+    return GetMemoryResponse(message="Memories retrieved successfully", data=filtered_results)
+
 
 def handle_delete_memories(delete_mem_req: DeleteMemoryRequest, naive_mem_cube: NaiveMemCube):
     logger.info(

{memoryos-2.0.1 → memoryos-2.0.2}/src/memos/api/handlers/search_handler.py

@@ -5,9 +5,12 @@ This module provides a class-based implementation of search handlers,
 using dependency injection for better modularity and testability.
 """
 
+import time
+
 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.log import get_logger
 from memos.memories.textual.tree_text_memory.retrieve.retrieve_utils import (
@@ -69,6 +72,18 @@ class SearchHandler(BaseHandler):
             # Restore original top_k for downstream logic or response metadata
             search_req.top_k = original_top_k
 
+        start_time = time.time()
+        text_mem = results["text_mem"]
+        results["text_mem"] = rerank_knowledge_mem(
+            self.reranker,
+            query=search_req.query,
+            text_mem=text_mem,
+            top_k=original_top_k,
+            file_mem_proportion=0.5,
+        )
+        rerank_time = time.time() - start_time
+
+        self.logger.info(f"[Knowledge_replace_memory_time] Rerank time: {rerank_time} seconds")
         self.logger.info(
             f"[SearchHandler] Final search results: count={len(results)} results={results}"
         )

{memoryos-2.0.1 → memoryos-2.0.2}/src/memos/api/product_models.py

@@ -771,7 +771,9 @@ class GetMemoryRequest(BaseRequest):
 
     mem_cube_id: str = Field(..., description="Cube ID")
     user_id: str | None = Field(None, description="User ID")
-    include_preference: bool = Field(True, description="Whether to handle preference memory")
+    include_preference: bool = Field(True, description="Whether to return preference memory")
+    include_tool_memory: bool = Field(False, description="Whether to return tool memory")
+    filter: dict[str, Any] | None = Field(None, description="Filter for the memory")
     page: int | None = Field(
         None,
         description="Page number (starts from 1). If None, exports all data without pagination.",

{memoryos-2.0.1 → memoryos-2.0.2}/src/memos/graph_dbs/base.py

@@ -19,12 +19,13 @@ class BaseGraphDB(ABC):
         """
 
     @abstractmethod
-    def update_node(self, id: str, fields: dict[str, Any]) -> None:
+    def update_node(self, id: str, fields: dict[str, Any], user_name: str | None = None) -> None:
         """
         Update attributes of an existing node.
         Args:
             id: Node identifier to be updated.
             fields: Dictionary of fields to update.
+            user_name: given user_name
         """
 
     @abstractmethod
@@ -70,7 +71,7 @@ class BaseGraphDB(ABC):
 
     # Graph Query & Reasoning
     @abstractmethod
-    def get_node(self, id: str, include_embedding: bool = False) -> dict[str, Any] | None:
+    def get_node(self, id: str, include_embedding: bool = False, **kwargs) -> dict[str, Any] | None:
         """
         Retrieve the metadata and content of a node.
         Args:
@@ -82,7 +83,7 @@ class BaseGraphDB(ABC):
 
     @abstractmethod
     def get_nodes(
-        self, id: str, include_embedding: bool = False, **kwargs
+        self, ids: list, include_embedding: bool = False, **kwargs
     ) -> dict[str, Any] | None:
         """
         Retrieve the metadata and memory of a list of nodes.
@@ -160,13 +161,17 @@ class BaseGraphDB(ABC):
         """
 
     @abstractmethod
-    def get_by_metadata(self, filters: list[dict[str, Any]]) -> list[str]:
+    def get_by_metadata(
+        self, filters: list[dict[str, Any]], status: str | None = None
+    ) -> list[str]:
         """
         Retrieve node IDs that match given metadata filters.
 
         Args:
             filters (dict[str, Any]): A dictionary of attribute-value filters.
                 Example: {"topic": "psychology", "importance": 2}
+            status (str, optional): Filter by status (e.g., 'activated', 'archived').
+                If None, no status filter is applied.
 
         Returns:
             list[str]: Node IDs whose metadata match the filter conditions.
@@ -239,13 +244,17 @@ class BaseGraphDB(ABC):
         """
 
     @abstractmethod
-    def get_all_memory_items(self, scope: str, include_embedding: bool = False) -> list[dict]:
+    def get_all_memory_items(
+        self, scope: str, include_embedding: bool = False, status: str | None = None
+    ) -> list[dict]:
         """
         Retrieve all memory items of a specific memory_type.
 
         Args:
             scope (str): Must be one of 'WorkingMemory', 'LongTermMemory', or 'UserMemory'.
             include_embedding: with/without embedding
+            status (str, optional): Filter by status (e.g., 'activated', 'archived').
+                If None, no status filter is applied.
 
         Returns:
             list[dict]: Full list of memory items under this scope.

{memoryos-2.0.1 → memoryos-2.0.2}/src/memos/graph_dbs/neo4j.py

@@ -916,6 +916,7 @@ class Neo4jGraphDB(BaseGraphDB):
         filter: dict | None = None,
         knowledgebase_ids: list[str] | None = None,
         user_name_flag: bool = True,
+        status: str | None = None,
     ) -> list[str]:
         """
         TODO:
@@ -933,6 +934,8 @@ class Neo4jGraphDB(BaseGraphDB):
                 {"field": "tags", "op": "contains", "value": "AI"},
                 ...
             ]
+        status (str, optional): Filter by status (e.g., 'activated', 'archived').
+            If None, no status filter is applied.
 
         Returns:
             list[str]: Node IDs whose metadata match the filter conditions. (AND logic).
@@ -942,15 +945,20 @@ class Neo4jGraphDB(BaseGraphDB):
             - Can be used for faceted recall or prefiltering before embedding rerank.
         """
         logger.info(
-            f"[get_by_metadata] filters: {filters},user_name: {user_name},filter: {filter},knowledgebase_ids: {knowledgebase_ids}"
+            f"[get_by_metadata] filters: {filters},user_name: {user_name},filter: {filter},knowledgebase_ids: {knowledgebase_ids},status: {status}"
         )
         print(
-            f"[get_by_metadata] filters: {filters},user_name: {user_name},filter: {filter},knowledgebase_ids: {knowledgebase_ids}"
+            f"[get_by_metadata] filters: {filters},user_name: {user_name},filter: {filter},knowledgebase_ids: {knowledgebase_ids},status: {status}"
         )
         user_name = user_name if user_name else self.config.user_name
         where_clauses = []
         params = {}
 
+        # Add status filter if provided
+        if status:
+            where_clauses.append("n.status = $status")
+            params["status"] = status
+
         for i, f in enumerate(filters):
             field = f["field"]
             op = f.get("op", "=")
@@ -1272,8 +1280,10 @@ class Neo4jGraphDB(BaseGraphDB):
     def get_all_memory_items(
         self,
         scope: str,
+        include_embedding: bool = False,
         filter: dict | None = None,
         knowledgebase_ids: list[str] | None = None,
+        status: str | None = None,
         **kwargs,
     ) -> list[dict]:
         """
@@ -1281,18 +1291,21 @@ class Neo4jGraphDB(BaseGraphDB):
 
         Args:
             scope (str): Must be one of 'WorkingMemory', 'LongTermMemory', or 'UserMemory'.
+            include_embedding (bool): Whether to include embedding in results.
             filter (dict, optional): Filter conditions with 'and' or 'or' logic for search results.
                 Example: {"and": [{"id": "xxx"}, {"A": "yyy"}]} or {"or": [{"id": "xxx"}, {"A": "yyy"}]}
-        Returns:
+            knowledgebase_ids (list[str], optional): List of knowledgebase IDs to filter by.
+            status (str, optional): Filter by status (e.g., 'activated', 'archived').
+                If None, no status filter is applied.
 
         Returns:
             list[dict]: Full list of memory items under this scope.
         """
         logger.info(
-            f"[get_all_memory_items] scope: {scope},filter: {filter},knowledgebase_ids: {knowledgebase_ids}"
+            f"[get_all_memory_items] scope: {scope},filter: {filter},knowledgebase_ids: {knowledgebase_ids},status: {status}"
         )
         print(
-            f"[get_all_memory_items] scope: {scope},filter: {filter},knowledgebase_ids: {knowledgebase_ids}"
+            f"[get_all_memory_items] scope: {scope},filter: {filter},knowledgebase_ids: {knowledgebase_ids},status: {status}"
         )
 
         user_name = kwargs.get("user_name") if kwargs.get("user_name") else self.config.user_name
@@ -1302,6 +1315,11 @@ class Neo4jGraphDB(BaseGraphDB):
         where_clauses = ["n.memory_type = $scope"]
         params = {"scope": scope}
 
+        # Add status filter if provided
+        if status:
+            where_clauses.append("n.status = $status")
+            params["status"] = status
+
         # Build user_name filter with knowledgebase_ids support (OR relationship) using common method
         user_name_conditions, user_name_params = self._build_user_name_and_kb_ids_conditions_cypher(
             user_name=user_name,