doudou-memory 1.0.0__py3-none-any.whl

doudou_memory/__init__.py

@@ -0,0 +1,64 @@
+"""
+豆豆记忆系统
+Doudou Memory System
+
+为 AI Agent 打造的科学记忆系统
+"""
+
+__version__ = "1.0.0"
+__author__ = "Doudou Software Studio"
+
+from .core.memory_system import (
+    MemorySystem,
+    memorize,
+    recall,
+    get_memory_system
+)
+
+from .core.working_memory import (
+    WorkingMemory,
+    get_working_memory
+)
+
+from .core.forgetting_mechanism import (
+    DecayManager,
+    get_decay_manager,
+    EbbinghausForgetting
+)
+
+from .core.review_scheduler import (
+    ReviewScheduler,
+    get_review_scheduler
+)
+
+from .core.intelligent_manager import (
+    IntelligentMemoryManager,
+    smart_memorize
+)
+
+__all__ = [
+    # 核心系统
+    "MemorySystem",
+    "get_memory_system",
+    
+    # 工作记忆
+    "WorkingMemory", 
+    "get_working_memory",
+    
+    # 遗忘机制
+    "DecayManager",
+    "get_decay_manager",
+    "EbbinghausForgetting",
+    
+    # 复习调度
+    "ReviewScheduler",
+    "get_review_scheduler",
+    
+    # 智能管理
+    "IntelligentMemoryManager",
+    "smart_memorize",
+    
+    # 便捷函数
+    "memorize",
+    "recall",
+]

doudou_memory/core/forgetting_mechanism.py

