powermem 0.1.0__py3-none-any.whl

powermem/intelligence/manager.py

@@ -0,0 +1,148 @@
+"""
+Intelligence manager
+
+This module provides the main intelligence management interface.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+from datetime import datetime
+
+from .intelligent_memory_manager import IntelligentMemoryManager
+
+logger = logging.getLogger(__name__)
+
+
+class IntelligenceManager:
+    """
+    Main intelligence manager for memory processing.
+    """
+    
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        """
+        Initialize intelligence manager.
+        
+        Args:
+            config: Configuration dictionary
+        """
+        self.config = config or {}
+        # Check if intelligent memory is enabled
+        intelligent_config = self.config.get("intelligent_memory", {})
+        self.enabled = intelligent_config.get("enabled", False)  # Default to False for backward compatibility
+        
+        if self.enabled:
+            self.intelligent_memory_manager = IntelligentMemoryManager(self.config)
+        else:
+            self.intelligent_memory_manager = None
+            
+        logger.info(f"IntelligenceManager initialized (enabled: {self.enabled})")
+    
+    def process_metadata(
+        self,
+        content: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        context: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Process metadata with intelligence.
+        
+        Args:
+            content: Content to analyze
+            metadata: Additional metadata
+            context: Additional context
+            
+        Returns:
+            Enhanced metadata with intelligence analysis
+        """
+        if not self.enabled or not self.intelligent_memory_manager:
+            return metadata or {}
+            
+        return self.intelligent_memory_manager.process_metadata(content, metadata, context)
+    
+    async def process_metadata_async(
+        self,
+        content: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        context: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Process metadata with intelligence asynchronously.
+        
+        Args:
+            content: Content to analyze
+            metadata: Additional metadata
+            context: Additional context
+            
+        Returns:
+            Enhanced metadata with intelligence analysis
+        """
+        if not self.enabled or not self.intelligent_memory_manager:
+            return metadata or {}
+            
+        return await self.intelligent_memory_manager.process_metadata_async(content, metadata, context)
+    
+    def process_search_results(
+        self,
+        results: List[Dict[str, Any]],
+        query: str
+    ) -> List[Dict[str, Any]]:
+        """
+        Process search results with intelligence.
+        
+        Args:
+            results: Search results
+            query: Original query
+            
+        Returns:
+            Processed and ranked results
+        """
+        if not self.enabled or not self.intelligent_memory_manager:
+            # Return original results if intelligence is disabled
+            return results
+            
+        return self.intelligent_memory_manager.process_search_results(results, query)
+    
+    async def process_search_results_async(
+        self,
+        results: List[Dict[str, Any]],
+        query: str
+    ) -> List[Dict[str, Any]]:
+        """
+        Process search results with intelligence asynchronously.
+        
+        Args:
+            results: Search results
+            query: Original query
+            
+        Returns:
+            Processed and ranked results
+        """
+        if not self.enabled or not self.intelligent_memory_manager:
+            # Return original results if intelligence is disabled
+            return results
+            
+        return await self.intelligent_memory_manager.process_search_results_async(results, query)
+    
+    def optimize_memories(self) -> Dict[str, Any]:
+        """
+        Optimize memory storage.
+        
+        Returns:
+            Optimization results
+        """
+        if not self.enabled or not self.intelligent_memory_manager:
+            return {"optimized": False, "reason": "intelligence disabled"}
+            
+        return self.intelligent_memory_manager.optimize_memories()
+    
+    def get_memory_stats(self) -> Dict[str, Any]:
+        """
+        Get memory statistics.
+        
+        Returns:
+            Memory statistics
+        """
+        if not self.enabled or not self.intelligent_memory_manager:
+            return {"stats": "intelligence disabled"}
+            
+        return self.intelligent_memory_manager.get_memory_stats()

powermem/intelligence/plugin.py

@@ -0,0 +1,229 @@
+"""
+Pluggable intelligent memory plugin interface and default implementation.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+from .importance_evaluator import ImportanceEvaluator
+from .ebbinghaus_algorithm import EbbinghausAlgorithm
+
+
+logger = logging.getLogger(__name__)
+
+
+class IntelligentMemoryPlugin:
+    """
+    Interface for intelligent memory plugins.
+    Implementations can annotate new memories and manage lifecycle on access/search.
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        self.config = config or {}
+
+    @property
+    def enabled(self) -> bool:  # pragma: no cover - trivial
+        return bool(self.config.get("enabled", False))
+
+    def on_add(self, *, content: str, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        Hook invoked before persisting a memory. Return extra fields to merge into record.
+        """
+        return {}
+
+    def on_get(self, memory: Dict[str, Any]) -> Tuple[Optional[Dict[str, Any]], bool]:
+        """
+        Hook invoked on single memory access.
+        Returns (updates, delete_flag). If delete_flag is True, caller should delete memory.
+        """
+        return None, False
+
+    def on_search(self, results: List[Dict[str, Any]]) -> Tuple[List[Tuple[str, Dict[str, Any]]], List[str]]:
+        """
+        Hook invoked on batch search results.
+        Returns (updates, delete_ids).
+        updates: list of (memory_id, update_dict)
+        delete_ids: list of memory ids to delete
+        """
+        return [], []
+
+
+class EbbinghausIntelligencePlugin(IntelligentMemoryPlugin):
+    """
+    Default plugin implementing importance evaluation and lifecycle with Ebbinghaus.
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        super().__init__(config)
+        self._importance = None
+        self._algo = None
+        if self.enabled:
+            try:
+                # Prepare importance config, merging custom_importance_evaluation_prompt if present
+                importance_config = self.config.get("importance", {})
+                if "custom_importance_evaluation_prompt" in self.config:
+                    importance_config = importance_config.copy() if isinstance(importance_config, dict) else {}
+                    importance_config["custom_importance_evaluation_prompt"] = self.config["custom_importance_evaluation_prompt"]
+                
+                self._importance = ImportanceEvaluator(
+                    importance_config,
+                    self.config.get("llm", {}),
+                )
+                # Support both "ebbinghaus" and direct intelligent_memory config
+                ebbinghaus_cfg = self.config.get("ebbinghaus", {})
+                # If no ebbinghaus config, use the main config as ebbinghaus config
+                if not ebbinghaus_cfg:
+                    ebbinghaus_cfg = self.config
+                self._algo = EbbinghausAlgorithm(ebbinghaus_cfg)
+            except Exception as e:  # pragma: no cover - defensive
+                logger.warning(f"Failed to init Ebbinghaus plugin: {e}")
+                self.config["enabled"] = False
+
+    def _classify(self, score: float) -> str:
+        if not self._algo:
+            return "working"
+        if score >= self._algo.long_term_threshold:
+            return "long_term"
+        if score >= self._algo.short_term_threshold:
+            return "short_term"
+        return "working"
+
+    def on_add(self, *, content: str, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        if not self.enabled or not self._importance or not self._algo:
+            return {}
+        try:
+            # Evaluate importance
+            score = self._importance.evaluate_importance(content, metadata)
+            
+            # Classify memory type
+            memory_type = self._classify(score)
+            
+            # Process with Ebbinghaus algorithm to get intelligence metadata
+            intelligence_metadata = self._algo.process_memory_metadata(content, score, memory_type)
+            
+            # Return enhanced metadata
+            return {
+                "importance_score": score,
+                "memory_type": memory_type,
+                "access_count": 0,
+                "intelligence": intelligence_metadata.get('intelligence', {}),
+                "memory_management": intelligence_metadata.get('memory_management', {}),
+                "processing_applied": True,
+            }
+        except Exception as e:
+            logger.warning(f"Failed to process memory in on_add: {e}")
+            return {"access_count": 0}
+
+    def on_get(self, memory: Dict[str, Any]) -> Tuple[Optional[Dict[str, Any]], bool]:
+        if not self.enabled or not self._algo:
+            return None, False
+        try:
+            updates: Dict[str, Any] = {
+                "access_count": (memory.get("access_count") or 0) + 1,
+                "updated_at": datetime.utcnow(),
+            }
+            
+            # Check if memory should be forgotten
+            if self._algo.should_forget(memory):
+                return None, True
+            
+            # Check if memory should be promoted
+            if self._algo.should_promote(memory):
+                current = memory.get("memory_type")
+                if current == "working":
+                    updates["memory_type"] = "short_term"
+                elif current == "short_term":
+                    updates["memory_type"] = "long_term"
+            
+            # Check if memory should be archived
+            if self._algo.should_archive(memory):
+                meta = memory.get("metadata") or {}
+                meta["archived"] = True
+                updates["metadata"] = meta
+            
+            # Re-process content if memory type changed or if it's been accessed multiple times
+            access_count = memory.get("access_count", 0) + 1
+            if (updates.get("memory_type") != memory.get("memory_type") or 
+                access_count % 5 == 0):  # Re-process every 5 accesses
+                
+                original_content = memory.get("original_content") or memory.get("content", "")
+                importance_score = memory.get("importance_score", 0.5)
+                memory_type = updates.get("memory_type") or memory.get("memory_type", "working")
+                
+                # Re-process with updated parameters
+                intelligence_metadata = self._algo.process_memory_metadata(original_content, importance_score, memory_type)
+                updates.update(intelligence_metadata)
+                updates["last_reprocessed_at"] = datetime.utcnow()
+            
+            return updates, False
+        except Exception as e:
+            logger.warning(f"Failed to process memory in on_get: {e}")
+            return None, False
+
+    def on_search(self, results: List[Dict[str, Any]]) -> Tuple[List[Tuple[str, Dict[str, Any]]], List[str]]:
+        if not self.enabled or not self._algo:
+            return [], []
+        updates: List[Tuple[str, Dict[str, Any]]] = []
+        deletes: List[str] = []
+        
+        for item in results:
+            try:
+                mem_id = item.get("id") or item.get("memory_id")
+                if not mem_id:
+                    continue
+                
+                # Process individual memory
+                upd, delete_flag = self.on_get(item)
+                
+                if delete_flag:
+                    deletes.append(mem_id)
+                elif upd:
+                    # Add search-specific enhancements
+                    search_updates = self._enhance_for_search(item, upd)
+                    updates.append((mem_id, search_updates))
+                    
+            except Exception as e:
+                logger.warning(f"Failed to process memory {mem_id} in on_search: {e}")
+                continue
+                
+        return updates, deletes
+    
+    def _enhance_for_search(self, memory: Dict[str, Any], base_updates: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Enhance memory for search context.
+        
+        Args:
+            memory: Memory data
+            base_updates: Base updates from on_get
+            
+        Returns:
+            Enhanced updates for search context
+        """
+        try:
+            # Add search-specific metadata
+            search_metadata = memory.get("metadata", {})
+            search_metadata["last_searched_at"] = datetime.utcnow()
+            search_metadata["search_count"] = search_metadata.get("search_count", 0) + 1
+            
+            # Update base updates with search metadata
+            enhanced_updates = base_updates.copy()
+            enhanced_updates["metadata"] = search_metadata
+            
+            # Add search relevance score if not present
+            if "search_relevance_score" not in memory:
+                # Simple relevance calculation based on access patterns
+                access_count = memory.get("access_count", 0)
+                importance_score = memory.get("importance_score", 0.5)
+                search_relevance = min(1.0, (access_count * 0.1) + (importance_score * 0.5))
+                enhanced_updates["search_relevance_score"] = search_relevance
+            
+            return enhanced_updates
+            
+        except Exception as e:
+            logger.warning(f"Failed to enhance memory for search: {e}")
+            return base_updates
+
+

powermem/prompts/__init__.py

@@ -0,0 +1,29 @@
+"""
+Prompt templates for memory operations
+
+This module provides prompt templates for different memory operations.
+"""
+
+from .templates import PromptTemplates
+from .graph.graph_prompts import GraphPrompts
+from .graph.graph_tools_prompts import GraphToolsPrompts
+from .intelligent_memory_prompts import (
+    FACT_RETRIEVAL_PROMPT,
+    FACT_EXTRACTION_PROMPT,
+    DEFAULT_UPDATE_MEMORY_PROMPT,
+    MEMORY_UPDATE_PROMPT,
+    get_memory_update_prompt,
+    parse_messages_for_facts
+)
+
+__all__ = [
+    "PromptTemplates",
+    "GraphPrompts",
+    "GraphToolsPrompts",
+    "FACT_RETRIEVAL_PROMPT",
+    "FACT_EXTRACTION_PROMPT",
+    "DEFAULT_UPDATE_MEMORY_PROMPT",
+    "MEMORY_UPDATE_PROMPT",
+    "get_memory_update_prompt",
+    "parse_messages_for_facts",
+]

powermem/prompts/graph/graph_prompts.py

@@ -0,0 +1,217 @@
+"""
+Graph prompts for memory operations
+
+This module provides prompts for graph-based memory operations.
+"""
+
+import logging
+from typing import Dict, Any, Optional
+from ..templates import PromptTemplates
+
+logger = logging.getLogger(__name__)
+
+# Graph prompts constants
+UPDATE_GRAPH_PROMPT = """
+You are an AI expert specializing in graph memory management and optimization. Your task is to analyze existing graph memories alongside new information, and update the relationships in the memory list to ensure the most accurate, current, and coherent representation of knowledge.
+
+Input:
+1. Existing Graph Memories: A list of current graph memories, each containing source, target, and relationship information.
+2. New Graph Memory: Fresh information to be integrated into the existing graph structure.
+
+Guidelines:
+1. Identification: Use the source and target as primary identifiers when matching existing memories with new information.
+2. Conflict Resolution:
+   - If new information contradicts an existing memory:
+     a) For matching source and target but differing content, update the relationship of the existing memory.
+     b) If the new memory provides more recent or accurate information, update the existing memory accordingly.
+3. Comprehensive Review: Thoroughly examine each existing graph memory against the new information, updating relationships as necessary. Multiple updates may be required.
+4. Consistency: Maintain a uniform and clear style across all memories. Each entry should be concise yet comprehensive.
+5. Semantic Coherence: Ensure that updates maintain or improve the overall semantic structure of the graph.
+6. Temporal Awareness: If timestamps are available, consider the recency of information when making updates.
+7. Relationship Refinement: Look for opportunities to refine relationship descriptions for greater precision or clarity.
+8. Redundancy Elimination: Identify and merge any redundant or highly similar relationships that may result from the update.
+
+Memory Format:
+source -- RELATIONSHIP -- destination
+
+Task Details:
+======= Existing Graph Memories:=======
+{existing_memories}
+
+======= New Graph Memory:=======
+{new_memories}
+
+Output:
+Provide a list of update instructions, each specifying the source, target, and the new relationship to be set. Only include memories that require updates.
+"""
+
+EXTRACT_RELATIONS_PROMPT = """
+
+You are an advanced algorithm designed to extract structured information from text to construct knowledge graphs. Your goal is to capture comprehensive and accurate information. Follow these key principles:
+
+1. Extract only explicitly stated information from the text.
+2. Establish relationships among the entities provided.
+3. Use "USER_ID" as the source entity for any self-references (e.g., "I," "me," "my," etc.) in user messages.
+CUSTOM_PROMPT
+
+Relationships:
+    - Use consistent, general, and timeless relationship types.
+    - Example: Prefer "professor" over "became_professor."
+    - Relationships should only be established among the entities explicitly mentioned in the user message.
+
+Entity Consistency:
+    - Ensure that relationships are coherent and logically align with the context of the message.
+    - Maintain consistent naming for entities across the extracted data.
+
+Strive to construct a coherent and easily understandable knowledge graph by eshtablishing all the relationships among the entities and adherence to the user's context.
+
+Adhere strictly to these guidelines to ensure high-quality knowledge graph extraction."""
+
+DELETE_RELATIONS_SYSTEM_PROMPT = """
+You are a graph memory manager specializing in identifying, managing, and optimizing relationships within graph-based memories. Your primary task is to analyze a list of existing relationships and determine which ones should be deleted based on the new information provided.
+Input:
+1. Existing Graph Memories: A list of current graph memories, each containing source, relationship, and destination information.
+2. New Text: The new information to be integrated into the existing graph structure.
+3. Use "USER_ID" as node for any self-references (e.g., "I," "me," "my," etc.) in user messages.
+
+Guidelines:
+1. Identification: Use the new information to evaluate existing relationships in the memory graph.
+2. Deletion Criteria: Delete a relationship only if it meets at least one of these conditions:
+   - Outdated or Inaccurate: The new information is more recent or accurate.
+   - Contradictory: The new information conflicts with or negates the existing information.
+3. DO NOT DELETE if their is a possibility of same type of relationship but different destination nodes.
+4. Comprehensive Analysis:
+   - Thoroughly examine each existing relationship against the new information and delete as necessary.
+   - Multiple deletions may be required based on the new information.
+5. Semantic Integrity:
+   - Ensure that deletions maintain or improve the overall semantic structure of the graph.
+   - Avoid deleting relationships that are NOT contradictory/outdated to the new information.
+6. Temporal Awareness: Prioritize recency when timestamps are available.
+7. Necessity Principle: Only DELETE relationships that must be deleted and are contradictory/outdated to the new information to maintain an accurate and coherent memory graph.
+
+Note: DO NOT DELETE if their is a possibility of same type of relationship but different destination nodes. 
+
+For example: 
+Existing Memory: alice -- loves_to_eat -- pizza
+New Information: Alice also loves to eat burger.
+
+Do not delete in the above example because there is a possibility that Alice loves to eat both pizza and burger.
+
+Memory Format:
+source -- relationship -- destination
+
+Provide a list of deletion instructions, each specifying the relationship to be deleted.
+"""
+
+class GraphPrompts(PromptTemplates):
+    """
+    Prompts for graph-based memory operations.
+    """
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        """
+        Initialize graph prompts.
+        
+        Args:
+            config: Configuration dictionary
+        """
+        super().__init__(config)
+        # Store custom prompts from config if provided
+        self._custom_update_graph_prompt = None
+        self._custom_extract_relations_prompt = None
+        self._custom_delete_relations_prompt = None
+        
+        if config:
+            # Support both graph_store config structure and direct config
+            graph_store_config = config.get("graph_store", {})
+            if isinstance(graph_store_config, dict):
+                self._custom_update_graph_prompt = graph_store_config.get("custom_update_graph_prompt")
+                self._custom_extract_relations_prompt = graph_store_config.get("custom_extract_relations_prompt") or graph_store_config.get("custom_prompt")
+                self._custom_delete_relations_prompt = graph_store_config.get("custom_delete_relations_prompt")
+            # Also support direct config keys
+            if not self._custom_update_graph_prompt:
+                self._custom_update_graph_prompt = config.get("custom_update_graph_prompt")
+            if not self._custom_extract_relations_prompt:
+                self._custom_extract_relations_prompt = config.get("custom_extract_relations_prompt") or config.get("custom_prompt")
+            if not self._custom_delete_relations_prompt:
+                self._custom_delete_relations_prompt = config.get("custom_delete_relations_prompt")
+    
+    def get_update_graph_prompt(self, existing_memories: str, new_memories: str) -> str:
+        """
+        Get graph update prompt.
+        
+        Args:
+            existing_memories: Existing graph memories
+            new_memories: New graph memories to integrate
+            
+        Returns:
+            Formatted prompt
+        """
+        # Use custom prompt if provided, otherwise use default
+        prompt_template = self._custom_update_graph_prompt or UPDATE_GRAPH_PROMPT
+        try:
+            return prompt_template.format(
+                existing_memories=existing_memories, 
+                new_memories=new_memories
+            )
+        except KeyError:
+            # If custom prompt doesn't have format placeholders, return as-is or append
+            if "{existing_memories}" not in prompt_template or "{new_memories}" not in prompt_template:
+                logger.warning("Custom update graph prompt missing format placeholders, appending data")
+                return f"{prompt_template}\n\nExisting Memories:\n{existing_memories}\n\nNew Memories:\n{new_memories}"
+            return prompt_template.format(
+                existing_memories=existing_memories, 
+                new_memories=new_memories
+            )
+    
+    def get_extract_relations_prompt(self, text: str) -> str:
+        """
+        Get relations extraction prompt.
+        
+        Args:
+            text: Text to extract relations from
+            
+        Returns:
+            Formatted prompt
+        """
+        # Use custom prompt if provided, otherwise use default
+        prompt = self._custom_extract_relations_prompt or EXTRACT_RELATIONS_PROMPT
+        return prompt.replace("USER_ID", "USER_ID")
+    
+    def get_delete_relations_prompt(self, existing_memories: str, new_text: str, user_id: str = "USER_ID") -> tuple[str, str]:
+        """
+        Get delete relations prompt.
+        
+        Args:
+            existing_memories: Existing graph memories
+            new_text: New text information
+            user_id: User ID for self-references
+            
+        Returns:
+            Tuple of (system_prompt, user_prompt)
+        """
+        # Use custom prompt if provided, otherwise use default
+        system_prompt = self._custom_delete_relations_prompt or DELETE_RELATIONS_SYSTEM_PROMPT
+        system_prompt = system_prompt.replace("USER_ID", user_id)
+        user_prompt = f"Here are the existing memories: {existing_memories} \n\n New Information: {new_text}"
+        
+        return system_prompt, user_prompt
+    
+    def get_system_prompt(self, prompt_type: str = "extract_relations") -> str:
+        """
+        Get system prompt for graph operations.
+        
+        Args:
+            prompt_type: Type of system prompt (extract_relations, delete_relations)
+            
+        Returns:
+            System prompt
+        """
+        if prompt_type == "extract_relations":
+            # Use custom prompt if provided, otherwise use default
+            return self._custom_extract_relations_prompt or EXTRACT_RELATIONS_PROMPT
+        elif prompt_type == "delete_relations":
+            # Use custom prompt if provided, otherwise use default
+            return self._custom_delete_relations_prompt or DELETE_RELATIONS_SYSTEM_PROMPT
+        else:
+            return self._custom_extract_relations_prompt or EXTRACT_RELATIONS_PROMPT