MemoryOS 2.0.3__py3-none-any.whl

memos/mem_cube/base.py

@@ -0,0 +1,30 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from memos.configs.mem_cube import BaseMemCubeConfig
+
+
+if TYPE_CHECKING:
+    from memos.memories.activation.base import BaseActMemory
+    from memos.memories.parametric.base import BaseParaMemory
+    from memos.memories.textual.base import BaseTextMemory
+
+
+class BaseMemCube(ABC):
+    """Base class for all MemCube implementations."""
+
+    @abstractmethod
+    def __init__(self, config: BaseMemCubeConfig):
+        """Initialize the MemCube with the given configuration."""
+        self.text_mem: BaseTextMemory
+        self.act_mem: BaseActMemory
+        self.para_mem: BaseParaMemory
+        self.pref_mem: BaseTextMemory
+
+    @abstractmethod
+    def load(self, dir: str) -> None:
+        """Load memories from a directory."""
+
+    @abstractmethod
+    def dump(self, dir: str) -> None:
+        """Dump memories to a directory."""

memos/mem_cube/general.py

@@ -0,0 +1,240 @@
+import os
+import time
+
+from typing import Literal
+
+from memos.configs.mem_cube import GeneralMemCubeConfig
+from memos.configs.utils import get_json_file_model_schema
+from memos.exceptions import ConfigurationError, MemCubeError
+from memos.log import get_logger
+from memos.mem_cube.base import BaseMemCube
+from memos.mem_cube.utils import download_repo, merge_config_with_default
+from memos.memories.activation.base import BaseActMemory
+from memos.memories.factory import MemoryFactory
+from memos.memories.parametric.base import BaseParaMemory
+from memos.memories.textual.base import BaseTextMemory
+
+
+logger = get_logger(__name__)
+
+
+class GeneralMemCube(BaseMemCube):
+    """MemCube is a box for loading and dumping three types of memories."""
+
+    def __init__(self, config: GeneralMemCubeConfig):
+        """Initialize the MemCube with a configuration."""
+        self.config = config
+        time_start = time.time()
+        self._text_mem: BaseTextMemory | None = (
+            MemoryFactory.from_config(config.text_mem)
+            if config.text_mem.backend != "uninitialized"
+            else None
+        )
+        logger.info(f"init_text_mem in {time.time() - time_start} seconds")
+        self._act_mem: BaseActMemory | None = (
+            MemoryFactory.from_config(config.act_mem)
+            if config.act_mem.backend != "uninitialized"
+            else None
+        )
+        self._para_mem: BaseParaMemory | None = (
+            MemoryFactory.from_config(config.para_mem)
+            if config.para_mem.backend != "uninitialized"
+            else None
+        )
+        self._pref_mem: BaseTextMemory | None = (
+            MemoryFactory.from_config(config.pref_mem)
+            if config.pref_mem.backend != "uninitialized"
+            else None
+        )
+
+    def load(
+        self,
+        dir: str,
+        memory_types: list[Literal["text_mem", "act_mem", "para_mem", "pref_mem"]] | None = None,
+    ) -> None:
+        """Load memories.
+        Args:
+            dir (str): The directory containing the memory files.
+            memory_types (list[str], optional): List of memory types to load.
+                If None, loads all available memory types.
+                Options: ["text_mem", "act_mem", "para_mem", "pref_mem"]
+        """
+        loaded_schema = get_json_file_model_schema(os.path.join(dir, self.config.config_filename))
+        if loaded_schema != self.config.model_schema:
+            raise ConfigurationError(
+                f"Configuration schema mismatch. Expected {self.config.model_schema}, "
+                f"but found {loaded_schema}."
+            )
+
+        # If no specific memory types specified, load all
+        if memory_types is None:
+            memory_types = ["text_mem", "act_mem", "para_mem", "pref_mem"]
+
+        # Load specified memory types
+        if "text_mem" in memory_types and self.text_mem:
+            self.text_mem.load(dir)
+            logger.debug(f"Loaded text_mem from {dir}")
+
+        if "act_mem" in memory_types and self.act_mem:
+            self.act_mem.load(dir)
+            logger.info(f"Loaded act_mem from {dir}")
+
+        if "para_mem" in memory_types and self.para_mem:
+            self.para_mem.load(dir)
+            logger.info(f"Loaded para_mem from {dir}")
+
+        if "pref_mem" in memory_types and self.pref_mem:
+            self.pref_mem.load(dir)
+            logger.info(f"Loaded pref_mem from {dir}")
+
+        logger.info(f"MemCube loaded successfully from {dir} (types: {memory_types})")
+
+    def dump(
+        self,
+        dir: str,
+        memory_types: list[Literal["text_mem", "act_mem", "para_mem", "pref_mem"]] | None = None,
+    ) -> None:
+        """Dump memories.
+        Args:
+            dir (str): The directory where the memory files will be saved.
+            memory_types (list[str], optional): List of memory types to dump.
+                If None, dumps all available memory types.
+                Options: ["text_mem", "act_mem", "para_mem", "pref_mem"]
+        """
+        if os.path.exists(dir) and os.listdir(dir):
+            raise MemCubeError(
+                f"Directory {dir} is not empty. Please provide an empty directory for dumping."
+            )
+
+        # Always dump config
+        self.config.to_json_file(os.path.join(dir, self.config.config_filename))
+
+        # If no specific memory types specified, dump all
+        if memory_types is None:
+            memory_types = ["text_mem", "act_mem", "para_mem", "pref_mem"]
+
+        # Dump specified memory types
+        if "text_mem" in memory_types and self.text_mem:
+            self.text_mem.dump(dir)
+            logger.info(f"Dumped text_mem to {dir}")
+
+        if "act_mem" in memory_types and self.act_mem:
+            self.act_mem.dump(dir)
+            logger.info(f"Dumped act_mem to {dir}")
+
+        if "para_mem" in memory_types and self.para_mem:
+            self.para_mem.dump(dir)
+            logger.info(f"Dumped para_mem to {dir}")
+
+        if "pref_mem" in memory_types and self.pref_mem:
+            self.pref_mem.dump(dir)
+            logger.info(f"Dumped pref_mem to {dir}")
+
+        logger.info(f"MemCube dumped successfully to {dir} (types: {memory_types})")
+
+    @staticmethod
+    def init_from_dir(
+        dir: str,
+        memory_types: list[Literal["text_mem", "act_mem", "para_mem", "pref_mem"]] | None = None,
+        default_config: GeneralMemCubeConfig | None = None,
+    ) -> "GeneralMemCube":
+        """Create a MemCube instance from a MemCube directory.
+
+        Args:
+            dir (str): The directory containing the memory files.
+            memory_types (list[str], optional): List of memory types to load.
+                If None, loads all available memory types.
+            default_config (GeneralMemCubeConfig, optional): Default configuration to merge with existing config.
+                If provided, will merge general settings while preserving critical user-specific fields.
+
+        Returns:
+            MemCube: An instance of MemCube loaded with memories from the specified directory.
+        """
+        config_path = os.path.join(dir, "config.json")
+        config = GeneralMemCubeConfig.from_json_file(config_path)
+
+        # Merge with default config if provided
+        if default_config is not None:
+            config = merge_config_with_default(config, default_config)
+            logger.info(f"Applied default config to cube {config.cube_id}")
+        mem_cube = GeneralMemCube(config)
+        mem_cube.load(dir, memory_types)
+        return mem_cube
+
+    @staticmethod
+    def init_from_remote_repo(
+        cube_id: str,
+        base_url: str = "https://huggingface.co/datasets",
+        memory_types: list[Literal["text_mem", "act_mem", "para_mem", "pref_mem"]] | None = None,
+        default_config: GeneralMemCubeConfig | None = None,
+    ) -> "GeneralMemCube":
+        """Create a MemCube instance from a remote repository.
+
+        Args:
+            cube_id (str): The repository name.
+            base_url (str): The base URL of the remote repository.
+            memory_types (list[str], optional): List of memory types to load.
+                If None, loads all available memory types.
+            default_config (GeneralMemCubeConfig, optional): Default configuration to merge with existing config.
+
+        Returns:
+            MemCube: An instance of MemCube loaded with memories from the specified remote repository.
+        """
+        dir = download_repo(cube_id, base_url)
+        return GeneralMemCube.init_from_dir(dir, memory_types, default_config)
+
+    @property
+    def text_mem(self) -> "BaseTextMemory | None":
+        """Get the textual memory."""
+        if self._text_mem is None:
+            logger.warning("Textual memory is not initialized. Returning None.")
+        return self._text_mem
+
+    @text_mem.setter
+    def text_mem(self, value: BaseTextMemory) -> None:
+        """Set the textual memory."""
+        if not isinstance(value, BaseTextMemory):
+            raise TypeError(f"Expected BaseTextMemory, got {type(value).__name__}")
+        self._text_mem = value
+
+    @property
+    def act_mem(self) -> "BaseActMemory | None":
+        """Get the activation memory."""
+        if self._act_mem is None:
+            logger.warning("Activation memory is not initialized. Returning None.")
+        return self._act_mem
+
+    @act_mem.setter
+    def act_mem(self, value: BaseActMemory) -> None:
+        """Set the activation memory."""
+        if not isinstance(value, BaseActMemory):
+            raise TypeError(f"Expected BaseActMemory, got {type(value).__name__}")
+        self._act_mem = value
+
+    @property
+    def para_mem(self) -> "BaseParaMemory | None":
+        """Get the parametric memory."""
+        if self._para_mem is None:
+            logger.warning("Parametric memory is not initialized. Returning None.")
+        return self._para_mem
+
+    @para_mem.setter
+    def para_mem(self, value: BaseParaMemory) -> None:
+        """Set the parametric memory."""
+        if not isinstance(value, BaseParaMemory):
+            raise TypeError(f"Expected BaseParaMemory, got {type(value).__name__}")
+        self._para_mem = value
+
+    @property
+    def pref_mem(self) -> "BaseTextMemory | None":
+        """Get the preference memory."""
+        if self._pref_mem is None:
+            logger.warning("Preference memory is not initialized. Returning None.")
+        return self._pref_mem
+
+    @pref_mem.setter
+    def pref_mem(self, value: BaseTextMemory) -> None:
+        """Set the preference memory."""
+        if not isinstance(value, BaseTextMemory):
+            raise TypeError(f"Expected BaseTextMemory, got {type(value).__name__}")
+        self._pref_mem = value