@@ -0,0 +1,312 @@
+"""
+L3/L4 遗忘机制模块
+Forgetting Mechanism Module
+
+基于 Ebbinghaus 遗忘曲线
+"""
+
+import json
+import math
+import logging
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# 默认存储路径
+DEFAULT_STORAGE_PATH = "D:/openclaw-agents/shared/experience/long_term_memory"
+
+
+class EbbinghausForgetting:
+    """
+    Ebbinghaus 遗忘曲线计算器
+    
+    公式: R = e^(-t/S)
+    - R: 保留率
+    - t: 时间（小时）
+    - S: 记忆强度（半衰期）
+    """
+    
+    # 标准遗忘曲线数据点
+    FORGETTING_CURVE = {
+        1/3: 58.2,    # 20分钟
+        1: 44.2,       # 1小时
+        24: 33.7,      # 1天
+        24 * 7: 25.4,  # 1周
+        24 * 31: 21.1  # 31天
+    }
+    
+    def __init__(self, min_retention: float = 0.3):
+        self.min_retention = min_retention
+    
+    def calculate_retention(self, age_hours: float, 
+                          strength: float = 24) -> float:
+        """
+        计算保留率
+        
+        Args:
+            age_hours: 记忆年龄（小时）
+            strength: 记忆强度（小时）
+        
+        Returns:
+            保留率 (0-1)
+        """
+        if age_hours <= 0:
+            return 1.0
+        
+        retention = math.exp(-age_hours / strength)
+        
+        # 确保不低于最小保留率
+        return max(self.min_retention, min(1.0, retention))
+    
+    def calculate_strength(self, retention: float, age_hours: float) -> float:
+        """根据保留率计算记忆强度"""
+        if retention <= 0 or retention >= 1:
+            return float('inf')
+        
+        return -age_hours / math.log(retention)
+
+
+class MemoryRecord:
+    """记忆记录"""
+    
+    def __init__(self, memory_id: str, content: str,
+                 importance: float = 0.5, memory_type: str = "episodic"):
+        self.id = memory_id
+        self.content = content
+        self.importance = importance
+        self.memory_type = memory_type
+        self.created_at = datetime.now()
+        self.last_accessed = datetime.now()
+        self.access_count = 0
+        self.retention_score = 1.0
+        self.review_count = 0
+        self.next_review: Optional[datetime] = None
+        self.archived = False
+        
+        # SM-2 参数
+        self.easy_factor = 2.5
+        self.interval = 1  # 天数
+    
+    def to_dict(self) -> Dict:
+        return {
+            "id": self.id,
+            "content": self.content,
+            "importance": self.importance,
+            "memory_type": self.memory_type,
+            "created_at": self.created_at.isoformat(),
+            "last_accessed": self.last_accessed.isoformat(),
+            "access_count": self.access_count,
+            "retention_score": self.retention_score,
+            "review_count": self.review_count,
+            "next_review": self.next_review.isoformat() if self.next_review else None,
+            "archived": self.archived,
+            "easy_factor": self.easy_factor,
+            "interval": self.interval
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict) -> 'MemoryRecord':
+        record = cls(
+            memory_id=data["id"],
+            content=data["content"],
+            importance=data.get("importance", 0.5),
+            memory_type=data.get("memory_type", "episodic")
+        )
+        record.created_at = datetime.fromisoformat(data["created_at"])
+        record.last_accessed = datetime.fromisoformat(data["last_accessed"])
+        record.access_count = data.get("access_count", 0)
+        record.retention_score = data.get("retention_score", 1.0)
+        record.review_count = data.get("review_count", 0)
+        if data.get("next_review"):
+            record.next_review = datetime.fromisoformat(data["next_review"])
+        record.archived = data.get("archived", False)
+        record.easy_factor = data.get("easy_factor", 2.5)
+        record.interval = data.get("interval", 1)
+        return record
+
+
+class DecayManager:
+    """
+    衰减管理器
+    
+    管理长期记忆的遗忘衰减和间隔重复
+    """
+    
+    def __init__(self, storage_path: str = DEFAULT_STORAGE_PATH):
+        self.storage_path = Path(storage_path)
+        self.storage_path.mkdir(parents=True, exist_ok=True)
+        
+        self.memories: Dict[str, MemoryRecord] = {}
+        self.ebbinghaus = EbbinghausForgetting()
+        
+        self._load_memories()
+    
+    def register_memory(self, memory_id: str, content: str,
+                       importance: float = 0.5, 
+                       memory_type: str = "episodic") -> str:
+        """注册新记忆"""
+        record = MemoryRecord(
+            memory_id=memory_id,
+            content=content,
+            importance=importance,
+            memory_type=memory_type
+        )
+        
+        # 设置首次复习时间
+        record.next_review = datetime.now() + timedelta(days=1)
+        
+        self.memories[memory_id] = record
+        self._save_memories()
+        
+        logger.info(f"[衰减管理] 注册记忆: {memory_id}")
+        
+        return memory_id
+    
+    def get_memory(self, memory_id: str) -> Optional[Dict]:
+        """获取记忆"""
+        record = self.memories.get(memory_id)
+        if record and not record.archived:
+            record.last_accessed = datetime.now()
+            record.access_count += 1
+            return record.to_dict()
+        return None
+    
+    def reinforce_memory(self, memory_id: str, quality: int = 3):
+        """
+        强化记忆（SM-2 算法）
+        
+        Args:
+            memory_id: 记忆ID
+            quality: 回忆质量 (0-5)
+        """
+        record = self.memories.get(memory_id)
+        if not record:
+            return
+        
+        # SM-2 算法
+        if quality >= 3:
+            # 成功回忆
+            if record.review_count == 0:
+                record.interval = 1
+            elif record.review_count == 1:
+                record.interval = 3
+            else:
+                record.interval = int(record.interval * record.easy_factor)
+            
+            # 更新 Easy Factor
+            record.easy_factor = max(1.3, record.easy_factor + (0.1 - (5 - quality) * 0.08))
+        else:
+            # 失败回忆
+            record.interval = 1
+            record.easy_factor = max(1.3, record.easy_factor - 0.2)
+        
+        record.review_count += 1
+        record.next_review = datetime.now() + timedelta(days=record.interval)
+        record.retention_score = 1.0
+        record.last_accessed = datetime.now()
+        
+        self._save_memories()
+        
+        logger.info(f"[衰减管理] 强化记忆: {memory_id}, 下次复习: {record.next_review.strftime('%Y-%m-%d')}")
+    
+    def apply_decay(self) -> List[str]:
+        """
+        应用遗忘衰减
+        
+        Returns:
+            归档的记忆ID列表
+        """
+        archived_ids = []
+        now = datetime.now()
+        
+        for memory_id, record in self.memories.items():
+            if record.archived:
+                continue
+            
+            # 计算年龄
+            age_hours = (now - record.created_at).total_seconds() / 3600
+            
+            # 计算保留率
+            record.retention_score = self.ebbinghaus.calculate_retention(age_hours)
+            
+            # 检查是否归档
+            if record.retention_score < 0.3 and record.importance < 0.6:
+                record.archived = True
+                archived_ids.append(memory_id)
+                logger.info(f"[衰减管理] 归档: {memory_id}")
+        
+        self._save_memories()
+        
+        return archived_ids
+    
+    def get_memories_for_review(self) -> List[Dict]:
+        """获取需要复习的记忆"""
+        now = datetime.now()
+        reviews = []
+        
+        for memory_id, record in self.memories.items():
+            if record.archived:
+                continue
+            
+            if record.next_review and record.next_review <= now:
+                reviews.append(record.to_dict())
+        
+        return reviews
+    
+    def get_stats(self) -> Dict:
+        """获取统计"""
+        total = len(self.memories)
+        archived = sum(1 for m in self.memories.values() if m.archived)
+        
+        retention_scores = [m.retention_score for m in self.memories.values() if not m.archived]
+        avg_retention = sum(retention_scores) / len(retention_scores) if retention_scores else 1.0
+        
+        return {
+            "total_memories": total,
+            "active_memories": total - archived,
+            "archived_count": archived,
+            "average_retention": round(avg_retention, 2)
+        }
+    
+    def _load_memories(self):
+        """加载记忆"""
+        memory_file = self.storage_path / "memories.json"
+        
+        if memory_file.exists():
+            try:
+                with open(memory_file, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                
+                for memory_id, record_data in data.items():
+                    self.memories[memory_id] = MemoryRecord.from_dict(record_data)
+                
+                logger.info(f"[衰减管理] 加载 {len(self.memories)} 条记忆")
+            except Exception as e:
+                logger.error(f"[衰减管理] 加载失败: {e}")
+    
+    def _save_memories(self):
+        """保存记忆"""
+        memory_file = self.storage_path / "memories.json"
+        
+        try:
+            data = {mid: record.to_dict() for mid, record in self.memories.items()}
+            
+            with open(memory_file, "w", encoding="utf-8") as f:
+                json.dump(data, f, ensure_ascii=False, indent=2)
+        except Exception as e:
+            logger.error(f"[衰减管理] 保存失败: {e}")
+
+
+# ==================== 全局实例 ====================
+
+_decay_manager_instance = None
+
+
+def get_decay_manager() -> DecayManager:
+    """获取衰减管理器实例"""
+    global _decay_manager_instance
+    if _decay_manager_instance is None:
+        _decay_manager_instance = DecayManager()
+    return _decay_manager_instance

doudou_memory/core/intelligent_manager.py

@@ -0,0 +1,339 @@
+"""
+智能记忆管理器
+Intelligent Memory Manager
+
+功能：
+1. 自动提取：从对话中自动提取关键记忆
+2. 操作决策：决定 ADD/UPDATE/DELETE/NOOP
+"""
+
+import requests
+import json
+import re
+import logging
+from datetime import datetime
+from typing import Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# 默认 API 配置
+DEFAULT_API_KEY = ""
+DEFAULT_MODEL = "glm-5"
+DEFAULT_API_URL = "https://coding.dashscope.aliyuncs.com/v1/chat/completions"
+
+
+class IntelligentMemoryManager:
+    """
+    智能记忆管理器
+    
+    实现自动提取和操作决策
+    """
+    
+    def __init__(self, api_key: str = None, model: str = DEFAULT_MODEL):
+        self.api_key = api_key or DEFAULT_API_KEY
+        self.model = model
+        self.api_url = DEFAULT_API_URL
+        
+        # 延迟加载
+        self._decay_manager = None
+        self._working_memory = None
+    
+    def _get_decay_manager(self):
+        """延迟加载衰减管理器"""
+        if self._decay_manager is None:
+            from .forgetting_mechanism import get_decay_manager
+            self._decay_manager = get_decay_manager()
+        return self._decay_manager
+    
+    def _get_working_memory(self):
+        """延迟加载工作记忆"""
+        if self._working_memory is None:
+            from .working_memory import get_working_memory
+            self._working_memory = get_working_memory()
+        return self._working_memory
+    
+    def _call_llm(self, prompt: str, max_tokens: int = 500) -> str:
+        """调用 LLM"""
+        if not self.api_key:
+            logger.warning("[智能记忆] API Key 未配置")
+            return ""
+        
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json"
+        }
+        
+        payload = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": prompt}],
+            "max_tokens": max_tokens
+        }
+        
+        try:
+            resp = requests.post(self.api_url, headers=headers, json=payload, timeout=60)
+            
+            if resp.status_code == 200:
+                result = resp.json()
+                return result.get("choices", [{}])[0].get("message", {}).get("content", "")
+            else:
+                logger.error(f"[智能记忆] API 错误: {resp.status_code}")
+                return ""
+        except Exception as e:
+            logger.error(f"[智能记忆] 调用失败: {e}")
+            return ""
+    
+    def _extract_json(self, text: str) -> Optional[Dict]:
+        """从文本中提取 JSON"""
+        try:
+            return json.loads(text)
+        except:
+            pass
+        
+        # 查找 JSON 块
+        json_match = re.search(r'```json\s*([\s\S]*?)\s*```', text)
+        if json_match:
+            try:
+                return json.loads(json_match.group(1))
+            except:
+                pass
+        
+        # 查找裸 JSON
+        json_match = re.search(r'\{[\s\S]*\}', text)
+        if json_match:
+            try:
+                return json.loads(json_match.group())
+            except:
+                pass
+        
+        return None
+    
+    def extract_memories(self, conversation: str, 
+                         context: str = "") -> List[Dict]:
+        """
+        从对话中自动提取记忆
+        
+        Args:
+            conversation: 对话内容
+            context: 额外上下文
+        
+        Returns:
+            提取的记忆列表
+        """
+        prompt = f"""从以下对话中提取关键记忆信息，返回 JSON 格式：
+
+对话：
+{conversation}
+
+上下文：{context}
+
+要求：提取重要的事实、偏好、决策，格式如下：
+{{"memories": [{{"content": "...", "type": "fact", "importance": 0.8}}]}}
+
+只返回 JSON，不要其他内容。"""
+        
+        response = self._call_llm(prompt, max_tokens=1000)
+        
+        if not response:
+            return []
+        
+        result = self._extract_json(response)
+        
+        if result and "memories" in result:
+            memories = result["memories"]
+            logger.info(f"[智能记忆] 提取 {len(memories)} 条记忆")
+            return memories
+        
+        return []
+    
+    def decide_operations(self, new_memories: List[Dict],
+                          existing_memories: List[Dict] = None) -> List[Dict]:
+        """
+        决定记忆操作
+        
+        Args:
+            new_memories: 新提取的记忆
+            existing_memories: 现有相关记忆
+        
+        Returns:
+            操作列表
+        """
+        if not new_memories:
+            return []
+        
+        # 如果没有现有记忆，全部 ADD
+        if not existing_memories:
+            return [{"action": "ADD", "memory": mem} for mem in new_memories]
+        
+        # 构建描述
+        existing_desc = "\n".join([
+            f"{i+1}. \"{mem.get('content', '')}\" (id: {mem.get('id', 'unknown')})"
+            for i, mem in enumerate(existing_memories[:10])
+        ])
+        
+        new_desc = "\n".join([f"- {mem.get('content', '')}" for mem in new_memories])
+        
+        prompt = f"""根据新信息和现有记忆，决定要执行的操作：
+
+现有记忆：
+{existing_desc}
+
+新信息：
+{new_desc}
+
+请决定操作（返回 JSON）：
+{{"operations": [
+  {{"action": "ADD", "memory": {{"content": "...", "type": "fact", "importance": 0.8}}}},
+  {{"action": "UPDATE", "memory_id": "...", "new_content": "..."}},
+  {{"action": "DELETE", "memory_id": "..."}},
+  {{"action": "NOOP"}}
+]}}
+
+只返回 JSON。"""
+        
+        response = self._call_llm(prompt, max_tokens=1000)
+        
+        if not response:
+            # 降级：全部 ADD
+            return [{"action": "ADD", "memory": mem} for mem in new_memories]
+        
+        result = self._extract_json(response)
+        
+        if result and "operations" in result:
+            logger.info(f"[智能记忆] 决策 {len(result['operations'])} 个操作")
+            return result["operations"]
+        
+        # 降级：全部 ADD
+        return [{"action": "ADD", "memory": mem} for mem in new_memories]
+    
+    def execute_operations(self, operations: List[Dict]) -> Dict:
+        """
+        执行记忆操作
+        
+        Returns:
+            执行结果
+        """
+        results = {
+            "added": 0,
+            "updated": 0,
+            "deleted": 0,
+            "skipped": 0,
+            "errors": []
+        }
+        
+        decay_manager = self._get_decay_manager()
+        
+        for op in operations:
+            action = op.get("action", "NOOP")
+            
+            try:
+                if action == "ADD":
+                    memory = op.get("memory", {})
+                    content = memory.get("content", "")
+                    importance = memory.get("importance", 0.5)
+                    mem_type = memory.get("type", "fact")
+                    
+                    if content:
+                        memory_id = f"mem_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+                        decay_manager.register_memory(
+                            memory_id=memory_id,
+                            content=content,
+                            importance=importance,
+                            memory_type=mem_type
+                        )
+                        results["added"] += 1
+                
+                elif action == "UPDATE":
+                    memory_id = op.get("memory_id", "")
+                    new_content = op.get("new_content", "")
+                    
+                    if memory_id and new_content:
+                        if memory_id in decay_manager.memories:
+                            decay_manager.memories[memory_id].content = new_content
+                            results["updated"] += 1
+                
+                elif action == "DELETE":
+                    memory_id = op.get("memory_id", "")
+                    
+                    if memory_id and memory_id in decay_manager.memories:
+                        decay_manager.memories[memory_id].archived = True
+                        results["deleted"] += 1
+                
+                elif action == "NOOP":
+                    results["skipped"] += 1
+            
+            except Exception as e:
+                results["errors"].append(str(e))
+        
+        logger.info(f"[智能记忆] 执行完成: +{results['added']} ~{results['updated']} -{results['deleted']}")
+        
+        return results
+    
+    def process_conversation(self, conversation: str,
+                              context: str = "") -> Dict:
+        """
+        处理对话：提取 + 决策 + 执行
+        
+        Args:
+            conversation: 对话内容
+            context: 额外上下文
+        
+        Returns:
+            处理结果
+        """
+        # Phase 1: 提取
+        new_memories = self.extract_memories(conversation, context)
+        
+        if not new_memories:
+            return {"status": "no_memories", "extracted": 0}
+        
+        # Phase 2: 检索相关记忆
+        decay_manager = self._get_decay_manager()
+        existing_memories = []
+        
+        for mem in new_memories:
+            content = mem.get("content", "")
+            for mid, m in decay_manager.memories.items():
+                if m.archived:
+                    continue
+                existing_content = m.content
+                # 简单关键词匹配
+                if any(word in existing_content for word in content.split()[:3] if len(word) > 2):
+                    existing_memories.append({"id": mid, **m.to_dict()})
+        
+        # Phase 3: 决策
+        operations = self.decide_operations(new_memories, existing_memories)
+        
+        # Phase 4: 执行
+        results = self.execute_operations(operations)
+        
+        return {
+            "status": "ok",
+            "extracted": len(new_memories),
+            "existing_checked": len(existing_memories),
+            "operations": results
+        }
+
+
+# ==================== 全局实例 ====================
+
+_manager_instance = None
+
+
+def get_intelligent_manager() -> IntelligentMemoryManager:
+    """获取智能记忆管理器实例"""
+    global _manager_instance
+    if _manager_instance is None:
+        _manager_instance = IntelligentMemoryManager()
+    return _manager_instance
+
+
+# ==================== 便捷函数 ====================
+
+def smart_memorize(conversation: str, context: str = "") -> Dict:
+    """
+    智能记忆：自动提取 + 决策 + 存储
+    
+    替代手动 memorize() 调用
+    """
+    manager = get_intelligent_manager()
+    return manager.process_conversation(conversation, context)