empathy-framework 5.1.1__py3-none-any.whl → 5.2.1__py3-none-any.whl

empathy_os/memory/long_term_types.py

@@ -0,0 +1,99 @@
+"""Type definitions for long-term memory system
+
+This module contains data classes, enums, and exceptions used by the long-term
+memory system. Extracted from long_term.py for better modularity and testability.
+
+Key Types:
+- Classification: Three-tier security classification system
+- ClassificationRules: Security rules per classification level
+- PatternMetadata: Metadata for stored patterns
+- SecurePattern: Pattern with content and metadata
+- SecurityError, PermissionError: Exception types
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class Classification(Enum):
+    """Three-tier classification system for MemDocs patterns"""
+
+    PUBLIC = "PUBLIC"  # Shareable across organization, anonymized
+    INTERNAL = "INTERNAL"  # Team/project only, no PII or secrets
+    SENSITIVE = "SENSITIVE"  # Encrypted at rest, access-controlled (HIPAA, finance)
+
+
+@dataclass
+class ClassificationRules:
+    """Security rules for each classification level"""
+
+    classification: Classification
+    encryption_required: bool
+    retention_days: int
+    access_level: str  # "all_users", "project_team", "explicit_permission"
+    audit_all_access: bool = False
+
+
+# Default classification rules based on enterprise security policy
+DEFAULT_CLASSIFICATION_RULES: dict[Classification, ClassificationRules] = {
+    Classification.PUBLIC: ClassificationRules(
+        classification=Classification.PUBLIC,
+        encryption_required=False,
+        retention_days=365,
+        access_level="all_users",
+        audit_all_access=False,
+    ),
+    Classification.INTERNAL: ClassificationRules(
+        classification=Classification.INTERNAL,
+        encryption_required=False,
+        retention_days=180,
+        access_level="project_team",
+        audit_all_access=False,
+    ),
+    Classification.SENSITIVE: ClassificationRules(
+        classification=Classification.SENSITIVE,
+        encryption_required=True,
+        retention_days=90,
+        access_level="explicit_permission",
+        audit_all_access=True,
+    ),
+}
+
+
+@dataclass
+class PatternMetadata:
+    """Metadata for stored MemDocs patterns"""
+
+    pattern_id: str
+    created_by: str
+    created_at: str
+    classification: str
+    retention_days: int
+    encrypted: bool
+    pattern_type: str
+    sanitization_applied: bool
+    pii_removed: int
+    secrets_detected: int
+    access_control: dict[str, Any] = field(default_factory=dict)
+    custom_metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SecurePattern:
+    """Represents a securely stored pattern"""
+
+    pattern_id: str
+    content: str
+    metadata: PatternMetadata
+
+
+class SecurityError(Exception):
+    """Raised when security policy is violated"""
+
+
+class PermissionError(Exception):
+    """Raised when access is denied"""

empathy_os/memory/mixins/__init__.py

@@ -0,0 +1,25 @@
+"""Memory mixins for UnifiedMemory composition.
+
+Provides modular capabilities through mixin composition pattern.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from .backend_init_mixin import BackendInitMixin
+from .capabilities_mixin import CapabilitiesMixin
+from .handoff_mixin import HandoffAndExportMixin
+from .lifecycle_mixin import LifecycleMixin
+from .long_term_mixin import LongTermOperationsMixin
+from .promotion_mixin import PatternPromotionMixin
+from .short_term_mixin import ShortTermOperationsMixin
+
+__all__ = [
+    "BackendInitMixin",
+    "CapabilitiesMixin",
+    "HandoffAndExportMixin",
+    "LifecycleMixin",
+    "LongTermOperationsMixin",
+    "PatternPromotionMixin",
+    "ShortTermOperationsMixin",
+]

empathy_os/memory/mixins/backend_init_mixin.py