memos/mem_cube/navie.py

@@ -0,0 +1,172 @@
+import os
+
+from typing import Literal
+
+from memos.configs.utils import get_json_file_model_schema
+from memos.exceptions import ConfigurationError, MemCubeError
+from memos.log import get_logger
+from memos.mem_cube.base import BaseMemCube
+from memos.memories.activation.base import BaseActMemory
+from memos.memories.parametric.base import BaseParaMemory
+from memos.memories.textual.base import BaseTextMemory
+
+
+logger = get_logger(__name__)
+
+
+class NaiveMemCube(BaseMemCube):
+    """MemCube is a box for loading and dumping three types of memories."""
+
+    def __init__(
+        self,
+        text_mem: BaseTextMemory | None = None,
+        pref_mem: BaseTextMemory | None = None,
+        act_mem: BaseActMemory | None = None,
+        para_mem: BaseParaMemory | None = None,
+    ):
+        """Initialize the MemCube with memory instances."""
+        self._text_mem: BaseTextMemory = text_mem
+        self._act_mem: BaseActMemory | None = act_mem
+        self._para_mem: BaseParaMemory | None = para_mem
+        self._pref_mem: BaseTextMemory | None = pref_mem
+
+    def load(
+        self,
+        dir: str,
+        memory_types: list[Literal["text_mem", "act_mem", "para_mem", "pref_mem"]] | None = None,
+    ) -> None:
+        """Load memories.
+        Args:
+            dir (str): The directory containing the memory files.
+            memory_types (list[str], optional): List of memory types to load.
+                If None, loads all available memory types.
+                Options: ["text_mem", "act_mem", "para_mem", "pref_mem"]
+        """
+        loaded_schema = get_json_file_model_schema(os.path.join(dir, self.config.config_filename))
+        if loaded_schema != self.config.model_schema:
+            raise ConfigurationError(
+                f"Configuration schema mismatch. Expected {self.config.model_schema}, "
+                f"but found {loaded_schema}."
+            )
+
+        # If no specific memory types specified, load all
+        if memory_types is None:
+            memory_types = ["text_mem", "act_mem", "para_mem", "pref_mem"]
+
+        # Load specified memory types
+        if "text_mem" in memory_types and self.text_mem:
+            self.text_mem.load(dir)
+            logger.debug(f"Loaded text_mem from {dir}")
+
+        if "act_mem" in memory_types and self.act_mem:
+            self.act_mem.load(dir)
+            logger.info(f"Loaded act_mem from {dir}")
+
+        if "para_mem" in memory_types and self.para_mem:
+            self.para_mem.load(dir)
+            logger.info(f"Loaded para_mem from {dir}")
+
+        if "pref_mem" in memory_types and self.pref_mem:
+            self.pref_mem.load(dir)
+            logger.info(f"Loaded pref_mem from {dir}")
+
+        logger.info(f"MemCube loaded successfully from {dir} (types: {memory_types})")
+
+    def dump(
+        self,
+        dir: str,
+        memory_types: list[Literal["text_mem", "act_mem", "para_mem", "pref_mem"]] | None = None,
+    ) -> None:
+        """Dump memories.
+        Args:
+            dir (str): The directory where the memory files will be saved.
+            memory_types (list[str], optional): List of memory types to dump.
+                If None, dumps all available memory types.
+                Options: ["text_mem", "act_mem", "para_mem", "pref_mem"]
+        """
+        if os.path.exists(dir) and os.listdir(dir):
+            raise MemCubeError(
+                f"Directory {dir} is not empty. Please provide an empty directory for dumping."
+            )
+
+        # Always dump config
+        self.config.to_json_file(os.path.join(dir, self.config.config_filename))
+
+        # If no specific memory types specified, dump all
+        if memory_types is None:
+            memory_types = ["text_mem", "act_mem", "para_mem", "pref_mem"]
+
+        # Dump specified memory types
+        if "text_mem" in memory_types and self.text_mem:
+            self.text_mem.dump(dir)
+            logger.info(f"Dumped text_mem to {dir}")
+
+        if "act_mem" in memory_types and self.act_mem:
+            self.act_mem.dump(dir)
+            logger.info(f"Dumped act_mem to {dir}")
+
+        if "para_mem" in memory_types and self.para_mem:
+            self.para_mem.dump(dir)
+            logger.info(f"Dumped para_mem to {dir}")
+
+        if "pref_mem" in memory_types and self.pref_mem:
+            self.pref_mem.dump(dir)
+            logger.info(f"Dumped pref_mem to {dir}")
+
+        logger.info(f"MemCube dumped successfully to {dir} (types: {memory_types})")
+
+    @property
+    def text_mem(self) -> "BaseTextMemory | None":
+        """Get the textual memory."""
+        if self._text_mem is None:
+            logger.warning("Textual memory is not initialized. Returning None.")
+        return self._text_mem
+
+    @text_mem.setter
+    def text_mem(self, value: BaseTextMemory) -> None:
+        """Set the textual memory."""
+        if not isinstance(value, BaseTextMemory):
+            raise TypeError(f"Expected BaseTextMemory, got {type(value).__name__}")
+        self._text_mem = value
+
+    @property
+    def act_mem(self) -> "BaseActMemory | None":
+        """Get the activation memory."""
+        if self._act_mem is None:
+            logger.warning("Activation memory is not initialized. Returning None.")
+        return self._act_mem
+
+    @act_mem.setter
+    def act_mem(self, value: BaseActMemory) -> None:
+        """Set the activation memory."""
+        if not isinstance(value, BaseActMemory):
+            raise TypeError(f"Expected BaseActMemory, got {type(value).__name__}")
+        self._act_mem = value
+
+    @property
+    def para_mem(self) -> "BaseParaMemory | None":
+        """Get the parametric memory."""
+        if self._para_mem is None:
+            logger.warning("Parametric memory is not initialized. Returning None.")
+        return self._para_mem
+
+    @para_mem.setter
+    def para_mem(self, value: BaseParaMemory) -> None:
+        """Set the parametric memory."""
+        if not isinstance(value, BaseParaMemory):
+            raise TypeError(f"Expected BaseParaMemory, got {type(value).__name__}")
+        self._para_mem = value
+
+    @property
+    def pref_mem(self) -> "BaseTextMemory | None":
+        """Get the preference memory."""
+        if self._pref_mem is None:
+            logger.warning("Preference memory is not initialized. Returning None.")
+        return self._pref_mem
+
+    @pref_mem.setter
+    def pref_mem(self, value: BaseTextMemory) -> None:
+        """Set the preference memory."""
+        if not isinstance(value, BaseTextMemory):
+            raise TypeError(f"Expected BaseTextMemory, got {type(value).__name__}")
+        self._pref_mem = value

