MemoryOS 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

memos/configs/embedder.py

@@ -18,6 +18,18 @@ class OllamaEmbedderConfig(BaseEmbedderConfig):
     api_base: str = Field(default="http://localhost:11434", description="Base URL for Ollama API")
 
 
+class ArkEmbedderConfig(BaseEmbedderConfig):
+    api_key: str = Field(..., description="Ark API key")
+    api_base: str = Field(
+        default="https://ark.cn-beijing.volces.com/api/v3/", description="Base URL for Ark API"
+    )
+    chunk_size: int = Field(default=1, description="Chunk size for Ark API")
+    multi_modal: bool = Field(
+        default=False,
+        description="Whether to use multi-modal embedding (text + image) with Ark",
+    )
+
+
 class SenTranEmbedderConfig(BaseEmbedderConfig):
     """Configuration class for Sentence Transformer embeddings."""
 
@@ -27,6 +39,19 @@ class SenTranEmbedderConfig(BaseEmbedderConfig):
     )
 
 
+class UniversalAPIEmbedderConfig(BaseEmbedderConfig):
+    """
+    Configuration class for universal API embedding providers, e.g.,
+    OpenAI, etc.
+    """
+
+    provider: str = Field(..., description="Provider name, e.g., 'openai'")
+    api_key: str = Field(..., description="API key for the embedding provider")
+    base_url: str | None = Field(
+        default=None, description="Optional base URL for custom or proxied endpoint"
+    )
+
+
 class EmbedderConfigFactory(BaseConfig):
     """Factory class for creating embedder configurations."""
 
@@ -36,6 +61,8 @@ class EmbedderConfigFactory(BaseConfig):
     backend_to_class: ClassVar[dict[str, Any]] = {
         "ollama": OllamaEmbedderConfig,
         "sentence_transformer": SenTranEmbedderConfig,
+        "ark": ArkEmbedderConfig,
+        "universal_api": UniversalAPIEmbedderConfig,
     }
 
     @field_validator("backend")

memos/configs/graph_db.py

@@ -3,25 +3,152 @@ from typing import Any, ClassVar
 from pydantic import BaseModel, Field, field_validator, model_validator
 
 from memos.configs.base import BaseConfig
+from memos.configs.vec_db import VectorDBConfigFactory
 
 
 class BaseGraphDBConfig(BaseConfig):
     """Base class for all graph database configurations."""
 
-    uri: str
+    uri: str | list
     user: str
     password: str
 
 
 class Neo4jGraphDBConfig(BaseGraphDBConfig):
-    """Neo4j-specific configuration."""
+    """
+    Neo4j-specific configuration.
+
+    This config supports:
+    1) Physical isolation (multi-db) — each user gets a dedicated Neo4j database.
+    2) Logical isolation (single-db) — all users share one or more databases, but each node is tagged with `user_name`.
+
+    How to use:
+    - If `use_multi_db=True`, then `db_name` should usually be the same as `user_name`.
+      Each user gets a separate database for physical isolation.
+      Example: db_name = "alice", user_name = None or "alice".
+
+    - If `use_multi_db=False`, then `db_name` is your shared database (e.g., "neo4j" or "shared_db").
+      You must provide `user_name` to logically isolate each user's data.
+      All nodes and queries must respect this tag.
+
+    Example configs:
+    ---
+    # Physical isolation:
+    db_name = "alice"
+    use_multi_db = True
+    user_name = None
+
+    # Logical isolation:
+    db_name = "shared_db_student_group"
+    use_multi_db = False
+    user_name = "alice"
+    """
 
     db_name: str = Field(..., description="The name of the target Neo4j database")
     auto_create: bool = Field(
-        default=False, description="Whether to create the DB if it doesn't exist"
+        default=False,
+        description="If True, automatically create the target db_name in multi-db mode if it does not exist.",
+    )
+
+    use_multi_db: bool = Field(
+        default=True,
+        description=(
+            "If True: use Neo4j's multi-database feature for physical isolation; "
+            "each user typically gets a separate database. "
+            "If False: use a single shared database with logical isolation by user_name."
+        ),
+    )
+
+    user_name: str | None = Field(
+        default=None,
+        description=(
+            "Logical user or tenant ID for data isolation. "
+            "Required if use_multi_db is False. "
+            "All nodes must be tagged with this and all queries must filter by this."
+        ),
     )
