MemoryOS 0.0.1__py3-none-any.whl → 0.1.12__py3-none-any.whl

memos/configs/graph_db.py

@@ -0,0 +1,45 @@
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from memos.configs.base import BaseConfig
+
+
+class BaseGraphDBConfig(BaseConfig):
+    """Base class for all graph database configurations."""
+
+    uri: str
+    user: str
+    password: str
+
+
+class Neo4jGraphDBConfig(BaseGraphDBConfig):
+    """Neo4j-specific configuration."""
+
+    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"
+    )
+    embedding_dimension: int = Field(default=768, description="Dimension of vector embedding")
+
+
+class GraphDBConfigFactory(BaseModel):
+    backend: str = Field(..., description="Backend for graph database")
+    config: dict[str, Any] = Field(..., description="Configuration for the graph database backend")
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "neo4j": Neo4jGraphDBConfig,
+    }
+
+    @field_validator("backend")
+    @classmethod
+    def validate_backend(cls, backend: str) -> str:
+        if backend not in cls.backend_to_class:
+            raise ValueError(f"Unsupported graph db 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/llm.py

@@ -0,0 +1,71 @@
+from typing import Any, ClassVar
+
+from pydantic import Field, field_validator, model_validator
+
+from memos.configs.base import BaseConfig
+
+
+class BaseLLMConfig(BaseConfig):
+    """Base configuration class for LLMs."""
+
+    model_name_or_path: str = Field(..., description="Model name or path")
+    temperature: float = Field(default=0.8, description="Temperature for sampling")
+    max_tokens: int = Field(default=1024, description="Maximum number of tokens to generate")
+    top_p: float = Field(default=0.9, description="Top-p sampling parameter")
+    top_k: int = Field(default=50, description="Top-k sampling parameter")
+    remove_think_prefix: bool = Field(
+        default=False,
+        description="Remove content within think tags from the generated text",
+    )
+
+
+class OpenAILLMConfig(BaseLLMConfig):
+    api_key: str = Field(..., description="API key for OpenAI")
+    api_base: str = Field(
+        default="https://api.openai.com/v1", description="Base URL for OpenAI API"
+    )
+
+
+class OllamaLLMConfig(BaseLLMConfig):
+    api_base: str = Field(
+        default="http://localhost:11434",
+        description="Base URL for Ollama API",
+    )
+
+
+class HFLLMConfig(BaseLLMConfig):
+    do_sample: bool = Field(
+        default=False,
+        description="Whether to use sampling (if False, always greedy/argmax decoding)",
+    )
+    add_generation_prompt: bool = Field(
+        default=True,
+        description="Apply generation template for the conversation",
+    )
+
+
+class LLMConfigFactory(BaseConfig):
+    """Factory class for creating LLM configurations."""
+
+    backend: str = Field(..., description="Backend for LLM")
+    config: dict[str, Any] = Field(..., description="Configuration for the LLM backend")
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "openai": OpenAILLMConfig,
+        "ollama": OllamaLLMConfig,
+        "huggingface": HFLLMConfig,
+    }
+
+    @field_validator("backend")
+    @classmethod
+    def validate_backend(cls, backend: str) -> str:
+        """Validate the backend field."""
+        if backend not in cls.backend_to_class:
+            raise ValueError(f"Invalid backend: {backend}")
+        return backend
+
+    @model_validator(mode="after")
+    def create_config(self) -> "LLMConfigFactory":
+        config_class = self.backend_to_class[self.backend]
+        self.config = config_class(**self.config)
+        return self

memos/configs/mem_chat.py