@@ -0,0 +1,244 @@
+"""Backend initialization mixin for UnifiedMemory.
+
+Handles initialization of file session, Redis, and long-term memory backends.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+if TYPE_CHECKING:
+    from ..file_session import FileSessionMemory
+    from ..long_term import LongTermMemory, SecureMemDocsIntegration
+    from ..redis_bootstrap import RedisStatus
+    from ..short_term import RedisShortTermMemory
+
+logger = structlog.get_logger(__name__)
+
+
+class BackendInitMixin:
+    """Mixin providing backend initialization for UnifiedMemory."""
+
+    # Type hints for attributes that will be provided by UnifiedMemory
+    user_id: str
+    config: Any  # MemoryConfig
+    _file_session: "FileSessionMemory | None"
+    _short_term: "RedisShortTermMemory | None"
+    _long_term: "SecureMemDocsIntegration | None"
+    _simple_long_term: "LongTermMemory | None"
+    _redis_status: "RedisStatus | None"
+    _initialized: bool
+
+    # =========================================================================
+    # BACKEND INITIALIZATION
+    # =========================================================================
+
+    def _initialize_backends(self):
+        """Initialize short-term and long-term memory backends.
+
+        File-First Architecture:
+        1. FileSessionMemory is always initialized (primary storage)
+        2. Redis is optional (for real-time features like pub/sub)
+        3. Falls back gracefully when Redis is unavailable
+        """
+        from ..claude_memory import ClaudeMemoryConfig
+        from ..config import get_redis_memory
+        from ..file_session import FileSessionConfig, FileSessionMemory
+        from ..long_term import LongTermMemory, SecureMemDocsIntegration
+        from ..redis_bootstrap import RedisStartMethod, RedisStatus, ensure_redis
+        from ..short_term import RedisShortTermMemory
+
+        if self._initialized:
+            return
+
+        # Initialize file-based session memory (PRIMARY - always available)
+        if self.config.file_session_enabled:
+            try:
+                file_config = FileSessionConfig(base_dir=self.config.file_session_dir)
+                self._file_session = FileSessionMemory(
+                    user_id=self.user_id,
+                    config=file_config,
+                )
+                logger.info(
+                    "file_session_memory_initialized",
+                    base_dir=self.config.file_session_dir,
+                    session_id=self._file_session._state.session_id,
+                )
+            except Exception as e:
+                logger.error("file_session_memory_failed", error=str(e))
+                self._file_session = None
+
+        # Initialize Redis short-term memory (OPTIONAL - for real-time features)
+        try:
+            if self.config.redis_mock:
+                self._short_term = RedisShortTermMemory(use_mock=True)
+                self._redis_status = RedisStatus(
+                    available=False,
+                    method=RedisStartMethod.MOCK,
+                    message="Mock mode explicitly enabled",
+                )
+            elif self.config.redis_url:
+                self._short_term = get_redis_memory(url=self.config.redis_url)
+                self._redis_status = RedisStatus(
+                    available=True,
+                    method=RedisStartMethod.ALREADY_RUNNING,
+                    message="Connected via REDIS_URL",
+                )
+            # Use auto-start if enabled
+            elif self.config.redis_auto_start:
+                self._redis_status = ensure_redis(
+                    host=self.config.redis_host,
+                    port=self.config.redis_port,
+                    auto_start=True,
+                    verbose=True,
+                )
+                if self._redis_status.available:
+                    self._short_term = RedisShortTermMemory(
+                        host=self.config.redis_host,
+                        port=self.config.redis_port,
+                        use_mock=False,
+                    )
+                else:
+                    # File session is primary, so Redis mock is not needed
+                    self._short_term = None
+                    self._redis_status = RedisStatus(
+                        available=False,
+                        method=RedisStartMethod.MOCK,
+                        message="Redis unavailable, using file-based storage",
+                    )
+            else:
+                # Try to connect to existing Redis
+                try:
+                    self._short_term = get_redis_memory()
+                    if self._short_term.is_connected():
+                        self._redis_status = RedisStatus(
+                            available=True,
+                            method=RedisStartMethod.ALREADY_RUNNING,
+                            message="Connected to existing Redis",
+                        )
+                    else:
+                        self._short_term = None
+                        self._redis_status = RedisStatus(
+                            available=False,
+                            method=RedisStartMethod.MOCK,
+                            message="Redis not available, using file-based storage",
+                        )
+                except Exception:
+                    self._short_term = None
+                    self._redis_status = RedisStatus(
+                        available=False,
+                        method=RedisStartMethod.MOCK,
+                        message="Redis not available, using file-based storage",
+                    )
+
+            logger.info(
+                "short_term_memory_initialized",
+                redis_available=self._redis_status.available if self._redis_status else False,
+                file_session_available=self._file_session is not None,
+                redis_method=self._redis_status.method.value if self._redis_status else "none",
+                environment=self.config.environment.value,
+            )
+
+            # Fail if Redis is required but not available
+            if self.config.redis_required and not (
+                self._redis_status and self._redis_status.available
+            ):
+                raise RuntimeError("Redis is required but not available")
+
+        except RuntimeError:
+            raise  # Re-raise required Redis error
+        except Exception as e:
+            logger.warning("redis_initialization_failed", error=str(e))
+            self._short_term = None
+            self._redis_status = RedisStatus(
+                available=False,
+                method=RedisStartMethod.MOCK,
+                message=f"Failed to initialize: {e}",
+            )
+
+        # Initialize long-term memory (SecureMemDocs)
+        try:
+            claude_config = ClaudeMemoryConfig(
+                enabled=self.config.claude_memory_enabled,
+                load_enterprise=self.config.load_enterprise_memory,
+                load_project=self.config.load_project_memory,
+                load_user=self.config.load_user_memory,
+            )
+            self._long_term = SecureMemDocsIntegration(
+                claude_memory_config=claude_config,
+                storage_dir=self.config.storage_dir,
+                enable_encryption=self.config.encryption_enabled,
+            )
+
+            logger.info(
+                "long_term_memory_initialized",
+                storage_dir=self.config.storage_dir,
+                encryption=self.config.encryption_enabled,
+            )
+        except Exception as e:
+            logger.error("long_term_memory_failed", error=str(e))
+            self._long_term = None
+
+        # Initialize simple long-term memory (for testing and simple use cases)
+        try:
+            self._simple_long_term = LongTermMemory(storage_path=self.config.storage_dir)
+            logger.debug("simple_long_term_memory_initialized")
+        except Exception as e:
+            logger.error("simple_long_term_memory_failed", error=str(e))
+            self._simple_long_term = None
+
+        self._initialized = True
+
+    def get_backend_status(self) -> dict[str, Any]:
+        """Get the current status of all memory backends.
+
+        Returns a structured dict suitable for health checks, debugging,
+        and dashboard display. Can be serialized to JSON.
+
+        Returns:
+            dict with keys:
+                - environment: Current environment (development/staging/production)
+                - short_term: Status of Redis-based short-term memory
+                - long_term: Status of persistent long-term memory
+                - initialized: Whether backends have been initialized
+
+        Example:
+            >>> memory = UnifiedMemory(user_id="agent")
+            >>> status = memory.get_backend_status()
+            >>> print(status["short_term"]["available"])
+            True
+
+        """
+        from ..redis_bootstrap import RedisStartMethod
+
+        short_term_status: dict[str, Any] = {
+            "available": False,
+            "mock": True,
+            "method": "unknown",
+            "message": "Not initialized",
+        }
+
+        if self._redis_status:
+            short_term_status = {
+                "available": self._redis_status.available,
+                "mock": not self._redis_status.available
+                or self._redis_status.method == RedisStartMethod.MOCK,
+                "method": self._redis_status.method.value,
+                "message": self._redis_status.message,
+            }
+
+        long_term_status: dict[str, Any] = {
+            "available": self._long_term is not None,
+            "storage_dir": self.config.storage_dir,
+            "encryption_enabled": self.config.encryption_enabled,
+        }
+
+        return {
+            "environment": self.config.environment.value,
+            "initialized": self._initialized,
+            "short_term": short_term_status,
+            "long_term": long_term_status,
+        }

empathy_os/memory/mixins/capabilities_mixin.py

@@ -0,0 +1,199 @@
+"""Capabilities and health check mixin for UnifiedMemory.
+
+Provides backend availability checks, health monitoring, and feature detection.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..file_session import FileSessionMemory
+    from ..long_term import LongTermMemory
+    from ..redis_bootstrap import RedisStatus
+    from ..short_term import RedisShortTermMemory
+
+
+class CapabilitiesMixin:
+    """Mixin providing capability detection and health checks for UnifiedMemory."""
+
+    # Type hints for attributes that will be provided by UnifiedMemory
+    _file_session: "FileSessionMemory | None"
+    _short_term: "RedisShortTermMemory | None"
+    _long_term: Any  # SecureMemDocsIntegration
+    _simple_long_term: "LongTermMemory | None"
+    _redis_status: "RedisStatus | None"
+    config: Any  # MemoryConfig
+
+    # =========================================================================
+    # BACKEND AVAILABILITY CHECKS
+    # =========================================================================
+
+    @property
+    def has_short_term(self) -> bool:
+        """Check if short-term memory is available."""
+        return self._short_term is not None
+
+    @property
+    def has_long_term(self) -> bool:
+        """Check if long-term memory is available."""
+        return self._long_term is not None
+
+    @property
+    def redis_status(self) -> "RedisStatus | None":
+        """Get Redis connection status."""
+        return self._redis_status
+
+    @property
+    def using_real_redis(self) -> bool:
+        """Check if using real Redis (not mock)."""
+        from ..redis_bootstrap import RedisStartMethod
+
+        return (
+            self._redis_status is not None
+            and self._redis_status.available
+            and self._redis_status.method != RedisStartMethod.MOCK
+        )
+
+    @property
+    def short_term(self) -> "RedisShortTermMemory":
+        """Get short-term memory backend for direct access (testing).
+
+        Returns:
+            RedisShortTermMemory instance
+
+        Raises:
+            RuntimeError: If short-term memory is not initialized
+
+        """
+        if self._short_term is None:
+            raise RuntimeError("Short-term memory not initialized")
+        return self._short_term
+
+    @property
+    def long_term(self) -> "LongTermMemory":
+        """Get simple long-term memory backend for direct access (testing).
+
+        Returns:
+            LongTermMemory instance
+
+        Raises:
+            RuntimeError: If long-term memory is not initialized
+
+        Note:
+            For production use with security features (PII scrubbing, encryption),
+            use persist_pattern() and recall_pattern() methods instead.
+
+        """
+        if self._simple_long_term is None:
+            raise RuntimeError("Long-term memory not initialized")
+        return self._simple_long_term
+
+    # =========================================================================
+    # HEALTH CHECKS
+    # =========================================================================
+
+    def health_check(self) -> dict[str, Any]:
+        """Check health of memory backends.
+
+        Returns:
+            Status of each memory backend
+
+        """
+        redis_info: dict[str, Any] = {
+            "available": self.has_short_term,
+            "mock_mode": not self.using_real_redis,
+        }
+        if self._redis_status:
+            redis_info["method"] = self._redis_status.method.value
+            redis_info["host"] = self._redis_status.host
+            redis_info["port"] = self._redis_status.port
+
+        return {
+            "file_session": {
+                "available": self._file_session is not None,
+                "session_id": self._file_session._state.session_id if self._file_session else None,
+                "base_dir": self.config.file_session_dir,
+            },
+            "short_term": redis_info,
+            "long_term": {
+                "available": self.has_long_term,
+                "storage_dir": self.config.storage_dir,
+                "encryption": self.config.encryption_enabled,
+            },
+            "environment": self.config.environment.value,
+        }
+
+    # =========================================================================
+    # CAPABILITY DETECTION (File-First Architecture)
+    # =========================================================================
+
+    @property
+    def has_file_session(self) -> bool:
+        """Check if file-based session memory is available (always True if enabled)."""
+        return self._file_session is not None
+
+    @property
+    def file_session(self) -> "FileSessionMemory":
+        """Get file session memory backend for direct access.
+
+        Returns:
+            FileSessionMemory instance
+
+        Raises:
+            RuntimeError: If file session memory is not initialized
+        """
+        if self._file_session is None:
+            raise RuntimeError("File session memory not initialized")
+        return self._file_session
+
+    def supports_realtime(self) -> bool:
+        """Check if real-time features are available (requires Redis).
+
+        Real-time features include:
+        - Pub/Sub messaging between agents
+        - Cross-session coordination
+        - Distributed task queues
+
+        Returns:
+            True if Redis is available and connected
+        """
+        return self.using_real_redis
+
+    def supports_distributed(self) -> bool:
+        """Check if distributed features are available (requires Redis).
+
+        Distributed features include:
+        - Multi-process coordination
+        - Cross-session state sharing
+        - Agent discovery
+
+        Returns:
+            True if Redis is available and connected
+        """
+        return self.using_real_redis
+
+    def supports_persistence(self) -> bool:
+        """Check if persistence is available (always True with file-first).
+
+        Returns:
+            True if file session or long-term memory is available
+        """
+        return self._file_session is not None or self._long_term is not None
+
+    def get_capabilities(self) -> dict[str, bool]:
+        """Get a summary of available memory capabilities.
+
+        Returns:
+            Dictionary mapping capability names to availability
+        """
+        return {
+            "file_session": self.has_file_session,
+            "redis": self.using_real_redis,
+            "long_term": self.has_long_term,
+            "persistence": self.supports_persistence(),
+            "realtime": self.supports_realtime(),
+            "distributed": self.supports_distributed(),
+            "encryption": self.config.encryption_enabled and self.has_long_term,
+        }