memorycoreclaw 2.0.0__py3-none-any.whl

memorycoreclaw/__init__.py

@@ -0,0 +1,21 @@
+# MemoryCoreClaw
+# Human-brain-inspired Long-term Memory Engine for AI Agents
+
+__version__ = "2.0.0"
+__author__ = "MemoryCoreClaw Team"
+
+from .core.memory import Memory, get_memory
+from .core.engine import MemoryEngine, MemoryLayer, Emotion, Fact, Lesson, STANDARD_RELATIONS
+from .cognitive.contextual import Context
+
+__all__ = [
+    'Memory',
+    'MemoryEngine',
+    'get_memory',
+    'Context',
+    'MemoryLayer',
+    'Emotion',
+    'Fact',
+    'Lesson',
+    'STANDARD_RELATIONS',
+]

memorycoreclaw/cognitive/__init__.py

@@ -0,0 +1,8 @@
+"""MemoryCoreClaw Cognitive Module"""
+
+from .forgetting import ForgettingCurve
+from .contextual import ContextualMemory
+from .working import WorkingMemory
+from .heuristic import HeuristicEngine
+
+__all__ = ["ForgettingCurve", "ContextualMemory", "WorkingMemory", "HeuristicEngine"]

memorycoreclaw/cognitive/contextual.py

@@ -0,0 +1,100 @@
+"""
+MemoryCoreClaw - Contextual Memory Module
+
+Implements context-based memory recall.
+"""
+
+from datetime import datetime
+from typing import Optional, List, Dict, Any
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Context:
+    """Memory context"""
+    location: Optional[str] = None
+    people: List[str] = field(default_factory=list)
+    emotion: Optional[str] = None
+    activity: Optional[str] = None
+    channel: Optional[str] = None
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+class ContextualMemory:
+    """
+    Contextual Memory Engine
+    
+    Features:
+    - Bind memories to contexts
+    - Trigger recall by context
+    - Score context matches
+    
+    Usage:
+        cm = ContextualMemory()
+        ctx = Context(location="office", people=["Alice"])
+        cm.bind("fact", 1, ctx)
+        results = cm.recall(people=["Alice"])
+    """
+    
+    def __init__(self, db_connection=None):
+        self.conn = db_connection
+    
+    def create_context(self, context: Context) -> int:
+        """Create a context record"""
+        # Implementation depends on database
+        pass
+    
+    def bind_memory(self, memory_type: str, memory_id: int, context: Context) -> int:
+        """Bind a memory to a context"""
+        pass
+    
+    def recall_by_context(
+        self,
+        location: str = None,
+        people: List[str] = None,
+        emotion: str = None,
+        activity: str = None
+    ) -> List[Dict]:
+        """Recall memories matching context"""
+        pass
+    
+    def score_match(self, query_context: Context, memory_context: Context) -> float:
+        """
+        Score how well two contexts match.
+        
+        Args:
+            query_context: The search context
+            memory_context: The memory's context
+            
+        Returns:
+            Match score (0-1)
+        """
+        score = 0.0
+        max_score = 0.0
+        
+        # Location match (weight: 1.0)
+        if query_context.location:
+            max_score += 1.0
+            if memory_context.location == query_context.location:
+                score += 1.0
+        
+        # People overlap (weight: 0.8 per person)
+        if query_context.people:
+            for person in query_context.people:
+                max_score += 0.8
+                if person in memory_context.people:
+                    score += 0.8
+        
+        # Emotion match (weight: 0.5)
+        if query_context.emotion:
+            max_score += 0.5
+            if memory_context.emotion == query_context.emotion:
+                score += 0.5
+        
+        # Activity match (weight: 0.7)
+        if query_context.activity:
+            max_score += 0.7
+            if memory_context.activity == query_context.activity:
+                score += 0.7
+        
+        return score / max_score if max_score > 0 else 0.0

memorycoreclaw/cognitive/forgetting.py

