Skip to content
Python
8.1 KB
Raw Blame
"""
Agent Memory - 记忆评分

计算记忆的综合评分,考虑语义相似度、时间衰减、重要性等因素
"""

import math
from typing import List, Optional
from datetime import datetime

from ..models import MemoryEntry, MemoryScore
from ..config import RecallConfig


class MemoryScorer:
    """
    记忆评分器
    
    计算记忆的综合评分,支持:
    - 语义相似度评分
    - 时间衰减评分
    - 重要性评分
    - 访问频率评分
    """
    
    def __init__(self, config: Optional[RecallConfig] = None):
        """
        初始化评分器
        
        Args:
            config: 召回配置
        """
        self.config = config or RecallConfig()
    
    def score(
        self,
        entry: MemoryEntry,
        semantic_score: float = 0.0,
        reference_time: Optional[datetime] = None
    ) -> MemoryScore:
        """
        计算单条记忆的综合评分
        
        Args:
            entry: 记忆条目
            semantic_score: 语义相似度分数(0-1)
            reference_time: 参考时间(用于计算时间衰减)
        
        Returns:
            评分结果
        """
        if reference_time is None:
            reference_time = datetime.now()
        
        # 1. 语义相似度分数(已由向量检索提供)
        semantic = max(0.0, min(1.0, semantic_score))
        
        # 2. 时间衰减分数
        recency = self._calc_recency_score(entry, reference_time)
        
        # 3. 重要性分数
        importance = self._calc_importance_score(entry)
        
        # 4. 访问频率分数
        access = self._calc_access_score(entry)
        
        return MemoryScore(
            semantic_score=semantic,
            recency_score=recency,
            importance_score=importance,
            access_score=access,
            semantic_weight=self.config.semantic_weight,
            recency_weight=self.config.recency_weight,
            importance_weight=self.config.importance_weight,
            access_weight=self.config.access_weight,
        )
    
    def _get_event_time(self, entry: MemoryEntry) -> Optional[datetime]:
        """获取 entry 的事件时间,兼容 V2 MemoryNode 和 V1 metadata"""
        # V2: MemoryNode 直接有 created_at / valid_from
        if hasattr(entry, 'created_at') and entry.created_at is not None:
            return entry.created_at
        # V1: entry.metadata.event_time
        if hasattr(entry, 'metadata') and entry.metadata and hasattr(entry.metadata, 'event_time'):
            return entry.metadata.event_time
        return None

    def _get_importance(self, entry: MemoryEntry) -> float:
        """获取 entry 的重要性,兼容 V2 MemoryNode 和 V1 metadata"""
        # V2: MemoryNode 直接有 confidence 字段作为重要性指标
        if hasattr(entry, 'confidence') and entry.confidence is not None:
            return entry.confidence
        # V1: entry.metadata.importance
        if hasattr(entry, 'metadata') and entry.metadata and hasattr(entry.metadata, 'importance'):
            return entry.metadata.importance
        return 0.5

    def _get_access_count(self, entry: MemoryEntry) -> int:
        """获取 entry 的访问次数,兼容 V2 MemoryNode 和 V1 metadata"""
        # V2: MemoryNode 直接有 access_count
        if hasattr(entry, 'access_count') and entry.access_count is not None:
            return entry.access_count
        # V1: entry.metadata.access_count
        if hasattr(entry, 'metadata') and entry.metadata and hasattr(entry.metadata, 'access_count'):
            return entry.metadata.access_count
        return 0

    def _get_semantic_score(self, entry: MemoryEntry) -> float:
        """获取 entry 的语义分数,兼容 score 对象"""
        if hasattr(entry, 'score') and entry.score and hasattr(entry.score, 'semantic_score'):
            return entry.score.semantic_score
        return 0.0

    def _get_final_score(self, entry: MemoryEntry) -> float:
        """获取 entry 的最终评分,兼容 score 对象"""
        if hasattr(entry, 'score') and entry.score and hasattr(entry.score, 'final_score'):
            return entry.score.final_score
        return 0.0

    def _calc_recency_score(
        self,
        entry: MemoryEntry,
        reference_time: datetime
    ) -> float:
        """
        计算时间衰减分数
        
        使用指数衰减:score = decay_factor ^ (days / decay_days)
        """
        event_time = self._get_event_time(entry)
        if event_time is None:
            return 0.5  # 默认中等分数
        days_passed = (reference_time - event_time).days
        
        if days_passed <= 0:
            return 1.0
        
        # 指数衰减
        decay_days = self.config.recency_decay_days
        decay_factor = self.config.recency_decay_factor
        
        score = math.pow(decay_factor, days_passed / decay_days)
        return max(0.0, min(1.0, score))
    
    def _calc_importance_score(self, entry: MemoryEntry) -> float:
        """计算重要性分数"""
        return max(0.0, min(1.0, self._get_importance(entry)))
    
    def _calc_access_score(self, entry: MemoryEntry) -> float:
        """
        计算访问频率分数
        
        使用对数函数:score = log(access_count + 1) / log(max_count + 1)
        """
        access_count = self._get_access_count(entry)
        
        # 假设最大访问次数为 100
        max_count = 100
        
        if access_count <= 0:
            return 0.0
        
        score = math.log(access_count + 1) / math.log(max_count + 1)
        return max(0.0, min(1.0, score))
    
    def score_batch(
        self,
        entries: List[MemoryEntry],
        reference_time: Optional[datetime] = None
    ) -> List[MemoryEntry]:
        """
        批量计算评分
        
        Args:
            entries: 记忆列表
            reference_time: 参考时间
        
        Returns:
            带评分的记忆列表
        """
        if reference_time is None:
            reference_time = datetime.now()
        
        for entry in entries:
            # 使用已有的语义分数
            semantic_score = self._get_semantic_score(entry)
            entry.score = self.score(entry, semantic_score, reference_time)
        
        return entries
    
    def rank(
        self,
        entries: List[MemoryEntry],
        reference_time: Optional[datetime] = None
    ) -> List[MemoryEntry]:
        """
        评分并排序
        
        Args:
            entries: 记忆列表
            reference_time: 参考时间
        
        Returns:
            按综合评分排序的记忆列表
        """
        scored = self.score_batch(entries, reference_time)
        return sorted(scored, key=lambda e: self._get_final_score(e), reverse=True)
    
    def filter_by_threshold(
        self,
        entries: List[MemoryEntry],
        min_score: float = 0.0
    ) -> List[MemoryEntry]:
        """
        按分数阈值过滤
        
        Args:
            entries: 记忆列表
            min_score: 最小分数阈值
        
        Returns:
            过滤后的记忆列表
        """
        return [e for e in entries if self._get_final_score(e) >= min_score]
    
    def adjust_weights(
        self,
        semantic_weight: Optional[float] = None,
        recency_weight: Optional[float] = None,
        importance_weight: Optional[float] = None,
        access_weight: Optional[float] = None
    ) -> None:
        """
        调整评分权重
        
        权重会自动归一化
        """
        weights = [
            semantic_weight or self.config.semantic_weight,
            recency_weight or self.config.recency_weight,
            importance_weight or self.config.importance_weight,
            access_weight or self.config.access_weight,
        ]
        
        # 归一化
        total = sum(weights)
        if total > 0:
            weights = [w / total for w in weights]
        
        self.config.semantic_weight = weights[0]
        self.config.recency_weight = weights[1]
        self.config.importance_weight = weights[2]
        self.config.access_weight = weights[3]