@@ -0,0 +1,81 @@
+import uuid
+
+from datetime import datetime
+from typing import Any, ClassVar
+
+from pydantic import Field, field_validator, model_validator
+
+from memos.configs.base import BaseConfig
+from memos.configs.llm import LLMConfigFactory
+
+
+class BaseMemChatConfig(BaseConfig):
+    """Base configuration class for MemChat."""
+
+    user_id: str = Field(..., description="User ID for the MemChat")
+    session_id: str = Field(
+        default_factory=lambda: str(uuid.uuid4()), description="Session ID for the MemChat"
+    )
+    created_at: datetime = Field(
+        default_factory=datetime.now,
+        description="Creation timestamp for the MemChat",
+    )
+    config_filename: str = Field(
+        default="config.json",
+        description="Filename for storing the MemChat configuration",
+    )
+
+
+class SimpleMemChatConfig(BaseMemChatConfig):
+    """Simple MemChat configuration class."""
+
+    chat_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the MemChat",
+    )
+    max_turns_window: int = Field(
+        default=15,
+        description="Maximum number of turns to keep in the conversation history",
+    )
+    top_k: int = Field(
+        default=5,
+        description="Maximum number of memories to retrieve for each query",
+    )
+    enable_textual_memory: bool = Field(
+        default=False,
+        description="Enable textual memory for the MemChat",
+    )
+    enable_activation_memory: bool = Field(
+        default=False,
+        description="Enable activation memory for the MemChat",
+    )
+    enable_parametric_memory: bool = Field(
+        default=False,
+        description="Enable parametric memory for the MemChat",
+    )
+
+
+class MemChatConfigFactory(BaseConfig):
+    """Factory class for creating MemChat configurations."""
+
+    backend: str = Field(..., description="Backend for MemChat")
+    config: dict[str, Any] = Field(..., description="Configuration for the MemChat backend")
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "simple": SimpleMemChatConfig,
+    }
+
+    @field_validator("backend")
+    @classmethod
+    def validate_backend(cls, backend: str) -> str:
+        """Validate the backend field."""
+        if backend not in cls.backend_to_class:
+            raise ValueError(f"Invalid backend: {backend}")
+        return backend
+
+    @model_validator(mode="after")
+    def create_config(self) -> "MemChatConfigFactory":
+        config_class = self.backend_to_class[self.backend]
+        self.config = config_class(**self.config)
+        return self

memos/configs/mem_cube.py

@@ -0,0 +1,89 @@
+import uuid
+
+from pydantic import Field, field_validator
+
+from memos.configs.base import BaseConfig
+from memos.configs.memory import (
+    MemoryConfigFactory,
+)
+from memos.exceptions import ConfigurationError
+from memos.log import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class BaseMemCubeConfig(BaseConfig):
+    """Base configuration class for MemCube."""
+
+    model_schema: str = Field(
+        "NOT_SET",
+        description="Schema for configuration. This value will be automatically set.",
+        exclude=False,
+    )
+
+    config_filename: str = Field(
+        "config.json",
+        description="Filename for storing MemCube configuration",
+    )
+
+
+class GeneralMemCubeConfig(BaseMemCubeConfig):
+    """General MemCube memory configuration class."""
+
+    user_id: str = Field(
+        "default_user",
+        description="User ID for the MemCube. This is used to distinguish between different users' memories.",
+    )
+    cube_id: str = Field(
+        str(uuid.uuid4()),
+        description="Cube ID for the MemCube. This is used to distinguish between different MemCubes.",
+    )
+    text_mem: MemoryConfigFactory = Field(
+        ...,
+        default_factory=MemoryConfigFactory,
+        description="Configuration for the textual memory",
+    )
+    act_mem: MemoryConfigFactory = Field(
+        ...,
+        default_factory=MemoryConfigFactory,
+        description="Configuration for the activation memory",
+    )
+    para_mem: MemoryConfigFactory = Field(
+        ...,
+        default_factory=MemoryConfigFactory,
+        description="Configuration for the parametric memory",
+    )
+
+    @field_validator("text_mem")
+    @classmethod
+    def validate_text_mem(cls, text_mem: MemoryConfigFactory) -> MemoryConfigFactory:
+        """Validate the text_mem field."""
+        allowed_backends = ["naive_text", "general_text", "tree_text", "uninitialized"]
+        if text_mem.backend not in allowed_backends:
+            raise ConfigurationError(
+                f"GeneralMemCubeConfig requires text_mem backend to be one of {allowed_backends}, got '{text_mem.backend}'"
+            )
+        return text_mem
+
+    @field_validator("act_mem")
+    @classmethod
+    def validate_act_mem(cls, act_mem: MemoryConfigFactory) -> MemoryConfigFactory:
+        """Validate the act_mem field."""
+        allowed_backends = ["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}'"
+            )
+        return act_mem
+
+    @field_validator("para_mem")
+    @classmethod
+    def validate_para_mem(cls, para_mem: MemoryConfigFactory) -> MemoryConfigFactory:
+        """Validate the para_mem field."""
+        allowed_backends = ["lora", "uninitialized"]
+        if para_mem.backend not in allowed_backends:
+            raise ConfigurationError(
+                f"GeneralMemCubeConfig requires para_mem backend to be one of {allowed_backends}, got '{para_mem.backend}'"
+            )
+        return para_mem

