claude-memory-agent 2.0.1 → 2.2.0

package/services/terminal_ui.py

@@ -0,0 +1,199 @@
+"""Rich Terminal UI for Claude Memory Agent.
+
+Provides:
+- Colorful startup splash screen with system stats
+- Rich logging handler with colored levels
+- Helper panels for status display
+"""
+import logging
+from datetime import datetime
+from typing import Dict, Any, Optional
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from rich.columns import Columns
+from rich.logging import RichHandler
+from rich.theme import Theme
+from rich.align import Align
+
+# Custom theme for the memory agent
+MEMORY_THEME = Theme({
+    "info": "cyan",
+    "warning": "yellow",
+    "error": "bold red",
+    "success": "bold green",
+    "memory.hot": "bold red",
+    "memory.warm": "bold yellow",
+    "memory.cold": "bold blue",
+    "header": "bold magenta",
+    "muted": "dim white",
+    "accent": "bold cyan",
+    "value": "bold white",
+})
+
+console = Console(theme=MEMORY_THEME)
+
+# ASCII art logo
+LOGO_MINI = r"""
+  ___ _              _     __  __
+ / __| |__ _ _  _ __| |___|  \/  |___ _ __  ___ _ _ _  _
+| (__| / _` | || / _` / -_) |\/| / -_) '  \/ _ \ '_| || |
+ \___|_\__,_|\_,_\__,_\___|_|  |_\___|_|_|_\___/_|  \_, |
+                                                     |__/  """
+
+
+def print_splash(
+    version: str = "2.4.0",
+    port: int = 8102,
+    auth_enabled: bool = False,
+    auth_keys: int = 0,
+    queue_depth: int = 0,
+    curator_interval: int = 24,
+    embedding_cache_size: int = 500,
+    precompute_interval: int = 60,
+    consolidation_threshold: float = 0.85,
+    consolidation_interval: int = 12,
+    db_stats: Optional[Dict[str, Any]] = None,
+):
+    """Print the startup splash screen with system info.
+
+    Args:
+        version: Server version
+        port: Server port
+        auth_enabled: Whether auth is enabled
+        auth_keys: Number of active auth keys
+        queue_depth: Retry queue depth
+        curator_interval: Curator check interval in hours
+        embedding_cache_size: LRU cache size
+        precompute_interval: Precompute loop interval in seconds
+        consolidation_threshold: Similarity threshold for consolidation
+        consolidation_interval: Consolidation loop interval in hours
+        db_stats: Optional database statistics dict
+    """
+    console.print()
+
+    # Logo panel
+    logo_text = Text(LOGO_MINI, style="bold cyan")
+    console.print(Panel(
+        Align.center(logo_text),
+        border_style="cyan",
+        padding=(0, 2),
+    ))
+
+    # Version bar
+    version_text = Text()
+    version_text.append("  v", style="muted")
+    version_text.append(version, style="bold green")
+    version_text.append("  (CLaRa)  ", style="muted")
+    version_text.append("|", style="muted")
+    version_text.append(f"  Port {port}  ", style="accent")
+    version_text.append("|", style="muted")
+    version_text.append(f"  {datetime.now().strftime('%Y-%m-%d %H:%M')}  ", style="muted")
+    console.print(Align.center(version_text))
+    console.print()
+
+    # Status panels in columns
+    panels = []
+
+    # Server panel
+    server_table = Table(show_header=False, box=None, padding=(0, 1))
+    server_table.add_column("key", style="muted", width=18)
+    server_table.add_column("value", style="value")
+
+    auth_status = "[green]ENABLED[/green]" if auth_enabled else "[yellow]DISABLED[/yellow]"
+    server_table.add_row("Authentication", auth_status)
+    if auth_enabled:
+        server_table.add_row("Active Keys", str(auth_keys))
+    server_table.add_row("Retry Queue", f"{queue_depth} pending")
+    server_table.add_row("Curator", f"every {curator_interval}h")
+
+    panels.append(Panel(server_table, title="[bold]Server[/bold]", border_style="green", width=36))
+
+    # CLaRa Features panel
+    clara_table = Table(show_header=False, box=None, padding=(0, 1))
+    clara_table.add_column("key", style="muted", width=18)
+    clara_table.add_column("value", style="value")
+
+    clara_table.add_row("Embedding Cache", f"{embedding_cache_size} slots")
+    clara_table.add_row("Precompute", f"every {precompute_interval}s")
+    clara_table.add_row("Consolidation", f"every {consolidation_interval}h")
+    clara_table.add_row("Similarity", f">= {consolidation_threshold}")
+
+    panels.append(Panel(clara_table, title="[bold]CLaRa Engine[/bold]", border_style="cyan", width=36))
+
+    # Database panel (if stats available)
+    if db_stats:
+        db_table = Table(show_header=False, box=None, padding=(0, 1))
+        db_table.add_column("key", style="muted", width=18)
+        db_table.add_column("value", style="value")
+
+        total = db_stats.get('total_memories', '?')
+        db_table.add_row("Memories", f"[bold]{total}[/bold]")
+
+        # Tier breakdown if available
+        tier_counts = db_stats.get('tier_counts', {})
+        if tier_counts:
+            hot = tier_counts.get('hot', 0)
+            warm = tier_counts.get('warm', 0)
+            cold = tier_counts.get('cold', 0)
+            db_table.add_row("Tiers", f"[memory.hot]{hot}[/memory.hot] / [memory.warm]{warm}[/memory.warm] / [memory.cold]{cold}[/memory.cold]")
+        else:
+            db_table.add_row("Tiers", "[muted]not evaluated[/muted]")
+
+        patterns = db_stats.get('total_patterns', '?')
+        db_table.add_row("Patterns", str(patterns))
+
+        panels.append(Panel(db_table, title="[bold]Database[/bold]", border_style="yellow", width=36))
+
+    console.print(Columns(panels, align="center", padding=(0, 1)))
+    console.print()
+
+    # Ready message
+    console.print(
+        Align.center(
+            Text.assemble(
+                ("  Ready  ", "bold white on green"),
+                ("  ", ""),
+                (f"http://localhost:{port}", "bold underline cyan"),
+                ("  |  ", "muted"),
+                (f"Dashboard: http://localhost:{port}/dashboard", "cyan"),
+            )
+        )
+    )
+    console.print()
+    _print_separator()
+
+
+def _print_separator():
+    """Print a subtle separator line."""
+    console.print("[muted]" + "-" * 70 + "[/muted]", justify="center")
+    console.print()
+
+
+def setup_rich_logging(level: str = "INFO") -> logging.Handler:
+    """Set up rich logging handler for the application.
+
+    Returns:
+        RichHandler instance configured for the memory agent
+    """
+    handler = RichHandler(
+        console=console,
+        show_time=True,
+        show_level=True,
+        show_path=False,
+        markup=True,
+        rich_tracebacks=True,
+        tracebacks_show_locals=False,
+        log_time_format="[%H:%M:%S]",
+    )
+    handler.setLevel(getattr(logging, level.upper(), logging.INFO))
+
+    # Format
+    formatter = logging.Formatter("%(message)s")
+    handler.setFormatter(formatter)
+
+    return handler
+
+

