KVCacheMemory(config: KVCacheMemoryConfig)

<dir>/<config.memory_filename>

MemCube
 ├── text_mem: TextualMemory
 ├── act_mem: ActivationMemory
 └── para_mem: ParametricMemory

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

    @abstractmethod
    def load(self, dir: str) -> None:
        """Load memories from a directory."""

    @abstractmethod
    def dump(self, dir: str) -> None:
        """Dump memories to a directory."""

from memos.mem_cube.general import GeneralMemCube
mem_cube = GeneralMemCube(config)

class GeneralMemCube(BaseMemCube):
    """記憶立方體（MemCube）是一個用於加載和存儲三種類型記憶的容器。
    支持的記憶類型：文本記憶（text_mem）、激活記憶（act_mem）、參數化記憶（para_mem）
    """

    def __init__(self, config: GeneralMemCubeConfig):
        """使用配置初始化記憶立方體。

        參數:
            config: 通用記憶立方體配置實例（GeneralMemCubeConfig），包含三種記憶的後端配置等信息
        """
        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
        )

        # 初始化激活記憶：邏輯同文本記憶
        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
        )

    def load(
        self, dir: str, memory_types: list[Literal["text_mem", "act_mem", "para_mem"]] | None = None
    ) -> None:
        """從指定目錄加載記憶數據。

        參數:
            dir: 存儲記憶文件的目錄路徑
            memory_types: 要加載的記憶類型列表（可選）。若為None，加載所有可用的記憶類型。
                          可選值：["text_mem", "act_mem", "para_mem"]
        """
        # 讀取目錄中的配置文件schema，用於校驗配置一致性
        loaded_schema = get_json_file_model_schema(os.path.join(dir, self.config.config_filename))
        # 校驗加載的配置schema是否與當前實例的配置schema一致，不一致則拋出配置錯誤
        if loaded_schema != self.config.model_schema:
            raise ConfigurationError(
                f"Configuration schema mismatch. Expected {self.config.model_schema}, "
                f"but found {loaded_schema}."
            )

        # 若未指定記憶類型，默認加載所有三種類型
        if memory_types is None:
            memory_types = ["text_mem", "act_mem", "para_mem"]

        # 加載指定類型的記憶（僅加載已初始化的記憶實例）
        if "text_mem" in memory_types and self.text_mem:
            self.text_mem.load(dir)  # 調用文本記憶的load方法加載數據

        if "act_mem" in memory_types and self.act_mem:
            self.act_mem.load(dir)  # 調用激活記憶的load方法加載數據

        if "para_mem" in memory_types and self.para_mem:
            self.para_mem.load(dir)  # 調用參數化記憶的load方法加載數據

    def dump(
        self, dir: str, memory_types: list[Literal["text_mem", "act_mem", "para_mem"]] | None = None
    ) -> None:
        """將記憶數據存儲到指定目錄。

        參數:
            dir: 保存記憶文件的目標目錄路徑
            memory_types: 要存儲的記憶類型列表（可選）。若為None，存儲所有可用的記憶類型。
                          可選值：["text_mem", "act_mem", "para_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."
            )

        # 始終先存儲配置文件（確保配置與記憶數據同步）
        self.config.to_json_file(os.path.join(dir, self.config.config_filename))

        # 若未指定記憶類型，默認存儲所有三種類型
        if memory_types is None:
            memory_types = ["text_mem", "act_mem", "para_mem"]

        # 存儲指定類型的記憶（僅存儲已初始化的記憶實例）
        if "text_mem" in memory_types and self.text_mem:
            self.text_mem.dump(dir)  # 調用文本記憶的dump方法存儲數據

        if "act_mem" in memory_types and self.act_mem:
            self.act_mem.dump(dir)  # 調用激活記憶的dump方法存儲數據

        if "para_mem" in memory_types and self.para_mem:
            self.para_mem.dump(dir)  # 調用參數化記憶的dump方法存儲數據

    @staticmethod
    def init_from_dir(
        dir: str,
        memory_types: list[Literal["text_mem", "act_mem", "para_mem"]] | None = None,
        default_config: GeneralMemCubeConfig | None = None,
    ) -> "GeneralMemCube":
        """從本地目錄創建並初始化記憶立方體實例。

        參數:
            dir: 存儲記憶文件和配置文件的本地目錄路徑
            memory_types: 要加載的記憶類型列表（可選）。若為None，加載所有可用類型。
            default_config: 用於合併的默認配置（可選）。若提供，會合並通用設置，
                          同時保留用户特定的關鍵配置字段。

        返回:
            GeneralMemCube: 已加載指定目錄記憶數據的記憶立方體實例
        """
        # 構建配置文件路徑（默認配置文件名為config.json）
        config_path = os.path.join(dir, "config.json")
        # 從JSON文件加載配置實例
        config = GeneralMemCubeConfig.from_json_file(config_path)

        # 若提供了默認配置，將其與加載的配置合併
        if default_config is not None:
            config = merge_config_with_default(config, default_config)

        # 創建記憶立方體實例並加載指定目錄的記憶數據
        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"]] | None = None,
        default_config: GeneralMemCubeConfig | None = None,
    ) -> "GeneralMemCube":
        """從遠程倉庫創建並初始化記憶立方體實例。

        參數:
            cube_id: 遠程倉庫名稱（即記憶立方體ID）
            base_url: 遠程倉庫的基礎URL（默認是Hugging Face數據集倉庫）
            memory_types: 要加載的記憶類型列表（可選）。若為None，加載所有可用類型。
            default_config: 用於合併的默認配置（可選）。

        返回:
            GeneralMemCube: 已加載遠程倉庫記憶數據的記憶立方體實例
        """
        # 下載遠程倉庫到本地目錄
        dir = download_repo(cube_id, base_url)
        # 調用本地目錄初始化方法，創建並返回記憶立方體實例
        return GeneralMemCube.init_from_dir(dir, memory_types, default_config)

    @property
    def text_mem(self) -> "BaseTextMemory | None":
        """獲取文本記憶實例（屬性訪問器）。"""
        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:
        """設置文本記憶實例（屬性修改器）。

        參數:
            value: 要設置的文本記憶實例，必須是BaseTextMemory的子類實例
        """
        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":
        """獲取激活記憶實例（屬性訪問器）。"""
        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:
        """設置激活記憶實例（屬性修改器）。

        參數:
            value: 要設置的激活記憶實例，必須是BaseActMemory的子類實例
        """
        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":
        """獲取參數化記憶實例（屬性訪問器）。"""
        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:
        """設置參數化記憶實例（屬性修改器）。

        參數:
            value: 要設置的參數化記憶實例，必須是BaseParaMemory的子類實例
        """
        if not isinstance(value, BaseParaMemory):
            raise TypeError(f"Expected BaseParaMemory, got {type(value).__name__}")
        self._para_mem = value

# 示例：智能時間線管理
timeline_memory = {
    "1094年": {
        "events": ["蕭峯身世之謎揭開", "聚賢莊大戰"],
        "consequences": ["江湖震動", "丐幫分裂"],
        "affected_characters": ["蕭峯", "阿朱", "段正淳"]
    },
    "1095年": {
        "events": ["雁門關事件真相", "阿朱之死"],
        "consequences": ["蕭峯心境轉變", "宋遼關係緊張"]
    }
}

# AI可以回答：如果蕭峯沒有去雁門關，後續會如何發展？

# 示例：動態世界狀態管理
from memos.memories.textual.base import TextualMemoryItem

# 創建世界狀態記憶項
world_state_memories = [
    TextualMemoryItem(
        memory="宋遼政治緊張程度達到0.8級別，邊境衝突頻發",
        metadata={"type": "world_state", "category": "politics"}
    ),
    TextualMemoryItem(
        memory="當前江湖流傳的絕世武功：九陽神功、易筋經",
        metadata={"type": "world_state", "category": "martial_arts"}
    ),
    TextualMemoryItem(
        memory="少林與武當保持中立，丐幫內部出現分裂",
        metadata={"type": "world_state", "category": "sect_relations"}
    )
]

# 使用MemCube的文本記憶管理世界狀態
mem_cube.text_mem.replace_working_memory(world_state_memories)

# 當蕭峯做出重要決定時，自動更新工作記憶
current_working_memory = mem_cube.text_mem.get_working_memory()