+
     embedding_dimension: int = Field(default=768, description="Dimension of vector embedding")
 
+    @model_validator(mode="after")
+    def validate_config(self):
+        """Validate logical constraints to avoid misconfiguration."""
+        if not self.use_multi_db and not self.user_name:
+            raise ValueError(
+                "In single-database mode (use_multi_db=False), `user_name` must be provided for logical isolation."
+            )
+        return self
+
+
+class Neo4jCommunityGraphDBConfig(Neo4jGraphDBConfig):
+    """
+    Community edition config for Neo4j.
+
+    Notes:
+    - Must set `use_multi_db = False`
+    - Must provide `user_name` for logical isolation
+    - Embedding vector DB config is required
+    """
+
+    vec_config: VectorDBConfigFactory = Field(
+        ..., description="Vector DB config for embedding search"
+    )
+
+    @model_validator(mode="after")
+    def validate_community(self):
+        if self.use_multi_db:
+            raise ValueError("Neo4j Community Edition does not support use_multi_db=True.")
+        if not self.user_name:
+            raise ValueError("Neo4j Community config requires user_name for logical isolation.")
+        return self
+
+
+class NebulaGraphDBConfig(BaseGraphDBConfig):
+    """
+    NebulaGraph-specific configuration.
+
+    Key concepts:
+    - `space`: Equivalent to a database or namespace. All tag/edge/schema live within a space.
+    - `user_name`: Used for logical tenant isolation if needed.
+    - `auto_create`: Whether to automatically create the target space if it does not exist.
+
+    Example:
+    ---
+    hosts = ["127.0.0.1:9669"]
+    user = "root"
+    password = "nebula"
+    space = "shared_graph"
+    user_name = "alice"
+    """
+
+    space: str = Field(
+        ..., description="The name of the target NebulaGraph space (like a database)"
+    )
+    user_name: str | None = Field(
+        default=None,
+        description="Logical user or tenant ID for data isolation (optional, used in metadata tagging)",
+    )
+    auto_create: bool = Field(
+        default=False,
+        description="Whether to auto-create the space if it does not exist",
+    )
+    use_multi_db: bool = Field(
+        default=True,
+        description=(
+            "If True: use Neo4j's multi-database feature for physical isolation; "
+            "each user typically gets a separate database. "
+            "If False: use a single shared database with logical isolation by user_name."
+        ),
+    )
+    embedding_dimension: int = Field(default=3072, description="Dimension of vector embedding")
+
+    @model_validator(mode="after")
+    def validate_config(self):
+        """Validate config."""
+        if not self.space:
+            raise ValueError("`space` must be provided")
+        return self
+
 
 class GraphDBConfigFactory(BaseModel):
     backend: str = Field(..., description="Backend for graph database")
@@ -29,6 +156,8 @@ class GraphDBConfigFactory(BaseModel):
 
     backend_to_class: ClassVar[dict[str, Any]] = {
         "neo4j": Neo4jGraphDBConfig,
+        "neo4j-community": Neo4jCommunityGraphDBConfig,
+        "nebular": NebulaGraphDBConfig,
     }
 
     @field_validator("backend")

memos/configs/internet_retriever.py

@@ -6,6 +6,7 @@ from pydantic import Field, field_validator, model_validator
 
 from memos.configs.base import BaseConfig
 from memos.exceptions import ConfigurationError
+from memos.mem_reader.factory import MemReaderConfigFactory
 
 
 class BaseInternetRetrieverConfig(BaseConfig):
@@ -47,6 +48,11 @@ class XinyuSearchConfig(BaseInternetRetrieverConfig):
     num_per_request: int = Field(
         default=10, description="Number of results per API request (not used for Xinyu)"
     )
+    reader: MemReaderConfigFactory = Field(
+        ...,
+        default_factory=MemReaderConfigFactory,
+        description="Reader configuration",
+    )
 
 
 class InternetRetrieverConfigFactory(BaseConfig):