package/services/tier_manager.py

@@ -0,0 +1,235 @@
+"""Hierarchical Memory Tier Manager - CLaRa-inspired multi-stage processing.
+
+Manages three tiers of memories with different search strategies:
+- Hot: Recent, high-importance, frequently accessed. Full semantic + keyword search, flat FAISS.
+- Warm: Older but relevant. Semantic search on compressed content, IVF FAISS.
+- Cold: Archived, low importance. Keyword-only search, no FAISS index.
+
+Permanent types (decision, preference, code) with importance >= 5 stay hot.
+"""
+import logging
+from datetime import datetime, timedelta
+from typing import Dict, Any, List, Optional
+
+from config import config
+from services.memory_decay import DECAY_LIFESPANS
+
+logger = logging.getLogger(__name__)
+
+# Tier constants
+TIER_HOT = 'hot'
+TIER_WARM = 'warm'
+TIER_COLD = 'cold'
+
+# Permanent types that resist demotion
+PERMANENT_TYPES = {'decision', 'preference', 'code'}
+
+
+class TierManager:
+    """Manages memory tier promotion and demotion.
+
+    Scoring algorithm considers:
+    - Age (days since creation)
+    - Importance (1-10)
+    - Access frequency (access_count)
+    - Memory type (permanent vs ephemeral)
+    - Decay factor
+    """
+
+    def __init__(self, db):
+        self.db = db
+        self.hot_max_age = config.TIER_HOT_MAX_AGE_DAYS
+        self.hot_min_importance = config.TIER_HOT_MIN_IMPORTANCE
+        self.warm_max_age = config.TIER_WARM_MAX_AGE_DAYS
+
+    def evaluate_tier(self, memory: dict) -> str:
+        """Evaluate which tier a memory belongs in.
+
+        Args:
+            memory: Dict with type, importance, created_at, access_count, decay_factor
+
+        Returns:
+            Tier string: 'hot', 'warm', or 'cold'
+        """
+        memory_type = memory.get('type', 'chunk')
+        importance = memory.get('importance', 5)
+        access_count = memory.get('access_count', 0) or 0
+        decay_factor = memory.get('decay_factor', 1.0) or 1.0
+
+        # Permanent types with importance >= 5 always stay hot
+        if memory_type in PERMANENT_TYPES and importance >= 5:
+            return TIER_HOT
+
+        # Calculate age
+        created_at = memory.get('created_at')
+        age_days = self._calculate_age_days(created_at)
+
+        # Hot tier criteria:
+        # - Recent (< hot_max_age days) OR
+        # - High importance (>= hot_min_importance) OR
+        # - Frequently accessed (access_count >= 5 in last 14 days)
+        if age_days < self.hot_max_age:
+            return TIER_HOT
+        if importance >= self.hot_min_importance:
+            return TIER_HOT
+        if access_count >= 5 and age_days < self.hot_max_age * 2:
+            return TIER_HOT
+
+        # Warm tier criteria:
+        # - Age < warm_max_age AND (importance >= 3 OR access_count >= 2)
+        if age_days < self.warm_max_age:
+            if importance >= 3 or access_count >= 2:
+                return TIER_WARM
+            # Low importance, low access but still within warm window
+            if decay_factor > 0.3:
+                return TIER_WARM
+
+        # Cold: everything else
+        return TIER_COLD
+
+    def _calculate_age_days(self, created_at: Optional[str]) -> float:
+        """Calculate age in days from a timestamp string."""
+        if not created_at:
+            return 0.0
+        try:
+            created_dt = datetime.fromisoformat(
+                created_at.replace('Z', '+00:00')
+            ).replace(tzinfo=None)
+            return (datetime.now() - created_dt).total_seconds() / 86400.0
+        except (ValueError, TypeError, AttributeError):
+            return 0.0
+
+    async def run_tier_maintenance(self, skip_recent_hours: int = 24) -> Dict[str, Any]:
+        """Evaluate and update tiers for all memories.
+
+        Combines with decay evaluation for efficiency (single pass over all memories).
+
+        Args:
+            skip_recent_hours: Skip memories whose tier was evaluated within this window
+
+        Returns:
+            Dict with maintenance statistics
+        """
+        cursor = self.db.conn.cursor()
+
+        # Fetch all memories that need tier evaluation
+        # Skip those evaluated recently (tier_changed_at within skip window)
+        cutoff = (datetime.now() - timedelta(hours=skip_recent_hours)).isoformat()
+
+        cursor.execute("""
+            SELECT id, type, importance, access_count, decay_factor, created_at,
+                   last_accessed, tier, tier_changed_at
+            FROM memories
+            WHERE tier_changed_at IS NULL OR tier_changed_at < ?
+        """, (cutoff,))
+
+        rows = cursor.fetchall()
+
+        stats = {
+            'evaluated': 0,
+            'promoted': 0,
+            'demoted': 0,
+            'unchanged': 0,
+            'tier_counts': {TIER_HOT: 0, TIER_WARM: 0, TIER_COLD: 0}
+        }
+
+        updates = []
+
+        for row in rows:
+            stats['evaluated'] += 1
+            memory_dict = dict(row)
+            new_tier = self.evaluate_tier(memory_dict)
+            old_tier = row['tier'] or TIER_HOT  # Default to hot for unmigrated
+
+            stats['tier_counts'][new_tier] = stats['tier_counts'].get(new_tier, 0) + 1
+
+            if new_tier != old_tier:
+                updates.append((new_tier, datetime.now().isoformat(), row['id']))
+                if self._tier_rank(new_tier) < self._tier_rank(old_tier):
+                    stats['promoted'] += 1
+                else:
+                    stats['demoted'] += 1
+            else:
+                stats['unchanged'] += 1
+                # Still update tier_changed_at to avoid re-evaluation
+                updates.append((new_tier, datetime.now().isoformat(), row['id']))
+
+        # Batch update
+        if updates:
+            cursor.executemany(
+                "UPDATE memories SET tier = ?, tier_changed_at = ? WHERE id = ?",
+                updates
+            )
+            self.db.conn.commit()
+
+        stats['timestamp'] = datetime.now().isoformat()
+        return stats
+
+    def _tier_rank(self, tier: str) -> int:
+        """Numeric rank for tier comparison (lower = hotter)."""
+        return {TIER_HOT: 0, TIER_WARM: 1, TIER_COLD: 2}.get(tier, 1)
+
+    async def promote_on_access(self, memory_id: int) -> Optional[str]:
+        """Re-evaluate and promote a memory's tier when it is accessed.
+
+        Called after search results are returned to ensure frequently-accessed
+        memories don't stay cold/warm until the next batch maintenance run.
+
+        Args:
+            memory_id: ID of the accessed memory
+
+        Returns:
+            New tier if promoted, None if unchanged
+        """
+        cursor = self.db.conn.cursor()
+        cursor.execute(
+            "SELECT id, type, importance, access_count, decay_factor, created_at, tier FROM memories WHERE id = ?",
+            (memory_id,)
+        )
+        row = cursor.fetchone()
+        if not row:
+            return None
+
+        current_tier = row['tier'] or TIER_HOT
+        new_tier = self.evaluate_tier(dict(row))
+
+        if self._tier_rank(new_tier) < self._tier_rank(current_tier):
+            cursor.execute(
+                "UPDATE memories SET tier = ?, tier_changed_at = ? WHERE id = ?",
+                (new_tier, datetime.now().isoformat(), memory_id)
+            )
+            self.db.conn.commit()
+            logger.info(f"Memory {memory_id} promoted from {current_tier} to {new_tier}")
+            return new_tier
+
+        return None
+
+    async def get_tier_stats(self) -> Dict[str, Any]:
+        """Get distribution of memories across tiers."""
+        cursor = self.db.conn.cursor()
+
+        cursor.execute("""
+            SELECT COALESCE(tier, 'hot') as tier, COUNT(*) as count,
+                   AVG(importance) as avg_importance,
+                   AVG(access_count) as avg_access_count
+            FROM memories
+            GROUP BY COALESCE(tier, 'hot')
+        """)
+
+        tiers = {}
+        total = 0
+        for row in cursor.fetchall():
+            tier = row['tier']
+            count = row['count']
+            total += count
+            tiers[tier] = {
+                'count': count,
+                'avg_importance': round(row['avg_importance'] or 0, 2),
+                'avg_access_count': round(row['avg_access_count'] or 0, 2)
+            }
+
+        return {
+            'total_memories': total,
+            'tiers': tiers,
+            'timestamp': datetime.now().isoformat()
+        }

