Milestone 3.2.1 — VectorStore interface and pgvector-HNSW implementation

## Decision
 
### 1) VectorStore interface (Python ABC, mirrors packages/provider's Go pattern)
 
class VectorStore(ABC):
 async def upsert(self, memory_id: UUID, embedding: list[float], org_id: UUID) -> None: ...
 async def search(self, org_id: UUID, agent_id: UUID, query_embedding: list[float],
 limit: int, min_confidence: float) -> list[tuple[UUID, float]]: ...
 async def delete(self, memory_id: UUID, org_id: UUID) -> None: ...
 
Concrete implementation: `PgVectorStore` (this milestone). A `QdrantStore` stub
is intentionally NOT built now — YAGNI — but the interface boundary means it
can be added later without touching MemoryService business logic.
 
### 2) ef_search tuning is a per-query, not per-connection, setting
 
`SET LOCAL hnsw.ef_search = 40` inside the same transaction as the search
query — never a global GUC change — so concurrent requests with different
recall/latency needs cannot interfere with each other.
 
### 3) Composite scoring formula v2 — category-conditional recency decay
 
score = 0.40 * relevance + 0.25 * recency(category) + 0.20 * usefulness
 + 0.10 * confidence + 0.05 * access_frequency
 
recency(category) uses exponential decay with a category-specific half-life:
 factual: 180 days (facts don't go stale quickly)
 procedural: 120 days (how-to knowledge is durable)
 preference: 45 days (preferences drift faster)
 behavioral: 30 days
 episodic: 14 days (original global default — correct only for this category)
 
For multi-label memories, recency uses the shortest half-life among the
memory's labels (conservative — decay faster, not slower, when ambiguous).

services/memory/
 vectorstore/
 __init__.py
 base.py # VectorStore ABC
 pgvector_store.py # PgVectorStore(VectorStore) — HNSW search + ef_search tuning
 pgvector_store_test.py
 scoring/
 __init__.py
 composite.py # score(memory, query_embedding_similarity) -> Decimal
 half_life.py # CATEGORY_HALF_LIFE_DAYS constant table
 composite_test.py
 embedding_client.py # thin HTTP client to Phase 2.5's embedder service
 embedding_client_test.py

from abc import ABC, abstractmethod
from uuid import UUID
 
class VectorStore(ABC):
 @abstractmethod
 async def upsert(
 self,
 memory_id: UUID,
 embedding: list[float],
 org_id: UUID,
 ) -> None:
 """Store or update an embedding for a memory."""
 ...
 
 @abstractmethod
 async def search(
 self,
 org_id: UUID,
 agent_id: UUID,
 query_embedding: list[float],
 limit: int,
 min_confidence: float = 0.0,
 ) -> list[tuple[UUID, float]]:
 """Return (memory_id, cosine_similarity) pairs, descending similarity, org/agent scoped."""
 ...
 
 @abstractmethod
 async def delete(self, memory_id: UUID, org_id: UUID) -> None:
 """Remove an embedding from the store."""
 ...

class PgVectorStore(VectorStore):
 async def search(
 self,
 org_id: UUID,
 agent_id: UUID,
 query_embedding: list[float],
 limit: int,
 min_confidence: float = 0.0,
 ) -> list[tuple[UUID, float]]:
 async with self._session() as session:
 # ef_search is set per-transaction, not globally (ADR-0053)
 await session.execute(text("SET LOCAL hnsw.ef_search = 40"))
 rows = await session.execute(
 text("""
 SELECT id, 1 - (embedding <=> :query) AS similarity
 FROM ibex_core.memories
 WHERE org_id = :org_id
 AND agent_id = :agent_id
 AND status = 'active'
 AND deleted_at IS NULL
 AND 1 - (embedding <=> :query) >= :min_confidence
 ORDER BY embedding <=> :query
 LIMIT :limit
 """),
 {"query": query_embedding, "org_id": org_id,
 "agent_id": agent_id, "min_confidence": min_confidence, "limit": limit},
 )
 return [(row.id, row.similarity) for row in rows]

# scoring/half_life.py
from typing import Final
 
CATEGORY_HALF_LIFE_DAYS: Final[dict[str, float]] = {
 "factual": 180.0,
 "procedural": 120.0,
 "preference": 45.0,
 "behavioral": 30.0,
 "episodic": 14.0,
}
 
def recency_decay(age_days: float, category: str) -> float:
 """Exponential decay. For multi-label memories, uses the shortest half-life."""
 half_life = CATEGORY_HALF_LIFE_DAYS.get(category, 14.0)
 import math
 return math.exp(-0.693 * age_days / half_life)

# scoring/composite.py
def score(
 relevance: float,
 recency: float,
 usefulness: float,
 confidence: float,
 access_frequency: float,
) -> float:
 return (
 0.40 * relevance
 + 0.25 * recency
 + 0.20 * usefulness
 + 0.10 * confidence
 + 0.05 * access_frequency
 )