memos/configs/llm.py

@@ -27,6 +27,40 @@ class OpenAILLMConfig(BaseLLMConfig):
     extra_body: Any = Field(default=None, description="extra body")
 
 
+class QwenLLMConfig(BaseLLMConfig):
+    api_key: str = Field(..., description="API key for DashScope (Qwen)")
+    api_base: str = Field(
+        default="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
+        description="Base URL for Qwen OpenAI-compatible API",
+    )
+    extra_body: Any = Field(default=None, description="extra body")
+    model_name_or_path: str = Field(..., description="Model name for Qwen, e.g., 'qwen-plus'")
+
+
+class DeepSeekLLMConfig(BaseLLMConfig):
+    api_key: str = Field(..., description="API key for DeepSeek")
+    api_base: str = Field(
+        default="https://api.deepseek.com",
+        description="Base URL for DeepSeek OpenAI-compatible API",
+    )
+    extra_body: Any = Field(default=None, description="Extra options for API")
+    model_name_or_path: str = Field(
+        ..., description="Model name: 'deepseek-chat' or 'deepseek-reasoner'"
+    )
+
+
+class AzureLLMConfig(BaseLLMConfig):
+    base_url: str = Field(
+        default="https://api.openai.azure.com/",
+        description="Base URL for Azure OpenAI API",
+    )
+    api_version: str = Field(
+        default="2024-03-01-preview",
+        description="API version for Azure OpenAI",
+    )
+    api_key: str = Field(..., description="API key for Azure OpenAI")
+
+
 class OllamaLLMConfig(BaseLLMConfig):
     api_base: str = Field(
         default="http://localhost:11434",
@@ -45,6 +79,14 @@ class HFLLMConfig(BaseLLMConfig):
     )
 
 
+class VLLMLLMConfig(BaseLLMConfig):
+    api_key: str = Field(default="", description="API key for vLLM (optional for local server)")
+    api_base: str = Field(
+        default="http://localhost:8088/v1",
+        description="Base URL for vLLM API",
+    )
+
+
 class LLMConfigFactory(BaseConfig):
     """Factory class for creating LLM configurations."""
 
@@ -54,7 +96,12 @@ class LLMConfigFactory(BaseConfig):
     backend_to_class: ClassVar[dict[str, Any]] = {
         "openai": OpenAILLMConfig,
         "ollama": OllamaLLMConfig,
+        "azure": AzureLLMConfig,
         "huggingface": HFLLMConfig,
+        "vllm": VLLMLLMConfig,
+        "huggingface_singleton": HFLLMConfig,  # Add singleton support
+        "qwen": QwenLLMConfig,
+        "deepseek": DeepSeekLLMConfig,
     }
 
     @field_validator("backend")

memos/configs/mem_cube.py

@@ -70,7 +70,7 @@ class GeneralMemCubeConfig(BaseMemCubeConfig):
     @classmethod
     def validate_act_mem(cls, act_mem: MemoryConfigFactory) -> MemoryConfigFactory:
         """Validate the act_mem field."""
-        allowed_backends = ["kv_cache", "uninitialized"]
+        allowed_backends = ["kv_cache", "vllm_kv_cache", "uninitialized"]
         if act_mem.backend not in allowed_backends:
             raise ConfigurationError(
                 f"GeneralMemCubeConfig requires act_mem backend to be one of {allowed_backends}, got '{act_mem.backend}'"

memos/configs/mem_os.py

@@ -8,6 +8,7 @@ from memos.configs.base import BaseConfig
 from memos.configs.llm import LLMConfigFactory
 from memos.configs.mem_reader import MemReaderConfigFactory
 from memos.configs.mem_scheduler import SchedulerConfigFactory
+from memos.configs.mem_user import UserManagerConfigFactory
 
 
 class MOSConfig(BaseConfig):
@@ -33,6 +34,10 @@ class MOSConfig(BaseConfig):
         default=None,
         description="Memory scheduler configuration for managing memory operations",
     )