package/services/websocket.py

@@ -14,6 +14,17 @@ from dataclasses import dataclass, field
 from fastapi import WebSocket, WebSocketDisconnect
 
 
+def _normalize_ws_path(path: Optional[str]) -> Optional[str]:
+    """Normalize path for WebSocket comparison.
+
+    Converts backslashes to forward slashes and removes trailing slashes.
+    This ensures consistent path comparison across platforms.
+    """
+    if not path:
+        return None
+    return path.replace("\\", "/").rstrip("/")
+
+
 @dataclass
 class WebSocketClient:
     """Represents a connected WebSocket client."""
@@ -84,7 +95,8 @@ class WebSocketManager:
 
         client = self.clients[client_id]
         client.subscriptions = set(event_types)
-        client.project_filter = project_path
+        # Normalize path for consistent comparison
+        client.project_filter = _normalize_ws_path(project_path)
 
         await self._send_to_client(client_id, {
             "type": "subscribed",
@@ -101,15 +113,18 @@ class WebSocketManager:
             data: Event data payload
             project_path: Project this event relates to (for filtering)
         """
+        # Normalize the project path for consistent comparison
+        normalized_project = _normalize_ws_path(project_path)
+
         message = {
             "type": event_type,
             "data": data,
-            "project_path": project_path,
+            "project_path": normalized_project,
             "timestamp": time.time()
         }
 
         # Debug logging
-        print(f"[WS] Broadcasting {event_type} to {len(self.clients)} clients, project={project_path}")
+        print(f"[WS] Broadcasting {event_type} to {len(self.clients)} clients, project={normalized_project}")
 
         # Send to all matching clients
         disconnected = []
@@ -120,11 +135,11 @@ class WebSocketManager:
                 print(f"[WS] Skipping {client_id}: not subscribed to {event_type}")
                 continue
 
-            # Check project filter
+            # Check project filter (both are already normalized)
             # If project_path is None, send to all clients (global event)
             # If project_path is set, only send to matching clients
-            if project_path and client.project_filter and client.project_filter != project_path:
-                print(f"[WS] Skipping {client_id}: project mismatch ({client.project_filter} != {project_path})")
+            if normalized_project and client.project_filter and client.project_filter != normalized_project:
+                print(f"[WS] Skipping {client_id}: project mismatch ({client.project_filter} != {normalized_project})")
                 continue
 
             try:
@@ -217,11 +232,16 @@ class EventTypes:
     """Standard event types for broadcasting."""
     # Memory events
     MEMORY_STORED = "memory_stored"
+    MEMORY_UPDATED = "memory_updated"
     MEMORY_SEARCHED = "memory_searched"
     MEMORY_DELETED = "memory_deleted"
     MEMORY_ARCHIVED = "memory_archived"
     MEMORY_RESTORED = "memory_restored"
 
+    # Relationship/Link events
+    LINK_CREATED = "link_created"
+    LINK_DELETED = "link_deleted"
+
     # Timeline events
     TIMELINE_LOGGED = "timeline_logged"
     CHECKPOINT_CREATED = "checkpoint_created"

package/skills/__init__.py

@@ -2,5 +2,25 @@ from .store import store_memory
 from .retrieve import retrieve_memory
 from .search import semantic_search
 from .summarize import summarize_session
+from .confidence_tracker import (
+    report_solution_outcome,
+    get_reliability_stats,
+    get_unreliable_memories,
+    reset_memory_reliability,
+    memory_worked,
+    memory_failed
+)
 
-__all__ = ["store_memory", "retrieve_memory", "semantic_search", "summarize_session"]
+__all__ = [
+    "store_memory",
+    "retrieve_memory",
+    "semantic_search",
+    "summarize_session",
+    # Self-correcting confidence
+    "report_solution_outcome",
+    "get_reliability_stats",
+    "get_unreliable_memories",
+    "reset_memory_reliability",
+    "memory_worked",
+    "memory_failed"
+]