@ngocsangairvds/vsaf 3.2.15 → 4.0.0

package/tools/vds-scripts/memory_orchestrator/src/vds_memory_orchestrator/service/database/postgres_manager.py

@@ -1,1897 +0,0 @@
-"""
-PostgreSQL Database Manager for VDS AI Memory Service
-Enhanced with pgvector 0.8.1 support for vector search operations
-
-Phase 2: PostgreSQL+pgvector Deployment
-Task POSTGRES-001: PostgreSQL Cluster Setup with pgvector 0.8.1
-"""
-
-import hashlib
-import json
-import logging
-import os
-from collections.abc import AsyncGenerator
-from contextlib import asynccontextmanager
-from datetime import UTC, datetime
-from typing import Any
-from uuid import UUID as PyUUID
-from uuid import uuid4
-
-import asyncpg
-from sqlalchemy import text
-from sqlalchemy.exc import OperationalError
-from sqlalchemy.ext.asyncio import (
-    AsyncEngine,
-    AsyncSession,
-    async_sessionmaker,
-    create_async_engine,
-)
-from sqlalchemy.pool import NullPool
-
-from vds_memory_orchestrator.service.core.ai_memory_exceptions import MemoryRevisionConflictError
-from vds_memory_orchestrator.service.core.config import get_config
-from vds_memory_orchestrator.service.models.ai_memory_models import (
-    ImportanceLevel,
-    Memory,
-    MemoryCategory,
-    MemoryStatus,
-    MemoryVersion,
-)
-from vds_memory_orchestrator.service.services.storage_strategy import StorageTier
-
-logger = logging.getLogger(__name__)
-
-_VEC_DIM = int(os.getenv("EMBEDDING_DIMENSION", "1024"))
-
-
-class PostgreSQLConnectionManager:
-    """
-    PostgreSQL connection manager with pgvector 0.8.1 support
-
-    Features:
-    - Connection pooling with health monitoring
-    - pgvector extension management
-    - Vector search operations with HNSW indexing
-    - Knowledge base schema management
-    """
-
-    def __init__(self):
-        self.engine: AsyncEngine = None
-        self.async_session = None
-        self._connection_pool = None
-        self.config = get_config()
-        self._initialized = False
-        self._pgvector_enabled = False
-        self._connection_targets: list[dict[str, str]] = []
-        self._active_target_index: int | None = None
-        self._use_null_pool: bool = False
-        self._pool_settings: dict[str, int] | None = None
-        self.query_stats = {
-            "count": 0,
-            "total_ms": 0.0,
-            "slow_queries": 0,
-            "threshold_ms": 200.0,
-        }
-
-    async def initialize(self):
-        """Initialize PostgreSQL connection pool with pgvector setup"""
-        if self._initialized:
-            return
-
-        try:
-            self._connection_targets = self._build_connection_targets()
-            if not self._connection_targets:
-                raise RuntimeError("No PostgreSQL connection targets configured")
-
-            self._use_null_pool = self.config.service.debug and not getattr(
-                self.config.database, "force_pooling_in_debug", False
-            )
-            if not self._use_null_pool:
-                self._pool_settings = self._calculate_pool_settings()
-
-            last_error: Exception | None = None
-            for idx, target in enumerate(self._connection_targets):
-                try:
-                    await self._initialize_target_engine(target)
-                    self._active_target_index = idx
-                    self._initialized = True
-                    logger.info(
-                        "PostgreSQL connection established via %s (%s)",
-                        target["label"],
-                        target.get("display"),
-                    )
-                    break
-                except Exception as exc:
-                    last_error = exc
-                    logger.exception(
-                        "Failed to initialize PostgreSQL target %s (%s): %s",
-                        target["label"],
-                        target.get("display"),
-                        exc,
-                    )
-                    await self._dispose_engine()
-
-            if not self._initialized:
-                raise last_error or RuntimeError("Unable to initialize any PostgreSQL target")
-
-        except Exception as e:
-            logger.exception(f"Failed to initialize PostgreSQL connection manager: {e}")
-            raise
-
-    def _build_connection_targets(self) -> list[dict[str, str]]:
-        """Assemble primary and failover connection targets."""
-        targets: list[dict[str, str]] = [
-            {
-                "label": "primary",
-                "role": "primary",
-                "url": self.config.postgres_url,
-                "display": f"{self.config.database.postgres_host}:{self.config.database.postgres_port}",
-            }
-        ]
-
-        for idx, failover in enumerate(self.config.postgres_failover_targets, start=1):
-            targets.append(
-                {
-                    "label": f"failover-{idx}",
-                    "role": "failover",
-                    "url": str(failover["url"]),
-                    "display": str(failover.get("display") or failover["url"]),
-                }
-            )
-        return targets
-
-    async def _initialize_target_engine(self, target: dict[str, str]) -> None:
-        """Create engine/session for the provided target."""
-        await self._dispose_engine()
-        self.engine = self._create_engine_for_url(target["url"])
-        self.async_session = async_sessionmaker(
-            self.engine,
-            class_=AsyncSession,
-            expire_on_commit=False,
-            autoflush=False,
-            autocommit=False,
-        )
-
-        # Test connection and setup pgvector for this target
-        await self._test_connection()
-        await self._setup_pgvector()
-        await self._create_vector_schema()
-        self._pgvector_enabled = True
-
-    @staticmethod
-    def _resolve_echo() -> bool:
-        """Resolve SQLAlchemy echo flag from env vars.
-
-        Primary:  VDS_DB_ECHO=true
-        Fallback: SQLALCHEMY_ECHO=true  (legacy alias, kept for backwards compat)
-        Default:  False (silent in all environments)
-        """
-        return os.getenv("VDS_DB_ECHO", os.getenv("SQLALCHEMY_ECHO", "false")).lower() == "true"
-
-    def _create_engine_for_url(self, database_url: str) -> AsyncEngine:
-        """Create an async engine for the provided DSN.
-
-        Post-P8 (v2.15.8+): SQLAlchemy `connect` event listener runs
-        `SET search_path TO memory, public` immediately after every asyncpg
-        connection establishes, BEFORE the first user query. This is the
-        only mechanism robust to PgBouncer backend reuse:
-
-        - PgBouncer's per-stanza `connect_query` only fires at backend SPAWN,
-          not on backend reuse.
-        - asyncpg's `server_settings` (via StartupMessage) is also only
-          forwarded to the backend at SPAWN — for reused backends, the
-          StartupMessage is never re-sent.
-        - `server_reset_query=DISCARD ALL` resets session state (including
-          search_path) to system default `"$user", public` between PgBouncer
-          client checkouts in session mode.
-        - The `connect` event fires AFTER PgBouncer hands a backend to the
-          asyncpg client — that's a regular SQL channel that reaches whatever
-          backend is currently held. Session mode then preserves the SET for
-          the asyncpg connection's lifetime.
-
-        Without this, unqualified DML against the `memory` schema (e.g.,
-        `SELECT FROM memory_evolution_events`) intermittently fails on reused
-        backends with `UndefinedTableError: relation does not exist`.
-        """
-        from sqlalchemy import event
-
-        echo = self._resolve_echo()
-        if self._use_null_pool:
-            engine = create_async_engine(
-                database_url,
-                echo=echo,
-                poolclass=NullPool,
-            )
-        else:
-            pool_settings = self._pool_settings or self._calculate_pool_settings()
-            logger.info(
-                "PostgreSQL connection pool configured (size=%d, overflow=%d, timeout=%ds)",
-                pool_settings["pool_size"],
-                pool_settings["max_overflow"],
-                pool_settings["pool_timeout"],
-            )
-            engine = create_async_engine(
-                database_url,
-                pool_size=pool_settings["pool_size"],
-                max_overflow=pool_settings["max_overflow"],
-                pool_timeout=pool_settings["pool_timeout"],
-                pool_pre_ping=True,
-                pool_recycle=pool_settings["pool_recycle"],
-                echo=echo,
-            )
-
-        @event.listens_for(engine.sync_engine, "connect")
-        def _set_search_path(dbapi_conn, _connection_record):
-            cursor = dbapi_conn.cursor()
-            cursor.execute("SET search_path TO memory, public")
-            cursor.close()
-
-        return engine
-
-    async def _dispose_engine(self) -> None:
-        """Dispose the current engine/session if present."""
-        if self.engine:
-            await self.engine.dispose()
-        self.engine = None
-        self.async_session = None
-        self._pgvector_enabled = False
-
-    async def _test_connection(self):
-        """Test database connection and version compatibility"""
-        try:
-            async with self.engine.begin() as conn:
-                # Test basic connectivity
-                await conn.execute(text("SELECT 1"))
-
-                # Check PostgreSQL version (target: PostgreSQL 18)
-                version_result = await conn.execute(
-                    text("""
-                    SELECT version() as pg_version
-                """)
-                )
-                pg_version = version_result.scalar()
-                logger.debug(f"PostgreSQL version: {pg_version}")
-
-                logger.debug("PostgreSQL connection test successful")
-        except Exception as e:
-            logger.exception(f"PostgreSQL connection test failed: {e}")
-            raise
-
-    async def _setup_pgvector(self):
-        """Setup and verify pgvector 0.8.1 extension"""
-        try:
-            async with self.engine.begin() as conn:
-                # Check if pgvector extension exists
-                result = await conn.execute(
-                    text("""
-                    SELECT 1 FROM pg_extension WHERE extname = 'vector'
-                """)
-                )
-
-                if not result.scalar():
-                    # Install pgvector extension
-                    logger.info("Installing pgvector extension...")
-                    await conn.execute(text("CREATE EXTENSION IF NOT EXISTS vector"))
-                    logger.info("pgvector extension installed successfully")
-                else:
-                    # Check pgvector version
-                    version_result = await conn.execute(
-                        text("""
-                        SELECT extversion FROM pg_extension WHERE extname = 'vector'
-                    """)
-                    )
-                    pgvector_version = version_result.scalar()
-                    logger.info(f"pgvector extension found, version: {pgvector_version}")
-
-                # Verify pgvector functionality with a simple test
-                test_result = await conn.execute(
-                    text("""
-                    SELECT '[1,2,3]'::vector <-> '[1,2,4]'::vector as distance
-                """)
-                )
-                distance = test_result.scalar()
-                logger.info(f"pgvector functionality verified - test distance: {distance}")
-
-                self._pgvector_enabled = True
-                logger.info("✅ pgvector extension setup completed successfully")
-
-        except Exception as e:
-            logger.exception(f"Failed to setup pgvector extension: {e}")
-            logger.exception(f"pgvector setup error details: {type(e).__name__}: {str(e)}")
-            self._pgvector_enabled = False
-            # Don't raise - allow service to continue without pgvector
-            logger.warning("⚠️ Continuing without pgvector vector functionality")
-
-    async def _create_vector_schema(self):
-        """Create vector database schema for knowledge base"""
-        try:
-            async with self.engine.begin() as conn:
-                # Create knowledge base tables with vector support
-
-                # Documents table with embeddings
-                await conn.execute(
-                    text(f"""
-                    CREATE TABLE IF NOT EXISTS knowledge_documents (
-                        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-                        title TEXT NOT NULL,
-                        content TEXT NOT NULL,
-                        metadata JSONB DEFAULT '{{}}',
-                        embedding vector({_VEC_DIM}),
-                        user_id VARCHAR(255) NOT NULL,
-                        team_id VARCHAR(255),
-                        created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-                        updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-                        access_count INTEGER DEFAULT 0
-                    )
-                """)
-                )
-
-                # Create HNSW index for vector search
-                await conn.execute(
-                    text("""
-                    CREATE INDEX IF NOT EXISTS idx_knowledge_documents_embedding_hnsw
-                    ON knowledge_documents USING hnsw (embedding vector_cosine_ops)
-                    WITH (m = 16, ef_construction = 64)
-                """)
-                )
-
-                # Create additional indexes for efficient filtering
-                await conn.execute(
-                    text("""
-                    CREATE INDEX IF NOT EXISTS idx_knowledge_documents_user_id
-                    ON knowledge_documents (user_id)
-                """)
-                )
-
-                await conn.execute(
-                    text("""
-                    CREATE INDEX IF NOT EXISTS idx_knowledge_documents_team_id
-                    ON knowledge_documents (team_id) WHERE team_id IS NOT NULL
-                """)
-                )
-
-                await conn.execute(
-                    text("""
-                    CREATE INDEX IF NOT EXISTS idx_knowledge_documents_created_at
-                    ON knowledge_documents (created_at DESC)
-                """)
-                )
-
-                # Memory fragments table for semantic chunks
-                await conn.execute(
-                    text(f"""
-                    CREATE TABLE IF NOT EXISTS memory_fragments (
-                        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-                        document_id UUID REFERENCES knowledge_documents(id) ON DELETE CASCADE,
-                        content TEXT NOT NULL,
-                        embedding vector({_VEC_DIM}),
-                        fragment_type VARCHAR(50) DEFAULT 'semantic',
-                        metadata JSONB DEFAULT '{{}}',
-                        user_id VARCHAR(255) NOT NULL,
-                        created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-                        access_count INTEGER DEFAULT 0
-                    )
-                """)
-                )
-
-                # Create HNSW index for memory fragments
-                await conn.execute(
-                    text("""
-                    CREATE INDEX IF NOT EXISTS idx_memory_fragments_embedding_hnsw
-                    ON memory_fragments USING hnsw (embedding vector_cosine_ops)
-                    WITH (m = 16, ef_construction = 64)
-                """)
-                )
-
-                # Vector search history for analytics
-                await conn.execute(
-                    text(f"""
-                    CREATE TABLE IF NOT EXISTS vector_search_history (
-                        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-                        query_embedding vector({_VEC_DIM}),
-                        query_text TEXT NOT NULL,
-                        user_id VARCHAR(255) NOT NULL,
-                        team_id VARCHAR(255),
-                        search_type VARCHAR(50) DEFAULT 'semantic',
-                        results_count INTEGER DEFAULT 0,
-                        response_time_ms FLOAT,
-                        created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-                    )
-                """)
-                )
-
-                # Canonical memories table for versioning support
-                await conn.execute(
-                    text("""
-                    CREATE TABLE IF NOT EXISTS memories (
-                        memory_id TEXT PRIMARY KEY,
-                        user_id VARCHAR(255) NOT NULL,
-                        session_id VARCHAR(255) NOT NULL,
-                        team_id VARCHAR(255),
-                        content TEXT NOT NULL,
-                        category VARCHAR(255) NOT NULL,
-                        importance VARCHAR(64) NOT NULL,
-                        metadata JSONB DEFAULT '{}',
-                        storage_tier VARCHAR(64) NOT NULL,
-                        status VARCHAR(32) NOT NULL DEFAULT 'active',
-                        versioning_enabled BOOLEAN NOT NULL DEFAULT TRUE,
-                        version_history_limit INTEGER NOT NULL DEFAULT 100,
-                        current_version_number INTEGER NOT NULL DEFAULT 1,
-                        total_versions INTEGER NOT NULL DEFAULT 1,
-                        last_version_created TIMESTAMP WITH TIME ZONE,
-                        created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-                        updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-                    )
-                """)
-                )
-
-                await conn.execute(
-                    text("""
-                    CREATE TABLE IF NOT EXISTS memory_versions (
-                        version_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-                        memory_id TEXT REFERENCES memories(memory_id) ON DELETE CASCADE,
-                        version_number INTEGER NOT NULL,
-                        content TEXT NOT NULL,
-                        category VARCHAR(255) NOT NULL,
-                        importance VARCHAR(64) NOT NULL,
-                        metadata JSONB DEFAULT '{}',
-                        is_active BOOLEAN NOT NULL DEFAULT FALSE,
-                        created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-                        created_by VARCHAR(255),
-                        change_reason TEXT,
-                        parent_version_id UUID,
-                        content_size_bytes INTEGER DEFAULT 0,
-                        processing_time_ms DOUBLE PRECISION DEFAULT 0
-                    )
-                """)
-                )
-
-                await conn.execute(
-                    text("""
-                    CREATE INDEX IF NOT EXISTS idx_memories_session_id
-                    ON memories (session_id)
-                """)
-                )
-
-                await conn.execute(
-                    text("""
-                    CREATE INDEX IF NOT EXISTS idx_memories_user_id
-                    ON memories (user_id)
-                """)
-                )
-
-                await conn.execute(
-                    text("""
-                    CREATE INDEX IF NOT EXISTS idx_memories_created_at
-                    ON memories (created_at DESC)
-                """)
-                )
-
-                await conn.execute(
-                    text("""
-                    CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_versions_unique
-                    ON memory_versions (memory_id, version_number)
-                """)
-                )
-
-                await conn.execute(
-                    text("""
-                    CREATE INDEX IF NOT EXISTS idx_memory_versions_active
-                    ON memory_versions (memory_id) WHERE is_active = TRUE
-                """)
-                )
-
-                await conn.execute(
-                    text("""
-                    CREATE INDEX IF NOT EXISTS idx_memory_versions_created_at
-                    ON memory_versions (created_at DESC)
-                """)
-                )
-
-                logger.info("Vector database schema created successfully")
-
-        except asyncpg.exceptions.UniqueViolationError as dup_exc:
-            logger.warning(
-                "Knowledge base schema already initialized elsewhere; continuing (%s)",
-                dup_exc,
-            )
-        except Exception as e:
-            logger.exception(f"Failed to create vector schema: {e}")
-            raise
-
-    async def health_check(self) -> dict[str, Any]:
-        """Perform comprehensive health check with pgvector verification"""
-        try:
-            if not self._initialized:
-                await self.initialize()
-
-            health_report = {
-                "status": "healthy",
-                "timestamp": datetime.now(UTC).isoformat(),
-                "postgres_version": None,
-                "pgvector_enabled": self._pgvector_enabled,
-                "extensions": {},
-                "vector_schema": {},
-                "performance_metrics": {},
-            }
-
-            async with self.engine.begin() as conn:
-                # Test basic connectivity
-                await conn.execute(text("SELECT 1"))
-
-                # Get PostgreSQL version
-                version_result = await conn.execute(text("SELECT version()"))
-                health_report["postgres_version"] = version_result.scalar()
-
-                # Check required extensions
-                extensions_query = """
-                    SELECT extname, extversion
-                    FROM pg_extension
-                    WHERE extname IN ('uuid-ossp', 'pg_trgm', 'pg_stat_statements', 'vector')
-                """
-                ext_result = await conn.execute(text(extensions_query))
-                extensions = ext_result.fetchall()
-
-                for ext in extensions:
-                    health_report["extensions"][ext[0]] = {
-                        "version": ext[1],
-                        "status": "installed",
-                    }
-
-                # Check pgvector functionality
-                if self._pgvector_enabled:
-                    try:
-                        # Test vector operations
-                        vector_test = await conn.execute(
-                            text("""
-                            SELECT '[1,2,3]'::vector <-> '[1,2,4]'::vector as distance
-                        """)
-                        )
-                        distance = vector_test.scalar()
-                        health_report["pgvector_functionality"] = {
-                            "status": "working",
-                            "test_distance": float(distance),
-                        }
-
-                        # Check vector schema
-                        schema_check = await conn.execute(
-                            text("""
-                            SELECT table_name
-                            FROM information_schema.tables
-                            WHERE table_schema = 'public'
-                            AND table_name IN ('knowledge_documents', 'memory_fragments', 'vector_search_history')
-                        """)
-                        )
-                        tables = [row[0] for row in schema_check.fetchall()]
-
-                        health_report["vector_schema"] = {
-                            "tables_found": tables,
-                            "expected_tables": [
-                                "knowledge_documents",
-                                "memory_fragments",
-                                "vector_search_history",
-                            ],
-                            "status": "complete" if len(tables) == 3 else "incomplete",
-                        }
-
-                        # Check HNSW indexes
-                        index_check = await conn.execute(
-                            text("""
-                            SELECT indexname, tablename
-                            FROM pg_indexes
-                            WHERE indexname LIKE '%_hnsw'
-                        """)
-                        )
-                        indexes = index_check.fetchall()
-                        health_report["vector_schema"]["hnsw_indexes"] = [
-                            {"name": idx[0], "table": idx[1]} for idx in indexes
-                        ]
-
-                    except Exception as e:
-                        health_report["pgvector_functionality"] = {
-                            "status": "error",
-                            "error": str(e),
-                        }
-                        health_report["status"] = "degraded"
-
-                # Get connection pool stats
-                pool_info = await self.get_connection_info()
-                health_report["performance_metrics"] = {
-                    "connection_pool": pool_info,
-                    "target_response_time_ms": 50.0,  # From DATABASE_ENHANCEMENT_PLAN.md
-                }
-
-                # Evaluate overall health
-                if not self._pgvector_enabled:
-                    health_report["status"] = "degraded"
-                    health_report["warnings"] = ["pgvector extension not available"]
-
-                return health_report
-
-        except Exception as e:
-            logger.exception(f"PostgreSQL health check failed: {e}")
-            return {
-                "status": "unhealthy",
-                "timestamp": datetime.now(UTC).isoformat(),
-                "error": str(e),
-            }
-
-    @asynccontextmanager
-    async def get_session(self) -> AsyncGenerator[AsyncSession, None]:
-        """Get database session with proper error handling"""
-        if not self._initialized:
-            await self.initialize()
-
-        async with self.async_session() as session:
-            try:
-                yield session
-            except (OperationalError, asyncpg.PostgresError) as e:
-                await session.rollback()
-                logger.exception(f"Database session error: {e}")
-                await self.promote_failover(reason="session_error")
-                raise
-            except Exception as e:
-                await session.rollback()
-                logger.exception(f"Database session error: {e}")
-                raise
-            finally:
-                await session.close()
-
-    async def execute_query(
-        self, query: str, params: dict = None, _failover_attempted: bool = False
-    ):
-        """Execute raw SQL query"""
-        if not self._initialized:
-            await self.initialize()
-
-        async with self.engine.begin() as conn:
-            try:
-                start = datetime.now(UTC)
-                statement = text(query)
-                if params:
-                    result = await conn.execute(statement, params)
-                else:
-                    result = await conn.execute(statement)
-                duration = (datetime.now(UTC) - start).total_seconds() * 1000
-                self._record_query_metric(duration, statement.text)
-                return result
-            except (OperationalError, asyncpg.PostgresError) as e:
-                logger.exception(f"Query execution failed: {query}, error: {e}")
-                if not _failover_attempted and await self.promote_failover(reason="query_error"):
-                    return await self.execute_query(query, params, _failover_attempted=True)
-                raise
-            except Exception as e:
-                logger.exception(f"Query execution failed: {query}, error: {e}")
-                raise
-
-    async def get_connection_info(self) -> dict:
-        """Get connection pool information"""
-        if not self._initialized:
-            return {"status": "not_initialized"}
-
-        pool = self.engine.pool
-        active_target = None
-        if (
-            self._connection_targets
-            and self._active_target_index is not None
-            and 0 <= self._active_target_index < len(self._connection_targets)
-        ):
-            target = self._connection_targets[self._active_target_index]
-            active_target = {
-                "label": target["label"],
-                "display": target.get("display"),
-                "role": target.get("role", "primary"),
-            }
-
-        invalid = pool.invalid() if hasattr(pool, "invalid") else None
-
-        return {
-            "status": "initialized",
-            "size": pool.size(),
-            "checked_in": pool.checkedin(),
-            "checked_out": pool.checkedout(),
-            "overflow": pool.overflow(),
-            "invalid": invalid,
-            "pgvector_enabled": self._pgvector_enabled,
-            "active_target": active_target,
-            "available_targets": [t["label"] for t in self._connection_targets],
-        }
-
-    def get_failover_targets(self) -> list[dict[str, Any]]:
-        """Return the configured primary+failover targets and active status."""
-        targets: list[dict[str, Any]] = []
-        for idx, target in enumerate(self._connection_targets):
-            targets.append(
-                {
-                    "label": target["label"],
-                    "role": target.get("role", "primary"),
-                    "display": target.get("display"),
-                    "active": idx == self._active_target_index,
-                }
-            )
-        return targets
-
-    async def promote_failover(
-        self, reason: str = "automatic", target_label: str | None = None
-    ) -> bool:
-        """Attempt to switch to the next available failover target."""
-        if not self._connection_targets:
-            self._connection_targets = self._build_connection_targets()
-
-        if len(self._connection_targets) <= 1:
-            logger.warning("No PostgreSQL failover targets configured")
-            return False
-
-        if target_label:
-            indices_to_try = [
-                idx
-                for idx, target in enumerate(self._connection_targets)
-                if target["label"] == target_label
-            ]
-            if not indices_to_try:
-                logger.error("Failover target %s not found", target_label)
-                return False
-        else:
-            start_idx = (self._active_target_index or -1) + 1
-            indices_to_try = list(range(start_idx, len(self._connection_targets)))
-
-        previous_label = None
-        if self._active_target_index is not None and 0 <= self._active_target_index < len(
-            self._connection_targets
-        ):
-            previous_label = self._connection_targets[self._active_target_index]["label"]
-
-        for idx in indices_to_try:
-            if idx == self._active_target_index:
-                continue
-            target = self._connection_targets[idx]
-            try:
-                self._initialized = False
-                await self._initialize_target_engine(target)
-                self._active_target_index = idx
-                self._initialized = True
-                logger.warning(
-                    "PostgreSQL failover activated: %s -> %s (reason=%s)",
-                    previous_label or "unknown",
-                    target["label"],
-                    reason,
-                )
-                return True
-            except Exception as exc:
-                logger.exception(
-                    "Failover attempt to %s failed: %s",
-                    target["label"],
-                    exc,
-                )
-                await self._dispose_engine()
-
-        logger.error("All PostgreSQL failover attempts failed for reason=%s", reason)
-        return False
-
-    def _calculate_pool_settings(self) -> dict[str, int]:
-        """Derive safe pool settings from configured min/max values."""
-        db_cfg = self.config.database
-        min_conn = max(int(getattr(db_cfg, "postgres_min_connections", 1)), 1)
-        max_conn = max(int(getattr(db_cfg, "postgres_max_connections", min_conn)), min_conn)
-        overflow = max(max_conn - min_conn, 0)
-
-        return {
-            "pool_size": min_conn,
-            "max_overflow": overflow if overflow > 0 else 0,
-            "pool_timeout": int(getattr(db_cfg, "postgres_pool_timeout", 30)),
-            "pool_recycle": int(getattr(db_cfg, "postgres_pool_recycle", 3600)),
-        }
-
-    def _record_query_metric(self, duration_ms: float, sql: str) -> None:
-        stats = self.query_stats
-        stats["count"] += 1
-        stats["total_ms"] += duration_ms
-        if duration_ms >= stats["threshold_ms"]:
-            stats["slow_queries"] += 1
-            logger.debug("Slow query (%.2f ms): %s", duration_ms, sql[:200])
-
-    async def vector_search(
-        self,
-        query_embedding: list[float],
-        user_id: str,
-        team_id: str | None = None,
-        limit: int = 10,
-        similarity_threshold: float = 0.7,
-        search_type: str = "knowledge_documents",
-        query_text: str | None = None,
-    ) -> list[dict[str, Any]]:
-        """
-        Perform vector similarity search using pgvector HNSW indexes
-
-        Args:
-            query_embedding: Query vector embedding (dimensions from EMBEDDING_DIMENSION env var)
-            user_id: User identifier for access control
-            team_id: Optional team identifier for team memory
-            limit: Maximum number of results to return
-            similarity_threshold: Minimum similarity score (0.0-1.0)
-            search_type: Table to search ('knowledge_documents' or 'memory_fragments')
-
-        Returns:
-            List of search results with similarity scores
-        """
-        if not self._pgvector_enabled:
-            raise RuntimeError("pgvector extension is not enabled")
-
-        start_time = datetime.now(UTC)
-
-        try:
-            async with self.engine.begin() as conn:
-                # Determine which table to search
-                if search_type == "memory_fragments":
-                    table_name = "memory_fragments"
-                    where_clause = "WHERE mf.user_id = :user_id"
-                    # Format query embedding as proper pgvector string
-                    query_embedding_str = f"[{','.join(str(x) for x in query_embedding)}]"
-                    params = {
-                        "query_embedding": query_embedding_str,
-                        "user_id": user_id,
-                        "limit": limit,
-                        "similarity_threshold": similarity_threshold,
-                    }
-                else:  # knowledge_documents
-                    table_name = "knowledge_documents"
-                    where_clause = "WHERE kd.user_id = :user_id"
-                    # Format query embedding as proper pgvector string
-                    query_embedding_str = f"[{','.join(str(x) for x in query_embedding)}]"
-                    params = {
-                        "query_embedding": query_embedding_str,
-                        "user_id": user_id,
-                        "limit": limit,
-                        "similarity_threshold": similarity_threshold,
-                    }
-
-                # Add team filter if provided
-                if team_id:
-                    where_clause += " AND kd.team_id = :team_id"
-                    params["team_id"] = team_id
-
-                # Vector similarity search query with HNSW index
-                search_query = f"""
-                    SELECT
-                        kd.id,
-                        kd.title,
-                        kd.content,
-                        kd.metadata,
-                        kd.user_id,
-                        kd.team_id,
-                        kd.created_at,
-                        kd.access_count,
-                        1 - (kd.embedding <=> CAST(:query_embedding AS vector)) as similarity_score
-                    FROM {table_name} kd
-                    {where_clause}
-                    AND 1 - (kd.embedding <=> CAST(:query_embedding AS vector)) > :similarity_threshold
-                    ORDER BY kd.embedding <=> CAST(:query_embedding AS vector)
-                    LIMIT :limit
-                """
-
-                if search_type == "memory_fragments":
-                    search_query = search_query.replace("kd.", "mf.")
-                    search_query = search_query.replace("knowledge_documents", "memory_fragments")
-
-                result = await conn.execute(text(search_query), params)
-                rows = result.fetchall()
-
-                # Convert to list of dictionaries
-                search_results = []
-                for row in rows:
-                    search_results.append(
-                        {
-                            "id": str(row[0]),
-                            "title": row[1],
-                            "content": row[2],
-                            "metadata": row[3],
-                            "user_id": row[4],
-                            "team_id": row[5],
-                            "created_at": row[6].isoformat() if row[6] else None,
-                            "access_count": row[7],
-                            "similarity_score": float(row[8]),
-                            "search_type": search_type,
-                        }
-                    )
-
-                # Log search for analytics
-                response_time = (datetime.now(UTC) - start_time).total_seconds() * 1000
-                await self._log_vector_search(
-                    query_embedding,
-                    user_id,
-                    team_id,
-                    len(search_results),
-                    response_time,
-                    query_text=query_text,
-                )
-
-                logger.debug(
-                    f"Vector search completed: {len(search_results)} results in {response_time:.2f}ms"
-                )
-                return search_results
-
-        except Exception as e:
-            logger.exception(f"Vector search failed: {e}")
-            raise
-
-    async def insert_document(
-        self,
-        title: str,
-        content: str,
-        embedding: list[float],
-        user_id: str,
-        team_id: str | None = None,
-        metadata: dict[str, Any] | None = None,
-    ) -> str:
-        """
-        Insert a new document with embedding into knowledge base
-
-        Args:
-            title: Document title
-            content: Document content
-            embedding: Vector embedding (dimensions from EMBEDDING_DIMENSION env var)
-            user_id: User identifier
-            team_id: Optional team identifier
-            metadata: Optional document metadata
-
-        Returns:
-            Document ID as UUID string
-        """
-        if not self._pgvector_enabled:
-            raise RuntimeError("pgvector extension is not enabled")
-
-        try:
-            async with self.engine.begin() as conn:
-                # Format embedding as proper pgvector string
-                embedding_str = f"[{','.join(str(x) for x in embedding)}]"
-
-                result = await conn.execute(
-                    text("""
-                    INSERT INTO knowledge_documents (
-                        title, content, embedding, user_id, team_id, metadata
-                    ) VALUES (
-                        :title, :content, :embedding, :user_id, :team_id, :metadata
-                    )
-                    RETURNING id
-                """),
-                    {
-                        "title": title,
-                        "content": content,
-                        "embedding": embedding_str,  # Already formatted as vector string
-                        "user_id": user_id,
-                        "team_id": team_id,
-                        "metadata": json.dumps(metadata or {}),
-                    },
-                )
-
-                document_id = str(result.scalar())
-                logger.debug(f"Document inserted: {document_id}")
-                return document_id
-
-        except Exception as e:
-            logger.exception(f"Failed to insert document: {e}")
-            raise
-
-    async def update_document_access(self, document_id: str):
-        """Update access count for a document"""
-        try:
-            async with self.engine.begin() as conn:
-                await conn.execute(
-                    text("""
-                    UPDATE knowledge_documents
-                    SET access_count = access_count + 1,
-                        updated_at = NOW()
-                    WHERE id = :document_id
-                """),
-                    {"document_id": document_id},
-                )
-
-        except Exception as e:
-            logger.debug(f"Failed to update document access: {e}")
-
-    async def _log_vector_search(
-        self,
-        query_embedding: list[float],
-        user_id: str,
-        team_id: str | None,
-        results_count: int,
-        response_time_ms: float,
-        query_text: str | None = None,
-    ):
-        """Log vector search for analytics and performance monitoring"""
-        try:
-            async with self.engine.begin() as conn:
-                # Format query embedding as proper pgvector string
-                query_embedding_str = f"[{','.join(str(x) for x in query_embedding)}]"
-                normalized_query_text = (query_text or "").strip()
-                if not normalized_query_text:
-                    # Keep vector_search_history.query_text non-null even for
-                    # embedding-only callers that do not have source text.
-                    normalized_query_text = (
-                        f"embedding:{hashlib.sha256(query_embedding_str.encode()).hexdigest()[:16]}"
-                    )
-
-                await conn.execute(
-                    text("""
-                    INSERT INTO vector_search_history (
-                        query_embedding, query_text, user_id, team_id, results_count, response_time_ms
-                    ) VALUES (
-                        :query_embedding, :query_text, :user_id, :team_id, :results_count, :response_time_ms
-                    )
-                """),
-                    {
-                        "query_embedding": query_embedding_str,  # Already formatted as vector string
-                        "query_text": normalized_query_text,
-                        "user_id": user_id,
-                        "team_id": team_id,
-                        "results_count": results_count,
-                        "response_time_ms": response_time_ms,
-                    },
-                )
-
-        except Exception:
-            query_repr = ",".join(f"{x:.4f}" for x in query_embedding[:4])
-            query_hash = hashlib.sha256(query_repr.encode()).hexdigest()[:16]
-            logger.warning(
-                "Failed to log vector search to history table",
-                exc_info=True,
-                extra={"user_id": user_id, "query_hash": query_hash},
-            )
-
-    async def close(self):
-        """Close all connections"""
-        await self._dispose_engine()
-        self._initialized = False
-        logger.info("PostgreSQL connections closed")
-
-
-class DatabaseService:
-    """High-level database service for application use"""
-
-    def __init__(self):
-        self.postgres = PostgreSQLConnectionManager()
-
-    async def initialize(self):
-        """Initialize database service"""
-        await self.postgres.initialize()
-
-    async def health_check(self) -> dict:
-        """Perform comprehensive health check"""
-        postgres_healthy = await self.postgres.health_check()
-
-        return {
-            "postgres": {
-                "status": "healthy" if postgres_healthy else "unhealthy",
-                "connection_info": await self.postgres.get_connection_info(),
-            },
-            "overall": "healthy" if postgres_healthy else "unhealthy",
-        }
-
-    @asynccontextmanager
-    async def get_session(self) -> AsyncGenerator[AsyncSession, None]:
-        """Get database session"""
-        async with self.postgres.get_session() as session:
-            yield session
-
-    @asynccontextmanager
-    async def transaction(self):
-        """Provide a raw transaction context for low-level operations."""
-        async with self.postgres.engine.begin() as conn:
-            yield conn
-
-    async def close(self):
-        """Close database connections"""
-        await self.postgres.close()
-
-    # --- Canonical memory helpers --------------------------------------------------
-
-    async def upsert_memory_record(
-        self,
-        memory_id: str,
-        *,
-        user_id: str,
-        session_id: str,
-        team_id: str | None,
-        content: str,
-        category: str,
-        importance: str,
-        metadata: dict[str, Any],
-        storage_tier: str,
-        status: str = "active",
-        versioning_enabled: bool = True,
-        version_history_limit: int = 100,
-    ) -> None:
-        """Insert or update the canonical memory record and ensure base version exists."""
-        metadata_json = json.dumps(metadata or {})
-        async with self.postgres.engine.begin() as conn:
-            params = {
-                "memory_id": memory_id,
-                "user_id": user_id,
-                "session_id": session_id,
-                "team_id": team_id,
-                "content": content,
-                "category": category,
-                "importance": importance,
-                "metadata": metadata_json,
-                "storage_tier": storage_tier,
-                "status": status,
-                "versioning_enabled": versioning_enabled,
-                "version_history_limit": version_history_limit,
-            }
-
-            await conn.execute(
-                text("""
-                INSERT INTO memories (
-                    memory_id, user_id, session_id, team_id, content, category,
-                    importance, metadata, storage_tier, status,
-                    versioning_enabled, version_history_limit,
-                    current_version_number, total_versions, last_version_created
-                ) VALUES (
-                    :memory_id, :user_id, :session_id, :team_id, :content, :category,
-                    :importance, :metadata, :storage_tier, :status,
-                    :versioning_enabled, :version_history_limit,
-                    1, 1, NOW()
-                )
-                ON CONFLICT (memory_id) DO UPDATE SET
-                    user_id = EXCLUDED.user_id,
-                    session_id = EXCLUDED.session_id,
-                    team_id = EXCLUDED.team_id,
-                    content = EXCLUDED.content,
-                    category = EXCLUDED.category,
-                    importance = EXCLUDED.importance,
-                    metadata = EXCLUDED.metadata,
-                    storage_tier = EXCLUDED.storage_tier,
-                    status = EXCLUDED.status,
-                    updated_at = NOW()
-            """),
-                params,
-            )
-
-            await conn.execute(
-                text("""
-                INSERT INTO memory_versions (
-                    memory_id, version_number, content, category, importance,
-                    metadata, is_active, created_by, change_reason,
-                    content_size_bytes, processing_time_ms
-                ) VALUES (
-                    :memory_id, 1, :content, :category, :importance,
-                    :metadata, TRUE, :user_id, 'Initial creation',
-                    :content_size_bytes, 0
-                )
-                ON CONFLICT (memory_id, version_number) DO NOTHING
-            """),
-                {
-                    "memory_id": memory_id,
-                    "content": content,
-                    "category": category,
-                    "importance": importance,
-                    "metadata": metadata_json,
-                    "user_id": user_id,
-                    "content_size_bytes": len(content.encode("utf-8")),
-                },
-            )
-
-    async def get_memory(self, memory_id: str) -> Memory | None:
-        """Fetch canonical memory record."""
-        query = text(
-            """
-            SELECT * FROM memories WHERE memory_id = :memory_id
-            """
-        )
-        async with self.postgres.engine.connect() as conn:
-            result = await conn.execute(query, {"memory_id": memory_id})
-            row = result.mappings().first()
-            if not row:
-                return None
-            return self._map_row_to_memory(row)
-
-    async def update_memory(
-        self,
-        conn,
-        memory_id: str,
-        updates: dict[str, Any],
-        *,
-        expected_current_version_number: int | None = None,
-    ) -> int:
-        """Apply updates to canonical memory within an existing transaction.
-
-        Returns the updated ``current_version_number``.
-        """
-        if not updates:
-            row = await conn.execute(
-                text(
-                    """
-                    SELECT current_version_number
-                    FROM memories
-                    WHERE memory_id = :memory_id
-                    """
-                ),
-                {"memory_id": memory_id},
-            )
-            current = row.mappings().first()
-            if current is None:
-                raise ValueError(f"Memory {memory_id} not found for update")
-            return int(current["current_version_number"])
-        params = {**updates}
-        params["memory_id"] = memory_id
-        if expected_current_version_number is not None:
-            params["expected_current_version_number"] = expected_current_version_number
-        set_clauses = []
-        for key in list(updates.keys()):
-            value = updates[key]
-            if key == "updated_at":
-                continue  # updated_at is set automatically
-            if key == "metadata":
-                params[key] = json.dumps(value or {})
-            set_clauses.append(f"{key} = :{key}")
-        set_sql = ", ".join(set_clauses)
-        where_sql = "memory_id = :memory_id"
-        if expected_current_version_number is not None:
-            where_sql += " AND current_version_number = :expected_current_version_number"
-        result = await conn.execute(
-            text(
-                f"""
-                UPDATE memories
-                SET {set_sql}, current_version_number = current_version_number + 1, updated_at = NOW()
-                WHERE {where_sql}
-                RETURNING current_version_number
-                """
-            ),
-            params,
-        )
-        updated_row = result.mappings().first()
-        if updated_row is not None:
-            return int(updated_row["current_version_number"])
-
-        existing = await conn.execute(
-            text(
-                """
-                SELECT current_version_number
-                FROM memories
-                WHERE memory_id = :memory_id
-                """
-            ),
-            {"memory_id": memory_id},
-        )
-        existing_row = existing.mappings().first()
-        if existing_row is None:
-            raise ValueError(f"Memory {memory_id} not found for update")
-        if expected_current_version_number is not None:
-            actual_revision = int(existing_row["current_version_number"])
-            raise MemoryRevisionConflictError(
-                memory_id,
-                expected_revision=expected_current_version_number,
-                actual_revision=actual_revision,
-            )
-        raise ValueError(f"Memory {memory_id} not found for update")
-
-    async def update_memory_if_not_terminal(
-        self,
-        conn,
-        memory_id: str,
-        updates: dict[str, Any],
-        *,
-        terminal_values: tuple[str, ...] = ("synced", "stalled", "success", "failed"),
-    ) -> int | None:
-        """Apply updates to a memory only if ``metadata.mem0_status`` is not
-        already in a terminal state (VAMI-018 T-F1-3, ADR-19).
-
-        Fixes the post-enqueue ``"pending"`` stamp race in async-mode store:
-        the enqueueing path stamps ``mem0_status="pending"`` AFTER dispatching
-        the Celery task; if the worker finishes first and writes the terminal
-        state, an unconditional stamp would clobber it. This helper skips the
-        write when a terminal state is already present.
-
-        Returns the new ``current_version_number`` when the update lands, or
-        ``None`` when the guard skipped the write.
-        """
-        if not updates:
-            return None
-        params = {**updates}
-        params["memory_id"] = memory_id
-        params["terminal_values"] = list(terminal_values)
-        set_clauses = []
-        for key in list(updates.keys()):
-            value = updates[key]
-            if key == "updated_at":
-                continue
-            if key == "metadata":
-                params[key] = json.dumps(value or {})
-            set_clauses.append(f"{key} = :{key}")
-        set_sql = ", ".join(set_clauses)
-        result = await conn.execute(
-            text(
-                f"""
-                UPDATE memories
-                SET {set_sql},
-                    current_version_number = current_version_number + 1,
-                    updated_at = NOW()
-                WHERE memory_id = :memory_id
-                  AND (
-                    metadata->>'mem0_status' IS NULL
-                    OR metadata->>'mem0_status' != ALL(:terminal_values)
-                  )
-                RETURNING current_version_number
-                """
-            ),
-            params,
-        )
-        row = result.mappings().first()
-        if row is None:
-            return None
-        return int(row["current_version_number"])
-
-    # --- Memory version helpers ----------------------------------------------------
-
-    async def save_memory_version(self, conn, version_data: dict[str, Any]) -> str:
-        payload = version_data.copy()
-        payload["category"] = (
-            payload["category"].value
-            if isinstance(payload["category"], MemoryCategory)
-            else payload["category"]
-        )
-        payload["importance"] = (
-            payload["importance"].value
-            if isinstance(payload["importance"], ImportanceLevel)
-            else payload["importance"]
-        )
-        payload["metadata"] = json.dumps(payload.get("metadata") or {})
-        payload["is_active"] = bool(payload.get("is_active", False))
-        payload.setdefault("content_size_bytes", len(payload["content"].encode("utf-8")))
-        result = await conn.execute(
-            text(
-                """
-            INSERT INTO memory_versions (
-                version_id, memory_id, version_number, content, category,
-                importance, metadata, is_active, created_at, created_by,
-                change_reason, parent_version_id, content_size_bytes, processing_time_ms
-            ) VALUES (
-                :version_id, :memory_id, :version_number, :content, :category,
-                :importance, :metadata, :is_active, :created_at, :created_by,
-                :change_reason, :parent_version_id, :content_size_bytes, :processing_time_ms
-            ) RETURNING version_id
-            """
-            ),
-            payload,
-        )
-        return str(result.scalar())
-
-    async def get_memory_version(self, memory_id: str, version_number: int) -> MemoryVersion | None:
-        query = text(
-            """
-            SELECT * FROM memory_versions
-            WHERE memory_id = :memory_id AND version_number = :version_number
-            ORDER BY created_at DESC
-            LIMIT 1
-            """
-        )
-        async with self.postgres.engine.connect() as conn:
-            result = await conn.execute(
-                query,
-                {
-                    "memory_id": memory_id,
-                    "version_number": version_number,
-                },
-            )
-            row = result.mappings().first()
-            if not row:
-                return None
-            return self._map_row_to_memory_version(row)
-
-    async def get_memory_version_by_id(self, version_id: str) -> MemoryVersion | None:
-        query = text(
-            """
-            SELECT * FROM memory_versions WHERE version_id = :version_id
-            """
-        )
-        async with self.postgres.engine.connect() as conn:
-            result = await conn.execute(query, {"version_id": version_id})
-            row = result.mappings().first()
-            if not row:
-                return None
-            return self._map_row_to_memory_version(row)
-
-    async def get_memory_versions(self, memory_id: str, limit: int = 50) -> list[MemoryVersion]:
-        query = text(
-            """
-            SELECT * FROM memory_versions
-            WHERE memory_id = :memory_id
-            ORDER BY version_number DESC
-            LIMIT :limit
-            """
-        )
-        async with self.postgres.engine.connect() as conn:
-            result = await conn.execute(query, {"memory_id": memory_id, "limit": limit})
-            rows = result.mappings().all()
-            return [self._map_row_to_memory_version(row) for row in rows]
-
-    async def update_memory_version(self, conn, version_id: str, updates: dict[str, Any]) -> None:
-        if not updates:
-            return
-        params = {**updates, "version_id": version_id}
-        set_clauses = []
-        for key in list(updates.keys()):
-            value = updates[key]
-            if key == "metadata":
-                params[key] = json.dumps(value or {})
-            set_clauses.append(f"{key} = :{key}")
-        set_sql = ", ".join(set_clauses)
-        await conn.execute(
-            text(
-                f"""
-                UPDATE memory_versions
-                SET {set_sql}
-                WHERE version_id = :version_id
-                """
-            ),
-            params,
-        )
-
-    async def deactivate_memory_version(self, conn, memory_id: str, version_number: int) -> None:
-        await conn.execute(
-            text(
-                """
-            UPDATE memory_versions
-            SET is_active = FALSE
-            WHERE memory_id = :memory_id AND version_number = :version_number
-            """
-            ),
-            {"memory_id": memory_id, "version_number": version_number},
-        )
-
-    async def activate_memory_version(self, conn, memory_id: str, version_number: int) -> None:
-        await conn.execute(
-            text(
-                """
-            UPDATE memory_versions
-            SET is_active = TRUE
-            WHERE memory_id = :memory_id AND version_number = :version_number
-            """
-            ),
-            {"memory_id": memory_id, "version_number": version_number},
-        )
-
-    async def delete_memory_version(self, conn, version_id: str) -> None:
-        await conn.execute(
-            text(
-                """
-            DELETE FROM memory_versions WHERE version_id = :version_id
-            """
-            ),
-            {"version_id": version_id},
-        )
-
-    async def get_versioning_stats(self) -> dict[str, Any]:
-        query = text(
-            """
-            SELECT
-                (SELECT COUNT(*) FROM memories) as total_memories,
-                (SELECT COALESCE(SUM(total_versions), 0) FROM memories) as total_versions,
-                (SELECT COUNT(*) FROM memory_versions WHERE is_active = TRUE) as active_versions
-            """
-        )
-        async with self.postgres.engine.connect() as conn:
-            result = await conn.execute(query)
-            row = result.mappings().first()
-            return dict(row) if row else {}
-
-    # --- Memory sharing + collaboration helpers -------------------------------
-
-    async def create_memory_permission(self, permission_data: dict[str, Any]) -> dict[str, Any]:
-        payload = permission_data.copy()
-        payload["memory_id"] = str(payload["memory_id"])
-        query = text(
-            """
-            INSERT INTO memory_permissions (
-                id, memory_id, user_id, team_id, role, created_at, updated_at
-            ) VALUES (
-                :id, :memory_id, :user_id, :team_id, :role, NOW(), NOW()
-            )
-            RETURNING id, memory_id, user_id, team_id, role, created_at, updated_at
-            """
-        )
-        async with self.postgres.engine.begin() as conn:
-            result = await conn.execute(query, payload)
-            row = result.mappings().first()
-            return dict(row) if row else {}
-
-    async def update_memory_permission(
-        self, permission_id: str, update_data: dict[str, Any]
-    ) -> dict[str, Any]:
-        update_payload = update_data.copy()
-        update_payload["permission_id"] = permission_id
-        query = text(
-            """
-            UPDATE memory_permissions
-            SET role = :role,
-                updated_at = NOW()
-            WHERE id = :permission_id
-            RETURNING id, memory_id, user_id, team_id, role, created_at, updated_at
-            """
-        )
-        async with self.postgres.engine.begin() as conn:
-            result = await conn.execute(query, update_payload)
-            row = result.mappings().first()
-            if not row:
-                raise ValueError("Permission not found")
-            return dict(row)
-
-    async def get_memory_permission(self, permission_id: str) -> dict[str, Any] | None:
-        query = text(
-            """
-            SELECT * FROM memory_permissions WHERE id = :permission_id
-            """
-        )
-        async with self.postgres.engine.connect() as conn:
-            result = await conn.execute(query, {"permission_id": permission_id})
-            row = result.mappings().first()
-            return dict(row) if row else None
-
-    async def delete_memory_permission(self, permission_id: str) -> bool:
-        query = text(
-            """
-            DELETE FROM memory_permissions WHERE id = :permission_id
-            """
-        )
-        async with self.postgres.engine.begin() as conn:
-            result = await conn.execute(query, {"permission_id": permission_id})
-            return result.rowcount > 0
-
-    async def get_memory_permissions(self, memory_id: str | PyUUID) -> list[dict[str, Any]]:
-        query = text(
-            """
-            SELECT mp.*, t.name AS team_name, t.description AS team_description,
-                   t.owner_id AS team_owner_id, t.member_count AS team_member_count,
-                   t.memory_count AS team_memory_count, t.created_at AS team_created_at,
-                   t.updated_at AS team_updated_at
-            FROM memory_permissions mp
-            LEFT JOIN teams t ON mp.team_id = t.id
-            WHERE mp.memory_id = :memory_id
-            ORDER BY mp.created_at DESC
-            """
-        )
-        async with self.postgres.engine.connect() as conn:
-            result = await conn.execute(query, {"memory_id": str(memory_id)})
-            rows = result.mappings().all()
-
-        permissions: list[dict[str, Any]] = []
-        for row in rows:
-            record = dict(row)
-            team_info = None
-            if record.get("team_id"):
-                team_info = {
-                    "id": record.get("team_id"),
-                    "name": record.get("team_name"),
-                    "description": record.get("team_description"),
-                    "owner_id": record.get("team_owner_id"),
-                    "member_count": record.get("team_member_count", 0),
-                    "memory_count": record.get("team_memory_count", 0),
-                    "created_at": record.get("team_created_at"),
-                    "updated_at": record.get("team_updated_at"),
-                }
-            record.pop("team_name", None)
-            record.pop("team_description", None)
-            record.pop("team_owner_id", None)
-            record.pop("team_member_count", None)
-            record.pop("team_memory_count", None)
-            record.pop("team_created_at", None)
-            record.pop("team_updated_at", None)
-            if team_info:
-                record["team"] = team_info
-            permissions.append(record)
-        return permissions
-
-    async def get_user_memory_permission(
-        self, memory_id: str | PyUUID, user_id: PyUUID | str
-    ) -> dict[str, Any] | None:
-        query = text(
-            """
-            SELECT * FROM memory_permissions
-            WHERE memory_id = :memory_id AND user_id = :user_id
-            LIMIT 1
-            """
-        )
-        async with self.postgres.engine.connect() as conn:
-            result = await conn.execute(query, {"memory_id": str(memory_id), "user_id": user_id})
-            row = result.mappings().first()
-            return dict(row) if row else None
-
-    async def get_user_team_memory_permissions(
-        self, memory_id: str | PyUUID, user_id: PyUUID | str
-    ) -> list[dict[str, Any]]:
-        query = text(
-            """
-            SELECT mp.*
-            FROM memory_permissions mp
-            INNER JOIN team_members tm ON mp.team_id = tm.team_id
-            WHERE mp.memory_id = :memory_id AND tm.user_id = :user_id
-            """
-        )
-        async with self.postgres.engine.connect() as conn:
-            result = await conn.execute(query, {"memory_id": str(memory_id), "user_id": user_id})
-            rows = result.mappings().all()
-            return [dict(row) for row in rows]
-
-    async def create_shareable_link(self, link_data: dict[str, Any]) -> dict[str, Any]:
-        payload = link_data.copy()
-        payload["memory_id"] = str(payload["memory_id"])
-        query = text(
-            """
-            INSERT INTO shareable_links (
-                id, memory_id, token, role, created_by_user_id,
-                expires_at, access_count, is_active, created_at, updated_at
-            ) VALUES (
-                :id, :memory_id, :token, :role, :created_by_user_id,
-                :expires_at, :access_count, :is_active, NOW(), NOW()
-            )
-            RETURNING id, memory_id, token, role, created_by_user_id,
-                      expires_at, access_count, is_active, created_at, updated_at
-            """
-        )
-        async with self.postgres.engine.begin() as conn:
-            result = await conn.execute(query, payload)
-            row = result.mappings().first()
-            return dict(row) if row else {}
-
-    async def get_shareable_link_by_token(self, token: str) -> dict[str, Any] | None:
-        query = text(
-            """
-            SELECT *
-            FROM shareable_links
-            WHERE token = :token
-              AND is_active = TRUE
-              AND (expires_at IS NULL OR expires_at > NOW())
-            LIMIT 1
-            """
-        )
-        async with self.postgres.engine.connect() as conn:
-            result = await conn.execute(query, {"token": token})
-            row = result.mappings().first()
-            return dict(row) if row else None
-
-    async def increment_link_access_count(self, link_id: PyUUID | str) -> None:
-        query = text(
-            """
-            UPDATE shareable_links
-            SET access_count = access_count + 1,
-                updated_at = NOW()
-            WHERE id = :link_id
-            """
-        )
-        async with self.postgres.engine.begin() as conn:
-            await conn.execute(query, {"link_id": link_id})
-
-    async def get_shareable_links(self, memory_id: str | PyUUID) -> list[dict[str, Any]]:
-        query = text(
-            """
-            SELECT * FROM shareable_links
-            WHERE memory_id = :memory_id
-            ORDER BY created_at DESC
-            """
-        )
-        async with self.postgres.engine.connect() as conn:
-            result = await conn.execute(query, {"memory_id": str(memory_id)})
-            rows = result.mappings().all()
-            return [dict(row) for row in rows]
-
-    async def get_shareable_link(self, link_id: PyUUID | str) -> dict[str, Any] | None:
-        query = text("SELECT * FROM shareable_links WHERE id = :link_id")
-        async with self.postgres.engine.connect() as conn:
-            result = await conn.execute(query, {"link_id": link_id})
-            row = result.mappings().first()
-            return dict(row) if row else None
-
-    async def deactivate_shareable_link(self, link_id: PyUUID | str) -> bool:
-        query = text(
-            """
-            UPDATE shareable_links
-            SET is_active = FALSE,
-                updated_at = NOW()
-            WHERE id = :link_id
-            """
-        )
-        async with self.postgres.engine.begin() as conn:
-            result = await conn.execute(query, {"link_id": link_id})
-            return result.rowcount > 0
-
-    async def create_team(self, team_data: dict[str, Any]) -> dict[str, Any]:
-        query = text(
-            """
-            INSERT INTO teams (
-                id, name, description, owner_id, member_count, memory_count, created_at, updated_at
-            ) VALUES (
-                :id, :name, :description, :owner_id, :member_count, :memory_count, NOW(), NOW()
-            )
-            RETURNING id, name, description, owner_id, member_count, memory_count, created_at, updated_at
-            """
-        )
-        async with self.postgres.engine.begin() as conn:
-            result = await conn.execute(query, team_data)
-            row = result.mappings().first()
-            return dict(row) if row else {}
-
-    async def add_team_member(
-        self, team_id: PyUUID | str, user_id: PyUUID | str, role: str
-    ) -> dict[str, Any]:
-        query = text(
-            """
-            INSERT INTO team_members (id, team_id, user_id, role, joined_at)
-            VALUES (:id, :team_id, :user_id, :role, NOW())
-            ON CONFLICT (team_id, user_id)
-            DO UPDATE SET role = EXCLUDED.role
-            RETURNING id, team_id, user_id, role, joined_at
-            """
-        )
-        payload = {
-            "id": str(uuid4()),
-            "team_id": team_id,
-            "user_id": user_id,
-            "role": role,
-        }
-        async with self.postgres.engine.begin() as conn:
-            result = await conn.execute(query, payload)
-            row = result.mappings().first()
-            await conn.execute(
-                text(
-                    """
-                UPDATE teams
-                SET member_count = (
-                    SELECT COUNT(*) FROM team_members WHERE team_id = :team_id
-                ),
-                    updated_at = NOW()
-                WHERE id = :team_id
-                """
-                ),
-                {"team_id": team_id},
-            )
-            return dict(row) if row else {}
-
-    async def get_team_membership(
-        self, team_id: PyUUID | str, user_id: PyUUID | str
-    ) -> dict[str, Any] | None:
-        query = text(
-            """
-            SELECT * FROM team_members
-            WHERE team_id = :team_id AND user_id = :user_id
-            LIMIT 1
-            """
-        )
-        async with self.postgres.engine.connect() as conn:
-            result = await conn.execute(query, {"team_id": team_id, "user_id": user_id})
-            row = result.mappings().first()
-            return dict(row) if row else None
-
-    async def create_activity_log(self, activity_data: dict[str, Any]) -> None:
-        payload = activity_data.copy()
-        metadata = payload.get("metadata") or {}
-        payload["metadata"] = json.dumps(metadata)
-        query = text(
-            """
-            INSERT INTO team_activity_logs (
-                id, user_id, memory_id, team_id, activity_type,
-                description, metadata, ip_address, user_agent, created_at
-            ) VALUES (
-                :id, :user_id, :memory_id, :team_id, :activity_type,
-                :description, :metadata, :ip_address, :user_agent, NOW()
-            )
-            """
-        )
-        async with self.postgres.engine.begin() as conn:
-            await conn.execute(query, payload)
-
-    # --- Mapping helpers ----------------------------------------------------------
-
-    def _map_row_to_memory(self, row: Any) -> Memory:
-        metadata = row.get("metadata")
-        if isinstance(metadata, str):
-            metadata = json.loads(metadata)
-        category_value = row.get("category")
-        importance_value = row.get("importance")
-        status_value = row.get("status", MemoryStatus.ACTIVE.value)
-        storage_tier_value = row.get("storage_tier", StorageTier.REDIS.value)
-
-        try:
-            category = MemoryCategory(category_value)
-        except Exception:
-            category = MemoryCategory.GENERAL
-
-        try:
-            importance = ImportanceLevel(importance_value)
-        except Exception:
-            importance = ImportanceLevel.MEDIUM
-
-        try:
-            status = MemoryStatus(status_value)
-        except Exception:
-            status = MemoryStatus.ACTIVE
-
-        try:
-            storage_tier = StorageTier(storage_tier_value)
-        except Exception:
-            storage_tier = StorageTier.REDIS
-
-        return Memory(
-            memory_id=row.get("memory_id"),
-            content=row.get("content", ""),
-            category=category,
-            importance=importance,
-            status=status,
-            session_id=row.get("session_id"),
-            user_id=row.get("user_id"),
-            team_id=row.get("team_id"),
-            working_directory=None,
-            metadata=metadata or {},
-            storage_tier=storage_tier,
-            current_version_number=row.get("current_version_number", 1),
-            total_versions=row.get("total_versions", 1),
-            versioning_enabled=row.get("versioning_enabled", True),
-            version_history_limit=row.get("version_history_limit", 100),
-            last_version_created=row.get("last_version_created"),
-            created_at=row.get("created_at"),
-            updated_at=row.get("updated_at"),
-        )
-
-    def _map_row_to_memory_version(self, row: Any) -> MemoryVersion:
-        metadata = row.get("metadata")
-        if isinstance(metadata, str):
-            metadata = json.loads(metadata)
-
-        category_value = row.get("category")
-        importance_value = row.get("importance")
-
-        try:
-            category = MemoryCategory(category_value)
-        except Exception:
-            category = MemoryCategory.GENERAL
-
-        try:
-            importance = ImportanceLevel(importance_value)
-        except Exception:
-            importance = ImportanceLevel.MEDIUM
-
-        return MemoryVersion(
-            version_id=str(row.get("version_id")),
-            memory_id=row.get("memory_id"),
-            version_number=row.get("version_number"),
-            content=row.get("content", ""),
-            category=category,
-            importance=importance,
-            metadata=metadata or {},
-            is_active=row.get("is_active", False),
-            created_at=row.get("created_at"),
-            created_by=row.get("created_by"),
-            change_reason=row.get("change_reason"),
-            parent_version_id=row.get("parent_version_id"),
-            content_size_bytes=row.get("content_size_bytes", 0),
-            processing_time_ms=row.get("processing_time_ms", 0.0),
-        )
-
-
-# Global database service instance
-database_service = DatabaseService()
-
-
-@asynccontextmanager
-async def get_database_session() -> AsyncGenerator[AsyncSession, None]:
-    """Async context manager for database session"""
-    async with database_service.get_session() as session:
-        yield session
-
-
-async def get_database_service() -> DatabaseService:
-    """Get database service instance"""
-    if not database_service.postgres._initialized:
-        await database_service.initialize()
-    return database_service
-
-
-async def initialize_database():
-    """Initialize database on application startup"""
-    await database_service.initialize()
-    logger.info("Database initialized successfully")
-
-
-async def close_database():
-    """Close database connections on application shutdown"""
-    await database_service.close()
-    logger.info("Database connections closed")