memos/configs/mem_os.py

@@ -0,0 +1,70 @@
+import uuid
+
+from typing import Any
+
+from pydantic import Field, model_validator
+
+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
+
+
+class MOSConfig(BaseConfig):
+    user_id: str = Field(
+        default="root",
+        description="User ID for the MOS. This is used to distinguish between different users' memories.",
+    )
+    session_id: str = Field(
+        default=str(uuid.uuid4()),
+        description="Session ID for the MOS. This is used to distinguish between different dialogue",
+    )
+    chat_model: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the chat model in the MOS",
+    )
+    mem_reader: MemReaderConfigFactory = Field(
+        ...,
+        default_factory=MemReaderConfigFactory,
+        description="MemReader configuration for the MOS",
+    )
+    mem_scheduler: SchedulerConfigFactory | None = Field(
+        default=None,
+        description="Memory scheduler configuration for managing memory operations",
+    )
+    max_turns_window: int = Field(
+        default=15,
+        description="Maximum number of turns to keep in the conversation history",
+    )
+    top_k: int = Field(
+        default=5,
+        description="Maximum number of memories to retrieve for each query",
+    )
+    enable_textual_memory: bool = Field(
+        default=True,
+        description="Enable textual memory for the MemChat",
+    )
+    enable_activation_memory: bool = Field(
+        default=False,
+        description="Enable activation memory for the MemChat",
+    )
+    enable_parametric_memory: bool = Field(
+        default=False,
+        description="Enable parametric memory for the MemChat",
+    )
+    enable_mem_scheduler: bool = Field(
+        default=False,
+        description="Enable memory scheduler for automated memory management",
+    )
+
+
+class MemOSConfigFactory(BaseConfig):
+    """Factory class for creating Memos configurations."""
+
+    config: dict[str, Any] = Field(..., description="Configuration for the MemOS backend")
+
+    @model_validator(mode="after")
+    def create_config(self) -> "MemOSConfigFactory":
+        self.config = MOSConfig(**self.config)
+        return self

memos/configs/mem_reader.py

@@ -0,0 +1,53 @@
+from datetime import datetime
+from typing import Any, ClassVar
+
+from pydantic import Field, field_validator, model_validator
+
+from memos.configs.base import BaseConfig
+from memos.configs.chunker import ChunkerConfigFactory
+from memos.configs.embedder import EmbedderConfigFactory
+from memos.configs.llm import LLMConfigFactory
+
+
+class BaseMemReaderConfig(BaseConfig):
+    """Base configuration class for MemReader."""
+
+    created_at: datetime = Field(
+        default_factory=datetime.now, description="Creation timestamp for the MemReader"
+    )
+    llm: LLMConfigFactory = Field(..., description="LLM configuration for the MemReader")
+    embedder: EmbedderConfigFactory = Field(
+        ..., description="Embedder configuration for the MemReader"
+    )
+    chunker: ChunkerConfigFactory = Field(
+        ..., description="Chunker configuration for the MemReader"
+    )
+
+
+class SimpleStructMemReaderConfig(BaseMemReaderConfig):
+    """SimpleStruct MemReader configuration class."""
+
+
+class MemReaderConfigFactory(BaseConfig):
+    """Factory class for creating MemReader configurations."""
+
+    backend: str = Field(..., description="Backend for MemReader")
+    config: dict[str, Any] = Field(..., description="Configuration for the MemReader backend")
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "simple_struct": SimpleStructMemReaderConfig,
+    }
+
+    @field_validator("backend")
+    @classmethod
+    def validate_backend(cls, backend: str) -> str:
+        """Validate the backend field."""
+        if backend not in cls.backend_to_class:
+            raise ValueError(f"Invalid backend: {backend}")
+        return backend
+
+    @model_validator(mode="after")
+    def create_config(self) -> "MemReaderConfigFactory":
+        config_class = self.backend_to_class[self.backend]
+        self.config = config_class(**self.config)
+        return self

