alma-memory 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

alma/storage/postgresql.py

@@ -0,0 +1,1452 @@
+"""
+ALMA PostgreSQL Storage Backend.
+
+Production-ready storage using PostgreSQL with pgvector extension for
+native vector similarity search. Supports connection pooling.
+
+Recommended for:
+- Customer deployments (Azure PostgreSQL, AWS RDS, etc.)
+- Self-hosted production environments
+- High-availability requirements
+"""
+
+import json
+import logging
+import os
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+# numpy is optional - only needed for fallback similarity when pgvector unavailable
+try:
+    import numpy as np
+
+    NUMPY_AVAILABLE = True
+except ImportError:
+    np = None  # type: ignore
+    NUMPY_AVAILABLE = False
+
+from alma.storage.base import StorageBackend
+from alma.types import (
+    AntiPattern,
+    DomainKnowledge,
+    Heuristic,
+    Outcome,
+    UserPreference,
+)
+
+logger = logging.getLogger(__name__)
+
+# Try to import psycopg (v3) with connection pooling
+try:
+    from psycopg.rows import dict_row
+    from psycopg_pool import ConnectionPool
+
+    PSYCOPG_AVAILABLE = True
+except ImportError:
+    PSYCOPG_AVAILABLE = False
+    logger.warning(
+        "psycopg not installed. Install with: pip install 'alma-memory[postgres]'"
+    )
+
+
+class PostgreSQLStorage(StorageBackend):
+    """
+    PostgreSQL storage backend with pgvector support.
+
+    Uses native PostgreSQL vector operations for efficient similarity search.
+    Falls back to application-level cosine similarity if pgvector is not installed.
+
+    Database schema:
+        - alma_heuristics: id, agent, project_id, condition, strategy, ...
+        - alma_outcomes: id, agent, project_id, task_type, ...
+        - alma_preferences: id, user_id, category, preference, ...
+        - alma_domain_knowledge: id, agent, project_id, domain, fact, ...
+        - alma_anti_patterns: id, agent, project_id, pattern, ...
+
+    Vector search:
+        - Uses pgvector extension if available
+        - Embeddings stored as VECTOR type with cosine distance operator (<=>)
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        database: str,
+        user: str,
+        password: str,
+        embedding_dim: int = 384,
+        pool_size: int = 10,
+        schema: str = "public",
+        ssl_mode: str = "prefer",
+    ):
+        """
+        Initialize PostgreSQL storage.
+
+        Args:
+            host: Database host
+            port: Database port
+            database: Database name
+            user: Database user
+            password: Database password
+            embedding_dim: Dimension of embedding vectors
+            pool_size: Connection pool size
+            schema: Database schema (default: public)
+            ssl_mode: SSL mode (disable, allow, prefer, require, verify-ca, verify-full)
+        """
+        if not PSYCOPG_AVAILABLE:
+            raise ImportError(
+                "psycopg not installed. Install with: pip install 'alma-memory[postgres]'"
+            )
+
+        self.embedding_dim = embedding_dim
+        self.schema = schema
+        self._pgvector_available = False
+
+        # Build connection string
+        conninfo = (
+            f"host={host} port={port} dbname={database} "
+            f"user={user} password={password} sslmode={ssl_mode}"
+        )
+
+        # Create connection pool
+        self._pool = ConnectionPool(
+            conninfo=conninfo,
+            min_size=1,
+            max_size=pool_size,
+            kwargs={"row_factory": dict_row},
+        )
+
+        # Initialize database
+        self._init_database()
+
+    @classmethod
+    def from_config(cls, config: Dict[str, Any]) -> "PostgreSQLStorage":
+        """Create instance from configuration."""
+        pg_config = config.get("postgres", {})
+
+        # Support environment variable expansion
+        def get_value(key: str, default: Any = None) -> Any:
+            value = pg_config.get(key, default)
+            if (
+                isinstance(value, str)
+                and value.startswith("${")
+                and value.endswith("}")
+            ):
+                env_var = value[2:-1]
+                return os.environ.get(env_var, default)
+            return value
+
+        return cls(
+            host=get_value("host", "localhost"),
+            port=int(get_value("port", 5432)),
+            database=get_value("database", "alma_memory"),
+            user=get_value("user", "postgres"),
+            password=get_value("password", ""),
+            embedding_dim=int(config.get("embedding_dim", 384)),
+            pool_size=int(get_value("pool_size", 10)),
+            schema=get_value("schema", "public"),
+            ssl_mode=get_value("ssl_mode", "prefer"),
+        )
+
+    @contextmanager
+    def _get_connection(self):
+        """Get database connection from pool."""
+        with self._pool.connection() as conn:
+            yield conn
+
+    def _init_database(self):
+        """Initialize database schema and pgvector extension."""
+        with self._get_connection() as conn:
+            # Try to enable pgvector extension
+            try:
+                conn.execute("CREATE EXTENSION IF NOT EXISTS vector")
+                conn.commit()
+                self._pgvector_available = True
+                logger.info("pgvector extension enabled")
+            except Exception as e:
+                conn.rollback()  # Important: rollback to clear aborted transaction
+                logger.warning(f"pgvector not available: {e}. Using fallback search.")
+                self._pgvector_available = False
+
+            # Create tables
+            vector_type = (
+                f"VECTOR({self.embedding_dim})" if self._pgvector_available else "BYTEA"
+            )
+
+            # Heuristics table
+            conn.execute(f"""
+                CREATE TABLE IF NOT EXISTS {self.schema}.alma_heuristics (
+                    id TEXT PRIMARY KEY,
+                    agent TEXT NOT NULL,
+                    project_id TEXT NOT NULL,
+                    condition TEXT NOT NULL,
+                    strategy TEXT NOT NULL,
+                    confidence REAL DEFAULT 0.0,
+                    occurrence_count INTEGER DEFAULT 0,
+                    success_count INTEGER DEFAULT 0,
+                    last_validated TIMESTAMPTZ,
+                    created_at TIMESTAMPTZ DEFAULT NOW(),
+                    metadata JSONB,
+                    embedding {vector_type}
+                )
+            """)
+            conn.execute(f"""
+                CREATE INDEX IF NOT EXISTS idx_heuristics_project_agent
+                ON {self.schema}.alma_heuristics(project_id, agent)
+            """)
+
+            # Outcomes table
+            conn.execute(f"""
+                CREATE TABLE IF NOT EXISTS {self.schema}.alma_outcomes (
+                    id TEXT PRIMARY KEY,
+                    agent TEXT NOT NULL,
+                    project_id TEXT NOT NULL,
+                    task_type TEXT,
+                    task_description TEXT NOT NULL,
+                    success BOOLEAN DEFAULT FALSE,
+                    strategy_used TEXT,
+                    duration_ms INTEGER,
+                    error_message TEXT,
+                    user_feedback TEXT,
+                    timestamp TIMESTAMPTZ DEFAULT NOW(),
+                    metadata JSONB,
+                    embedding {vector_type}
+                )
+            """)
+            conn.execute(f"""
+                CREATE INDEX IF NOT EXISTS idx_outcomes_project_agent
+                ON {self.schema}.alma_outcomes(project_id, agent)
+            """)
+            conn.execute(f"""
+                CREATE INDEX IF NOT EXISTS idx_outcomes_task_type
+                ON {self.schema}.alma_outcomes(project_id, agent, task_type)
+            """)
+            conn.execute(f"""
+                CREATE INDEX IF NOT EXISTS idx_outcomes_timestamp
+                ON {self.schema}.alma_outcomes(project_id, timestamp DESC)
+            """)
+
+            # User preferences table
+            conn.execute(f"""
+                CREATE TABLE IF NOT EXISTS {self.schema}.alma_preferences (
+                    id TEXT PRIMARY KEY,
+                    user_id TEXT NOT NULL,
+                    category TEXT,
+                    preference TEXT NOT NULL,
+                    source TEXT,
+                    confidence REAL DEFAULT 1.0,
+                    timestamp TIMESTAMPTZ DEFAULT NOW(),
+                    metadata JSONB
+                )
+            """)
+            conn.execute(f"""
+                CREATE INDEX IF NOT EXISTS idx_preferences_user
+                ON {self.schema}.alma_preferences(user_id)
+            """)
+
+            # Domain knowledge table
+            conn.execute(f"""
+                CREATE TABLE IF NOT EXISTS {self.schema}.alma_domain_knowledge (
+                    id TEXT PRIMARY KEY,
+                    agent TEXT NOT NULL,
+                    project_id TEXT NOT NULL,
+                    domain TEXT,
+                    fact TEXT NOT NULL,
+                    source TEXT,
+                    confidence REAL DEFAULT 1.0,
+                    last_verified TIMESTAMPTZ DEFAULT NOW(),
+                    metadata JSONB,
+                    embedding {vector_type}
+                )
+            """)
+            conn.execute(f"""
+                CREATE INDEX IF NOT EXISTS idx_domain_knowledge_project_agent
+                ON {self.schema}.alma_domain_knowledge(project_id, agent)
+            """)
+
+            # Anti-patterns table
+            conn.execute(f"""
+                CREATE TABLE IF NOT EXISTS {self.schema}.alma_anti_patterns (
+                    id TEXT PRIMARY KEY,
+                    agent TEXT NOT NULL,
+                    project_id TEXT NOT NULL,
+                    pattern TEXT NOT NULL,
+                    why_bad TEXT,
+                    better_alternative TEXT,
+                    occurrence_count INTEGER DEFAULT 1,
+                    last_seen TIMESTAMPTZ DEFAULT NOW(),
+                    created_at TIMESTAMPTZ DEFAULT NOW(),
+                    metadata JSONB,
+                    embedding {vector_type}
+                )
+            """)
+            conn.execute(f"""
+                CREATE INDEX IF NOT EXISTS idx_anti_patterns_project_agent
+                ON {self.schema}.alma_anti_patterns(project_id, agent)
+            """)
+
+            # Create vector indexes if pgvector available
+            # Using HNSW instead of IVFFlat because HNSW can be built on empty tables
+            # IVFFlat requires existing data to build, which causes silent failures on fresh databases
+            if self._pgvector_available:
+                for table in [
+                    "alma_heuristics",
+                    "alma_outcomes",
+                    "alma_domain_knowledge",
+                    "alma_anti_patterns",
+                ]:
+                    try:
+                        conn.execute(f"""
+                            CREATE INDEX IF NOT EXISTS idx_{table}_embedding
+                            ON {self.schema}.{table}
+                            USING hnsw (embedding vector_cosine_ops)
+                            WITH (m = 16, ef_construction = 64)
+                        """)
+                    except Exception as e:
+                        logger.warning(f"Failed to create HNSW index for {table}: {e}")
+
+            conn.commit()
+
+    def _embedding_to_db(self, embedding: Optional[List[float]]) -> Any:
+        """Convert embedding to database format."""
+        if embedding is None:
+            return None
+        if self._pgvector_available:
+            # pgvector expects string format: '[1.0, 2.0, 3.0]'
+            return f"[{','.join(str(x) for x in embedding)}]"
+        else:
+            # Store as bytes (requires numpy)
+            if not NUMPY_AVAILABLE:
+                raise ImportError("numpy required for non-pgvector embedding storage")
+            return np.array(embedding, dtype=np.float32).tobytes()
+
+    def _embedding_from_db(self, value: Any) -> Optional[List[float]]:
+        """Convert embedding from database format."""
+        if value is None:
+            return None
+        if self._pgvector_available:
+            # pgvector returns as string or list
+            if isinstance(value, str):
+                value = value.strip("[]")
+                return [float(x) for x in value.split(",")]
+            return list(value)
+        else:
+            # Stored as bytes (requires numpy)
+            if not NUMPY_AVAILABLE or np is None:
+                return None
+            return np.frombuffer(value, dtype=np.float32).tolist()
+
+    def _cosine_similarity(self, a: List[float], b: List[float]) -> float:
+        """Compute cosine similarity between two vectors."""
+        if not NUMPY_AVAILABLE or np is None:
+            # Fallback to pure Python
+            dot = sum(x * y for x, y in zip(a, b, strict=False))
+            norm_a = sum(x * x for x in a) ** 0.5
+            norm_b = sum(x * x for x in b) ** 0.5
+            return dot / (norm_a * norm_b) if norm_a and norm_b else 0.0
+        a_arr = np.array(a)
+        b_arr = np.array(b)
+        return float(
+            np.dot(a_arr, b_arr) / (np.linalg.norm(a_arr) * np.linalg.norm(b_arr))
+        )
+
+    # ==================== WRITE OPERATIONS ====================
+
+    def save_heuristic(self, heuristic: Heuristic) -> str:
+        """Save a heuristic."""
+        with self._get_connection() as conn:
+            conn.execute(
+                f"""
+                INSERT INTO {self.schema}.alma_heuristics
+                (id, agent, project_id, condition, strategy, confidence,
+                 occurrence_count, success_count, last_validated, created_at, metadata, embedding)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+                ON CONFLICT (id) DO UPDATE SET
+                    condition = EXCLUDED.condition,
+                    strategy = EXCLUDED.strategy,
+                    confidence = EXCLUDED.confidence,
+                    occurrence_count = EXCLUDED.occurrence_count,
+                    success_count = EXCLUDED.success_count,
+                    last_validated = EXCLUDED.last_validated,
+                    metadata = EXCLUDED.metadata,
+                    embedding = EXCLUDED.embedding
+                """,
+                (
+                    heuristic.id,
+                    heuristic.agent,
+                    heuristic.project_id,
+                    heuristic.condition,
+                    heuristic.strategy,
+                    heuristic.confidence,
+                    heuristic.occurrence_count,
+                    heuristic.success_count,
+                    heuristic.last_validated,
+                    heuristic.created_at,
+                    json.dumps(heuristic.metadata) if heuristic.metadata else None,
+                    self._embedding_to_db(heuristic.embedding),
+                ),
+            )
+            conn.commit()
+
+        logger.debug(f"Saved heuristic: {heuristic.id}")
+        return heuristic.id
+
+    def save_outcome(self, outcome: Outcome) -> str:
+        """Save an outcome."""
+        with self._get_connection() as conn:
+            conn.execute(
+                f"""
+                INSERT INTO {self.schema}.alma_outcomes
+                (id, agent, project_id, task_type, task_description, success,
+                 strategy_used, duration_ms, error_message, user_feedback, timestamp, metadata, embedding)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+                ON CONFLICT (id) DO UPDATE SET
+                    task_description = EXCLUDED.task_description,
+                    success = EXCLUDED.success,
+                    strategy_used = EXCLUDED.strategy_used,
+                    duration_ms = EXCLUDED.duration_ms,
+                    error_message = EXCLUDED.error_message,
+                    user_feedback = EXCLUDED.user_feedback,
+                    metadata = EXCLUDED.metadata,
+                    embedding = EXCLUDED.embedding
+                """,
+                (
+                    outcome.id,
+                    outcome.agent,
+                    outcome.project_id,
+                    outcome.task_type,
+                    outcome.task_description,
+                    outcome.success,
+                    outcome.strategy_used,
+                    outcome.duration_ms,
+                    outcome.error_message,
+                    outcome.user_feedback,
+                    outcome.timestamp,
+                    json.dumps(outcome.metadata) if outcome.metadata else None,
+                    self._embedding_to_db(outcome.embedding),
+                ),
+            )
+            conn.commit()
+
+        logger.debug(f"Saved outcome: {outcome.id}")
+        return outcome.id
+
+    def save_user_preference(self, preference: UserPreference) -> str:
+        """Save a user preference."""
+        with self._get_connection() as conn:
+            conn.execute(
+                f"""
+                INSERT INTO {self.schema}.alma_preferences
+                (id, user_id, category, preference, source, confidence, timestamp, metadata)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+                ON CONFLICT (id) DO UPDATE SET
+                    preference = EXCLUDED.preference,
+                    source = EXCLUDED.source,
+                    confidence = EXCLUDED.confidence,
+                    metadata = EXCLUDED.metadata
+                """,
+                (
+                    preference.id,
+                    preference.user_id,
+                    preference.category,
+                    preference.preference,
+                    preference.source,
+                    preference.confidence,
+                    preference.timestamp,
+                    json.dumps(preference.metadata) if preference.metadata else None,
+                ),
+            )
+            conn.commit()
+
+        logger.debug(f"Saved preference: {preference.id}")
+        return preference.id
+
+    def save_domain_knowledge(self, knowledge: DomainKnowledge) -> str:
+        """Save domain knowledge."""
+        with self._get_connection() as conn:
+            conn.execute(
+                f"""
+                INSERT INTO {self.schema}.alma_domain_knowledge
+                (id, agent, project_id, domain, fact, source, confidence, last_verified, metadata, embedding)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+                ON CONFLICT (id) DO UPDATE SET
+                    fact = EXCLUDED.fact,
+                    source = EXCLUDED.source,
+                    confidence = EXCLUDED.confidence,
+                    last_verified = EXCLUDED.last_verified,
+                    metadata = EXCLUDED.metadata,
+                    embedding = EXCLUDED.embedding
+                """,
+                (
+                    knowledge.id,
+                    knowledge.agent,
+                    knowledge.project_id,
+                    knowledge.domain,
+                    knowledge.fact,
+                    knowledge.source,
+                    knowledge.confidence,
+                    knowledge.last_verified,
+                    json.dumps(knowledge.metadata) if knowledge.metadata else None,
+                    self._embedding_to_db(knowledge.embedding),
+                ),
+            )
+            conn.commit()
+
+        logger.debug(f"Saved domain knowledge: {knowledge.id}")
+        return knowledge.id
+
+    def save_anti_pattern(self, anti_pattern: AntiPattern) -> str:
+        """Save an anti-pattern."""
+        with self._get_connection() as conn:
+            conn.execute(
+                f"""
+                INSERT INTO {self.schema}.alma_anti_patterns
+                (id, agent, project_id, pattern, why_bad, better_alternative,
+                 occurrence_count, last_seen, created_at, metadata, embedding)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+                ON CONFLICT (id) DO UPDATE SET
+                    pattern = EXCLUDED.pattern,
+                    why_bad = EXCLUDED.why_bad,
+                    better_alternative = EXCLUDED.better_alternative,
+                    occurrence_count = EXCLUDED.occurrence_count,
+                    last_seen = EXCLUDED.last_seen,
+                    metadata = EXCLUDED.metadata,
+                    embedding = EXCLUDED.embedding
+                """,
+                (
+                    anti_pattern.id,
+                    anti_pattern.agent,
+                    anti_pattern.project_id,
+                    anti_pattern.pattern,
+                    anti_pattern.why_bad,
+                    anti_pattern.better_alternative,
+                    anti_pattern.occurrence_count,
+                    anti_pattern.last_seen,
+                    anti_pattern.created_at,
+                    (
+                        json.dumps(anti_pattern.metadata)
+                        if anti_pattern.metadata
+                        else None
+                    ),
+                    self._embedding_to_db(anti_pattern.embedding),
+                ),
+            )
+            conn.commit()
+
+        logger.debug(f"Saved anti-pattern: {anti_pattern.id}")
+        return anti_pattern.id
+
+    # ==================== BATCH WRITE OPERATIONS ====================
+
+    def save_heuristics(self, heuristics: List[Heuristic]) -> List[str]:
+        """Save multiple heuristics in a batch using executemany."""
+        if not heuristics:
+            return []
+
+        with self._get_connection() as conn:
+            conn.executemany(
+                f"""
+                INSERT INTO {self.schema}.alma_heuristics
+                (id, agent, project_id, condition, strategy, confidence,
+                 occurrence_count, success_count, last_validated, created_at, metadata, embedding)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+                ON CONFLICT (id) DO UPDATE SET
+                    condition = EXCLUDED.condition,
+                    strategy = EXCLUDED.strategy,
+                    confidence = EXCLUDED.confidence,
+                    occurrence_count = EXCLUDED.occurrence_count,
+                    success_count = EXCLUDED.success_count,
+                    last_validated = EXCLUDED.last_validated,
+                    metadata = EXCLUDED.metadata,
+                    embedding = EXCLUDED.embedding
+                """,
+                [
+                    (
+                        h.id,
+                        h.agent,
+                        h.project_id,
+                        h.condition,
+                        h.strategy,
+                        h.confidence,
+                        h.occurrence_count,
+                        h.success_count,
+                        h.last_validated,
+                        h.created_at,
+                        json.dumps(h.metadata) if h.metadata else None,
+                        self._embedding_to_db(h.embedding),
+                    )
+                    for h in heuristics
+                ],
+            )
+            conn.commit()
+
+        logger.debug(f"Batch saved {len(heuristics)} heuristics")
+        return [h.id for h in heuristics]
+
+    def save_outcomes(self, outcomes: List[Outcome]) -> List[str]:
+        """Save multiple outcomes in a batch using executemany."""
+        if not outcomes:
+            return []
+
+        with self._get_connection() as conn:
+            conn.executemany(
+                f"""
+                INSERT INTO {self.schema}.alma_outcomes
+                (id, agent, project_id, task_type, task_description, success,
+                 strategy_used, duration_ms, error_message, user_feedback, timestamp, metadata, embedding)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+                ON CONFLICT (id) DO UPDATE SET
+                    task_description = EXCLUDED.task_description,
+                    success = EXCLUDED.success,
+                    strategy_used = EXCLUDED.strategy_used,
+                    duration_ms = EXCLUDED.duration_ms,
+                    error_message = EXCLUDED.error_message,
+                    user_feedback = EXCLUDED.user_feedback,
+                    metadata = EXCLUDED.metadata,
+                    embedding = EXCLUDED.embedding
+                """,
+                [
+                    (
+                        o.id,
+                        o.agent,
+                        o.project_id,
+                        o.task_type,
+                        o.task_description,
+                        o.success,
+                        o.strategy_used,
+                        o.duration_ms,
+                        o.error_message,
+                        o.user_feedback,
+                        o.timestamp,
+                        json.dumps(o.metadata) if o.metadata else None,
+                        self._embedding_to_db(o.embedding),
+                    )
+                    for o in outcomes
+                ],
+            )
+            conn.commit()
+
+        logger.debug(f"Batch saved {len(outcomes)} outcomes")
+        return [o.id for o in outcomes]
+
+    def save_domain_knowledge_batch(
+        self, knowledge_items: List[DomainKnowledge]
+    ) -> List[str]:
+        """Save multiple domain knowledge items in a batch using executemany."""
+        if not knowledge_items:
+            return []
+
+        with self._get_connection() as conn:
+            conn.executemany(
+                f"""
+                INSERT INTO {self.schema}.alma_domain_knowledge
+                (id, agent, project_id, domain, fact, source, confidence, last_verified, metadata, embedding)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+                ON CONFLICT (id) DO UPDATE SET
+                    fact = EXCLUDED.fact,
+                    source = EXCLUDED.source,
+                    confidence = EXCLUDED.confidence,
+                    last_verified = EXCLUDED.last_verified,
+                    metadata = EXCLUDED.metadata,
+                    embedding = EXCLUDED.embedding
+                """,
+                [
+                    (
+                        k.id,
+                        k.agent,
+                        k.project_id,
+                        k.domain,
+                        k.fact,
+                        k.source,
+                        k.confidence,
+                        k.last_verified,
+                        json.dumps(k.metadata) if k.metadata else None,
+                        self._embedding_to_db(k.embedding),
+                    )
+                    for k in knowledge_items
+                ],
+            )
+            conn.commit()
+
+        logger.debug(f"Batch saved {len(knowledge_items)} domain knowledge items")
+        return [k.id for k in knowledge_items]
+
+    # ==================== READ OPERATIONS ====================
+
+    def get_heuristics(
+        self,
+        project_id: str,
+        agent: Optional[str] = None,
+        embedding: Optional[List[float]] = None,
+        top_k: int = 5,
+        min_confidence: float = 0.0,
+    ) -> List[Heuristic]:
+        """Get heuristics with optional vector search."""
+        with self._get_connection() as conn:
+            if embedding and self._pgvector_available:
+                # Use pgvector similarity search
+                query = f"""
+                    SELECT *, 1 - (embedding <=> %s::vector) as similarity
+                    FROM {self.schema}.alma_heuristics
+                    WHERE project_id = %s AND confidence >= %s
+                """
+                params: List[Any] = [
+                    self._embedding_to_db(embedding),
+                    project_id,
+                    min_confidence,
+                ]
+
+                if agent:
+                    query += " AND agent = %s"
+                    params.append(agent)
+
+                query += " ORDER BY similarity DESC LIMIT %s"
+                params.append(top_k)
+            else:
+                # Standard query
+                query = f"""
+                    SELECT *
+                    FROM {self.schema}.alma_heuristics
+                    WHERE project_id = %s AND confidence >= %s
+                """
+                params = [project_id, min_confidence]
+
+                if agent:
+                    query += " AND agent = %s"
+                    params.append(agent)
+
+                query += " ORDER BY confidence DESC LIMIT %s"
+                params.append(top_k)
+
+            cursor = conn.execute(query, params)
+            rows = cursor.fetchall()
+
+        results = [self._row_to_heuristic(row) for row in rows]
+
+        # If embedding provided but pgvector not available, do app-level filtering
+        if embedding and not self._pgvector_available and results:
+            results = self._filter_by_similarity(results, embedding, top_k, "embedding")
+
+        return results
+
+    def get_outcomes(
+        self,
+        project_id: str,
+        agent: Optional[str] = None,
+        task_type: Optional[str] = None,
+        embedding: Optional[List[float]] = None,
+        top_k: int = 5,
+        success_only: bool = False,
+    ) -> List[Outcome]:
+        """Get outcomes with optional vector search."""
+        with self._get_connection() as conn:
+            if embedding and self._pgvector_available:
+                query = f"""
+                    SELECT *, 1 - (embedding <=> %s::vector) as similarity
+                    FROM {self.schema}.alma_outcomes
+                    WHERE project_id = %s
+                """
+                params: List[Any] = [self._embedding_to_db(embedding), project_id]
+            else:
+                query = f"""
+                    SELECT *
+                    FROM {self.schema}.alma_outcomes
+                    WHERE project_id = %s
+                """
+                params = [project_id]
+
+            if agent:
+                query += " AND agent = %s"
+                params.append(agent)
+
+            if task_type:
+                query += " AND task_type = %s"
+                params.append(task_type)
+
+            if success_only:
+                query += " AND success = TRUE"
+
+            if embedding and self._pgvector_available:
+                query += " ORDER BY similarity DESC LIMIT %s"
+            else:
+                query += " ORDER BY timestamp DESC LIMIT %s"
+            params.append(top_k)
+
+            cursor = conn.execute(query, params)
+            rows = cursor.fetchall()
+
+        results = [self._row_to_outcome(row) for row in rows]
+
+        if embedding and not self._pgvector_available and results:
+            results = self._filter_by_similarity(results, embedding, top_k, "embedding")
+
+        return results
+
+    def get_user_preferences(
+        self,
+        user_id: str,
+        category: Optional[str] = None,
+    ) -> List[UserPreference]:
+        """Get user preferences."""
+        with self._get_connection() as conn:
+            query = f"SELECT * FROM {self.schema}.alma_preferences WHERE user_id = %s"
+            params: List[Any] = [user_id]
+
+            if category:
+                query += " AND category = %s"
+                params.append(category)
+
+            cursor = conn.execute(query, params)
+            rows = cursor.fetchall()
+
+        return [self._row_to_preference(row) for row in rows]
+
+    def get_domain_knowledge(
+        self,
+        project_id: str,
+        agent: Optional[str] = None,
+        domain: Optional[str] = None,
+        embedding: Optional[List[float]] = None,
+        top_k: int = 5,
+    ) -> List[DomainKnowledge]:
+        """Get domain knowledge with optional vector search."""
+        with self._get_connection() as conn:
+            if embedding and self._pgvector_available:
+                query = f"""
+                    SELECT *, 1 - (embedding <=> %s::vector) as similarity
+                    FROM {self.schema}.alma_domain_knowledge
+                    WHERE project_id = %s
+                """
+                params: List[Any] = [self._embedding_to_db(embedding), project_id]
+            else:
+                query = f"""
+                    SELECT *
+                    FROM {self.schema}.alma_domain_knowledge
+                    WHERE project_id = %s
+                """
+                params = [project_id]
+
+            if agent:
+                query += " AND agent = %s"
+                params.append(agent)
+
+            if domain:
+                query += " AND domain = %s"
+                params.append(domain)
+
+            if embedding and self._pgvector_available:
+                query += " ORDER BY similarity DESC LIMIT %s"
+            else:
+                query += " ORDER BY confidence DESC LIMIT %s"
+            params.append(top_k)
+
+            cursor = conn.execute(query, params)
+            rows = cursor.fetchall()
+
+        results = [self._row_to_domain_knowledge(row) for row in rows]
+
+        if embedding and not self._pgvector_available and results:
+            results = self._filter_by_similarity(results, embedding, top_k, "embedding")
+
+        return results
+
+    def get_anti_patterns(
+        self,
+        project_id: str,
+        agent: Optional[str] = None,
+        embedding: Optional[List[float]] = None,
+        top_k: int = 5,
+    ) -> List[AntiPattern]:
+        """Get anti-patterns with optional vector search."""
+        with self._get_connection() as conn:
+            if embedding and self._pgvector_available:
+                query = f"""
+                    SELECT *, 1 - (embedding <=> %s::vector) as similarity
+                    FROM {self.schema}.alma_anti_patterns
+                    WHERE project_id = %s
+                """
+                params: List[Any] = [self._embedding_to_db(embedding), project_id]
+            else:
+                query = f"""
+                    SELECT *
+                    FROM {self.schema}.alma_anti_patterns
+                    WHERE project_id = %s
+                """
+                params = [project_id]
+
+            if agent:
+                query += " AND agent = %s"
+                params.append(agent)
+
+            if embedding and self._pgvector_available:
+                query += " ORDER BY similarity DESC LIMIT %s"
+            else:
+                query += " ORDER BY occurrence_count DESC LIMIT %s"
+            params.append(top_k)
+
+            cursor = conn.execute(query, params)
+            rows = cursor.fetchall()
+
+        results = [self._row_to_anti_pattern(row) for row in rows]
+
+        if embedding and not self._pgvector_available and results:
+            results = self._filter_by_similarity(results, embedding, top_k, "embedding")
+
+        return results
+
+    def _filter_by_similarity(
+        self,
+        items: List[Any],
+        query_embedding: List[float],
+        top_k: int,
+        embedding_attr: str,
+    ) -> List[Any]:
+        """Filter items by cosine similarity (fallback when pgvector unavailable)."""
+        scored = []
+        for item in items:
+            item_embedding = getattr(item, embedding_attr, None)
+            if item_embedding:
+                similarity = self._cosine_similarity(query_embedding, item_embedding)
+                scored.append((item, similarity))
+            else:
+                scored.append((item, 0.0))
+
+        scored.sort(key=lambda x: x[1], reverse=True)
+        return [item for item, _ in scored[:top_k]]
+
+    # ==================== MULTI-AGENT MEMORY SHARING ====================
+
+    def get_heuristics_for_agents(
+        self,
+        project_id: str,
+        agents: List[str],
+        embedding: Optional[List[float]] = None,
+        top_k: int = 5,
+        min_confidence: float = 0.0,
+    ) -> List[Heuristic]:
+        """Get heuristics from multiple agents using optimized ANY query."""
+        if not agents:
+            return []
+
+        with self._get_connection() as conn:
+            if embedding and self._pgvector_available:
+                query = f"""
+                    SELECT *, 1 - (embedding <=> %s::vector) as similarity
+                    FROM {self.schema}.alma_heuristics
+                    WHERE project_id = %s AND confidence >= %s AND agent = ANY(%s)
+                    ORDER BY similarity DESC LIMIT %s
+                """
+                params: List[Any] = [
+                    self._embedding_to_db(embedding),
+                    project_id,
+                    min_confidence,
+                    agents,
+                    top_k * len(agents),
+                ]
+            else:
+                query = f"""
+                    SELECT *
+                    FROM {self.schema}.alma_heuristics
+                    WHERE project_id = %s AND confidence >= %s AND agent = ANY(%s)
+                    ORDER BY confidence DESC LIMIT %s
+                """
+                params = [project_id, min_confidence, agents, top_k * len(agents)]
+
+            cursor = conn.execute(query, params)
+            rows = cursor.fetchall()
+
+        results = [self._row_to_heuristic(row) for row in rows]
+
+        if embedding and not self._pgvector_available and results:
+            results = self._filter_by_similarity(
+                results, embedding, top_k * len(agents), "embedding"
+            )
+
+        return results
+
+    def get_outcomes_for_agents(
+        self,
+        project_id: str,
+        agents: List[str],
+        task_type: Optional[str] = None,
+        embedding: Optional[List[float]] = None,
+        top_k: int = 5,
+        success_only: bool = False,
+    ) -> List[Outcome]:
+        """Get outcomes from multiple agents using optimized ANY query."""
+        if not agents:
+            return []
+
+        with self._get_connection() as conn:
+            if embedding and self._pgvector_available:
+                query = f"""
+                    SELECT *, 1 - (embedding <=> %s::vector) as similarity
+                    FROM {self.schema}.alma_outcomes
+                    WHERE project_id = %s AND agent = ANY(%s)
+                """
+                params: List[Any] = [
+                    self._embedding_to_db(embedding),
+                    project_id,
+                    agents,
+                ]
+            else:
+                query = f"""
+                    SELECT *
+                    FROM {self.schema}.alma_outcomes
+                    WHERE project_id = %s AND agent = ANY(%s)
+                """
+                params = [project_id, agents]
+
+            if task_type:
+                query += " AND task_type = %s"
+                params.append(task_type)
+
+            if success_only:
+                query += " AND success = TRUE"
+
+            if embedding and self._pgvector_available:
+                query += " ORDER BY similarity DESC LIMIT %s"
+            else:
+                query += " ORDER BY timestamp DESC LIMIT %s"
+            params.append(top_k * len(agents))
+
+            cursor = conn.execute(query, params)
+            rows = cursor.fetchall()
+
+        results = [self._row_to_outcome(row) for row in rows]
+
+        if embedding and not self._pgvector_available and results:
+            results = self._filter_by_similarity(
+                results, embedding, top_k * len(agents), "embedding"
+            )
+
+        return results
+
+    def get_domain_knowledge_for_agents(
+        self,
+        project_id: str,
+        agents: List[str],
+        domain: Optional[str] = None,
+        embedding: Optional[List[float]] = None,
+        top_k: int = 5,
+    ) -> List[DomainKnowledge]:
+        """Get domain knowledge from multiple agents using optimized ANY query."""
+        if not agents:
+            return []
+
+        with self._get_connection() as conn:
+            if embedding and self._pgvector_available:
+                query = f"""
+                    SELECT *, 1 - (embedding <=> %s::vector) as similarity
+                    FROM {self.schema}.alma_domain_knowledge
+                    WHERE project_id = %s AND agent = ANY(%s)
+                """
+                params: List[Any] = [
+                    self._embedding_to_db(embedding),
+                    project_id,
+                    agents,
+                ]
+            else:
+                query = f"""
+                    SELECT *
+                    FROM {self.schema}.alma_domain_knowledge
+                    WHERE project_id = %s AND agent = ANY(%s)
+                """
+                params = [project_id, agents]
+
+            if domain:
+                query += " AND domain = %s"
+                params.append(domain)
+
+            if embedding and self._pgvector_available:
+                query += " ORDER BY similarity DESC LIMIT %s"
+            else:
+                query += " ORDER BY confidence DESC LIMIT %s"
+            params.append(top_k * len(agents))
+
+            cursor = conn.execute(query, params)
+            rows = cursor.fetchall()
+
+        results = [self._row_to_domain_knowledge(row) for row in rows]
+
+        if embedding and not self._pgvector_available and results:
+            results = self._filter_by_similarity(
+                results, embedding, top_k * len(agents), "embedding"
+            )
+
+        return results
+
+    def get_anti_patterns_for_agents(
+        self,
+        project_id: str,
+        agents: List[str],
+        embedding: Optional[List[float]] = None,
+        top_k: int = 5,
+    ) -> List[AntiPattern]:
+        """Get anti-patterns from multiple agents using optimized ANY query."""
+        if not agents:
+            return []
+
+        with self._get_connection() as conn:
+            if embedding and self._pgvector_available:
+                query = f"""
+                    SELECT *, 1 - (embedding <=> %s::vector) as similarity
+                    FROM {self.schema}.alma_anti_patterns
+                    WHERE project_id = %s AND agent = ANY(%s)
+                """
+                params: List[Any] = [
+                    self._embedding_to_db(embedding),
+                    project_id,
+                    agents,
+                ]
+            else:
+                query = f"""
+                    SELECT *
+                    FROM {self.schema}.alma_anti_patterns
+                    WHERE project_id = %s AND agent = ANY(%s)
+                """
+                params = [project_id, agents]
+
+            if embedding and self._pgvector_available:
+                query += " ORDER BY similarity DESC LIMIT %s"
+            else:
+                query += " ORDER BY occurrence_count DESC LIMIT %s"
+            params.append(top_k * len(agents))
+
+            cursor = conn.execute(query, params)
+            rows = cursor.fetchall()
+
+        results = [self._row_to_anti_pattern(row) for row in rows]
+
+        if embedding and not self._pgvector_available and results:
+            results = self._filter_by_similarity(
+                results, embedding, top_k * len(agents), "embedding"
+            )
+
+        return results
+
+    # ==================== UPDATE OPERATIONS ====================
+
+    def update_heuristic(
+        self,
+        heuristic_id: str,
+        updates: Dict[str, Any],
+    ) -> bool:
+        """Update a heuristic's fields."""
+        if not updates:
+            return False
+
+        set_clauses = []
+        params = []
+        for key, value in updates.items():
+            if key == "metadata" and value:
+                value = json.dumps(value)
+            set_clauses.append(f"{key} = %s")
+            params.append(value)
+
+        params.append(heuristic_id)
+
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                f"UPDATE {self.schema}.alma_heuristics SET {', '.join(set_clauses)} WHERE id = %s",
+                params,
+            )
+            conn.commit()
+            return cursor.rowcount > 0
+
+    def increment_heuristic_occurrence(
+        self,
+        heuristic_id: str,
+        success: bool,
+    ) -> bool:
+        """Increment heuristic occurrence count."""
+        with self._get_connection() as conn:
+            if success:
+                cursor = conn.execute(
+                    f"""
+                    UPDATE {self.schema}.alma_heuristics
+                    SET occurrence_count = occurrence_count + 1,
+                        success_count = success_count + 1,
+                        last_validated = %s
+                    WHERE id = %s
+                    """,
+                    (datetime.now(timezone.utc), heuristic_id),
+                )
+            else:
+                cursor = conn.execute(
+                    f"""
+                    UPDATE {self.schema}.alma_heuristics
+                    SET occurrence_count = occurrence_count + 1,
+                        last_validated = %s
+                    WHERE id = %s
+                    """,
+                    (datetime.now(timezone.utc), heuristic_id),
+                )
+            conn.commit()
+            return cursor.rowcount > 0
+
+    def update_heuristic_confidence(
+        self,
+        heuristic_id: str,
+        new_confidence: float,
+    ) -> bool:
+        """Update confidence score for a heuristic."""
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                f"UPDATE {self.schema}.alma_heuristics SET confidence = %s WHERE id = %s",
+                (new_confidence, heuristic_id),
+            )
+            conn.commit()
+            return cursor.rowcount > 0
+
+    def update_knowledge_confidence(
+        self,
+        knowledge_id: str,
+        new_confidence: float,
+    ) -> bool:
+        """Update confidence score for domain knowledge."""
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                f"UPDATE {self.schema}.alma_domain_knowledge SET confidence = %s WHERE id = %s",
+                (new_confidence, knowledge_id),
+            )
+            conn.commit()
+            return cursor.rowcount > 0
+
+    # ==================== DELETE OPERATIONS ====================
+
+    def delete_heuristic(self, heuristic_id: str) -> bool:
+        """Delete a heuristic by ID."""
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                f"DELETE FROM {self.schema}.alma_heuristics WHERE id = %s",
+                (heuristic_id,),
+            )
+            conn.commit()
+            return cursor.rowcount > 0
+
+    def delete_outcome(self, outcome_id: str) -> bool:
+        """Delete an outcome by ID."""
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                f"DELETE FROM {self.schema}.alma_outcomes WHERE id = %s",
+                (outcome_id,),
+            )
+            conn.commit()
+            return cursor.rowcount > 0
+
+    def delete_domain_knowledge(self, knowledge_id: str) -> bool:
+        """Delete domain knowledge by ID."""
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                f"DELETE FROM {self.schema}.alma_domain_knowledge WHERE id = %s",
+                (knowledge_id,),
+            )
+            conn.commit()
+            return cursor.rowcount > 0
+
+    def delete_anti_pattern(self, anti_pattern_id: str) -> bool:
+        """Delete an anti-pattern by ID."""
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                f"DELETE FROM {self.schema}.alma_anti_patterns WHERE id = %s",
+                (anti_pattern_id,),
+            )
+            conn.commit()
+            return cursor.rowcount > 0
+
+    def delete_outcomes_older_than(
+        self,
+        project_id: str,
+        older_than: datetime,
+        agent: Optional[str] = None,
+    ) -> int:
+        """Delete old outcomes."""
+        with self._get_connection() as conn:
+            query = f"DELETE FROM {self.schema}.alma_outcomes WHERE project_id = %s AND timestamp < %s"
+            params: List[Any] = [project_id, older_than]
+
+            if agent:
+                query += " AND agent = %s"
+                params.append(agent)
+
+            cursor = conn.execute(query, params)
+            conn.commit()
+            deleted = cursor.rowcount
+
+        logger.info(f"Deleted {deleted} old outcomes")
+        return deleted
+
+    def delete_low_confidence_heuristics(
+        self,
+        project_id: str,
+        below_confidence: float,
+        agent: Optional[str] = None,
+    ) -> int:
+        """Delete low-confidence heuristics."""
+        with self._get_connection() as conn:
+            query = f"DELETE FROM {self.schema}.alma_heuristics WHERE project_id = %s AND confidence < %s"
+            params: List[Any] = [project_id, below_confidence]
+
+            if agent:
+                query += " AND agent = %s"
+                params.append(agent)
+
+            cursor = conn.execute(query, params)
+            conn.commit()
+            deleted = cursor.rowcount
+
+        logger.info(f"Deleted {deleted} low-confidence heuristics")
+        return deleted
+
+    # ==================== STATS ====================
+
+    def get_stats(
+        self,
+        project_id: str,
+        agent: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Get memory statistics."""
+        stats = {
+            "project_id": project_id,
+            "agent": agent,
+            "storage_type": "postgresql",
+            "pgvector_available": self._pgvector_available,
+        }
+
+        with self._get_connection() as conn:
+            tables = [
+                ("heuristics", "alma_heuristics"),
+                ("outcomes", "alma_outcomes"),
+                ("domain_knowledge", "alma_domain_knowledge"),
+                ("anti_patterns", "alma_anti_patterns"),
+            ]
+
+            for stat_name, table in tables:
+                query = f"SELECT COUNT(*) as count FROM {self.schema}.{table} WHERE project_id = %s"
+                params: List[Any] = [project_id]
+                if agent:
+                    query += " AND agent = %s"
+                    params.append(agent)
+                cursor = conn.execute(query, params)
+                row = cursor.fetchone()
+                stats[f"{stat_name}_count"] = row["count"] if row else 0
+
+            # Preferences don't have project_id
+            cursor = conn.execute(
+                f"SELECT COUNT(*) as count FROM {self.schema}.alma_preferences"
+            )
+            row = cursor.fetchone()
+            stats["preferences_count"] = row["count"] if row else 0
+
+        stats["total_count"] = sum(
+            stats.get(k, 0) for k in stats if k.endswith("_count")
+        )
+
+        return stats
+
+    # ==================== HELPERS ====================
+
+    def _parse_datetime(self, value: Any) -> Optional[datetime]:
+        """Parse datetime from database value."""
+        if value is None:
+            return None
+        if isinstance(value, datetime):
+            return value
+        try:
+            return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+        except (ValueError, AttributeError):
+            return None
+
+    def _row_to_heuristic(self, row: Dict[str, Any]) -> Heuristic:
+        """Convert database row to Heuristic."""
+        return Heuristic(
+            id=row["id"],
+            agent=row["agent"],
+            project_id=row["project_id"],
+            condition=row["condition"],
+            strategy=row["strategy"],
+            confidence=row["confidence"] or 0.0,
+            occurrence_count=row["occurrence_count"] or 0,
+            success_count=row["success_count"] or 0,
+            last_validated=self._parse_datetime(row["last_validated"])
+            or datetime.now(timezone.utc),
+            created_at=self._parse_datetime(row["created_at"])
+            or datetime.now(timezone.utc),
+            embedding=self._embedding_from_db(row.get("embedding")),
+            metadata=row["metadata"] if row["metadata"] else {},
+        )
+
+    def _row_to_outcome(self, row: Dict[str, Any]) -> Outcome:
+        """Convert database row to Outcome."""
+        return Outcome(
+            id=row["id"],
+            agent=row["agent"],
+            project_id=row["project_id"],
+            task_type=row["task_type"] or "general",
+            task_description=row["task_description"],
+            success=bool(row["success"]),
+            strategy_used=row["strategy_used"] or "",
+            duration_ms=row["duration_ms"],
+            error_message=row["error_message"],
+            user_feedback=row["user_feedback"],
+            timestamp=self._parse_datetime(row["timestamp"])
+            or datetime.now(timezone.utc),
+            embedding=self._embedding_from_db(row.get("embedding")),
+            metadata=row["metadata"] if row["metadata"] else {},
+        )
+
+    def _row_to_preference(self, row: Dict[str, Any]) -> UserPreference:
+        """Convert database row to UserPreference."""
+        return UserPreference(
+            id=row["id"],
+            user_id=row["user_id"],
+            category=row["category"] or "general",
+            preference=row["preference"],
+            source=row["source"] or "unknown",
+            confidence=row["confidence"] or 1.0,
+            timestamp=self._parse_datetime(row["timestamp"])
+            or datetime.now(timezone.utc),
+            metadata=row["metadata"] if row["metadata"] else {},
+        )
+
+    def _row_to_domain_knowledge(self, row: Dict[str, Any]) -> DomainKnowledge:
+        """Convert database row to DomainKnowledge."""
+        return DomainKnowledge(
+            id=row["id"],
+            agent=row["agent"],
+            project_id=row["project_id"],
+            domain=row["domain"] or "general",
+            fact=row["fact"],
+            source=row["source"] or "unknown",
+            confidence=row["confidence"] or 1.0,
+            last_verified=self._parse_datetime(row["last_verified"])
+            or datetime.now(timezone.utc),
+            embedding=self._embedding_from_db(row.get("embedding")),
+            metadata=row["metadata"] if row["metadata"] else {},
+        )
+
+    def _row_to_anti_pattern(self, row: Dict[str, Any]) -> AntiPattern:
+        """Convert database row to AntiPattern."""
+        return AntiPattern(
+            id=row["id"],
+            agent=row["agent"],
+            project_id=row["project_id"],
+            pattern=row["pattern"],
+            why_bad=row["why_bad"] or "",
+            better_alternative=row["better_alternative"] or "",
+            occurrence_count=row["occurrence_count"] or 1,
+            last_seen=self._parse_datetime(row["last_seen"])
+            or datetime.now(timezone.utc),
+            created_at=self._parse_datetime(row["created_at"])
+            or datetime.now(timezone.utc),
+            embedding=self._embedding_from_db(row.get("embedding")),
+            metadata=row["metadata"] if row["metadata"] else {},
+        )
+
+    def close(self):
+        """Close connection pool."""
+        if self._pool:
+            self._pool.close()