+    user_manager: UserManagerConfigFactory = Field(
+        default_factory=lambda: UserManagerConfigFactory(backend="sqlite", config={}),
+        description="User manager configuration for database operations",
+    )
     max_turns_window: int = Field(
         default=15,
         description="Maximum number of turns to keep in the conversation history",

memos/configs/mem_reader.py

@@ -15,6 +15,15 @@ class BaseMemReaderConfig(BaseConfig):
     created_at: datetime = Field(
         default_factory=datetime.now, description="Creation timestamp for the MemReader"
     )
+
+    @field_validator("created_at", mode="before")
+    @classmethod
+    def parse_datetime(cls, value):
+        """Parse datetime from string if needed."""
+        if isinstance(value, str):
+            return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        return value
+
     llm: LLMConfigFactory = Field(..., description="LLM configuration for the MemReader")
     embedder: EmbedderConfigFactory = Field(
         ..., description="Embedder configuration for the MemReader"

memos/configs/mem_scheduler.py

@@ -1,11 +1,15 @@
+import os
+
+from pathlib import Path
 from typing import Any, ClassVar
 
 from pydantic import ConfigDict, Field, field_validator, model_validator
 
 from memos.configs.base import BaseConfig
-from memos.mem_scheduler.modules.schemas import (
+from memos.mem_scheduler.modules.misc import DictConversionMixin
+from memos.mem_scheduler.schemas.general_schemas import (
+    BASE_DIR,
     DEFAULT_ACT_MEM_DUMP_PATH,
-    DEFAULT_ACTIVATION_MEM_SIZE,
     DEFAULT_CONSUME_INTERVAL_SECONDS,
     DEFAULT_THREAD__POOL_MAX_WORKERS,
 )
@@ -17,6 +21,7 @@ class BaseSchedulerConfig(BaseConfig):
     top_k: int = Field(
         default=10, description="Number of top candidates to consider in initial retrieval"
     )
+    # TODO: The 'top_n' field is deprecated and will be removed in future versions.
     top_n: int = Field(default=5, description="Number of final results to return after processing")
     enable_parallel_dispatch: bool = Field(
         default=True, description="Whether to enable parallel message processing using thread pool"
@@ -33,6 +38,10 @@ class BaseSchedulerConfig(BaseConfig):
         le=60,
         description=f"Interval for consuming messages from queue in seconds (default: {DEFAULT_CONSUME_INTERVAL_SECONDS})",
     )
+    auth_config_path: str | None = Field(
+        default=None,
+        description="Path to the authentication configuration file containing private credentials",
+    )
 
 
 class GeneralSchedulerConfig(BaseSchedulerConfig):
@@ -40,16 +49,15 @@ class GeneralSchedulerConfig(BaseSchedulerConfig):
         default=300, description="Interval in seconds for updating activation memory"
     )
     context_window_size: int | None = Field(
-        default=5, description="Size of the context window for conversation history"
-    )
-    activation_mem_size: int | None = Field(
-        default=DEFAULT_ACTIVATION_MEM_SIZE,  # Assuming DEFAULT_ACTIVATION_MEM_SIZE is 1000
-        description="Maximum size of the activation memory",
+        default=10, description="Size of the context window for conversation history"
     )
     act_mem_dump_path: str | None = Field(
         default=DEFAULT_ACT_MEM_DUMP_PATH,  # Replace with DEFAULT_ACT_MEM_DUMP_PATH
         description="File path for dumping activation memory",
     )
+    enable_act_memory_update: bool = Field(
+        default=False, description="Whether to enable automatic activation memory updates"
+    )
 
 
 class SchedulerConfigFactory(BaseConfig):
@@ -76,3 +84,95 @@ class SchedulerConfigFactory(BaseConfig):
         config_class = self.backend_to_class[self.backend]
         self.config = config_class(**self.config)
         return self
+
+
+# ************************* Auth *************************
+class RabbitMQConfig(
+    BaseConfig,
+):
+    host_name: str = Field(default="", description="Endpoint for RabbitMQ instance access")
+    user_name: str = Field(default="", description="Static username for RabbitMQ instance")
+    password: str = Field(default="", description="Password for the static username")
+    virtual_host: str = Field(default="", description="Vhost name for RabbitMQ instance")
+    erase_on_connect: bool = Field(
+        default=True, description="Whether to clear connection state or buffers upon connecting"
+    )
+    port: int = Field(
+        default=5672,
+        description="Port number for RabbitMQ instance access",
+        ge=1,  # Port must be >= 1
+        le=65535,  # Port must be <= 65535
+    )
+
+
+class GraphDBAuthConfig(BaseConfig):
+    uri: str = Field(
+        default="bolt://localhost:7687",
+        description="URI for graph database access (e.g., bolt://host:port)",
+    )
+    user: str = Field(default="neo4j", description="Username for graph database authentication")
+    password: str = Field(
+        default="",
+        description="Password for graph database authentication",
+        min_length=8,  # 建议密码最小长度
+    )
+    db_name: str = Field(default="neo4j", description="Database name to connect to")
+    auto_create: bool = Field(
+        default=True, description="Whether to automatically create the database if it doesn't exist"
+    )
+
+
+class OpenAIConfig(BaseConfig):
+    api_key: str = Field(default="", description="API key for OpenAI service")
+    base_url: str = Field(default="", description="Base URL for API endpoint")
+    default_model: str = Field(default="", description="Default model to use")
+
+
+class AuthConfig(BaseConfig, DictConversionMixin):
+    rabbitmq: RabbitMQConfig
+    openai: OpenAIConfig
+    graph_db: GraphDBAuthConfig
+    default_config_path: ClassVar[str] = (
+        f"{BASE_DIR}/examples/data/config/mem_scheduler/scheduler_auth.yaml"
+    )
+
+    @classmethod
+    def from_local_yaml(cls, config_path: str | None = None) -> "AuthConfig":
+        """
+        Load configuration from YAML file
+
+        Args:
+            config_path: Path to YAML configuration file
+
+        Returns:
+            AuthConfig instance
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+            ValueError: If YAML parsing or validation fails
+        """
+
+        if config_path is None:
+            config_path = cls.default_config_path
+
+        # Check file exists
+        if not Path(config_path).exists():
+            raise FileNotFoundError(f"Config file not found: {config_path}")
+
+        return cls.from_yaml_file(yaml_path=config_path)
+
+    def set_openai_config_to_environment(self):
+        # Set environment variables
+        os.environ["OPENAI_API_KEY"] = self.openai.api_key
+        os.environ["OPENAI_BASE_URL"] = self.openai.base_url
+        os.environ["MODEL"] = self.openai.default_model
+
+    @classmethod
+    def default_config_exists(cls) -> bool:
+        """
+        Check if the default configuration file exists.
+
+        Returns:
+            bool: True if the default config file exists, False otherwise
+        """
+        return Path(cls.default_config_path).exists()

memos/configs/mem_user.py

@@ -0,0 +1,58 @@
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from memos.configs.base import BaseConfig
+
+
+class BaseUserManagerConfig(BaseConfig):
+    """Base configuration class for user managers."""
+
+    user_id: str = Field(default="root", description="Default user ID for initialization")
+
+
+class SQLiteUserManagerConfig(BaseUserManagerConfig):
+    """SQLite user manager configuration."""
+
+    db_path: str | None = Field(
+        default=None,
+        description="Path to SQLite database file. If None, uses default path in MEMOS_DIR",
+    )
+
+
+class MySQLUserManagerConfig(BaseUserManagerConfig):
+    """MySQL user manager configuration."""
+
+    host: str = Field(default="localhost", description="MySQL server host")
+    port: int = Field(default=3306, description="MySQL server port")
+    username: str = Field(default="root", description="MySQL username")
+    password: str = Field(default="", description="MySQL password")
+    database: str = Field(default="memos_users", description="MySQL database name")
+    charset: str = Field(default="utf8mb4", description="MySQL charset")
+
+
+class UserManagerConfigFactory(BaseModel):
+    """Factory for user manager configurations."""
+
+    backend: str = Field(default="sqlite", description="Backend for user manager")
+    config: dict[str, Any] = Field(
+        default_factory=dict, description="Configuration for the user manager backend"
+    )
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "sqlite": SQLiteUserManagerConfig,
+        "mysql": MySQLUserManagerConfig,
+    }
+
+    @field_validator("backend")
+    @classmethod
+    def validate_backend(cls, backend: str) -> str:
+        if backend not in cls.backend_to_class:
+            raise ValueError(f"Unsupported user manager backend: {backend}")
+        return backend
+
+    @model_validator(mode="after")
+    def instantiate_config(self):
+        config_class = self.backend_to_class[self.backend]
+        self.config = config_class(**self.config)
+        return self

memos/configs/memory.py

@@ -52,9 +52,9 @@ class KVCacheMemoryConfig(BaseActMemoryConfig):
     @classmethod
     def validate_extractor_llm(cls, extractor_llm: LLMConfigFactory) -> LLMConfigFactory:
         """Validate the extractor_llm field."""
-        if extractor_llm.backend != "huggingface":
+        if extractor_llm.backend not in ["huggingface", "huggingface_singleton", "vllm"]:
             raise ConfigurationError(
-                f"KVCacheMemoryConfig requires extractor_llm backend to be 'huggingface', got '{extractor_llm.backend}'"
+                f"KVCacheMemoryConfig requires extractor_llm backend to be 'huggingface' or 'huggingface_singleton', got '{extractor_llm.backend}'"
             )
         return extractor_llm
 
@@ -84,9 +84,9 @@ class LoRAMemoryConfig(BaseParaMemoryConfig):
     @classmethod
     def validate_extractor_llm(cls, extractor_llm: LLMConfigFactory) -> LLMConfigFactory:
         """Validate the extractor_llm field."""
-        if extractor_llm.backend not in ["huggingface"]:
+        if extractor_llm.backend not in ["huggingface", "huggingface_singleton"]:
             raise ConfigurationError(
-                f"LoRAMemoryConfig requires extractor_llm backend to be 'huggingface', got '{extractor_llm.backend}'"
+                f"LoRAMemoryConfig requires extractor_llm backend to be 'huggingface' or 'huggingface_singleton', got '{extractor_llm.backend}'"
             )
         return extractor_llm
 
@@ -181,6 +181,7 @@ class MemoryConfigFactory(BaseConfig):
         "general_text": GeneralTextMemoryConfig,
         "tree_text": TreeTextMemoryConfig,
         "kv_cache": KVCacheMemoryConfig,
+        "vllm_kv_cache": KVCacheMemoryConfig,  # Use same config as kv_cache
         "lora": LoRAMemoryConfig,
         "uninitialized": UninitializedMemoryConfig,
     }