@@ -0,0 +1,162 @@
+"""
+MemoryCoreClaw - Cognitive Module: Forgetting Curve
+
+Implements Ebbinghaus forgetting curve for memory strength decay.
+"""
+
+import math
+from datetime import datetime, timedelta
+from typing import Optional
+import sqlite3
+
+
+class ForgettingCurve:
+    """
+    Ebbinghaus forgetting curve implementation.
+    
+    Formula: R = e^(-t/(S*100))
+    Where:
+        R = retention rate
+        t = time since last access (days)
+        S = memory strength (importance)
+    
+    Features:
+    - Time-based decay
+    - Importance-based strength
+    - Emotion enhancement
+    - Access reinforcement
+    """
+    
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+        self._init_tables()
+    
+    def _init_tables(self):
+        """Initialize memory strength table."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        
+        cursor.execute('''
+            CREATE TABLE IF NOT EXISTS memory_strength (
+                memory_id INTEGER PRIMARY KEY,
+                memory_type TEXT DEFAULT 'fact',
+                base_strength REAL DEFAULT 0.5,
+                current_strength REAL DEFAULT 0.5,
+                last_accessed TIMESTAMP,
+                access_count INTEGER DEFAULT 0,
+                decay_rate REAL DEFAULT 0.1
+            )
+        ''')
+        
+        conn.commit()
+        conn.close()
+    
+    def calculate_retention(self, days_since_access: float, 
+                           importance: float,
+                           emotion: str = "neutral") -> float:
+        """
+        Calculate memory retention rate.
+        
+        Args:
+            days_since_access: Days since last access
+            importance: Memory importance (0-1)
+            emotion: Emotional marker
+            
+        Returns:
+            Retention rate (0-1)
+        """
+        # Base strength from importance
+        strength = importance
+        
+        # Emotion enhancement
+        emotion_multiplier = {
+            "milestone": 1.5,
+            "negative": 1.3,
+            "positive": 1.2,
+            "neutral": 1.0
+        }
+        strength *= emotion_multiplier.get(emotion, 1.0)
+        
+        # Ebbinghaus formula
+        if days_since_access <= 0:
+            return 1.0
+        
+        retention = math.exp(-days_since_access / (strength * 100))
+        
+        # Minimum retention
+        return max(0.1, min(1.0, retention))
+    
+    def apply_forgetting_curve(self, min_importance: float = 0.3):
+        """
+        Apply forgetting curve to all memories.
+        
+        Memories below min_importance will be candidates for removal.
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        
+        # Get all facts
+        cursor.execute('''
+            SELECT f.id, f.importance, f.emotion, f.last_accessed, f.created_at
+            FROM facts f
+            WHERE f.importance >= ?
+        ''', (min_importance,))
+        
+        facts = cursor.fetchall()
+        updated = 0
+        
+        for fact_id, importance, emotion, last_accessed, created_at in facts:
+            # Calculate days since access
+            if last_accessed:
+                last = datetime.fromisoformat(last_accessed)
+            elif created_at:
+                last = datetime.fromisoformat(created_at)
+            else:
+                last = datetime.now()
+            
+            days_since = (datetime.now() - last).days
+            
+            # Calculate new retention
+            retention = self.calculate_retention(days_since, importance, emotion or "neutral")
+            
+            # Update strength
+            new_strength = importance * retention
+            
+            # Core memories (importance >= 0.9) don't decay below 0.8
+            if importance >= 0.9:
+                new_strength = max(0.8, new_strength)
+            
+            cursor.execute('''
+                INSERT OR REPLACE INTO memory_strength 
+                (memory_id, memory_type, current_strength, last_accessed)
+                VALUES (?, 'fact', ?, ?)
+            ''', (fact_id, new_strength, datetime.now().isoformat()))
+            
+            updated += 1
+        
+        conn.commit()
+        conn.close()
+        
+        return updated
+    
+    def reinforce_memory(self, memory_id: int, factor: float = 1.1):
+        """
+        Reinforce memory strength (called on access).
+        
+        Args:
+            memory_id: Memory ID
+            factor: Reinforcement factor (default 1.1 = 10% increase)
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        
+        cursor.execute('''
+            UPDATE memory_strength
+            SET current_strength = MIN(1.0, current_strength * ?),
+                access_count = access_count + 1,
+                last_accessed = ?
+            WHERE memory_id = ?
+        ''', (factor, datetime.now().isoformat(), memory_id))
+        
+        conn.commit()
+        conn.close()

memorycoreclaw/cognitive/heuristic.py

@@ -0,0 +1,217 @@
+"""
+MemoryCoreClaw - Heuristic Engine Module
+
+Implements cognitive schema recognition and thought patterns.
+"""
+
+from typing import List, Dict, Optional
+from dataclasses import dataclass
+import re
+
+
+@dataclass
+class Schema:
+    """A cognitive schema pattern"""
+    name: str
+    description: str
+    patterns: List[str]
+    triggers: List[str]
+
+
+class HeuristicEngine:
+    """
+    Cognitive Heuristic Engine
+    
+    Recognizes thought patterns and cognitive schemas.
+    
+    Usage:
+        he = HeuristicEngine()
+        schemas = he.recognize("Why did this happen? How can I fix it?")
+        for s in schemas:
+            print(f"Detected: {s.name}")
+    """
+    
+    # Predefined cognitive schemas
+    DEFAULT_SCHEMAS = [
+        Schema(
+            name="problem_solving",
+            description="Identifying problem and seeking solution",
+            patterns=[
+                r"why\s+did",
+                r"how\s+can\s+i\s+fix",
+                r"what\s+caused",
+                r"how\s+to\s+solve"
+            ],
+            triggers=["why", "how", "fix", "solve", "problem"]
+        ),
+        Schema(
+            name="planning",
+            description="Planning future actions",
+            patterns=[
+                r"i\s+will",
+                r"we\s+plan\s+to",
+                r"scheduled\s+for",
+                r"next\s+step"
+            ],
+            triggers=["plan", "will", "schedule", "next", "tomorrow"]
+        ),
+        Schema(
+            name="learning",
+            description="Learning from experience",
+            patterns=[
+                r"i\s+learned",
+                r"the\s+lesson\s+is",
+                r"i\s+realized",
+                r"now\s+i\s+know"
+            ],
+            triggers=["learned", "lesson", "realized", "know", "understand"]
+        ),
+        Schema(
+            name="inquiry",
+            description="Asking questions to understand",
+            patterns=[
+                r"who\s+is",
+                r"what\s+is",
+                r"where\s+is",
+                r"when\s+did",
+                r"\?$"
+            ],
+            triggers=["who", "what", "where", "when", "?"]
+        ),
+        Schema(
+            name="reflection",
+            description="Reflecting on past events",
+            patterns=[
+                r"i\s+remember",
+                r"looking\s+back",
+                r"in\s+the\s+past",
+                r"previously"
+            ],
+            triggers=["remember", "past", "before", "previously"]
+        ),
+        Schema(
+            name="decision",
+            description="Making a decision",
+            patterns=[
+                r"i\s+decided",
+                r"i\s+chose",
+                r"the\s+best\s+option",
+                r"i\s+prefer"
+            ],
+            triggers=["decided", "chose", "option", "prefer", "better"]
+        ),
+        Schema(
+            name="emotion_expression",
+            description="Expressing emotions",
+            patterns=[
+                r"i\s+feel",
+                r"i\s+am\s+(happy|sad|angry|worried|excited)",
+                r"makes\s+me\s+feel"
+            ],
+            triggers=["feel", "happy", "sad", "angry", "worried", "excited"]
+        )
+    ]
+    
+    def __init__(self, custom_schemas: List[Schema] = None):
+        """
+        Initialize heuristic engine.
+        
+        Args:
+            custom_schemas: Additional schemas to include
+        """
+        self.schemas = self.DEFAULT_SCHEMAS.copy()
+        if custom_schemas:
+            self.schemas.extend(custom_schemas)
+    
+    def recognize(self, text: str) -> List[Schema]:
+        """
+        Recognize cognitive schemas in text.
+        
+        Args:
+            text: Input text
+            
+        Returns:
+            List of matched schemas (sorted by relevance)
+        """
+        text_lower = text.lower()
+        matches = []
+        
+        for schema in self.schemas:
+            score = 0
+            
+            # Check patterns
+            for pattern in schema.patterns:
+                if re.search(pattern, text_lower):
+                    score += 2
+            
+            # Check triggers
+            for trigger in schema.triggers:
+                if trigger in text_lower:
+                    score += 1
+            
+            if score > 0:
+                matches.append((schema, score))
+        
+        # Sort by score
+        matches.sort(key=lambda x: x[1], reverse=True)
+        
+        return [m[0] for m in matches]
+    
+    def get_schema(self, name: str) -> Optional[Schema]:
+        """Get a schema by name"""
+        for schema in self.schemas:
+            if schema.name == name:
+                return schema
+        return None
+    
+    def add_schema(self, schema: Schema) -> bool:
+        """Add a custom schema"""
+        if self.get_schema(schema.name):
+            return False
+        self.schemas.append(schema)
+        return True
+    
+    def suggest_followup(self, schema_name: str) -> List[str]:
+        """
+        Suggest follow-up questions/actions for a schema.
+        
+        Args:
+            schema_name: Name of detected schema
+            
+        Returns:
+            List of suggestions
+        """
+        suggestions = {
+            "problem_solving": [
+                "What is the root cause?",
+                "What solutions have been tried?",
+                "What resources are available?"
+            ],
+            "planning": [
+                "What is the timeline?",
+                "Who is responsible?",
+                "What could go wrong?"
+            ],
+            "learning": [
+                "How can this be applied elsewhere?",
+                "What would you do differently?",
+                "Who else should know this?"
+            ],
+            "inquiry": [
+                "What do you already know?",
+                "Where can you find more information?",
+                "Who might have the answer?"
+            ],
+            "reflection": [
+                "What changed since then?",
+                "What did you learn?",
+                "How does this affect the future?"
+            ],
+            "decision": [
+                "What alternatives were considered?",
+                "What are the trade-offs?",
+                "When will you reevaluate?"
+            ]
+        }
+        
+        return suggestions.get(schema_name, [])

memorycoreclaw/cognitive/working.py

@@ -0,0 +1,179 @@
+"""
+MemoryCoreClaw - Working Memory Module
+
+Implements limited-capacity temporary storage (7±2 model).
+"""
+
+from datetime import datetime, timedelta
+from typing import Optional, Any, Dict, List
+from dataclasses import dataclass
+import json
+
+
+@dataclass
+class WorkingItem:
+    """An item in working memory"""
+    key: str
+    value: Any
+    priority: float
+    created_at: datetime
+    expires_at: Optional[datetime] = None
+    access_count: int = 0
+
+
+class WorkingMemory:
+    """
+    Working Memory Engine
+    
+    Based on Baddeley's working memory model with capacity limit.
+    
+    Features:
+    - Limited capacity (default 9 items, 7±2)
+    - Priority-based eviction
+    - TTL support
+    - Access tracking
+    
+    Usage:
+        wm = WorkingMemory()
+        wm.hold("task", "processing", priority=0.9)
+        task = wm.retrieve("task")
+    """
+    
+    DEFAULT_CAPACITY = 9  # 7±2 model
+    
+    def __init__(self, capacity: int = DEFAULT_CAPACITY):
+        """
+        Initialize working memory.
+        
+        Args:
+            capacity: Maximum items (default 9)
+        """
+        self.capacity = capacity
+        self.items: Dict[str, WorkingItem] = {}
+        self.stats = {
+            'adds': 0,
+            'retrieves': 0,
+            'evictions': 0,
+            'expirations': 0
+        }
+    
+    def hold(
+        self,
+        key: str,
+        value: Any,
+        priority: float = 0.5,
+        ttl_seconds: int = None
+    ) -> bool:
+        """
+        Store an item in working memory.
+        
+        Args:
+            key: Item key
+            value: Item value
+            priority: Priority (0-1, higher = less likely to evict)
+            ttl_seconds: Time to live in seconds
+            
+        Returns:
+            True if stored successfully
+        """
+        # Evict if at capacity
+        if len(self.items) >= self.capacity and key not in self.items:
+            self._evict_lowest_priority()
+        
+        expires_at = None
+        if ttl_seconds:
+            expires_at = datetime.now() + timedelta(seconds=ttl_seconds)
+        
+        self.items[key] = WorkingItem(
+            key=key,
+            value=value,
+            priority=priority,
+            created_at=datetime.now(),
+            expires_at=expires_at
+        )
+        
+        self.stats['adds'] += 1
+        return True
+    
+    def retrieve(self, key: str) -> Optional[Any]:
+        """
+        Retrieve an item from working memory.
+        
+        Args:
+            key: Item key
+            
+        Returns:
+            Item value or None if not found/expired
+        """
+        if key not in self.items:
+            return None
+        
+        item = self.items[key]
+        
+        # Check expiration
+        if item.expires_at and datetime.now() > item.expires_at:
+            del self.items[key]
+            self.stats['expirations'] += 1
+            return None
+        
+        item.access_count += 1
+        self.stats['retrieves'] += 1
+        return item.value
+    
+    def forget(self, key: str) -> bool:
+        """Remove an item"""
+        if key in self.items:
+            del self.items[key]
+            return True
+        return False
+    
+    def clear(self) -> int:
+        """Clear all items"""
+        count = len(self.items)
+        self.items.clear()
+        return count
+    
+    def _evict_lowest_priority(self):
+        """Evict the lowest priority item"""
+        if not self.items:
+            return
+        
+        # Find lowest priority item
+        lowest_key = min(self.items.keys(), key=lambda k: self.items[k].priority)
+        del self.items[lowest_key]
+        self.stats['evictions'] += 1
+    
+    def get_all(self) -> List[Dict]:
+        """Get all items"""
+        self._clean_expired()
+        return [
+            {
+                'key': item.key,
+                'value': item.value,
+                'priority': item.priority,
+                'created_at': item.created_at.isoformat(),
+                'expires_at': item.expires_at.isoformat() if item.expires_at else None
+            }
+            for item in self.items.values()
+        ]
+    
+    def _clean_expired(self):
+        """Remove expired items"""
+        now = datetime.now()
+        expired = [
+            key for key, item in self.items.items()
+            if item.expires_at and now > item.expires_at
+        ]
+        for key in expired:
+            del self.items[key]
+            self.stats['expirations'] += 1
+    
+    def get_stats(self) -> Dict:
+        """Get statistics"""
+        self._clean_expired()
+        return {
+            'capacity': self.capacity,
+            'used': len(self.items),
+            'utilization': len(self.items) / self.capacity,
+            'stats': self.stats
+        }