# 中文注释：
# 文件：echobot/agent/memory.py
# 说明：智能体核心逻辑，包括主循环、上下文、记忆与任务队列。

"""Memory Store - 记忆管理系统
=================================================

此模块负责管理 Agent 的持久化记忆，分为三种类型：

1. 长期记忆（Long-term Memory）:
   - 存储位置：memory/MEMORY.md
   - 用途：存储需要长期保留的重要信息
   - 特点：不会自动删除，需要手动管理

2. 历史记录（History）:
   - 存储位置：memory/HISTORY.md
   - 用途：可grep检索的事件日志
   - 特点：追加写入，支持全文搜索

3. 每日笔记（Daily Notes）:
   - 存储位置：memory/YYYY-MM-DD.md
   - 用途：记录每日工作、临时信息
   - 特点：按日期组织

设计理念：
- 轻量级：使用纯文本 Markdown 格式
- 持久化：文件存储，重启后数据不丢失
- 检索：Agent 可以检索相关记忆

主要类：
- MemoryStore: 记忆管理核心类

使用示例：
    memory = MemoryStore(workspace)
    memory.append_today("Completed task X")
    context = memory.get_memory_context()
"""

from pathlib import Path
from datetime import datetime

from echobot.utils.helpers import ensure_dir, today_date


class MemoryStore:
    """
    记忆管理系统 - 管理 Agent 的持久化记忆
    
    支持三种记忆类型：
    1. 长期记忆：MEMORY.md
    2. 历史记录：HISTORY.md（可grep检索）
    3. 每日笔记：YYYY-MM-DD.md
    
    主要功能：
    - 读取/写入长期记忆
    - 追加历史记录
    - grep搜索历史
    - 读取/写入今日笔记
    - 构建记忆上下文（供 Agent 使用）
    
    使用示例：
        memory = MemoryStore(Path("~/.echobot/workspace"))
        
        # 追加历史记录
        memory.append_history("Completed task X")
        
        # 搜索历史
        results = memory.grep_history("task")
        
        # 获取记忆上下文
        context = memory.get_memory_context()
    """
    
    def __init__(self, workspace: Path):
        """
        初始化记忆存储
        
        Args:
            workspace: 工作空间路径
        """
        self.workspace = workspace
        self.memory_dir = ensure_dir(workspace / "memory")
        self.memory_file = self.memory_dir / "MEMORY.md"
        self.history_file = self.memory_dir / "HISTORY.md"
    
    def get_today_file(self) -> Path:
        """
        获取今日笔记文件的路径
        
        文件名格式：YYYY-MM-DD.md
        
        Returns:
            Path: 今日笔记文件的完整路径
        """
        return self.memory_dir / f"{today_date()}.md"
    
    def read_today(self) -> str:
        """
        读取今日笔记内容
        
        Returns:
            str: 今日笔记的文本内容，如果文件不存在则返回空字符串
        """
        today_file = self.get_today_file()
        if today_file.exists():
            return today_file.read_text(encoding="utf-8")
        return ""
    
    def append_today(self, content: str) -> None:
        """
        向今日笔记追加内容
        
        如果文件已存在，则在末尾追加；否则创建新文件并添加日期标题。
        
        Args:
            content: 要追加的内容
        
        Returns:
            None
        """
        today_file = self.get_today_file()
        
        if today_file.exists():
            existing = today_file.read_text(encoding="utf-8")
            content = existing + "\n" + content
        else:
            # 为新文件添加标题
            header = f"# {today_date()}\n\n"
            content = header + content
        
        today_file.write_text(content, encoding="utf-8")
    
    def read_long_term(self) -> str:
        """
        读取长期记忆（MEMORY.md）
        
        Returns:
            str: 长期记忆的文本内容，如果文件不存在则返回空字符串
        """
        if self.memory_file.exists():
            return self.memory_file.read_text(encoding="utf-8")
        return ""
    
    def write_long_term(self, content: str) -> None:
        """
        写入长期记忆（覆盖写入）
        
        Args:
            content: 要写入的内容
        
        Returns:
            None
        """
        self.memory_file.write_text(content, encoding="utf-8")
    
    # === History (新增) ===
    
    def append_history(self, entry: str) -> None:
        """
        追加历史记录到 HISTORY.md
        
        Args:
            entry: 要追加的条目
        
        Returns:
            None
        """
        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M")
        with open(self.history_file, "a", encoding="utf-8") as f:
            f.write(f"[{timestamp}] {entry}\n\n")
    
    def grep_history(self, query: str) -> list[str]:
        """
        在历史记录中搜索匹配的行
        
        Args:
            query: 搜索关键词
        
        Returns:
            list[str]: 匹配的行列表
        """
        if not self.history_file.exists():
            return []
        
        results = []
        query_lower = query.lower()
        with open(self.history_file, "r", encoding="utf-8") as f:
            for line in f:
                if query_lower in line.lower():
                    results.append(line.rstrip())
        return results
    
    # ===
    
    def get_recent_memories(self, days: int = 7) -> str:
        """
        获取最近 N 天的记忆
        
        用于在 Agent 启动时加载最近的上下文。
        
        Args:
            days: 回溯天数，默认为 7 天
        
        Returns:
            str: 所有相关记忆的连接文本
        """
        from datetime import timedelta
        
        memories = []
        today = datetime.now().date()
        
        for i in range(days):
            date = today - timedelta(days=i)
            date_str = date.strftime("%Y-%m-%d")
            file_path = self.memory_dir / f"{date_str}.md"
            
            if file_path.exists():
                content = file_path.read_text(encoding="utf-8")
                memories.append(content)
        
        return "\n\n---\n\n".join(memories)
    
    def list_memory_files(self) -> list[Path]:
        """
        列出所有记忆文件（按日期排序，新文件在前）
        
        Returns:
            list[Path]: 排序后的记忆文件路径列表
        """
        if not self.memory_dir.exists():
            return []
        
        files = list(self.memory_dir.glob("????-??-??.md"))
        return sorted(files, reverse=True)
    
    def get_memory_context(self) -> str:
        """
        构建记忆上下文（供 Agent 使用）
        
        组合长期记忆和今日笔记，格式化为单一字符串。
        
        Returns:
            str: 格式化的记忆上下文，包含 "## Long-term Memory" 和 "## Today's Notes" 部分
        """
        parts = []
        
        # 长期记忆
        long_term = self.read_long_term()
        if long_term:
            parts.append("## Long-term Memory\n" + long_term)
        
        # 今日笔记
        today = self.read_today()
        if today:
            parts.append("## Today's Notes\n" + today)
        
        return "\n\n".join(parts) if parts else ""
