@ngocsangairvds/vsaf 3.2.16 → 4.0.1

package/tools/vds-scripts/memory_orchestrator/src/vds_memory_orchestrator/service/models/ai_memory_models.py

@@ -1,1587 +0,0 @@
-"""Pydantic models for the VDS AI Memory service."""
-
-from __future__ import annotations
-
-from datetime import UTC, datetime, timedelta
-from enum import StrEnum
-from typing import Any, Literal
-
-from pydantic import BaseModel, Field, field_validator
-
-from vds_memory_orchestrator.service.integrations.memory_transformer import (
-    BusinessDomain,
-    ImportanceLevel,
-    MCPUserPreferences,
-    MemoryCategory,
-    SessionEnvironment,
-)
-from vds_memory_orchestrator.service.services.storage_strategy import StorageTier
-
-
-def _normalize_category(value: str | MemoryCategory | None) -> MemoryCategory | None:
-    """
-    Normalize category inputs (case/underscore tolerant) to the unified enum.
-    """
-    if value is None:
-        return None
-    if isinstance(value, MemoryCategory):
-        return value
-
-    if isinstance(value, str):
-        norm = value.strip().lower().replace("_", "-")
-        alias_map = {
-            "session-summary": "session-summary",
-            "session_summary": "session-summary",
-            "hook-insight": "hook-insight",
-            "hook_insight": "hook-insight",
-            "business-logic": "business-logic",
-            "business_logic": "business-logic",
-            "api-call": "api-call",
-            "api_call": "api-call",
-            "user-preference": "user_preference",
-            "user_preference": "user_preference",
-        }
-        norm = alias_map.get(norm, norm)
-        try:
-            return MemoryCategory(norm)
-        except ValueError as exc:
-            allowed = ", ".join([c.value for c in MemoryCategory])
-            raise ValueError(f"Unsupported category '{value}'. Allowed: {allowed}") from exc
-    raise ValueError("Category must be a string or MemoryCategory")
-
-
-class OperationType(StrEnum):
-    """Types of operations that can be tracked."""
-
-    CREATE = "create"
-    READ = "read"
-    UPDATE = "update"
-    DELETE = "delete"
-    SEARCH = "search"
-    EXECUTE = "execute"
-    HOOK = "hook"
-    ANALYZE = "analyze"
-
-
-class ToolType(StrEnum):
-    """VDS tool types."""
-
-    BASH = "bash"
-    READ = "read"
-    WRITE = "write"
-    EDIT = "edit"
-    MULTI_EDIT = "multi_edit"
-    WEB_FETCH = "web_fetch"
-    WEB_SEARCH = "web_search"
-    JIRA = "jira"
-    BITBUCKET = "bitbucket"
-    CONFLUENCE = "confluence"
-
-
-class SessionStatus(StrEnum):
-    """Session status values."""
-
-    ACTIVE = "active"
-    INACTIVE = "inactive"
-    EXPIRED = "expired"
-    CLOSED = "closed"
-    ERROR = "error"
-
-
-class MemoryStatus(StrEnum):
-    """Memory status values."""
-
-    ACTIVE = "active"
-    ARCHIVED = "archived"
-    DELETED = "deleted"
-    PROCESSING = "processing"
-    ERROR = "error"
-
-
-class TimeRangePreset(StrEnum):
-    """Supported time range presets for memory queries."""
-
-    HOUR = "hour"
-    DAY = "day"
-    WEEK = "week"
-    MONTH = "month"
-    YEAR = "year"
-
-
-# Core unified models
-class Session(BaseModel):
-    """Session model combining Memory and Session service capabilities."""
-
-    # Basic session information
-    session_id: str = Field(..., description="Unique session identifier")
-    user_id: str = Field(..., description="User identifier")
-    status: SessionStatus = Field(default=SessionStatus.ACTIVE, description="Session status")
-
-    # Project and working context
-    project_domain: BusinessDomain = Field(..., description="Business domain")
-    working_directory: str | None = Field(None, description="Current working directory")
-    git_branch: str | None = Field(None, description="Current git branch")
-    git_repository: str | None = Field(None, description="Git repository URL")
-    environment: SessionEnvironment = Field(
-        default=SessionEnvironment.DEVELOPMENT, description="Session environment"
-    )
-    session_context: str | None = Field(
-        None, description="High-level purpose or narrative for the session"
-    )
-    template_id: str | None = Field(
-        None, description="Template identifier used to create the session"
-    )
-    template_name: str | None = Field(
-        None, description="Template display name used during creation"
-    )
-    context_tags: list[str] = Field(
-        default_factory=list, description="Derived tags summarizing the session"
-    )
-    key_tasks: list[str] = Field(
-        default_factory=list, description="Active tasks inferred for the session"
-    )
-    risk_flags: list[str] = Field(
-        default_factory=list, description="Potential risks or alerts detected"
-    )
-
-    # Session lifecycle
-    created_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Session creation time"
-    )
-    last_accessed: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Last access time"
-    )
-    expires_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC) + timedelta(hours=1),
-        description="Session expiration time",
-    )
-    duration_seconds: int | None = Field(None, description="Session duration in seconds")
-
-    # Session activity
-    total_operations: int = Field(default=0, description="Total operations in session")
-    total_memories: int = Field(default=0, description="Total memories created in session")
-    last_operation: str | None = Field(None, description="Last performed operation")
-    current_task: str | None = Field(None, description="Current task description")
-
-    # User preferences and context
-    preferences: MCPUserPreferences = Field(
-        default_factory=lambda: MCPUserPreferences(), description="User preferences"
-    )
-    context_metadata: dict[str, Any] = Field(
-        default_factory=dict, description="Additional context metadata"
-    )
-
-    # Memory integration
-    last_memory_content: str | None = Field(None, description="Most recent memory content")
-    session_summary: str | None = Field(None, description="Generated session summary")
-    memory_categories: list[str] = Field(
-        default_factory=list, description="Memory categories used in session"
-    )
-
-    # Analytics and insights
-    session_patterns: list[str] = Field(
-        default_factory=list, description="Detected session patterns"
-    )
-    suggested_actions: list[str] = Field(
-        default_factory=list, description="AI-generated suggestions"
-    )
-    performance_metrics: dict[str, Any] = Field(
-        default_factory=dict, description="Session performance metrics"
-    )
-
-    # Storage strategy tracking
-    storage_decisions: dict[str, Any] = Field(
-        default_factory=dict, description="Storage tier decisions made in this session"
-    )
-    storage_performance: dict[str, float] = Field(
-        default_factory=dict, description="Storage performance metrics by tier"
-    )
-    consolidation_events: list[dict[str, Any]] = Field(
-        default_factory=list, description="Memory consolidation events"
-    )
-
-    # Health and status
-    error_count: int = Field(default=0, description="Number of errors in session")
-    health_score: float = Field(default=1.0, description="Session health score (0-1)")
-
-    @field_validator("expires_at")
-    @classmethod
-    def validate_expiration(cls, v, info):
-        """Ensure expiration is after creation."""
-        if info.context and "created_at" in info.context and v <= info.context["created_at"]:
-            msg = "Expiration time must be after creation time"
-            raise ValueError(msg)
-        return v
-
-    @field_validator("duration_seconds")
-    @classmethod
-    def calculate_duration(cls, v, info):
-        """Calculate duration from timestamps if not provided."""
-        if (
-            v is None
-            and info.context
-            and "last_accessed" in info.context
-            and "created_at" in info.context
-        ):
-            return int((info.context["last_accessed"] - info.context["created_at"]).total_seconds())
-        return v
-
-
-class Memory(BaseModel):
-    """Memory model with enhanced session integration."""
-
-    # Basic memory information
-    memory_id: str | None = Field(None, description="Unique memory identifier")
-    content: str = Field(..., min_length=1, max_length=10000, description="Memory content")
-    category: MemoryCategory = Field(default=MemoryCategory.GENERAL, description="Memory category")
-    importance: ImportanceLevel = Field(
-        default=ImportanceLevel.MEDIUM, description="Memory importance level"
-    )
-    status: MemoryStatus = Field(default=MemoryStatus.ACTIVE, description="Memory status")
-
-    # Session integration
-    session_id: str = Field(..., description="Associated session ID")
-    user_id: str | None = Field(None, description="User identifier")
-    team_id: str | None = Field(None, description="Team identifier for shared memories")
-    conversation_id: str | None = Field(None, description="Conversation identifier")
-
-    # Context and metadata
-    working_directory: str | None = Field(None, description="Working directory context")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
-    expires_at: datetime | None = Field(
-        default=None, description="Optional expiration timestamp for the memory"
-    )
-
-    # Session context enhancement
-    session_context: dict[str, Any] | None = Field(
-        None, description="Session context at memory creation"
-    )
-    operation_type: OperationType | None = Field(
-        None, description="Operation type that triggered memory"
-    )
-    tool_used: ToolType | None = Field(None, description="Tool used for operation")
-
-    # Content analysis
-    entities: list[str] = Field(default_factory=list, description="Extracted entities")
-    tags: list[str] = Field(default_factory=list, description="Memory tags")
-    keywords: list[str] = Field(default_factory=list, description="Extracted keywords")
-
-    # Graph relations returned by Mem0 (optional)
-    relations: list[dict[str, Any]] | None = Field(
-        default=None, description="Graph relations returned by Mem0 search"
-    )
-
-    # Storage strategy fields
-    storage_tier: StorageTier | None = Field(
-        None, description="Selected storage tier for this memory"
-    )
-    storage_decision_confidence: float | None = Field(
-        None, ge=0.0, le=1.0, description="Confidence in storage tier decision"
-    )
-    storage_reasoning: str | None = Field(None, description="Reasoning for storage tier selection")
-    storage_processing_time_ms: int | None = Field(
-        None, description="Time taken for storage classification in milliseconds"
-    )
-    consolidation_status: str | None = Field(None, description="Current consolidation status")
-    consolidation_candidates: list[str] = Field(
-        default_factory=list, description="Candidate memory IDs for consolidation"
-    )
-    merged_into_memory: str | None = Field(
-        None, description="ID of memory this was merged into (if applicable)"
-    )
-    related_memories: list[str] = Field(default_factory=list, description="Related memory IDs")
-
-    # Versioning fields (Phase 2.1.1)
-    current_version_number: int = Field(default=1, description="Current active version number")
-    total_versions: int = Field(default=1, description="Total number of versions for this memory")
-    versioning_enabled: bool = Field(
-        default=True, description="Whether versioning is enabled for this memory"
-    )
-    version_history_limit: int = Field(
-        default=100, description="Maximum number of versions to keep"
-    )
-    last_version_created: datetime | None = Field(
-        None, description="When the last version was created"
-    )
-
-    # AI enhancement
-    vector_embedding: list[float] | None = Field(
-        None, description="Vector embedding for semantic search"
-    )
-    relevance_score: float | None = Field(None, description="Relevance score for search")
-    graph_relationships: list[dict[str, Any]] = Field(
-        default_factory=list, description="Graph relationships"
-    )
-
-    # Timestamps
-    created_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Creation time"
-    )
-    updated_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Last update time"
-    )
-    accessed_at: datetime | None = Field(None, description="Last access time")
-
-    # Performance metrics
-    processing_time_ms: int | None = Field(None, description="Processing time in milliseconds")
-    cache_hit: bool = Field(default=False, description="Whether this was a cache hit")
-
-    @field_validator("session_context")
-    @classmethod
-    def validate_session_context(cls, v):
-        """Validate session context structure."""
-        if v and not isinstance(v, dict):
-            msg = "Session context must be a dictionary"
-            raise ValueError(msg)
-        return v
-
-    @field_validator("created_at", "updated_at", mode="before")
-    @classmethod
-    def coerce_datetime_field(cls, v: Any) -> Any:
-        """Coerce invalid datetime strings to now() so invalid mem0 timestamps
-        never crash response construction (graceful degradation)."""
-        if v is None or isinstance(v, datetime):
-            return v
-        if isinstance(v, str):
-            try:
-                normalized = v.replace("Z", "+00:00")
-                return datetime.fromisoformat(normalized)
-            except (ValueError, TypeError):
-                return datetime.now(UTC)
-        return v
-
-    @field_validator(
-        "tags",
-        "keywords",
-        "entities",
-        "consolidation_candidates",
-        "related_memories",
-        "graph_relationships",
-        mode="before",
-    )
-    @classmethod
-    def normalize_list_fields(cls, v):
-        if v is None:
-            return []
-        if isinstance(v, list):
-            return v
-        return [v]
-
-
-class Operation(BaseModel):
-    """Operation tracking model."""
-
-    # Basic operation information
-    operation_id: str = Field(..., description="Unique operation identifier")
-    session_id: str = Field(..., description="Associated session ID")
-    user_id: str = Field(..., description="User identifier")
-
-    # Operation details
-    operation_type: OperationType = Field(..., description="Type of operation")
-    tool_used: ToolType = Field(..., description="Tool used")
-    operation_parameters: dict[str, Any] = Field(
-        default_factory=dict, description="Operation parameters"
-    )
-
-    # Execution details
-    status: str = Field(default="pending", description="Operation status")
-    result: Any | None = Field(None, description="Operation result")
-    error: str | None = Field(None, description="Error message if failed")
-
-    # Performance metrics
-    start_time: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Operation start time"
-    )
-    end_time: datetime | None = Field(None, description="Operation end time")
-    duration_ms: int | None = Field(None, description="Duration in milliseconds")
-
-    # Context information
-    working_directory: str | None = Field(None, description="Working directory")
-    project_context: str | None = Field(None, description="Project context")
-
-    # AI enhancement
-    success_probability: float | None = Field(None, description="Predicted success probability")
-    suggested_improvements: list[str] = Field(
-        default_factory=list, description="AI-suggested improvements"
-    )
-
-    @field_validator("duration_ms")
-    @classmethod
-    def calculate_duration(cls, v, info):
-        """Calculate duration from timestamps if not provided."""
-        if (
-            v is None
-            and info.context
-            and "end_time" in info.context
-            and "start_time" in info.context
-            and info.context["end_time"]
-        ):
-            return int(
-                (info.context["end_time"] - info.context["start_time"]).total_seconds() * 1000
-            )
-        return v
-
-
-class Analytics(BaseModel):
-    """Analytics model for both memory and session data."""
-
-    # Analytics metadata
-    analytics_id: str = Field(..., description="Unique analytics identifier")
-    user_id: str | None = Field(None, description="User identifier (None for global analytics)")
-    timeframe_start: datetime = Field(..., description="Analytics timeframe start")
-    timeframe_end: datetime = Field(..., description="Analytics timeframe end")
-
-    # Session analytics
-    total_sessions: int = Field(default=0, description="Total sessions")
-    active_sessions: int = Field(default=0, description="Active sessions")
-    average_session_duration: float = Field(
-        default=0.0, description="Average session duration in minutes"
-    )
-    session_success_rate: float = Field(default=1.0, description="Session success rate")
-
-    # Memory analytics
-    total_memories: int = Field(default=0, description="Total memories created")
-    memories_per_session: float = Field(default=0.0, description="Average memories per session")
-
-    # Operation analytics
-    total_operations: int = Field(default=0, description="Total operations tracked")
-    memory_categories: dict[str, int] = Field(
-        default_factory=dict, description="Memory usage by category"
-    )
-    memory_importance_distribution: dict[str, int] = Field(
-        default_factory=dict, description="Memory importance distribution"
-    )
-
-    # Tool and operation analytics
-    tool_usage: dict[str, int] = Field(default_factory=dict, description="Tool usage counts")
-    operation_types: dict[str, int] = Field(
-        default_factory=dict, description="Operation type counts"
-    )
-    operation_success_rates: dict[str, float] = Field(
-        default_factory=dict, description="Operation success rates"
-    )
-    average_operation_duration: dict[str, float] = Field(
-        default_factory=dict, description="Average operation durations"
-    )
-    user_analytics: dict[str, Any] = Field(
-        default_factory=dict, description="User analytics payload"
-    )
-    system_analytics: dict[str, Any] = Field(
-        default_factory=dict, description="System analytics payload"
-    )
-    patterns: dict[str, Any] = Field(default_factory=dict, description="Detected patterns/insights")
-
-    # Project and domain analytics
-    project_distribution: dict[str, int] = Field(
-        default_factory=dict, description="Project usage distribution"
-    )
-    domain_distribution: dict[str, int] = Field(
-        default_factory=dict, description="Business domain distribution"
-    )
-    working_directories: list[str] = Field(
-        default_factory=list, description="Top working directories"
-    )
-
-    # Performance analytics
-    cache_hit_rates: dict[str, float] = Field(
-        default_factory=dict, description="Cache hit rates by type"
-    )
-    response_times: dict[str, float] = Field(
-        default_factory=dict, description="Average response times"
-    )
-    error_rates: dict[str, float] = Field(
-        default_factory=dict, description="Error rates by operation"
-    )
-
-    # AI and pattern analytics
-    detected_patterns: list[str] = Field(
-        default_factory=list, description="Detected usage patterns"
-    )
-    user_preferences: dict[str, Any] = Field(
-        default_factory=dict, description="User preference analysis"
-    )
-    suggested_optimizations: list[str] = Field(
-        default_factory=list, description="AI-suggested optimizations"
-    )
-
-    # Storage strategy analytics
-    storage_tier_distribution: dict[str, int] = Field(
-        default_factory=dict, description="Memory distribution by storage tier"
-    )
-    storage_performance_metrics: dict[str, dict[str, float]] = Field(
-        default_factory=dict, description="Performance metrics by storage tier"
-    )
-    consolidation_operations: dict[str, int] = Field(
-        default_factory=dict, description="Consolidation operation counts"
-    )
-    consolidation_success_rates: dict[str, float] = Field(
-        default_factory=dict, description="Consolidation success rates"
-    )
-    storage_cost_analysis: dict[str, float] = Field(
-        default_factory=dict, description="Cost analysis by storage tier"
-    )
-    storage_efficiency_metrics: dict[str, float] = Field(
-        default_factory=dict, description="Storage efficiency metrics"
-    )
-
-    # Health and quality metrics
-    overall_health_score: float = Field(default=1.0, description="Overall system health score")
-    data_quality_score: float = Field(default=1.0, description="Data quality score")
-    user_satisfaction_score: float | None = Field(None, description="User satisfaction score")
-
-
-class SessionBehaviorEvent(BaseModel):
-    """Atomic event describing a session interaction."""
-
-    timestamp: datetime = Field(..., description="Event timestamp")
-    operation_type: OperationType = Field(..., description="Operation type")
-    tool_used: ToolType = Field(..., description="Tool involved in the event")
-    status: str = Field(..., description="Execution status")
-    duration_ms: int | None = Field(None, description="Duration in milliseconds")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional event metadata")
-
-
-class SessionBehaviorAnalytics(BaseModel):
-    """Detailed analytics describing a single session's behavior."""
-
-    session_id: str = Field(..., description="Session identifier")
-    user_id: str | None = Field(None, description="User owning the session")
-    template_id: str | None = Field(None, description="Template used")
-    total_operations: int = Field(default=0, description="Total recorded operations")
-    success_rate: float = Field(default=0.0, description="Success ratio (0-1)")
-    error_count: int = Field(default=0, description="Number of failed operations")
-    duration_minutes: float = Field(
-        default=0.0, description="Session duration based on lifecycle timestamps"
-    )
-    active_minutes: float = Field(
-        default=0.0, description="Active minutes derived from operation timestamps"
-    )
-    idle_minutes: float = Field(default=0.0, description="Idle minutes (duration - active)")
-    operations_by_type: dict[str, int] = Field(
-        default_factory=dict, description="Operation counts grouped by type"
-    )
-    tool_usage: dict[str, int] = Field(default_factory=dict, description="Tool usage histogram")
-    average_operation_duration_ms: float = Field(
-        default=0.0, description="Mean duration across operations"
-    )
-    first_event_at: datetime | None = Field(
-        None, description="Timestamp of the first recorded event"
-    )
-    last_event_at: datetime | None = Field(None, description="Timestamp of the last recorded event")
-    recent_activity: list[SessionBehaviorEvent] = Field(
-        default_factory=list, description="Chronological slice of recent activity"
-    )
-
-
-# Request/Response models for API
-class SessionCreateRequest(BaseModel):
-    """Request model for creating a session."""
-
-    user_id: str = Field(..., description="User identifier")
-    project_domain: BusinessDomain = Field(..., description="Business domain")
-    context: str | None = Field(None, description="Session context or narrative")
-    working_directory: str | None = Field(None, description="Initial working directory")
-    git_branch: str | None = Field(None, description="Git branch for the session")
-    git_repository: str | None = Field(None, description="Git repository URL")
-    environment: SessionEnvironment = Field(
-        default=SessionEnvironment.DEVELOPMENT, description="Session environment"
-    )
-    preferences: MCPUserPreferences | None = Field(None, description="User preferences")
-    ttl_hours: int = Field(default=1, description="Session TTL in hours")
-    metadata: dict[str, Any] | None = Field(default_factory=dict)
-    template_id: str | None = Field(None, description="Template identifier used for creation")
-    template_name: str | None = Field(None, description="Template display name used for creation")
-
-
-class SessionUpdateRequest(BaseModel):
-    """Request model for updating a session."""
-
-    session_id: str = Field(..., description="Session identifier")
-    updates: dict[str, Any] = Field(..., description="Fields to update")
-    extend_ttl: bool | None = Field(None, description="Whether to extend TTL")
-    ttl_hours: int | None = Field(None, description="New TTL in hours if extending")
-
-
-class MemoryCreateRequest(BaseModel):
-    """Request model for creating a memory."""
-
-    content: str = Field(..., min_length=1, max_length=10000, description="Memory content")
-    category: MemoryCategory = Field(default=MemoryCategory.GENERAL, description="Memory category")
-    importance: ImportanceLevel = Field(
-        default=ImportanceLevel.MEDIUM, description="Memory importance"
-    )
-    force_mem0: bool = Field(
-        default=False,
-        description="Force routing to Mem0 Pro regardless of rule classification",
-    )
-    conversation_id: str | None = Field(None, description="Conversation identifier")
-    ttl_minutes: int | None = Field(
-        None, description="Optional TTL in minutes for short-lived memories"
-    )
-    session_id: str = Field(..., description="Session identifier")
-    user_id: str | None = Field(None, description="User identifier")
-    team_id: str | None = Field(None, description="Team identifier for shared access")
-    working_directory: str | None = Field(None, description="Working directory")
-    project_domain: BusinessDomain | None = Field(None, description="Project/domain for the memory")
-    metadata: dict[str, Any] | None = Field(default_factory=dict)
-    operation_type: OperationType | None = Field(
-        None, description="Operation type that triggered memory"
-    )
-    tool_used: ToolType | None = Field(None, description="Tool used")
-
-    @field_validator("category", mode="before")
-    @classmethod
-    def normalize_category(cls, v):
-        return _normalize_category(v)
-
-
-class MemoryBatchCreateRequest(BaseModel):
-    """Batch create payload for multiple memories."""
-
-    memories: list[MemoryCreateRequest] = Field(
-        ..., min_length=1, max_length=100, description="List of memories to create"
-    )
-
-
-class MemorySearchRequest(BaseModel):
-    """Request model for searching memories."""
-
-    query: str = Field(..., min_length=1, max_length=1000, description="Search query")
-    session_id: str | None = Field(None, description="Filter by session ID")
-    conversation_id: str | None = Field(None, description="Filter by conversation ID")
-    user_id: str | None = Field(None, description="Filter by user ID")
-    team_id: str | None = Field(None, description="Filter by team ID")
-    category: MemoryCategory | None = Field(None, description="Filter by category")
-    importance: ImportanceLevel | None = Field(None, description="Filter by importance")
-    tags: list[str] | None = Field(None, description="Filter by tags")
-    memory_ids: list[str] | None = Field(None, description="Filter by explicit Mem0 memory IDs")
-    external_id: str | None = Field(None, description="Filter by external/canonical memory ID")
-    project_domain: BusinessDomain | None = Field(None, description="Filter by project domain")
-    tool_used: ToolType | None = Field(None, description="Filter by tool used")
-    created_after: datetime | None = Field(
-        None, description="Filter memories created after this timestamp"
-    )
-    created_before: datetime | None = Field(
-        None, description="Filter memories created before this timestamp"
-    )
-    updated_after: datetime | None = Field(
-        None, description="Filter memories updated after this timestamp"
-    )
-    updated_before: datetime | None = Field(
-        None, description="Filter memories updated before this timestamp"
-    )
-    time_range: TimeRangePreset | None = Field(
-        None, description="Relative time range filter (hour/day/week/month/year)"
-    )
-
-    @field_validator("category", mode="before")
-    @classmethod
-    def normalize_category(cls, v):
-        return _normalize_category(v)
-
-    limit: int = Field(default=10, ge=1, le=50, description="Maximum results")
-    offset: int = Field(default=0, ge=0, description="Results offset")
-    enable_overfetch: bool = Field(default=True, description="Overfetch before rerank")
-
-
-class MemoryUpdateRequest(BaseModel):
-    """Request model for updating a single memory."""
-
-    memory_id: str | None = Field(
-        None, description="Memory identifier (optional when passed via path)"
-    )
-    content: str | None = Field(None, description="Updated memory content")
-    category: MemoryCategory | None = Field(None, description="Updated category")
-    importance: ImportanceLevel | None = Field(None, description="Updated importance level")
-    metadata: dict[str, Any] | None = Field(
-        default=None, description="Metadata patch (merged over existing)"
-    )
-    tags: list[str] | None = Field(None, description="Updated tags")
-    conversation_id: str | None = Field(None, description="Conversation scope")
-    ttl_minutes: int | None = Field(
-        None, description="Optional TTL in minutes (updates expires_at)"
-    )
-    session_id: str | None = Field(None, description="Session override")
-    user_id: str | None = Field(None, description="User override")
-    team_id: str | None = Field(None, description="Team override")
-    expected_current_version_number: int | None = Field(
-        None,
-        ge=1,
-        description=(
-            "Optimistic concurrency precondition. When set, update applies only if "
-            "current_version_number matches this value."
-        ),
-    )
-
-
-class MemoryBatchUpdateRequest(BaseModel):
-    """Batch update payload for multiple memories."""
-
-    updates: list[MemoryUpdateRequest] = Field(
-        ..., min_length=1, description="List of memory updates"
-    )
-    upsert: bool = Field(
-        default=False,
-        description="If true, create memories in Mem0 when missing (Mem0 batch_update)",
-    )
-
-
-class MemoryDeleteRequest(BaseModel):
-    """Request model for deleting a single memory."""
-
-    memory_id: str = Field(..., description="Memory identifier")
-    hard_delete: bool = Field(
-        default=False,
-        description="Physically delete from Postgres/Redis instead of soft-delete",
-    )
-
-
-class MemoryBatchDeleteRequest(BaseModel):
-    """Batch delete payload."""
-
-    memory_ids: list[str] | None = Field(
-        default=None, description="Explicit list of memory IDs to delete"
-    )
-    user_id: str | None = Field(None, description="Filter by user ID")
-    session_id: str | None = Field(None, description="Filter by session ID")
-    conversation_id: str | None = Field(None, description="Filter by conversation")
-    project_domain: BusinessDomain | None = Field(None, description="Filter by project domain")
-    importance: ImportanceLevel | None = Field(None, description="Filter importance")
-    category: MemoryCategory | None = Field(None, description="Filter category")
-    tags: list[str] | None = Field(None, description="Filter tags")
-
-
-class MemoryExportCreateRequest(BaseModel):
-    """Request to create a memory export job via Mem0."""
-
-    project_id: str | None = Field(None, description="Project scope for export")
-    org_id: str | None = Field(None, description="Organization scope for export")
-    filters: dict[str, Any] | None = Field(None, description="Filters for export")
-    format: str = Field(default="jsonl", description="Export format (jsonl, csv)")
-
-
-class MemoryExportStatusResponse(BaseModel):
-    """Response for memory export status."""
-
-    export_id: str = Field(..., description="Export job identifier")
-    status: str | None = Field(None, description="Export job status")
-    url: str | None = Field(None, description="Download URL if ready")
-    detail: dict[str, Any] | None = Field(None, description="Raw status payload")
-
-
-class MemoryFeedbackRequest(BaseModel):
-    """Feedback payload for a memory."""
-
-    memory_id: str | None = Field(
-        None, description="Memory identifier (optional when passed via path)"
-    )
-    feedback: str = Field(..., description="Mem0 feedback enum POSITIVE|NEGATIVE|VERY_NEGATIVE")
-    feedback_reason: str | None = Field(None, description="Optional free-text reason")
-
-
-class SessionContextRequest(BaseModel):
-    """Request model for getting session context."""
-
-    session_id: str = Field(..., description="Session identifier")
-    include_memories: bool = Field(default=True, description="Include session memories")
-    include_operations: bool = Field(default=True, description="Include session operations")
-    include_analytics: bool = Field(default=False, description="Include analytics")
-    memory_limit: int = Field(default=20, ge=1, le=100, description="Memory limit")
-    operation_limit: int = Field(default=50, ge=1, le=200, description="Operation limit")
-
-
-class SessionContextSummary(BaseModel):
-    """Lightweight summary for session context responses."""
-
-    total_memories: int = Field(default=0, description="Total memories in session")
-    total_operations: int = Field(default=0, description="Total operations in session")
-
-
-class SessionConsolidationRequest(BaseModel):
-    """Request model for consolidating session memories."""
-
-    session_id: str = Field(..., description="Session identifier")
-    user_id: str = Field(..., description="User identifier")
-    consolidation_type: str = Field(default="summary", description="Type of consolidation")
-    include_operations: bool = Field(
-        default=True, description="Include operations in consolidation"
-    )
-    generate_insights: bool = Field(default=True, description="Generate AI insights")
-
-
-class AnalyticsRequest(BaseModel):
-    """Request model for analytics data."""
-
-    user_id: str | None = Field(None, description="User identifier (None for global)")
-    timeframe_hours: int = Field(default=24, ge=1, le=8760, description="Timeframe in hours")
-    include_sessions: bool = Field(default=True, description="Include session analytics")
-    include_memories: bool = Field(default=True, description="Include memory analytics")
-    include_operations: bool = Field(default=True, description="Include operation analytics")
-    include_patterns: bool = Field(default=True, description="Include pattern analysis")
-    group_by: str | None = Field(None, description="Group results by field")
-
-
-# Response models
-class SessionCreateResponse(BaseModel):
-    """Response model for session creation."""
-
-    success: bool = Field(..., description="Operation success")
-    session_id: str = Field(..., description="Created session ID")
-    user_id: str | None = Field(None, description="Owner user ID")
-    project_domain: BusinessDomain | None = Field(None, description="Project domain")
-    status: SessionStatus | None = Field(None, description="Session status")
-    created_at: datetime | None = Field(None, description="Session creation timestamp")
-    message: str = Field(..., description="Response message")
-    expires_at: datetime = Field(..., description="Session expiration time")
-
-
-class SessionBackupRequest(BaseModel):
-    """Request payload for creating a session backup snapshot."""
-
-    session_id: str = Field(..., description="Session identifier to back up")
-    include_memories: bool = Field(default=False, description="Include cached memory payloads")
-    include_operations: bool = Field(default=False, description="Include recent operation events")
-    memory_limit: int = Field(default=50, ge=1, le=200, description="Maximum memories to capture")
-    operation_limit: int = Field(
-        default=100, ge=10, le=1000, description="Maximum operations to capture"
-    )
-    notes: str | None = Field(None, description="Optional operator notes")
-    retention_hours: int | None = Field(
-        None, ge=1, le=720, description="Override backup retention window"
-    )
-
-
-class SessionBackupResponse(BaseModel):
-    """Response returned after creating a session backup."""
-
-    backup_id: str = Field(..., description="Backup identifier")
-    session_id: str = Field(..., description="Session that was backed up")
-    created_at: datetime = Field(..., description="Backup creation timestamp")
-    expires_at: datetime = Field(..., description="Backup expiration timestamp")
-    include_memories: bool = Field(..., description="Whether memories were captured")
-    include_operations: bool = Field(..., description="Whether operations were captured")
-    size_bytes: int = Field(..., description="Approximate serialized backup size")
-
-
-class SessionBackupSummary(BaseModel):
-    """Summary metadata used when listing backups."""
-
-    backup_id: str = Field(..., description="Backup identifier")
-    session_id: str = Field(..., description="Session identifier")
-    created_at: datetime = Field(..., description="Creation timestamp")
-    expires_at: datetime = Field(..., description="Expiration timestamp")
-    has_memories: bool = Field(..., description="Whether snapshot includes memories")
-    has_operations: bool = Field(..., description="Whether snapshot includes operations")
-    notes: str | None = Field(None, description="Operator notes")
-
-
-class SessionRestoreRequest(BaseModel):
-    """Request payload for restoring a session from backup."""
-
-    backup_id: str = Field(..., description="Source backup identifier")
-    target_session_id: str | None = Field(
-        None, description="Session ID to restore into (auto-generated if omitted)"
-    )
-    restore_mode: Literal["overwrite", "create"] = Field(
-        default="overwrite",
-        description="Overwrite existing session data or create a new session",
-    )
-    ttl_hours: int | None = Field(
-        None, ge=1, le=48, description="Override TTL for restored session"
-    )
-
-
-class SessionRestoreResponse(BaseModel):
-    """Response describing the outcome of a restore operation."""
-
-    success: bool = Field(..., description="Whether the restore succeeded")
-    restored_session_id: str = Field(..., description="Session identifier that was restored")
-    backup_id: str = Field(..., description="Backup used for restore")
-    message: str = Field(..., description="Human-readable status message")
-
-
-class SessionContextResponse(BaseModel):
-    """Response model for session context."""
-
-    session_id: str = Field(..., description="Session ID")
-    session_data: Session = Field(..., description="Session data")
-    summary: SessionContextSummary = Field(
-        default_factory=SessionContextSummary, description="Quick session summary"
-    )
-    memories: list[Memory] = Field(default_factory=list, description="Session memories")
-    operations: list[Operation] = Field(default_factory=list, description="Session operations")
-    analytics: Analytics | None = Field(None, description="Session analytics")
-    behavior: SessionBehaviorAnalytics | None = Field(
-        None, description="Detailed session behavior analytics"
-    )
-    suggested_actions: list[str] = Field(default_factory=list, description="Suggested actions")
-    patterns: list[str] = Field(default_factory=list, description="Detected patterns")
-
-    @property
-    def session(self) -> Session:
-        """Backward-compatible accessor used in older tests/callers."""
-        return self.session_data
-
-
-class MemorySearchResponse(BaseModel):
-    """Response model for memory search."""
-
-    query: str = Field(..., description="Original search query")
-    results: list[Memory] = Field(default_factory=list, description="Search results")
-    total_count: int = Field(default=0, description="Total results available")
-    limit: int = Field(..., description="Results limit")
-    offset: int = Field(..., description="Results offset")
-    search_time_ms: int | None = Field(None, description="Search time in milliseconds")
-    cached: bool = Field(default=False, description="Whether results came from cache")
-    search_mode: str | None = Field(None, description="Search backend used")
-    mem0_latency_ms: float | None = Field(None, description="Mem0 search latency in milliseconds")
-    fallback_triggered: bool = Field(default=False, description="Whether fallback search was used")
-    mem0_error: str | None = Field(None, description="Mem0 error message when fallback is used")
-    cache_hits: int | None = Field(None, description="Cache hit counter")
-    cache_misses: int | None = Field(None, description="Cache miss counter")
-    cache_writes: int | None = Field(None, description="Cache write counter")
-
-
-class TopicClusteringRequest(BaseModel):
-    """Request payload for topic clustering."""
-
-    user_id: str | None = Field(None, description="Filter by user ID")
-    session_id: str | None = Field(None, description="Filter by session ID")
-    team_id: str | None = Field(None, description="Filter by team ID")
-    project_domain: BusinessDomain | None = Field(None, description="Filter by project domain")
-    limit: int = Field(default=200, ge=10, le=1000, description="Maximum memories to cluster")
-    num_clusters: int | None = Field(
-        default=None,
-        ge=2,
-        le=50,
-        description="Number of clusters (auto if omitted)",
-    )
-    min_cluster_size: int = Field(default=3, ge=1, le=50, description="Minimum cluster size")
-    max_iterations: int = Field(default=50, ge=5, le=200, description="Max k-means iterations")
-    include_noise: bool = Field(
-        default=False, description="Include small/noise clusters in response"
-    )
-
-
-class TopicCluster(BaseModel):
-    """Topic cluster representation."""
-
-    cluster_id: int = Field(..., description="Cluster identifier")
-    size: int = Field(..., description="Number of memories in the cluster")
-    keywords: list[str] = Field(default_factory=list, description="Cluster keywords")
-    memory_ids: list[str] = Field(default_factory=list, description="Memory IDs in the cluster")
-    sample_memories: list[str] = Field(default_factory=list, description="Sample memory snippets")
-
-
-class TopicClusteringResponse(BaseModel):
-    """Response payload for topic clustering."""
-
-    total_memories: int = Field(..., description="Total memories considered")
-    cluster_count: int = Field(..., description="Number of clusters returned")
-    unclustered_count: int = Field(
-        default=0, description="Memories not assigned to output clusters"
-    )
-    algorithm: str = Field(default="kmeans", description="Clustering algorithm used")
-    generated_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC),
-        description="Cluster generation timestamp",
-    )
-    clusters: list[TopicCluster] = Field(default_factory=list, description="Cluster definitions")
-
-
-class ConsolidationResponse(BaseModel):
-    """Response model for session consolidation."""
-
-    success: bool = Field(..., description="Operation success")
-    session_id: str = Field(..., description="Session ID")
-    consolidation_id: str | None = Field(None, description="Consolidation run identifier")
-    consolidated_memory_id: str | None = Field(None, description="ID of consolidated memory")
-    summary: str = Field(..., description="Consolidation summary")
-    insights: list[str] = Field(default_factory=list, description="Generated insights")
-    metrics: dict[str, Any] = Field(
-        default_factory=dict, description="Consolidation metrics/results"
-    )
-    processing_time_ms: int | None = Field(None, description="Processing time in milliseconds")
-
-
-class HealthResponse(BaseModel):
-    """Response model for health check."""
-
-    status: str = Field(..., description="Service status")
-    service_name: str = Field(..., description="Service name")
-    version: str = Field(..., description="Service version")
-    timestamp: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Health check timestamp"
-    )
-    components: dict[str, Any] = Field(default_factory=dict, description="Component health status")
-    uptime_seconds: int | None = Field(None, description="Service uptime in seconds")
-    metrics: dict[str, Any] = Field(default_factory=dict, description="Service metrics")
-
-
-# Team Collaboration Models
-class TeamMemoryAccessLevel(StrEnum):
-    """Team memory access levels."""
-
-    READ_ONLY = "read_only"
-    READ_WRITE = "read_write"
-    ADMIN = "admin"
-    OWNER = "owner"
-
-
-class TeamMemoryShare(BaseModel):
-    """Team memory sharing configuration."""
-
-    memory_id: str = Field(..., description="Memory ID to share")
-    team_id: str = Field(..., description="Team ID to share with")
-    access_level: TeamMemoryAccessLevel = Field(
-        default=TeamMemoryAccessLevel.READ_ONLY, description="Access level for team"
-    )
-    shared_by: str = Field(..., description="User who shared the memory")
-    shared_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Share timestamp"
-    )
-    expires_at: datetime | None = Field(None, description="Share expiration")
-    permissions: list[str] = Field(default_factory=list, description="Additional permissions")
-
-
-class TeamInsightRequest(BaseModel):
-    """Request model for generating team insights."""
-
-    team_id: str = Field(..., description="Team ID")
-    user_id: str = Field(..., description="Requesting user ID")
-    insight_types: list[str] = Field(
-        default_factory=lambda: ["patterns", "knowledge_gaps", "collaboration"],
-        description="Types of insights to generate",
-    )
-    timeframe_hours: int = Field(
-        default=168, ge=1, le=8760, description="Timeframe in hours (default 1 week)"
-    )
-    include_anonymous: bool = Field(default=False, description="Include anonymous contributions")
-    focus_areas: list[str] = Field(default_factory=list, description="Specific areas to focus on")
-
-
-class TeamInsightResponse(BaseModel):
-    """Response model for team insights."""
-
-    team_id: str = Field(..., description="Team ID")
-    insights_generated_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Generation timestamp"
-    )
-    insights: dict[str, Any] = Field(..., description="Generated insights by type")
-    summary: str = Field(..., description="Executive summary")
-    recommendations: list[str] = Field(
-        default_factory=list, description="Actionable recommendations"
-    )
-    collaboration_metrics: dict[str, float] = Field(
-        default_factory=dict, description="Collaboration metrics"
-    )
-    knowledge_gaps: list[str] = Field(default_factory=list, description="Identified knowledge gaps")
-    top_contributors: list[dict[str, Any]] = Field(
-        default_factory=list, description="Top contributors"
-    )
-    processing_time_ms: int | None = Field(None, description="Processing time")
-
-
-class TeamMemorySynthesisRequest(BaseModel):
-    """Request model for synthesizing team memories."""
-
-    team_id: str = Field(..., description="Team ID")
-    user_id: str = Field(..., description="Requesting user ID")
-    synthesis_type: str = Field(
-        default="summary", description="Type of synthesis: summary, analysis, insights"
-    )
-    focus_query: str | None = Field(None, description="Specific focus for synthesis")
-    include_personal: bool = Field(default=True, description="Include personal memories")
-    timeframe_hours: int = Field(default=168, ge=1, le=8760, description="Timeframe in hours")
-    max_memories: int = Field(
-        default=100, ge=10, le=1000, description="Maximum memories to synthesize"
-    )
-
-
-class TeamMemorySynthesisResponse(BaseModel):
-    """Response model for team memory synthesis."""
-
-    team_id: str = Field(..., description="Team ID")
-    synthesis_type: str = Field(..., description="Type of synthesis performed")
-    synthesis: str = Field(..., description="Generated synthesis")
-    key_points: list[str] = Field(default_factory=list, description="Key points extracted")
-    action_items: list[str] = Field(default_factory=list, description="Recommended action items")
-    related_memories: list[str] = Field(default_factory=list, description="Related memory IDs")
-    confidence_score: float = Field(..., description="Confidence in synthesis quality")
-    contributors: list[str] = Field(default_factory=list, description="Contributing users")
-    processing_time_ms: int | None = Field(None, description="Processing time")
-    synthesized_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Synthesis timestamp"
-    )
-
-
-class SessionShareAccessLevel(StrEnum):
-    """Access levels for shared sessions."""
-
-    VIEW = "view"
-    CONTRIBUTE = "contribute"
-    MANAGE = "manage"
-
-
-class SessionShareRequest(BaseModel):
-    """Request payload for sharing a session."""
-
-    session_id: str = Field(..., description="Session identifier")
-    target_user_id: str | None = Field(None, description="Recipient user ID")
-    target_team_id: str | None = Field(None, description="Recipient team ID")
-    access_level: SessionShareAccessLevel = Field(
-        default=SessionShareAccessLevel.VIEW, description="Granted access level"
-    )
-    expires_at: datetime | None = Field(None, description="Optional expiration timestamp")
-    notes: str | None = Field(None, description="Optional share note")
-    granted_by: str = Field(..., description="User initiating the share")
-
-    @field_validator("target_user_id")
-    @classmethod
-    def validate_target(cls, user_id, info):
-        team_id = info.data.get("target_team_id")
-        if not user_id and not team_id:
-            raise ValueError("Provide target_user_id or target_team_id")
-        if user_id and team_id:
-            raise ValueError("Specify only one of target_user_id or target_team_id")
-        return user_id
-
-
-class SessionShareResponse(BaseModel):
-    """Response describing a session share entry."""
-
-    share_id: str = Field(..., description="Share record identifier")
-    session_id: str = Field(..., description="Shared session ID")
-    access_level: SessionShareAccessLevel = Field(..., description="Access level")
-    target_user_id: str | None = Field(None, description="Recipient user ID")
-    target_team_id: str | None = Field(None, description="Recipient team ID")
-    granted_by: str = Field(..., description="User granting access")
-    granted_at: datetime = Field(..., description="Grant timestamp")
-    expires_at: datetime | None = Field(None, description="Expiration timestamp")
-    notes: str | None = Field(None, description="Operator notes")
-
-
-class SessionShareListEntry(SessionShareResponse):
-    """Entry returned when listing sessions shared with a user/team."""
-
-    session_summary: str | None = Field(None, description="Optional session description")
-
-
-class SessionPerformanceMetrics(BaseModel):
-    """Performance metrics for a single session."""
-
-    session_id: str = Field(..., description="Session identifier")
-    timeframe_hours: int = Field(..., description="Hours evaluated")
-    total_operations: int = Field(default=0, description="Operations in timeframe")
-    success_count: int = Field(default=0, description="Successful operations")
-    failure_count: int = Field(default=0, description="Failed operations")
-    success_rate: float = Field(default=0.0, description="Success ratio (0-1)")
-    average_duration_ms: float = Field(default=0.0, description="Average operation duration")
-    p95_duration_ms: float = Field(default=0.0, description="95th percentile duration")
-    ops_per_minute: float = Field(default=0.0, description="Throughput per minute")
-    last_operation_at: datetime | None = Field(
-        None, description="Timestamp of the most recent operation"
-    )
-
-
-class SessionPerformanceSummary(BaseModel):
-    """Aggregated performance metrics across sessions."""
-
-    timeframe_hours: int = Field(..., description="Hours evaluated")
-    sessions_evaluated: int = Field(..., description="Number of sessions considered")
-    total_operations: int = Field(..., description="Total operations across sessions")
-    average_success_rate: float = Field(
-        default=0.0, description="Mean success rate across sessions"
-    )
-    p95_duration_ms: float = Field(default=0.0, description="Aggregated p95 duration")
-    busiest_session_id: str | None = Field(None, description="Session with highest throughput")
-    peak_ops_per_minute: float = Field(default=0.0, description="Highest ops/min observed")
-
-
-# Storage Strategy Models
-class StorageDecisionRecord(BaseModel):
-    """Record of storage tier decision for tracking and analytics."""
-
-    decision_id: str = Field(..., description="Unique decision identifier")
-    memory_id: str = Field(..., description="Memory ID the decision was made for")
-    session_id: str = Field(..., description="Session ID when decision was made")
-    selected_tier: StorageTier = Field(..., description="Selected storage tier")
-    confidence_score: float = Field(..., ge=0.0, le=1.0, description="Decision confidence")
-    processing_time_ms: float = Field(..., description="Decision processing time")
-    rules_evaluated: list[str] = Field(..., description="Rules that were evaluated")
-    matching_rules: list[str] = Field(..., description="Rules that matched")
-    reasoning: str = Field(..., description="Decision reasoning")
-    memory_features: dict[str, Any] = Field(..., description="Memory features at decision time")
-    created_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Decision timestamp"
-    )
-
-
-class ConsolidationEvent(BaseModel):
-    """Memory consolidation event tracking."""
-
-    event_id: str = Field(..., description="Unique event identifier")
-    operation_id: str = Field(..., description="Consolidation operation ID")
-    consolidation_type: str = Field(..., description="Type of consolidation")
-    source_memory_ids: list[str] = Field(..., description="Source memory IDs")
-    target_memory_id: str | None = Field(None, description="Target memory ID (if merge)")
-    confidence_score: float = Field(..., ge=0.0, le=1.0, description="Consolidation confidence")
-    similarity_scores: dict[str, float] = Field(
-        default_factory=dict, description="Similarity scores between memories"
-    )
-    processing_time_ms: float = Field(..., description="Consolidation processing time")
-    status: str = Field(default="pending", description="Event status")
-    result: str | None = Field(None, description="Consolidation result")
-    error_message: str | None = Field(None, description="Error if consolidation failed")
-    created_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Event timestamp"
-    )
-    completed_at: datetime | None = Field(None, description="Completion timestamp")
-
-
-class StoragePerformanceMetrics(BaseModel):
-    """Performance metrics for storage tiers."""
-
-    tier: StorageTier = Field(..., description="Storage tier")
-    timeframe_start: datetime = Field(..., description="Metrics timeframe start")
-    timeframe_end: datetime = Field(..., description="Metrics timeframe end")
-
-    # Performance metrics
-    total_operations: int = Field(default=0, description="Total storage operations")
-    average_processing_time_ms: float = Field(default=0.0, description="Average processing time")
-    success_rate: float = Field(default=1.0, description="Operation success rate")
-    cache_hit_rate: float = Field(default=0.0, description="Cache hit rate")
-
-    # Storage metrics
-    total_memories_stored: int = Field(default=0, description="Total memories stored")
-    storage_size_bytes: int = Field(default=0, description="Storage size in bytes")
-    retrieval_count: int = Field(default=0, description="Number of retrievals")
-    average_retrieval_time_ms: float = Field(default=0.0, description="Average retrieval time")
-
-    # Cost metrics
-    cost_per_operation: float = Field(default=0.0, description="Cost per operation")
-    total_cost: float = Field(default=0.0, description="Total cost for timeframe")
-
-    # Quality metrics
-    classification_accuracy: float = Field(default=0.0, description="Classification accuracy")
-    consolidation_efficiency: float = Field(default=0.0, description="Consolidation efficiency")
-    user_satisfaction: float | None = Field(None, description="User satisfaction score")
-
-
-class ContentAnalysisResult(BaseModel):
-    """Result of content analysis for memory classification."""
-
-    analysis_id: str = Field(..., description="Unique analysis identifier")
-    memory_id: str = Field(..., description="Memory ID analyzed")
-    content_length: int = Field(..., description="Content length")
-    word_count: int = Field(..., description="Word count")
-
-    # Pattern matches
-    has_solution_pattern: bool = Field(default=False, description="Solution pattern detected")
-    has_decision_pattern: bool = Field(default=False, description="Decision pattern detected")
-    has_code_pattern: bool = Field(default=False, description="Code pattern detected")
-    has_question_pattern: bool = Field(default=False, description="Question pattern detected")
-
-    # Content scores
-    readability_score: float = Field(default=0.0, description="Readability score")
-    complexity_score: float = Field(default=0.0, description="Content complexity score")
-    uniqueness_score: float = Field(default=0.0, description="Content uniqueness score")
-    semantic_importance: float = Field(default=0.0, description="Semantic importance score")
-
-    # Analysis metadata
-    processing_tier: str = Field(..., description="Processing tier used")
-    processing_time_ms: float = Field(..., description="Analysis processing time")
-    semantic_features: dict[str, Any] = Field(
-        default_factory=dict, description="Semantic features extracted"
-    )
-    consolidation_candidates: int = Field(
-        default=0, description="Number of consolidation candidates found"
-    )
-    created_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Analysis timestamp"
-    )
-
-
-# Configuration and utility models
-class ServiceConfiguration(BaseModel):
-    """Service configuration model."""
-
-    service_name: str = "VDS AI Memory Service"
-    version: str = "1.0.0"
-    environment: str = "development"
-    debug: bool = False
-
-    # API configuration
-    api_host: str = "0.0.0.0"
-    api_port: int = 8000
-    api_prefix: str = "/api/v1"
-
-    # Feature flags
-    enable_mem0_pro: bool = False
-    enable_mcp_server: bool = True
-    enable_analytics: bool = True
-    enable_storage_strategy: bool = True
-    enable_content_analysis: bool = True
-    enable_consolidation: bool = True
-
-    # Performance settings
-    default_session_ttl_hours: int = 1
-    max_sessions_per_user: int = 10
-    cache_ttl_minutes: int = 5
-    max_background_tasks: int = 100
-
-    # Storage strategy settings
-    storage_rules_config_path: str = "config/rules/storage_rules.yaml"
-    classification_latency_target_ms: float = 1.0
-    classification_accuracy_target: float = 0.999
-    consolidation_batch_size: int = 50
-    consolidation_interval_minutes: int = 60
-    shadow_mode_enabled: bool = True
-
-
-# Request Models for API Endpoints
-class SessionCreateRequest(BaseModel):
-    """Request model for session creation."""
-
-    user_id: str = Field(..., description="User identifier")
-    project_domain: BusinessDomain = Field(..., description="Business domain")
-    context: str | None = Field(None, description="Session context")
-    working_directory: str | None = Field(None, description="Working directory")
-    git_branch: str | None = Field(None, description="Git branch")
-    git_repository: str | None = Field(None, description="Git repository URL")
-    environment: SessionEnvironment = Field(
-        default=SessionEnvironment.DEVELOPMENT, description="Session environment"
-    )
-    ttl_hours: int = Field(default=1, ge=1, le=24, description="Session TTL in hours")
-    preferences: dict[str, Any] = Field(default_factory=dict, description="User preferences")
-    metadata: dict[str, Any] = Field(
-        default_factory=dict, description="Additional session metadata"
-    )
-    template_id: str | None = Field(None, description="Template identifier used for creation")
-    template_name: str | None = Field(None, description="Template display name used for creation")
-    context_tags: list[str] = Field(default_factory=list, description="Pre-supplied context tags")
-    key_tasks: list[str] = Field(default_factory=list, description="Current key tasks")
-
-    @field_validator("project_domain", mode="before")
-    @classmethod
-    def validate_project_domain(cls, v):
-        """Handle string to BusinessDomain conversion."""
-        if isinstance(v, str):
-            try:
-                return BusinessDomain(v.upper())
-            except ValueError:
-                # Fallback to GENERAL if invalid
-                return BusinessDomain.GENERAL
-        return v
-
-
-class SessionTemplateMetadata(BaseModel):
-    """Metadata describing a reusable session preset."""
-
-    template_id: str = Field(..., description="Template identifier")
-    name: str = Field(..., description="Template display name")
-    description: str = Field(..., description="What the template configures")
-    project_domain: BusinessDomain = Field(..., description="Default business domain")
-    environment: SessionEnvironment = Field(
-        default=SessionEnvironment.DEVELOPMENT, description="Default environment"
-    )
-    ttl_hours: int = Field(1, ge=1, le=24, description="Default TTL in hours")
-    context: str | None = Field(None, description="Default session context")
-    working_directory: str | None = Field(None, description="Default working directory")
-    git_branch: str | None = Field(None, description="Default Git branch")
-    git_repository: str | None = Field(None, description="Default Git repository")
-    default_preferences: dict[str, Any] = Field(
-        default_factory=dict, description="Preferences applied when instantiating"
-    )
-    default_metadata: dict[str, Any] = Field(
-        default_factory=dict, description="Metadata applied when instantiating"
-    )
-
-
-class SessionTemplateInstantiateRequest(BaseModel):
-    """Request payload for instantiating a session template."""
-
-    user_id: str = Field(..., description="User identifier")
-    project_domain: BusinessDomain | None = Field(None, description="Override domain")
-    environment: SessionEnvironment | None = Field(None, description="Override environment")
-    context: str | None = Field(None, description="Context override")
-    working_directory: str | None = Field(None, description="Working directory override")
-    git_branch: str | None = Field(None, description="Git branch override")
-    git_repository: str | None = Field(None, description="Git repository override")
-    ttl_hours: int | None = Field(None, ge=1, le=24, description="TTL override")
-    preferences: dict[str, Any] = Field(default_factory=dict, description="Preference overrides")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Metadata overrides")
-
-
-class SessionContextRequest(BaseModel):
-    """Request model for session context retrieval."""
-
-    session_id: str = Field(..., description="Session identifier")
-    include_memories: bool = Field(default=True, description="Include memories")
-    include_operations: bool = Field(default=True, description="Include operations")
-    include_analytics: bool = Field(default=True, description="Include analytics")
-    memory_limit: int = Field(default=50, ge=1, le=200, description="Memory limit")
-    operation_limit: int = Field(default=100, ge=1, le=500, description="Operation limit")
-
-
-class SessionConsolidationRequest(BaseModel):
-    """Request model for session consolidation."""
-
-    session_id: str = Field(..., description="Session identifier")
-    user_id: str = Field(..., description="User identifier")
-    consolidation_strategy: str = Field(default="auto", description="Consolidation strategy")
-    include_all_memories: bool = Field(default=True, description="Include all memories")
-    summary_length: int = Field(default=500, ge=100, le=2000, description="Summary length")
-    generate_insights: bool = Field(default=True, description="Generate insights")
-
-
-class AnalyticsRequest(BaseModel):
-    """Request model for analytics retrieval."""
-
-    user_id: str | None = Field(None, description="User identifier (optional for global analytics)")
-    timeframe_hours: int = Field(default=24, ge=1, le=8760, description="Timeframe in hours")
-    include_sessions: bool = Field(default=True, description="Include session analytics")
-    include_memories: bool = Field(default=True, description="Include memory analytics")
-    include_operations: bool = Field(default=True, description="Include operation analytics")
-    include_patterns: bool = Field(default=True, description="Include pattern analysis")
-    group_by: str | None = Field(None, description="Group results by field")
-
-
-class CacheWarmupRequest(BaseModel):
-    """Request model for cache warmup."""
-
-    user_id: str = Field(..., description="User identifier")
-    session_count: int = Field(default=5, ge=1, le=20, description="Number of recent sessions")
-    memory_count: int = Field(default=50, ge=10, le=200, description="Number of recent memories")
-    include_analytics: bool = Field(default=True, description="Include analytics cache")
-
-
-class CacheInvalidationRequest(BaseModel):
-    """Request model for cache invalidation."""
-
-    session_id: str = Field(..., description="Session identifier")
-    invalidate_memories: bool = Field(default=True, description="Invalidate memory cache")
-    invalidate_operations: bool = Field(default=True, description="Invalidate operation cache")
-    invalidate_analytics: bool = Field(default=True, description="Invalidate analytics cache")
-
-
-# ============================================================================
-# MEMORY VERSIONING MODELS (Phase 2.1.1)
-# ============================================================================
-
-
-class MemoryVersion(BaseModel):
-    """Represents an immutable version of a memory."""
-
-    # Core identification
-    version_id: str = Field(..., description="Unique version identifier")
-    memory_id: str = Field(..., description="Parent memory identifier")
-    version_number: int = Field(..., description="Sequential version number per memory")
-
-    # Version content (immutable snapshot)
-    content: str = Field(..., description="Memory content at this version")
-    category: MemoryCategory = Field(..., description="Memory category at this version")
-    importance: ImportanceLevel = Field(..., description="Importance level at this version")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Version-specific metadata")
-
-    # Version management
-    is_active: bool = Field(default=False, description="Whether this is the active version")
-    created_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Version creation time"
-    )
-    created_by: str | None = Field(None, description="User who created this version")
-    change_reason: str | None = Field(None, description="Reason for this version")
-    parent_version_id: str | None = Field(None, description="Parent version this was created from")
-
-    # Performance tracking
-    content_size_bytes: int = Field(default=0, description="Size of content in bytes")
-    processing_time_ms: float = Field(default=0.0, description="Time taken to create this version")
-
-
-class MemoryVersioningRequest(BaseModel):
-    """Request model for creating a new memory version."""
-
-    memory_id: str | None = Field(
-        None, description="Memory identifier to version (filled by router)"
-    )
-    change_reason: str = Field(..., description="Reason for creating this version")
-    content_update: str | None = Field(None, description="Updated content if any")
-    metadata_updates: dict[str, Any] = Field(default_factory=dict, description="Metadata updates")
-    category_update: MemoryCategory | None = Field(None, description="Category update")
-    importance_update: ImportanceLevel | None = Field(None, description="Importance update")
-    auto_increment: bool = Field(default=True, description="Auto-increment version number")
-
-
-class MemoryRollbackRequest(BaseModel):
-    """Request model for rolling back to a previous memory version."""
-
-    memory_id: str | None = Field(
-        None, description="Memory identifier to rollback (filled by router)"
-    )
-    target_version_number: int = Field(..., description="Target version number to rollback to")
-    rollback_reason: str = Field(..., description="Reason for rollback")
-    create_backup_version: bool = Field(
-        default=True, description="Create backup version before rollback"
-    )
-
-
-class MemoryVersionHistory(BaseModel):
-    """Response model for memory version history."""
-
-    memory_id: str = Field(..., description="Memory identifier")
-    total_versions: int = Field(..., description="Total number of versions")
-    current_version_number: int = Field(..., description="Current active version number")
-    versions: list[MemoryVersion] = Field(..., description="All versions for this memory")
-
-    # Statistics
-    average_version_size: float = Field(..., description="Average version size in bytes")
-    total_storage_used: int = Field(..., description="Total storage used by all versions")
-    creation_frequency: float = Field(..., description="Versions created per day")
-
-    # Tracking
-    first_version_created: datetime | None = Field(None, description="First version creation time")
-    last_version_created: datetime | None = Field(None, description="Last version creation time")
-
-
-class MemoryVersionComparison(BaseModel):
-    """Comparison between two memory versions."""
-
-    base_version: MemoryVersion = Field(..., description="Base version for comparison")
-    target_version: MemoryVersion = Field(..., description="Target version for comparison")
-
-    # Comparison results
-    content_changes: bool = Field(default=False, description="Content has changes")
-    metadata_changes: dict[str, Any] = Field(default_factory=dict, description="Metadata changes")
-    category_change: bool = Field(default=False, description="Category has changed")
-    importance_change: bool = Field(default=False, description="Importance has changed")
-
-    # Detailed analysis
-    content_similarity: float = Field(default=1.0, description="Content similarity score (0-1)")
-    change_summary: str = Field(default="", description="Summary of changes")
-    significant_changes: list[str] = Field(
-        default_factory=list, description="List of significant changes"
-    )
-
-
-class RollbackResponse(BaseModel):
-    """Response for memory rollback operations."""
-
-    success: bool = Field(..., description="Whether the rollback was successful")
-    message: str = Field(..., description="Response message")
-    memory_id: str = Field(..., description="ID of the memory that was rolled back")
-    restored_version: MemoryVersion = Field(..., description="Restored target version")
-    backup_version_id: str | None = Field(
-        None, description="Backup version created before rollback"
-    )
-    rollback_timestamp: datetime = Field(..., description="Timestamp of the rollback operation")
-
-
-class VersioningResponse(BaseModel):
-    """Response for memory versioning operations."""
-
-    success: bool = Field(..., description="Whether the operation was successful")
-    message: str = Field(..., description="Response message")
-    memory_id: str = Field(..., description="ID of the memory")
-    version_id: str = Field(..., description="ID of the created/referenced version")
-    operation: str = Field(..., description="Type of operation performed")
-    timestamp: datetime = Field(..., description="Timestamp of the operation")