memos/configs/mem_scheduler.py

@@ -0,0 +1,78 @@
+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 (
+    DEFAULT_ACT_MEM_DUMP_PATH,
+    DEFAULT_ACTIVATION_MEM_SIZE,
+    DEFAULT_CONSUME_INTERVAL_SECONDS,
+    DEFAULT_THREAD__POOL_MAX_WORKERS,
+)
+
+
+class BaseSchedulerConfig(BaseConfig):
+    """Base configuration class for mem_scheduler."""
+
+    top_k: int = Field(
+        default=10, description="Number of top candidates to consider in initial retrieval"
+    )
+    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"
+    )
+    thread_pool_max_workers: int = Field(
+        default=DEFAULT_THREAD__POOL_MAX_WORKERS,
+        gt=1,
+        lt=20,
+        description=f"Maximum worker threads in pool (default: {DEFAULT_THREAD__POOL_MAX_WORKERS})",
+    )
+    consume_interval_seconds: int = Field(
+        default=DEFAULT_CONSUME_INTERVAL_SECONDS,
+        gt=0,
+        le=60,
+        description=f"Interval for consuming messages from queue in seconds (default: {DEFAULT_CONSUME_INTERVAL_SECONDS})",
+    )
+
+
+class GeneralSchedulerConfig(BaseSchedulerConfig):
+    act_mem_update_interval: int | None = Field(
+        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",
+    )
+    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",
+    )
+
+
+class SchedulerConfigFactory(BaseConfig):
+    """Factory class for creating scheduler configurations."""
+
+    backend: str = Field(..., description="Backend for scheduler")
+    config: dict[str, Any] = Field(..., description="Configuration for the scheduler backend")
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "general_scheduler": GeneralSchedulerConfig,
+    }
+
+    @field_validator("backend")
+    @classmethod
+    def validate_backend(cls, backend: str) -> str:
+        """Validate the backend field."""
+        if backend not in cls.backend_to_class:
+            raise ValueError(f"Invalid backend: {backend}")
+        return backend
+
+    @model_validator(mode="after")
+    def create_config(self) -> "SchedulerConfigFactory":
+        config_class = self.backend_to_class[self.backend]
+        self.config = config_class(**self.config)
+        return self

memos/configs/memory.py