memos/dependency.py

@@ -0,0 +1,52 @@
+"""
+This utility provides tools for managing dependencies in MemOS.
+"""
+
+import functools
+import importlib
+
+
+def require_python_package(
+    import_name: str, install_command: str | None = None, install_link: str | None = None
+):
+    """Check if a package is available and provide installation hints on import failure.
+
+    Args:
+        import_name (str): The top-level importable module name a package provides.
+        install_command (str, optional): Installation command.
+        install_link (str, optional): URL link to installation guide.
+
+    Returns:
+        Callable: A decorator function that wraps the target function with package availability check.
+
+    Raises:
+        ImportError: When the specified package is not available, with installation
+            instructions included in the error message.
+
+    Example:
+        >>> @require_python_package(
+        ...     import_name='faiss',
+        ...     install_command='pip install faiss-cpu',
+        ...     install_link='https://github.com/facebookresearch/faiss/blob/main/INSTALL.md'
+        ... )
+        ... def create_faiss_index():
+        ...     from faiss import IndexFlatL2  # Actual import in function
+        ...     return IndexFlatL2(128)
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                importlib.import_module(import_name)
+            except ImportError:
+                error_msg = f"Missing required module - '{import_name}'\n"
+                error_msg += f"💡 Install command: {install_command}\n" if install_command else ""
+                error_msg += f"💡 Install guide:   {install_link}\n" if install_link else ""
+
+                raise ImportError(error_msg) from None
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator