MemoryOS 2.0.3__py3-none-any.whl

memos/configs/memory.py

@@ -0,0 +1,324 @@
+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.internet_retriever import InternetRetrieverConfigFactory
+from memos.configs.llm import LLMConfigFactory
+from memos.configs.mem_reader import MemReaderConfigFactory
+from memos.configs.reranker import RerankerConfigFactory
+from memos.configs.vec_db import VectorDBConfigFactory
+from memos.exceptions import ConfigurationError
+from memos.memories.textual.prefer_text_memory.config import (
+    AdderConfigFactory,
+    ExtractorConfigFactory,
+    RetrieverConfigFactory,
+)
+
+
+# ─── 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 not in ["huggingface", "huggingface_singleton", "vllm"]:
+            raise ConfigurationError(
+                f"KVCacheMemoryConfig requires extractor_llm backend to be 'huggingface' or 'huggingface_singleton', 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", "huggingface_singleton"]:
+            raise ConfigurationError(
+                f"LoRAMemoryConfig requires extractor_llm backend to be 'huggingface' or 'huggingface_singleton', 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):
+    """Tree text 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",
+    )
+    reranker: RerankerConfigFactory | None = Field(
+        None,
+        description="Reranker configuration (optional, defaults to cosine_local).",
+    )
+    graph_db: GraphDBConfigFactory = Field(
+        ...,
+        default_factory=GraphDBConfigFactory,
+        description="Graph database configuration for the tree-memory storage",
+    )
+    internet_retriever: InternetRetrieverConfigFactory | None = Field(
+        None,
+        description="Internet retriever configuration (optional)",
+    )
+
+    reorganize: bool | None = Field(
+        False,
+        description="Optional description for this memory configuration.",
+    )
+
+    memory_size: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "Maximum item counts per memory bucket, e.g.: "
+            '{"WorkingMemory": 20, "LongTermMemory": 10000, "UserMemory": 10000}'
+        ),
+    )
+
+    search_strategy: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            'Set search strategy for this memory configuration.{"bm25": true, "cot": false}'
+        ),
+    )
+
+    mode: str | None = Field(
+        default="sync",
+        description=("whether use asynchronous mode in memory add"),
+    )
+    include_embedding: bool | None = Field(
+        default=False,
+        description="Whether to include embedding in the memory retrieval",
+    )
+
+
+class SimpleTreeTextMemoryConfig(TreeTextMemoryConfig):
+    """Simple tree text memory configuration class."""
+
+
+class PreferenceTextMemoryConfig(BaseTextMemoryConfig):
+    """Preference 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",
+    )
+    reranker: RerankerConfigFactory | None = Field(
+        None,
+        description="Reranker configuration (optional).",
+    )
+    extractor: ExtractorConfigFactory = Field(
+        ...,
+        default_factory=ExtractorConfigFactory,
+        description="Extractor configuration for the memory extracting",
+    )
+    adder: AdderConfigFactory = Field(
+        ...,
+        default_factory=AdderConfigFactory,
+        description="Adder configuration for the memory adding",
+    )
+    retriever: RetrieverConfigFactory = Field(
+        ...,
+        default_factory=RetrieverConfigFactory,
+        description="Retriever configuration for the memory retrieving",
+    )
+
+
+class MemFeedbackConfig(BaseMemoryConfig):
+    """Memory feedback configuration class."""
+
+    extractor_llm: LLMConfigFactory = Field(
+        ...,
+        default_factory=LLMConfigFactory,
+        description="LLM configuration for the memory extractor",
+    )
+    embedder: EmbedderConfigFactory = Field(
+        ...,
+        default_factory=EmbedderConfigFactory,
+        description="Embedder configuration for the memory embedding",
+    )
+    reranker: RerankerConfigFactory | None = Field(
+        None,
+        description="Reranker configuration (optional).",
+    )
+    graph_db: GraphDBConfigFactory = Field(
+        ...,
+        default_factory=GraphDBConfigFactory,
+        description="Graph database configuration for the tree-memory storage",
+    )
+    reorganize: bool | None = Field(
+        False,
+        description="Optional description for this memory configuration.",
+    )
+
+    memory_size: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "Maximum item counts per memory bucket, e.g.: "
+            '{"WorkingMemory": 20, "LongTermMemory": 10000, "UserMemory": 10000}'
+        ),
+    )
+
+    mem_reader: MemReaderConfigFactory = Field(
+        ...,
+        default_factory=MemReaderConfigFactory,
+        description="MemReader configuration for the Feedback",
+    )
+
+
+# ─── 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,
+        "simple_tree_text": SimpleTreeTextMemoryConfig,
+        "tree_text": TreeTextMemoryConfig,
+        "pref_text": PreferenceTextMemoryConfig,
+        "kv_cache": KVCacheMemoryConfig,
+        "vllm_kv_cache": KVCacheMemoryConfig,  # Use same config as kv_cache
+        "lora": LoRAMemoryConfig,
+        "uninitialized": UninitializedMemoryConfig,
+        "mem_feedback": MemFeedbackConfig,
+    }
+
+    @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

memos/configs/parser.py

@@ -0,0 +1,38 @@
+from typing import Any, ClassVar
+
+from pydantic import Field, field_validator, model_validator
+
+from memos.configs.base import BaseConfig
+
+
+class BaseParserConfig(BaseConfig):
+    """Base configuration class for parser models."""
+
+
+class MarkItDownParserConfig(BaseParserConfig):
+    pass
+
+
+class ParserConfigFactory(BaseConfig):
+    """Factory class for creating Parser configurations."""
+
+    backend: str = Field(..., description="Backend for parser")
+    config: dict[str, Any] = Field(..., description="Configuration for the parser backend")
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "markitdown": MarkItDownParserConfig,
+    }
+
+    @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) -> "ParserConfigFactory":
+        config_class = self.backend_to_class[self.backend]
+        self.config = config_class(**self.config)
+        return self

memos/configs/reranker.py

@@ -0,0 +1,18 @@
+# memos/configs/reranker.py
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class RerankerConfigFactory(BaseModel):
+    """
+    {
+      "backend": "http_bge" | "cosine_local" | "noop",
+      "config": { ... backend-specific ... }
+    }
+    """
+
+    backend: str = Field(..., description="Reranker backend id")
+    config: dict[str, Any] = Field(default_factory=dict, description="Backend-specific options")

memos/configs/utils.py

@@ -0,0 +1,8 @@
+import json
+
+
+def get_json_file_model_schema(json_path: str) -> str:
+    """Retrieve the model schema from a JSON file."""
+    with open(json_path, encoding="utf-8") as f:
+        data = json.load(f)
+    return data.get("model_schema", None)

memos/configs/vec_db.py

@@ -0,0 +1,80 @@
+from typing import Any, ClassVar, Literal
+
+from pydantic import Field, field_validator, model_validator
+
+from memos import settings
+from memos.configs.base import BaseConfig
+from memos.log import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class BaseVecDBConfig(BaseConfig):
+    """Base class for all vector database configurations."""
+
+    collection_name: str = Field(..., description="Name of the collection")
+    vector_dimension: int | None = Field(default=None, description="Dimension of the vectors")
+    distance_metric: Literal["cosine", "euclidean", "dot"] | None = Field(
+        default=None,
+        description="Distance metric for vector similarity calculation. Options: 'cosine', 'euclidean', 'dot'",
+    )
+
+
+class QdrantVecDBConfig(BaseVecDBConfig):
+    """Configuration for Qdrant vector database."""
+
+    host: str | None = Field(default=None, description="Host for Qdrant")
+    port: int | None = Field(default=None, description="Port for Qdrant")
+    path: str | None = Field(default=None, description="Path for Qdrant")
+    url: str | None = Field(default=None, description="Qdrant Cloud/remote endpoint URL")
+    api_key: str | None = Field(default=None, description="Qdrant Cloud API key")
+
+    @model_validator(mode="after")
+    def set_default_path(self):
+        # Only fall back to embedded/local path when no remote host/port/path/url is provided.
+        if all(x is None for x in (self.host, self.port, self.path, self.url)):
+            logger.warning(
+                "No host, port, or path provided for Qdrant. Defaulting to local path: %s",
+                settings.MEMOS_DIR / "qdrant",
+            )
+            self.path = str(settings.MEMOS_DIR / "qdrant")
+        return self
+
+
+class MilvusVecDBConfig(BaseVecDBConfig):
+    """Configuration for Milvus vector database."""
+
+    uri: str = Field(..., description="URI for Milvus connection")
+    collection_name: list[str] = Field(..., description="Name(s) of the collection(s)")
+    max_length: int = Field(
+        default=65535, description="Maximum length for string fields (varChar type)"
+    )
+    user_name: str = Field(default="", description="User name for Milvus connection")
+    password: str = Field(default="", description="Password for Milvus connection")
+
+
+class VectorDBConfigFactory(BaseConfig):
+    """Factory class for creating vector database configurations."""
+
+    backend: str = Field(..., description="Backend for vector database")
+    config: dict[str, Any] = Field(..., description="Configuration for the vector database backend")
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "qdrant": QdrantVecDBConfig,
+        "milvus": MilvusVecDBConfig,
+    }
+
+    @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 vector database backend: {backend}")
+        return backend
+
+    @model_validator(mode="after")
+    def create_config(self) -> "VectorDBConfigFactory":
+        config_class = self.backend_to_class[self.backend]
+        self.config = config_class(**self.config)
+        return self