@@ -0,0 +1,190 @@
+from typing import Any, ClassVar
+
+from pydantic import Field, field_validator, model_validator
+
+from memos.configs.base import BaseConfig
+from memos.configs.embedder import EmbedderConfigFactory
+from memos.configs.graph_db import GraphDBConfigFactory
+from memos.configs.llm import LLMConfigFactory
+from memos.configs.vec_db import VectorDBConfigFactory
+from memos.exceptions import ConfigurationError
+
+
+# ─── 1. Global Base Memory Config ─────────────────────────────────────────────
+
+
+class BaseMemoryConfig(BaseConfig):
+    """Base configuration class for memories."""
+
+    cube_id: str | None = Field(
+        None,
+        description="Unique identifier for a MemCube that contains this memory",
+    )
+
+
+class UninitializedMemoryConfig(BaseMemoryConfig):
+    """Uninitialized memory configuration class."""
+
+
+# ─── 2.1. Activation Memory Configs ───────────────────────────────────────────
+
+
+class BaseActMemoryConfig(BaseMemoryConfig):
+    """Base configuration class for activation memories."""
+
+    memory_filename: str = Field(
+        "activation_memory.pickle",
+        description="Filename for storing memories",
+    )
+
+
+class KVCacheMemoryConfig(BaseActMemoryConfig):
+    """LLM KV Cache Memory configuration class."""
+
+    extractor_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the memory extractor",
+    )
+
+    @field_validator("extractor_llm")
+    @classmethod
+    def validate_extractor_llm(cls, extractor_llm: LLMConfigFactory) -> LLMConfigFactory:
+        """Validate the extractor_llm field."""
+        if extractor_llm.backend != "huggingface":
+            raise ConfigurationError(
+                f"KVCacheMemoryConfig requires extractor_llm backend to be 'huggingface', got '{extractor_llm.backend}'"
+            )
+        return extractor_llm
+
+
+# ─── 2.2. Parametric Memory Configs ───────────────────────────────────────────
+
+
+class BaseParaMemoryConfig(BaseMemoryConfig):
+    """Base configuration class for parametric memories."""
+
+    memory_filename: str = Field(
+        "parametric_memory.adapter",
+        description="Filename for storing memories",
+    )
+
+
+class LoRAMemoryConfig(BaseParaMemoryConfig):
+    """LoRA memory configuration class."""
+
+    extractor_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the memory extractor",
+    )
+
+    @field_validator("extractor_llm")
+    @classmethod
+    def validate_extractor_llm(cls, extractor_llm: LLMConfigFactory) -> LLMConfigFactory:
+        """Validate the extractor_llm field."""
+        if extractor_llm.backend not in ["huggingface"]:
+            raise ConfigurationError(
+                f"LoRAMemoryConfig requires extractor_llm backend to be 'huggingface', got '{extractor_llm.backend}'"
+            )
+        return extractor_llm
+
+
+# ─── 2.3. Textual Memory Configs ──────────────────────────────────────────────
+
+
+class BaseTextMemoryConfig(BaseMemoryConfig):
+    """Base configuration class for textual memories."""
+
+    memory_filename: str = Field(
+        "textual_memory.json",
+        description="Filename for storing memories",
+    )
+
+
+class NaiveTextMemoryConfig(BaseTextMemoryConfig):
+    """Naive textual memory configuration class."""
+
+    extractor_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the memory extractor",
+    )
+
+
+class GeneralTextMemoryConfig(BaseTextMemoryConfig):
+    """General memory configuration class."""
+
+    extractor_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the memory extractor",
+    )
+    vector_db: VectorDBConfigFactory = Field(
+        ...,
+        default_factory=VectorDBConfigFactory,
+        description="Vector database configuration for the memory storage",
+    )
+    embedder: EmbedderConfigFactory = Field(
+        ...,
+        default_factory=EmbedderConfigFactory,
+        description="Embedder configuration for the memory embedding",
+    )
+
+
+class TreeTextMemoryConfig(BaseTextMemoryConfig):
+    """General memory configuration class."""
+
+    extractor_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the memory extractor",
+    )
+    dispatcher_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the memory dispatcher_llm in retrieve module",
+    )
+    embedder: EmbedderConfigFactory = Field(
+        ...,
+        default_factory=EmbedderConfigFactory,
+        description="Embedder configuration for the memory embedding",
+    )
+    graph_db: GraphDBConfigFactory = Field(
+        ...,
+        default_factory=GraphDBConfigFactory,
+        description="Graph database configuration for the tree-memory storage",
+    )
+
+
+# ─── 3. Global Memory Config Factory ──────────────────────────────────────────
+
+
+class MemoryConfigFactory(BaseConfig):
+    """Factory class for creating memory configurations."""
+
+    backend: str = Field("uninitialized", description="Backend for memory")
+    config: dict[str, Any] = Field({}, description="Configuration for the memory backend")
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "naive_text": NaiveTextMemoryConfig,
+        "general_text": GeneralTextMemoryConfig,
+        "tree_text": TreeTextMemoryConfig,
+        "kv_cache": KVCacheMemoryConfig,
+        "lora": LoRAMemoryConfig,
+        "uninitialized": UninitializedMemoryConfig,
+    }
+
+    @field_validator("backend")
+    @classmethod
+    def validate_backend(cls, backend: str) -> str:
+        """Validate the backend field."""
+        if backend not in cls.backend_to_class:
+            raise ConfigurationError(f"Invalid backend: {backend}")
+        return backend
+
+    @model_validator(mode="after")
+    def create_config(self) -> "MemoryConfigFactory":
+        config_class = self.backend_to_class[self.backend]
+        self.config = config_class(**self.config)
+        return self