memos/mem_cube/utils.py

@@ -0,0 +1,169 @@
+import copy
+import logging
+import subprocess
+import tempfile
+
+from memos.configs.mem_cube import GeneralMemCubeConfig
+
+
+logger = logging.getLogger(__name__)
+
+
+def download_repo(repo: str, base_url: str, dir: str | None = None) -> str:
+    """Download a repository from a remote source.
+
+    Args:
+        repo (str): The repository name.
+        base_url (str): The base URL of the remote repository.
+        dir (str, optional): The directory where the repository will be downloaded. If None, a temporary directory will be created.
+    If a directory is provided, it will be used instead of creating a temporary one.
+
+    Returns:
+        str: The local directory where the repository is downloaded.
+    """
+    if dir is None:
+        dir = tempfile.mkdtemp()
+    repo_url = f"{base_url}/{repo}"
+
+    # Clone the repo
+    subprocess.run(["git", "clone", repo_url, dir], check=True)
+
+    return dir
+
+
+def merge_config_with_default(
+    existing_config: GeneralMemCubeConfig, default_config: GeneralMemCubeConfig
+) -> GeneralMemCubeConfig:
+    """
+    Merge existing cube config with default config, preserving critical fields.
+
+    This method updates general configuration fields (like API keys, model parameters)
+    while preserving critical user-specific fields (like user_id, cube_id, graph_db settings).
+
+    Args:
+        existing_config (GeneralMemCubeConfig): The existing cube configuration loaded from file
+        default_config (GeneralMemCubeConfig): The default configuration to merge from
+
+    Returns:
+        GeneralMemCubeConfig: Merged configuration
+    """
+
+    # Convert configs to dictionaries
+    existing_dict = existing_config.model_dump(mode="json")
+    default_dict = default_config.model_dump(mode="json")
+
+    logger.info(
+        f"Starting config merge for user {existing_config.user_id}, cube {existing_config.cube_id}"
+    )
+
+    # Define fields that should be preserved from existing config
+    preserve_fields = {"user_id", "cube_id", "config_filename", "model_schema"}
+
+    # Preserve graph_db from existing config if it exists, but merge some fields
+    preserved_graph_db = None
+    if "text_mem" in existing_dict and "text_mem" in default_dict:
+        existing_text_config = existing_dict["text_mem"].get("config", {})
+        default_text_config = default_dict["text_mem"].get("config", {})
+
+        if "graph_db" in existing_text_config and "graph_db" in default_text_config:
+            existing_graph_config = existing_text_config["graph_db"]["config"]
+            default_graph_config = default_text_config["graph_db"]["config"]
+            existing_backend = existing_text_config["graph_db"]["backend"]
+            default_backend = default_text_config["graph_db"]["backend"]
+
+            # Detect backend change
+            backend_changed = existing_backend != default_backend
+
+            if backend_changed:
+                logger.info(
+                    f"Detected graph_db backend change: {existing_backend} -> {default_backend}. "
+                    f"Migrating configuration..."
+                )
+                # Start with default config as base when backend changes
+                merged_graph_config = copy.deepcopy(default_graph_config)
+
+                # Preserve user-specific fields if they exist in both configs
+                preserve_graph_fields = {
+                    "auto_create",
+                    "user_name",
+                    "use_multi_db",
+                }
+                for field in preserve_graph_fields:
+                    if field in existing_graph_config:
+                        merged_graph_config[field] = existing_graph_config[field]
+                        logger.debug(
+                            f"Preserved graph_db field '{field}': {existing_graph_config[field]}"
+                        )
+
+                # Clean up backend-specific fields that don't exist in the new backend
+                # This approach is generic: remove any field from merged config that's not in default config
+                # and not in the preserve list
+                fields_to_remove = []
+                for field in list(merged_graph_config.keys()):
+                    if field not in default_graph_config and field not in preserve_graph_fields:
+                        fields_to_remove.append(field)
+
+                for field in fields_to_remove:
+                    removed_value = merged_graph_config.pop(field)
+                    logger.info(
+                        f"Removed {existing_backend}-specific field '{field}' (value: {removed_value}) "
+                        f"during migration to {default_backend}"
+                    )
+            else:
+                # Same backend: merge configs while preserving user-specific fields
+                logger.debug(f"Same graph_db backend ({default_backend}), merging configurations")
+                preserve_graph_fields = {
+                    "auto_create",
+                    "user_name",
+                    "use_multi_db",
+                }
+
+                # Start with existing config as base
+                merged_graph_config = copy.deepcopy(existing_graph_config)
+
+                # Update with default config except preserved fields
+                for key, value in default_graph_config.items():
+                    if key not in preserve_graph_fields:
+                        merged_graph_config[key] = value
+                        logger.debug(
+                            f"Updated graph_db field '{key}': {existing_graph_config.get(key)} -> {value}"
+                        )
+
+                # Handle use_multi_db transition
+                if not default_graph_config.get("use_multi_db", True) and merged_graph_config.get(
+                    "use_multi_db", True
+                ):
+                    merged_graph_config["use_multi_db"] = False
+                    # For Neo4j: db_name becomes user_name in single-db mode
+                    if "neo4j" in default_backend and "db_name" in merged_graph_config:
+                        merged_graph_config["user_name"] = merged_graph_config.get("db_name")
+                        merged_graph_config["db_name"] = default_graph_config.get("db_name")
+                    logger.info("Transitioned to single-db mode (use_multi_db=False)")
+
+            preserved_graph_db = {
+                "backend": default_backend,
+                "config": merged_graph_config,
+            }
+
+    # Use default config as base
+    merged_dict = copy.deepcopy(default_dict)
+
+    # Restore preserved fields from existing config
+    for field in preserve_fields:
+        if field in existing_dict:
+            merged_dict[field] = existing_dict[field]
+            logger.debug(f"Preserved field '{field}': {existing_dict[field]}")
+
+    # Restore graph_db if it was preserved
+    if preserved_graph_db and "text_mem" in merged_dict:
+        merged_dict["text_mem"]["config"]["graph_db"] = preserved_graph_db
+        logger.debug(f"Preserved graph_db with merged config: {preserved_graph_db}")
+
+    # Create new config from merged dictionary
+    merged_config = GeneralMemCubeConfig.model_validate(merged_dict)
+
+    logger.info(
+        f"Successfully merged cube config for user {merged_config.user_id}, cube {merged_config.cube_id}"
+    )
+
+    return merged_config

memos/mem_feedback/base.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+
+from memos.configs.memory import MemFeedbackConfig
+
+
+class BaseMemFeedback(ABC):
+    """MemFeedback interface class for reading information."""
+
+    @abstractmethod
+    def __init__(self, config: MemFeedbackConfig):
+        """Initialize the MemFeedback with the given configuration."""
+
+    @abstractmethod
+    def process_feedback(self, data: dict) -> None:
+        """Process user's feedback"""