iflow-mcp_hanw39_reasoning-bank-mcp 0.2.0__py3-none-any.whl

src/merge/strategies/voting_merge.py

@@ -0,0 +1,108 @@
+"""
+Voting-based Merge Strategy
+
+Selects the "best" memory from a group and removes the rest.
+Does not create a new merged memory, just chooses a representative.
+"""
+
+from typing import List, Dict, Any, Optional
+from ..base import MergeStrategy
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class VotingMergeStrategy(MergeStrategy):
+    """
+    Voting merge: Select best memory, remove others.
+
+    Selection criteria (in priority order):
+    1. Highest retrieval_count (most used)
+    2. Success=true preferred over false
+    3. Most recent timestamp
+    """
+
+    @property
+    def name(self) -> str:
+        return "voting"
+
+    def __init__(self, config: Dict[str, Any]):
+        super().__init__(config)
+        self.min_group_size = config.get("voting", {}).get("min_group_size", 2)
+
+    async def should_merge(
+        self,
+        memories: List[Dict[str, Any]],
+        agent_id: Optional[str] = None
+    ) -> bool:
+        """
+        Check if group meets minimum size requirement.
+        Also validates all memories belong to the same agent.
+        """
+        if len(memories) < self.min_group_size:
+            return False
+
+        # Validate all memories have same agent_id
+        if agent_id:
+            for mem in memories:
+                if mem.get("agent_id") != agent_id:
+                    logger.warning(
+                        f"Memory {mem.get('memory_id')} has different agent_id: "
+                        f"{mem.get('agent_id')} != {agent_id}"
+                    )
+                    return False
+
+        return True
+
+    async def merge(
+        self,
+        memories: List[Dict[str, Any]],
+        agent_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Select the "best" memory from the group.
+
+        Returns the selected memory with added merge metadata.
+        """
+        if not memories:
+            raise ValueError("Cannot merge empty memory list")
+
+        # Validate agent_id consistency
+        if agent_id:
+            for mem in memories:
+                if mem.get("agent_id") != agent_id:
+                    raise ValueError(
+                        f"Memory {mem.get('memory_id')} belongs to different agent"
+                    )
+
+        # Sort by: retrieval_count (desc), success (desc), timestamp (desc)
+        # todo 是否不公平，对于新经验
+        def sort_key(mem):
+            return (
+                mem.get("retrieval_count", 0),  # Higher is better
+                1 if mem.get("success", False) else 0,  # Success preferred
+                mem.get("timestamp", "")  # More recent preferred
+            )
+
+        sorted_memories = sorted(memories, key=sort_key, reverse=True)
+        best_memory = sorted_memories[0]
+
+        logger.info(
+            f"Selected best memory: {best_memory.get('memory_id')} "
+            f"from group of {len(memories)} (agent_id={agent_id})"
+        )
+
+        # Return the best memory with merge metadata
+        merged_from = [ m["memory_id"] for m in memories if m["memory_id"] != best_memory["memory_id"] ]
+
+        return {
+            **best_memory,
+            "is_merged": True,
+            "merged_from": merged_from,
+            "merge_metadata": {
+                "merge_strategy": self.name,
+                "original_count": len(memories),
+                "selection_reason": "highest_usage",
+                "abstraction_level": 0  # Same level, just selected best
+            }
+        }

src/prompts/__init__.py

@@ -0,0 +1,21 @@
+"""提示词模块"""
+from .templates import (
+    EXTRACT_SUCCESS_PROMPT,
+    EXTRACT_FAILURE_PROMPT,
+    JUDGE_TRAJECTORY_PROMPT,
+    get_extract_prompt,
+    get_judge_prompt,
+    get_merge_prompt,
+)
+from .formatters import format_trajectory, format_memory_for_prompt
+
+__all__ = [
+    "EXTRACT_SUCCESS_PROMPT",
+    "EXTRACT_FAILURE_PROMPT",
+    "JUDGE_TRAJECTORY_PROMPT",
+    "get_extract_prompt",
+    "get_judge_prompt",
+    "get_merge_prompt",
+    "format_trajectory",
+    "format_memory_for_prompt",
+]

src/prompts/formatters.py

@@ -0,0 +1,74 @@
+"""轨迹格式化工具"""
+from typing import List, Dict
+
+
+def format_trajectory(trajectory: List[Dict]) -> str:
+    """
+    将轨迹列表格式化为可读的文本
+
+    Args:
+        trajectory: 轨迹步骤列表，每个步骤包含：
+            - step: 步骤序号
+            - role: 角色 ("user" | "assistant" | "tool")
+            - content: 具体内容
+            - metadata: 额外信息（可选）
+
+    Returns:
+        格式化的轨迹文本
+    """
+    if not trajectory:
+        return "（空轨迹）"
+
+    lines = []
+
+    for step_data in trajectory:
+        step_num = step_data.get("step", "?")
+        role = step_data.get("role", "unknown")
+        content = step_data.get("content", "")
+        metadata = step_data.get("metadata", {})
+
+        # 角色标签
+        role_label = {
+            "user": "User",
+            "assistant": "Assistant",
+            "tool": "Tool"
+        }.get(role, role.capitalize())
+
+        # 如果是 tool 角色且有工具名称
+        if role == "tool" and "tool_name" in metadata:
+            tool_name = metadata["tool_name"]
+            # todo action_type？
+            action_type = metadata.get("action_type", "")
+            if action_type:
+                role_label = f"Tool - {tool_name} ({action_type})"
+            else:
+                role_label = f"Tool - {tool_name}"
+
+        # 格式化步骤
+        line = f"步骤 {step_num} [{role_label}]: {content}"
+        lines.append(line)
+
+    return "\n".join(lines)
+
+
+def format_memory_for_prompt(memories: List[Dict]) -> str:
+    """
+    将检索到的记忆格式化为可直接用于 LLM 提示的文本
+
+    Args:
+        memories: 记忆项列表
+
+    Returns:
+        格式化的提示文本
+    """
+    if not memories:
+        return ""
+
+    prompt = "以下是我从过去与环境的交互中积累的一些记忆项，可能有助于解决任务。当您觉得它们相关时可以使用它们。\n\n"
+
+    for i, mem in enumerate(memories, 1):
+        status = "✓ 成功经验" if mem.get("success", True) else "✗ 失败教训"
+        prompt += f"**记忆 {i} [{status}] - {mem['title']}**\n"
+        prompt += f"{mem['content']}\n\n"
+
+    return prompt.strip()

src/prompts/templates.py

@@ -0,0 +1,184 @@
+"""提示词模板"""
+
+
+# 成功轨迹提取提示词
+EXTRACT_SUCCESS_PROMPT = """你是一个专业的AI经验总结专家。请分析以下成功完成的任务轨迹，并提取可复用的推理策略。
+
+**任务查询：**
+{query}
+
+**成功的轨迹：**
+{trajectory}
+
+**分析目标：**
+1. 成功原因分析：解释该轨迹中关键的推理路径、决策点或信息利用方式，说明为何任务能被成功完成。
+2. 抽象可复用策略：从成功行为中提炼出可迁移的思维模式或操作步骤，而非表层动作。
+3. 形成记忆项（3条以内）：每条代表一种通用策略或方法论，适合未来相似任务的快速复用。
+
+**输出格式（JSON）：**
+```json
+{{
+  "memories": [
+    {{
+      "title": "策略标题（5-10字）",
+      "description": "一句话说明策略适用的典型场景",
+      "content": "详细说明策略的逻辑结构、关键判断点和可执行步骤"
+    }}
+  ]
+}}
+```
+
+**注意事项：**
+- 聚焦于“如何思考”而不是“做了什么”
+- 优先提取体现分解问题、假设验证、信息整合、动态调整等高层推理能力的内容
+- 策略要具备跨任务适用性，避免与具体工具、网站或数据源绑定
+- 输出应简洁、概念清晰、结构稳定，方便后续自动化学习或知识库吸收
+- 避免冗余，每个记忆项应该关注不同的方面
+
+请按照上述格式输出，只输出JSON，不要包含其他内容。
+"""
+
+
+# 失败轨迹提取提示词
+EXTRACT_FAILURE_PROMPT = """你是一个专业的AI经验总结专家。请分析以下失败的任务轨迹，并提取教训和预防策略。
+
+**任务查询：**
+{query}
+
+**失败的轨迹：**
+{trajectory}
+
+**要求：**
+1. 反思这个轨迹为何失败
+2. 识别导致失败的关键错误或陷阱
+3. 提取最多3个记忆项（教训），每个记忆项包含：
+   - **标题**：简短描述教训（5-10个字）
+   - **描述**：一句话说明这个错误的常见场景
+   - **内容**：详细说明错误原因、后果，以及如何避免
+
+**注意事项：**
+- 提取的教训应该具有警示作用，帮助避免类似错误
+- 避免冗余，每个记忆项应该关注不同的失败原因
+- 内容要包含"不要做X，应该做Y"的明确指导
+
+**输出格式（JSON）：**
+```json
+{{
+  "memories": [
+    {{
+      "title": "教训标题",
+      "description": "错误场景描述",
+      "content": "详细的错误分析和避免方法"
+    }}
+  ]
+}}
+```
+
+请按照上述格式输出，只输出JSON，不要包含其他内容。
+"""
+
+
+# 轨迹判断提示词
+JUDGE_TRAJECTORY_PROMPT = """你是一个专业的任务评估专家。请判断以下任务执行是否成功。
+
+**任务查询：**
+{query}
+
+**执行轨迹：**
+{trajectory}
+
+**判断标准：**
+- 是否完成了任务查询中要求的目标
+- 最终结果是否准确、完整
+- 执行过程是否达到了预期状态
+
+**要求：**
+请仔细分析轨迹，判断任务是"成功"还是"失败"，并给出简短的理由。
+
+**输出格式（JSON）：**
+```json
+{{
+  "result": "success",  // "success" 或 "failure"
+  "reason": "简短的判断理由（1-2句话）"
+}}
+```
+
+请按照上述格式输出，只输出JSON，不要包含其他内容。
+"""
+
+
+# 记忆合并提示词
+MEMORY_MERGE_PROMPT = """你是一个经验提炼专家。以下是 {len(memories)} 条相似的经验，它们来自同一个AI Agent在不同任务中积累的知识。
+
+{memories_text}
+
+请分析这些经验的**共同模式**，提炼出一条更通用、更深层的经验。
+
+要求：
+1. **title**: 5-15字的简洁标题，概括核心策略
+2. **description**: 一句话（20-40字）概括适用场景
+3. **content**: 详细描述通用策略（200-500字），包括：
+   - 这个策略解决什么问题
+   - 为什么这样做
+   - 如何应用到新场景
+   - 需要注意的事项
+4. **query**: 提炼出的通用场景描述（可以是"<通用场景：xxx>"格式）
+5. **abstraction_level**: 抽象层级
+   - 0 = 具体案例（特定问题的解决方案）
+   - 1 = 模式识别（一类问题的通用方法）
+   - 2 = 原则层面（跨领域的指导原则）
+
+请以JSON格式返回，只返回JSON，不要其他内容：
+```json
+{{
+  "title": "...",
+  "description": "...",
+  "content": "...",
+  "query": "...",
+  "abstraction_level": 1
+}}
+```
+"""
+
+
+def get_extract_prompt(query: str, trajectory: str, success: bool) -> str:
+    """
+    获取记忆提取提示词
+
+    Args:
+        query: 任务查询
+        trajectory: 格式化的轨迹文本
+        success: 是否成功
+
+    Returns:
+        完整的提示词
+    """
+    template = EXTRACT_SUCCESS_PROMPT if success else EXTRACT_FAILURE_PROMPT
+    return template.format(query=query, trajectory=trajectory)
+
+
+def get_judge_prompt(query: str, trajectory: str) -> str:
+    """
+    获取轨迹判断提示词
+
+    Args:
+        query: 任务查询
+        trajectory: 格式化的轨迹文本
+
+    Returns:
+        完整的提示词
+    """
+    return JUDGE_TRAJECTORY_PROMPT.format(query=query, trajectory=trajectory)
+
+
+def get_merge_prompt(memories_text: str) -> str:
+    """
+    获取记忆合并提示词
+
+    Args:
+        memories_text: 需要合并的记忆项
+
+    Returns:
+        完整的提示词
+    """
+    return MEMORY_MERGE_PROMPT.format(memories_text=memories_text)

src/retrieval/__init__.py

@@ -0,0 +1,8 @@
+"""检索模块"""
+from .base import RetrievalStrategy
+from .factory import RetrievalFactory
+
+__all__ = [
+    "RetrievalStrategy",
+    "RetrievalFactory",
+]

src/retrieval/base.py

@@ -0,0 +1,37 @@
+"""检索策略抽象基类"""
+from abc import ABC, abstractmethod
+from typing import List, Tuple, Dict
+import numpy as np
+
+
+class RetrievalStrategy(ABC):
+    """检索策略抽象基类"""
+
+    @abstractmethod
+    async def retrieve(
+        self,
+        query: str,
+        query_embedding: np.ndarray,
+        storage_backend: 'StorageBackend',
+        top_k: int = 1,
+        **kwargs
+    ) -> List[Tuple[str, float]]:
+        """
+        检索相关记忆
+
+        Args:
+            query: 查询文本
+            query_embedding: 查询的嵌入向量
+            storage_backend: 存储后端实例
+            top_k: 返回的记忆数量
+            **kwargs: 其他参数
+
+        Returns:
+            [(memory_id, score), ...] 按分数降序排列
+        """
+        pass
+
+    @abstractmethod
+    def get_name(self) -> str:
+        """返回策略名称"""
+        pass

src/retrieval/factory.py

@@ -0,0 +1,55 @@
+"""检索策略工厂"""
+from typing import Dict
+from .base import RetrievalStrategy
+from .strategies import CosineRetrievalStrategy, HybridRetrievalStrategy
+
+
+class RetrievalFactory:
+    """检索策略工厂"""
+
+    _strategies = {
+        "cosine": CosineRetrievalStrategy,
+        "hybrid": HybridRetrievalStrategy,
+    }
+
+    @classmethod
+    def create(cls, strategy_name: str, config: Dict = None) -> RetrievalStrategy:
+        """
+        创建检索策略实例
+
+        Args:
+            strategy_name: 策略名称 ("cosine" | "hybrid")
+            config: 策略配置参数
+
+        Returns:
+            RetrievalStrategy 实例
+        """
+        if strategy_name not in cls._strategies:
+            raise ValueError(
+                f"Unknown retrieval strategy: {strategy_name}. "
+                f"Available strategies: {list(cls._strategies.keys())}"
+            )
+
+        strategy_class = cls._strategies[strategy_name]
+
+        # 根据策略类型传递配置
+        if strategy_name == "hybrid":
+            return strategy_class(config)
+        else:
+            return strategy_class()
+
+    @classmethod
+    def register_strategy(cls, name: str, strategy_class: type):
+        """
+        注册新的检索策略（插件机制）
+
+        Args:
+            name: 策略名称
+            strategy_class: 策略类
+        """
+        cls._strategies[name] = strategy_class
+
+    @classmethod
+    def list_strategies(cls) -> list:
+        """返回所有可用的策略名称"""
+        return list(cls._strategies.keys())

src/retrieval/strategies/__init__.py

@@ -0,0 +1,8 @@
+"""检索策略包"""
+from .cosine_retrieval import CosineRetrievalStrategy
+from .hybrid_retrieval import HybridRetrievalStrategy
+
+__all__ = [
+    "CosineRetrievalStrategy",
+    "HybridRetrievalStrategy",
+]

src/retrieval/strategies/cosine_retrieval.py

@@ -0,0 +1,47 @@
+"""余弦相似度检索策略（论文基线方法）"""
+from typing import List, Tuple
+import numpy as np
+from ..base import RetrievalStrategy
+from ...utils.similarity import cosine_similarity
+
+
+class CosineRetrievalStrategy(RetrievalStrategy):
+    """纯余弦相似度检索策略"""
+
+    async def retrieve(
+        self,
+        query: str,
+        query_embedding: np.ndarray,
+        storage_backend,
+        top_k: int = 1,
+        agent_id: str = None,
+        **kwargs
+    ) -> List[Tuple[str, float]]:
+        """
+        使用余弦相似度检索记忆
+
+        这是论文中使用的基线方法
+
+        Args:
+            agent_id: Agent ID，用于过滤记忆
+        """
+        # 获取所有记忆的嵌入（支持 agent_id 过滤）
+        memory_embeddings = await storage_backend.get_all_embeddings(agent_id)
+
+        if not memory_embeddings:
+            return []
+
+        # 计算相似度
+        similarities = []
+        for memory_id, memory_vec in memory_embeddings.items():
+            score = cosine_similarity(query_embedding, memory_vec)
+            similarities.append((memory_id, float(score)))
+
+        # 按分数降序排序
+        similarities.sort(key=lambda x: x[1], reverse=True)
+
+        # 返回 Top-K
+        return similarities[:top_k]
+
+    def get_name(self) -> str:
+        return "cosine"

src/retrieval/strategies/hybrid_retrieval.py

@@ -0,0 +1,155 @@
+"""混合评分检索策略"""
+from typing import List, Tuple, Dict
+import numpy as np
+from datetime import datetime, timezone
+from ..base import RetrievalStrategy
+from ...utils.similarity import cosine_similarity
+
+
+class HybridRetrievalStrategy(RetrievalStrategy):
+    """
+    混合评分检索策略
+
+    综合考虑多个因素：
+    - 语义相似度（余弦相似度）
+    - 记忆置信度（基于检索次数）
+    - 成功/失败偏好
+    - 时间衰减
+    """
+
+    def __init__(self, config: Dict = None):
+        """
+        初始化混合检索策略
+
+        Args:
+            config: 配置字典，包含权重和衰减参数
+        """
+        default_weights = {
+            "semantic": 0.6,
+            "confidence": 0.2,
+            "success": 0.15,
+            "recency": 0.05
+        }
+
+        if config:
+            self.weights = config.get("weights", default_weights)
+            self.time_decay_halflife = config.get("time_decay_halflife", 30)
+        else:
+            self.weights = default_weights
+            self.time_decay_halflife = 30
+
+    def _compute_time_decay(self, created_at: str) -> float:
+        """
+        计算时间衰减因子
+
+        使用指数衰减: decay = exp(-λ * t)
+        其中 λ = ln(2) / halflife
+
+        Args:
+            created_at: ISO 8601 时间戳
+
+        Returns:
+            衰减因子 [0, 1]，越新越接近 1
+        """
+        try:
+            created_time = datetime.fromisoformat(created_at.replace('Z', '+00:00'))
+            current_time = datetime.now(timezone.utc)
+            days_elapsed = (current_time - created_time).days
+
+            # 指数衰减
+            lambda_decay = np.log(2) / self.time_decay_halflife
+            decay = np.exp(-lambda_decay * days_elapsed)
+
+            return float(decay)
+        except Exception:
+            # 如果时间解析失败，返回默认值
+            return 1.0
+
+    def _compute_confidence_score(self, memory: Dict) -> float:
+        """
+        计算记忆置信度
+
+        基于检索次数，使用对数缩放防止过度偏向高频记忆
+
+        Args:
+            memory: 记忆项字典
+
+        Returns:
+            置信度 [0.5, 1.0]
+        """
+        retrieval_count = memory.get("retrieval_count", 0)
+
+        # 使用 tanh 进行平滑映射
+        # confidence ∈ [0.5, 1.0]
+        confidence = 0.5 + 0.5 * np.tanh(retrieval_count / 10)
+
+        return float(confidence)
+
+    async def retrieve(
+        self,
+        query: str,
+        query_embedding: np.ndarray,
+        storage_backend,
+        top_k: int = 1,
+        agent_id: str = None,
+        **kwargs
+    ) -> List[Tuple[str, float]]:
+        """
+        使用混合评分检索记忆
+
+        score = w1*semantic + w2*confidence + w3*success - w4*(1-recency)
+
+        Args:
+            agent_id: Agent ID，用于过滤记忆
+        """
+        # 获取所有记忆（支持 agent_id 过滤）
+        memory_embeddings = await storage_backend.get_all_embeddings(agent_id)
+        memories = await storage_backend.get_all_memories(agent_id)
+
+        if not memories or not memory_embeddings:
+            return []
+
+        # 创建 memory_id -> memory 的映射
+        memory_map = {m["memory_id"]: m for m in memories}
+
+        scores = []
+
+        for memory in memories:
+            memory_id = memory["memory_id"]
+
+            # 确保嵌入存在
+            if memory_id not in memory_embeddings:
+                continue
+
+            memory_vec = memory_embeddings[memory_id]
+
+            # 1. 语义相似度
+            semantic_sim = cosine_similarity(query_embedding, memory_vec)
+
+            # 2. 置信度
+            confidence = self._compute_confidence_score(memory)
+
+            # 3. 成功/失败偏好
+            success_bonus = 1.0 if memory.get("success", True) else -0.5
+
+            # 4. 时间衰减
+            time_decay = self._compute_time_decay(memory["timestamp"])
+
+            # 混合评分
+            final_score = (
+                self.weights["semantic"] * semantic_sim
+                + self.weights["confidence"] * confidence
+                + self.weights["success"] * success_bonus
+                - self.weights["recency"] * (1 - time_decay)  # 越新越好
+            )
+
+            scores.append((memory_id, float(final_score)))
+
+        # 按分数降序排序
+        scores.sort(key=lambda x: x[1], reverse=True)
+
+        # 返回 Top-K
+        return scores[:top_k]
+
+    def get_name(self) -> str:
+        return "hybrid"